From 5a250d63dfb135dcbcabb3df27ddf75b094fcc23 Mon Sep 17 00:00:00 2001
From: Wilfred Hughes <me@wilfred.me.uk>
Date: Mon, 13 May 2024 16:31:30 -0700
Subject: [PATCH] Expand usage docs and fix obsolete reference to --language

Fixes #712
---
 manual/src/usage.md                         | 44 +++++++++++++++------
 translation/zh-CN/manual-zh-CN/src/usage.md | 29 +++++++++-----
 2 files changed, 51 insertions(+), 22 deletions(-)

diff --git a/manual/src/usage.md b/manual/src/usage.md
index 6f50846c4c..f25e1edf8d 100644
--- a/manual/src/usage.md
+++ b/manual/src/usage.md
@@ -4,13 +4,19 @@
 
 ### Diffing Files
 
-```
-$ difft sample_files/before.js sample_files/after.js
+```bash
+$ difft FIRST-FILE SECOND-FILE
+
+# For example:
+$ difft sample_files/simple_1.js sample_files/simple_2.js
 ```
 
 ### Diffing Directories
 
-```
+```bash
+$ difft FIRST-DIRECTORY SECOND-DIRECTORY
+
+# For example:
 $ difft sample_files/dir_1/ sample_files/dir_2/
 ```
 
@@ -24,8 +30,11 @@ contain many unchanged files.
 
 You can read a file from stdin by specifying `-` as the file path.
 
-```
-$ cat sample_files/before.js | difft - sample_files/after.js
+```bash
+$ difft - SECOND-FILE
+
+# For example:
+$ cat sample_files/simple_1.js | difft - sample_files/simple_2.js
 ```
 
 ### Files With Conflicts
@@ -36,23 +45,32 @@ If you have a file with `<<<<<<<` conflict markers, you can pass it as
 a single argument to difftastic. Difftastic will construct the two
 file states and diff those.
 
-```
+```bash
+$ difft FILE-WITH-CONFLICTS
+
+# For example:
 $ difft sample_files/conflicts.el
 ```
 
-
 ## Language Detection
 
 Difftastic guesses the language used based on the file extension, file
-name, and the contents of the first lines.
+name, and the contents of the first lines. To see the languages
+available, and the associated file names, use the `--list-languages`
+option.
+
+```
+$ difft --list-languages
+```
 
-You can override the language detection by passing the `--language`
-option. Difftastic will treat input files as if they had that
-extension, and ignore other language detection heuristics.
+You can override language detection for specific file globs using the
+`--override` option.
 
+```bash
+$ difft --override=GLOB:NAME FIRST-FILE SECOND-FILE
 
-```
-$ difft --language cpp before.c after.c
+# 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
diff --git a/translation/zh-CN/manual-zh-CN/src/usage.md b/translation/zh-CN/manual-zh-CN/src/usage.md
index f6d9c02951..0eeb08e2ba 100644
--- a/translation/zh-CN/manual-zh-CN/src/usage.md
+++ b/translation/zh-CN/manual-zh-CN/src/usage.md
@@ -4,13 +4,18 @@
 
 ### 比较文件
 
-```
-$ difft sample_files/before.js sample_files/after.js
+```bash
+$ difft FIRST-FILE SECOND-FILE
+
+$ difft sample_files/simple_1.js sample_files/simple_2.js
 ```
 
 ### 比较文件夹
 
-```
+```bash
+$ difft FIRST-DIRECTORY SECOND-DIRECTORY
+
+# For example:
 $ difft sample_files/dir_1/ sample_files/dir_2/
 ```
 
@@ -22,8 +27,10 @@ Difftastic 会递归地浏览这两个文件夹，对同名的文件进行差异
 
 您可以通过指定 `-` 作为文件路径从标准输入（stdin）读取文件。
 
-```
-$ cat sample_files/before.js | difft - sample_files/after.js
+```bash
+$ difft - SECOND-FILE
+
+$ cat sample_files/simple_1.js | difft - sample_files/simple_2.js
 ```
 
 ### 带冲突标记的文件
@@ -32,7 +39,9 @@ $ cat sample_files/before.js | difft - sample_files/after.js
 
 如果你有一个带 `<<<<<<<` 冲突标记的文件，可以将它作为一个参数传入 Difftastic。Difftastic 会构建和比较文件的两个状态。
 
-```
+```bash
+$ difft FILE-WITH-CONFLICTS
+
 $ difft sample_files/conflicts.el
 ```
 
@@ -40,10 +49,12 @@ $ difft sample_files/conflicts.el
 
 Difftastic 根据文件的扩展名、文件名和第一行的内容猜测文件所用的语言。
 
-你可以通过 `--language` 选项覆盖语言检测。如果输入的文件有所设定的后缀， Difftastic 将会处理它们，并且忽略其他语言。
+你可以通过 `--override` 选项覆盖语言检测。如果输入的文件有所设定的后缀， Difftastic 将会处理它们，并且忽略其他语言。
 
-```
-$ difft --language cpp before.c after.c
+```bash
+$ difft --override=GLOB:NAME FIRST-FILE SECOND-FILE
+
+$ difft --override=*.h:c sample_files/preprocesor_1.h sample_files/preprocesor_2.h
 ```
 
 ## 选项