From c52bca44ddcdb17855e3735978fb5e87b7eb4fa4 Mon Sep 17 00:00:00 2001
From: Wilfred Hughes <me@wilfred.me.uk>
Date: Sun, 22 Sep 2024 11:21:55 -0700
Subject: [PATCH] Improve usage docs

Separate out language detection, add intro sentence, clarify options
docs.
---
 manual/src/SUMMARY.md            |  1 +
 manual/src/language_detection.md | 30 +++++++++++++++++++
 manual/src/usage.md              | 50 +++++++++++++++-----------------
 3 files changed, 54 insertions(+), 27 deletions(-)
 create mode 100644 manual/src/language_detection.md

diff --git a/manual/src/SUMMARY.md b/manual/src/SUMMARY.md
index f8f6d8b9f..2a6f371fc 100644
--- a/manual/src/SUMMARY.md
+++ b/manual/src/SUMMARY.md
@@ -8,6 +8,7 @@
   - [Mercurial](./mercurial.md)
   - [Fossil](./fossil.md)
 - [Languages Supported](./languages_supported.md)
+  - [Language Detection](./language_detection.md)
 - [Internals: Parsing](./parsing.md)
 - [Internals: Diffing](./diffing.md)
   - [Tricky Cases](./tricky_cases.md)
diff --git a/manual/src/language_detection.md b/manual/src/language_detection.md
new file mode 100644
index 000000000..1f69cbf3f
--- /dev/null
+++ b/manual/src/language_detection.md
@@ -0,0 +1,30 @@
+# Language Detection
+
+Difftastic guesses the language used based on the file extension, file
+name, and the contents of the first few lines.
+
+To see the languages available, and the associated file names, use the
+`--list-languages` option.
+
+```bash
+$ difft --list-languages
+...
+XML
+ *.ant *.csproj *.plist *.resx *.svg *.ui *.vbproj *.xaml *.xml *.xsd *.xsl *.xslt *.zcml App.config nuget.config packages.config .classpath .cproject .project
+YAML
+ *.yaml *.yml
+Zig
+ *.zig
+```
+
+You can override language detection for specific file globs using the
+`--override` option.
+
+```bash
+$ difft --override=GLOB:NAME FIRST-FILE SECOND-FILE
+
+# For example, treating .h files as C rather than C++:
+$ difft --override=*.h:c sample_files/preprocesor_1.h sample_files/preprocesor_2.h
+```
+
+See `difft --help` for more examples of `--override` usage.
diff --git a/manual/src/usage.md b/manual/src/usage.md
index f25e1edf8..769173d0d 100644
--- a/manual/src/usage.md
+++ b/manual/src/usage.md
@@ -1,5 +1,10 @@
 # Usage
 
+This page describes how to use the `difft` binary directly. See also
+the [Git](./git.html), [Mercurial](./mercurial.html) and
+[Fossil](./fossil.html) pages for instructions on how to configure
+them to use difftastic.
+
 ## File Arguments
 
 ### Diffing Files
@@ -52,38 +57,29 @@ $ difft FILE-WITH-CONFLICTS
 $ difft sample_files/conflicts.el
 ```
 
-## Language Detection
+## Configuration Options
 
-Difftastic guesses the language used based on the file extension, file
-name, and the contents of the first lines. To see the languages
-available, and the associated file names, use the `--list-languages`
-option.
+Every difftastic option can be set with a command line argument or an
+environment variable. For example, `DFT_BACKGROUND=light` is equivalent to
+`--background=light`.
 
-```
-$ difft --list-languages
-```
+Environment variables are often useful when using VCS tools like git,
+because they invoke the `difft` binary directly.
 
-You can override language detection for specific file globs using the
-`--override` option.
-
-```bash
-$ difft --override=GLOB:NAME FIRST-FILE SECOND-FILE
+For a full list of configuration options, see `--help`.
 
-# For example, treating .h files as C rather than C++:
-$ difft --override=*.h:c sample_files/preprocesor_1.h sample_files/preprocesor_2.h
 ```
-
-## Options
-
-Difftastic includes a range of configuration CLI options, see `difft
---help` for the full list.
-
-Difftastic can also be configured with environment variables. These
-are also visible in `--help`.
-
-For example, `DFT_BACKGROUND=light` is equivalent to
-`--background=light`. This is useful when using VCS tools like git,
-where you are not invoking the `difft` binary directly.
+$ difft --help
+...
+OPTIONS:
+        --background <BACKGROUND>
+            Set the background brightness. Difftastic will prefer brighter colours on dark backgrounds.
+
+            [env: DFT_BACKGROUND=]
+            [default: dark]
+            [possible values: dark, light]
+...
+```
 
 ## Exit Codes