From cdfebcc5a0201199f70e90a8df7b93561fcbc4a4 Mon Sep 17 00:00:00 2001 From: Kevin Ernst Date: Mon, 13 Jan 2025 21:42:44 -0500 Subject: [PATCH] Suggest minimum bat version in manual - make explicit mention of which bat version should be installed in the "Installation" and "Supported languages and themes" sections of the manual - add missing "Tips & tricks" page See https://github.com/dandavison/delta/issues/1712 for context. --- manual/src/installation.md | 2 ++ manual/src/supported-languages-and-themes.md | 3 +++ manual/src/tips-and-tricks.md | 5 +++++ 3 files changed, 10 insertions(+) create mode 100644 manual/src/tips-and-tricks.md diff --git a/manual/src/installation.md b/manual/src/installation.md index 4ad5d3fc7..8bc11335e 100644 --- a/manual/src/installation.md +++ b/manual/src/installation.md @@ -97,3 +97,5 @@ Users of older MacOS versions (e.g. 10.11 El Capitan) should install using Homeb Behind the scenes, delta uses [`less`](https://www.greenwoodsoftware.com/less/) for paging. It's important to have a reasonably recent version of less installed. On MacOS, install `less` from Homebrew. For Windows, see [Using Delta on Windows](./tips-and-tricks/using-delta-on-windows.md). + +Delta also relies on [`bat`](https://github.com/sharkdp/bat) for [custom themes and syntaxes](./supported-languages-and-themes.md). Ideally, you should install the same version of bat as specified in the [`Cargo.toml`](https://github.com/dandavison/delta/blob/main/Cargo.toml) for the delta release you're using. There are [known problems](https://github.com/dandavison/delta/issues/1712) with v0.18.3 and prior versions of bat. diff --git a/manual/src/supported-languages-and-themes.md b/manual/src/supported-languages-and-themes.md index 2e90d53c1..fc6303709 100644 --- a/manual/src/supported-languages-and-themes.md +++ b/manual/src/supported-languages-and-themes.md @@ -9,4 +9,7 @@ To add your own custom color theme, or language, please follow the instructions Delta automatically recognizes custom themes and languages added to bat. You will need to install bat in order to run the `bat cache --build` command. +Ideally, the version of bat you install should match the version specified in delta's [`Cargo.toml`](https://github.com/dandavison/delta/blob/main/Cargo.toml) for the delta release you're using. There are [known problems](https://github.com/dandavison/delta/issues/1712) with bat v0.18.3 and below. + The languages and color themes that ship with delta are those that ship with bat. So, to propose a new language or color theme for inclusion in delta, it would need to be a helpful addition to bat, in which case please open a PR against bat. + diff --git a/manual/src/tips-and-tricks.md b/manual/src/tips-and-tricks.md new file mode 100644 index 000000000..603823736 --- /dev/null +++ b/manual/src/tips-and-tricks.md @@ -0,0 +1,5 @@ +# Tips & tricks + +Delta has a number of options to configure the appearance and behavior of the user interface, and integrate with other programs, including the programmable completion features of various shells. + +The following sections discuss these features and integrations.