New manual content: environment variables and configuration.

Ref #1113

5 files changed, 70 insertions, 28 deletions

diff --git a/manual/src/SUMMARY.md b/manual/src/SUMMARY.md
index 992c51d6..c997740e 100644
--- a/manual/src/SUMMARY.md
+++ b/manual/src/SUMMARY.md
@@ -5,6 +5,7 @@
 - [Features](./features.md)
 - [Installation](./installation.md)
 - [Configuration](./configuration.md)
+- [Environment variables](./environment-variables.md)
 - [How delta works](./how-delta-works.md)
 - [Usage](./usage.md)
   - [Choosing colors (styles)](./choosing-colors-styles.md)
diff --git a/manual/src/configuration.md b/manual/src/configuration.md
index 9895cc9f..248afa36 100644
--- a/manual/src/configuration.md
+++ b/manual/src/configuration.md
@@ -31,8 +31,6 @@ The most convenient way to configure delta is with a `[delta]` section in `~/.gi
 
 </sub>
 
-If you have the `GIT_PAGER` environment variable set, you'll need to unset it.
-
 Use `delta --help` to see all the available options.
 
 Note that delta style argument values in ~/.gitconfig should be in double quotes, like `--minus-style="syntax #340001"`. For theme names and other values, do not use quotes as they will be passed on to delta, like `theme = Monokai Extended`.
@@ -52,14 +50,5 @@ To change your delta options in a one-off git command, use `git -c`. For example
 git -c delta.line-numbers=false show
 ```
 
-Delta can also be used as a shorthand for diffing two files: the following two commands do the same thing:
-
-```
-delta a.txt b.txt
-
-git diff a.txt b.txt
-```
-
-Delta also handles unified diff format, e.g. `diff -u a.txt b.txt | delta`.
-
-For Mercurial, you can add delta, with its command line options, to the `[pager]` section of `.hgrc`.
+There are several important environment variables that affect delta configuration and which can be used to configure delta dynamically.
+Please see [Environment variables](./environment-variables.md).
diff --git a/manual/src/environment-variables.md b/manual/src/environment-variables.md
new file mode 100644
index 00000000..93fa034c
--- /dev/null
+++ b/manual/src/environment-variables.md
@@ -0,0 +1,47 @@
+# Environment variables
+
+## Git environment variables
+
+The `GIT_PAGER` environment variable must either not be set at all, or set to the value `delta` (you can add argument here if you want; this env var plays the same role as the `core.pager` config entry).
+
+Unfortunately, delta does not currently honor all relevant [git environment variables](https://git-scm.com/docs/git-config#_environment).
+For example, it does not honor `GIT_CONFIG_GLOBAL`.
+This is because delta uses [libgit2](https://github.com/libgit2/libgit2) to read git config, whereas git uses its own code.
+(libgit2 is a project run by volunteers; if this affects you, please do consider contributing the required features to libgit2!)
+
+## Pager environment variables
+
+A pager is a program that accepts many lines of text as input, and displays them one screenful at a time.
+The standard pager is [less](https://linux.die.net/man/1/less), and this is what delta uses by default (it's also what [`bat`](https://github.com/sharkdp/bat) uses).
+Therefore:
+
+1. It is very important that you are using a recent version of less. In particular, on Windows, the installed version of less is often broken and it is usually necessary to install it yourself or use the version of less that is installed with git on Windows.
+
+2. The command line flags passed to `less` are important, and there are some environment variables that affect these (see below). By default, delta will try to ensure that they are sensible.
+
+3. When delta is displaying lengthy output, anything you do with the keyboard or mouse is actually received by less, and it is worth looking at less documentation (`less --help` or `man less` or [online](https://linux.die.net/man/1/less)) to discover what you can do.
+
+The exact command that `delta` uses to start its pager is taken from one of the following environment variables (in this order):
+
+- `DELTA_PAGER`
+- `PAGER`
+
+If none of these is set, delta uses `less -R`, and you should always include `-R` if you are setting these environment variables yourself.
+
+In addition to those `*PAGER` environment variables, the behavior of `less` is also affected by the `LESS` environment variable (see `man less` or [online documentation](https://linux.die.net/man/1/less)). This env var can contain command line options and/or interactive less-commands (prefixed by a leading `+` sign; these are executed every time right after less is launched).
+
+In addition to `DELTA_PAGER`, and `PAGER`, delta currently also consults `$BAT_PAGER` (with priority between the two).
+However, this is deprecated: please use `DELTA_PAGER` instead.
+No other [`bat`](https://github.com/sharkdp/bat) environment variables are used by delta, and delta does not use `bat` when it is running (it does use some code from the excellent `bat` project, but users don't need to be aware of this).
+
+## Delta-specific environment variables
+
+To temporarily activate and inactivate delta features, you can use `DELTA_FEATURES`, e.g.
+
+```
+export DELTA_FEATURES='+side-by-side my-feature'
+```
+
+(The `+` means "add these features to those configured in git config".)
+
+The `DELTA_PAGER` env var is described above.
diff --git a/manual/src/how-delta-works.md b/manual/src/how-delta-works.md
index d08d9727..75d17e91 100644
--- a/manual/src/how-delta-works.md
+++ b/manual/src/how-delta-works.md
@@ -8,19 +8,4 @@ If you need to force delta to be invoked when git itself would not invoke it, th
 For example, `git diff | delta | something-that-expects-delta-output-with-colors` (in this example, git's output is being sent to a pipe, so git itself will not invoke delta).
 In general however, delta's output is intended for humans, not machines.
 
-The pager that delta uses is determined by consulting the following environment variables (in this order):
-
-- `DELTA_PAGER`
-- `PAGER`
-
-If neither is set, delta's fallback is `less -R`.
-
-The behavior of delta's default pager, `less`, can be controlled using the `LESS` environment variable.
-It may contain any of the `less` command line options and/or interactive less-commands (prefixed by a leading `+` sign; these are executed every time right after less is launched).
-For full documentation of `less` configuration options, please see the `less(1)` [manual](https://jlk.fjfi.cvut.cz/arch/manpages/man/core/less/less.1.en).
-
-In addition to `DELTA_PAGER`, and `PAGER`, delta currently also consults `$BAT_PAGER` (with priority between the two).
-However, this is deprecated: please use `DELTA_PAGER` instead.
-No other [`bat`](https://github.com/sharkdp/bat) environment variables are used by delta.
-
 If you are interested in the implementation of delta, please see [ARCHITECTURE.md](https://github.com/dandavison/delta/blob/master/ARCHITECTURE.md).
diff --git a/manual/src/usage.md b/manual/src/usage.md
index 8f04b05a..029bf282 100644
--- a/manual/src/usage.md
+++ b/manual/src/usage.md
@@ -1 +1,21 @@
 # Usage
+
+The main way to use delta is to configure it as the pager for git: see [Configuration](./configuration.md).
+
+Delta can also be used as a shorthand for diffing two files, even if they are not in a git repo: the following two commands do the same thing:
+
+```
+delta /somewhere/a.txt /somewhere/else/b.txt
+
+git diff /somewhere/a.txt /somewhere/else/b.txt
+```
+
+You can also use [process substitution](https://en.wikipedia.org/wiki/Process_substitution) shell syntax with delta, e.g.
+
+```
+delta <(sort file1) <(sort file2)
+```
+
+In addition to git output, delta handles standard unified diff format, e.g. `diff -u a.txt b.txt | delta`.
+
+For Mercurial, you can add delta, with its command line options, to the `[pager]` section of `.hgrc`.