Documentation
¶
Overview ¶
clidoc rewrites the reference blocks between docs/CLI.md's clidoc markers from the built tools' own help, so the reference cannot drift from the binaries it documents.
For every `<!-- clidoc:begin <tool> -->` marker in the file it runs that tool's `help` and each verb's `-h` from the --bin directory and rewrites only the block between the marker and its `<!-- clidoc:end <tool> -->`; the prose and the worked examples outside the markers are hand-written and stay as they are. The verb list is read from the help's own usage block, so a verb the tool adds joins the reference the next time clidoc runs.
A pasted text keeps its typed lines whole — the usage synopsis, the flags with what each wants, the exit codes and the effect — and drops one thing the hand-written prose around the block already carries: a verb help's free-text paragraph. The banner is pasted whole, its `example:` block included; every example line of these five banners runs through the comparator in the tool's own tests.
Source Files