;doc:DOCS

doc/DOCS.md

@@ -5,7 +5,7 @@
 <!-- toc -->
 </div>
 
-## Four kinds of documentation
+## hledger's documentation structure
 
 <div style="margin:1em 2em; font-style:italic;">
 "There is a secret that needs to be understood in order to write good
@@ -16,8 +16,6 @@ functions, and require four different approaches to their creation."
 --[Daniele Procida] (https://news.ycombinator.com/item?id=21289832)
 </div>
 
-## hledger's documentation structure
-
 2019: out of date, needs update.
 
 Project documentation lives in a number of places:
@@ -74,30 +72,37 @@ hledger doc files can be divided into several groups:
 Last updated: 2025-09
 <!-- keep synced with Justfile, Shake.hs -->
 
+### Compile the Shake script
+
+`Shake.hs` automates some doc maintenance tasks (complementing `Justfile)`.
+Most contributors don't need to use it, but if you do, compile it like so:
+in the hledger repo, run:
+```
+$ ./Shake.hs
+```
+
+### Update options help
+
+Edit general options definitions in `hledger/Hledger/Cli/CliOptions.hs`
+and  command options definitions in `hledger/Hledger/Cli/Commands/*.hs`.
+
 ### Update manuals' content
 
-Updates to the manuals' content are welcome and encouraged!
+Updates and fixes for the manuals' content are welcome and encouraged!
 They can be committed together with related code changes, or separately.
 
-Note the manuals have (a) source files and (b) files generated from these by scripts.
+The manuals have (a) source files, kept in the hledger repo and (b) generated files derived from those.
 Don't edit the generated files, such as:
 - `hledger/hledger.md` or `hledger-ui/hledger-ui.md` in the hledger repo
 - `site/src/1.50/hledger*.md` or `site/src/dev/hledger*.md` in the hledger_site repo
 
-Instead, edit the source files, in the hledger repo's master branch. Usually that means:
+Instead, edit the source files:
 - `hledger/hledger.m4.md` or `hledger/Hledger/Cli/Commands/*.md` for the hledger manual
 - `hledger-ui/hledger-ui.m4.md` for the hledger-ui manual
 - `hledger-web/hledger-web.m4.md` for the hledger-web manual.
 
-If you click "edit this page" on a recent release manual on the website, you'll see all of its source files listed.
+(There are a few more source files which change less often;
-
+if you click "edit this page" on a recent release manual on the website, you'll see all source files listed.)
-### Compile the Shake script
-
-`Shake.hs` automates some doc maintenance tasks (complementing `Justfile)`.
-If you use it, it's best to compile it first: in the hledger repo, run:
-```
-$ ./Shake.hs
-```
 
 ### Update manuals' generated files
 
@@ -109,32 +114,23 @@ In the hledger repo: first, set current year and month for the man pages:
 $ just mandates
 ```
 
+Then update the lists of command line options in the manuals' source files (only as needed, if command line options or option help have changed):
+```
+$ stack build && ./Shake cmddocs -c
+```
+
 Then regenerate the text, man, info, and markdown manuals in hledger*/ from their source files:
 
-```
-$ ./Shake manuals
-```
-
-To also commit the generated files, run it with -c:
-
 ```
 $ ./Shake manuals -c
 ```
 
-### Update hledger binaries with latest manuals included
-
-The next build of the hledger executables will embed the latest text, man and info manuals from hledger*/. Eg:
-
-```
-$ stack build
-```
-
 ### Update dev manuals on the website
 
-When updates to the generated manuals land in the master branch of the hledger repo on github,
+When updates to manuals' generated files land in the master branch of the hledger repo on github,
-the latest (dev) manuals on hledger.org will update automatically.
+the dev manuals on hledger.org will update automatically.
 
-(The website manuals are rendered from `site/src/VERSION/*.md` in the hledger_site repo,
+(The manuals on the website are rendered from `site/src/VERSION/*.md` in the hledger_site repo,
 which are symlinked copies of `hledger/hledger.md`, `hledger-ui/hledger-ui.md` and `hledger-web/hledger-web.md` in the hledger repo.)
 
 ### Update release manuals on the website
@@ -144,7 +140,8 @@ Contributors can do this, but doing it the right way is a little complicated; yo
 The release manuals on the website are rendered from `site/src/1.50/*.md`, `site/src/1.43/*.md`, etc.
 These are generated as follows:
 
-In the hledger repo, with the hledger_site repo symlinked as `./site`, for each major release REL that needs updating:
+In the hledger repo, with the hledger_site repo symlinked as `./site`;\
+for each major release REL that needs updating:
 
 1. Cherry pick the manuals' content updates for REL (not generated files updates) from `master` to `REL-branch`
 2. In master, run `just site-manuals-snapshot REL` to update the release manuals in the site repo.
@@ -152,6 +149,18 @@ In the hledger repo, with the hledger_site repo symlinked as `./site`, for each
 When these commits land in the hledger_site repo on github,
 the release manuals on hledger.org will update automatically.
 
+### Update hledger binaries with latest docs
+
+This ensures the hledger dev executables are embedding the latest manuals' generated files, affecting:
+- options help displayed by `--help`
+- command docs displayed by `CMD --help`
+- manuals displayed by `help`, `--info`, and `--man`.
+
+Update the options help, manuals' content and manuals' generated files as above, then rebuild:
+```
+$ stack build
+```
+
 
 ## 201901 docs reorg (#920, WIP)