Add CLI docs, copying help text during build

docs/01_intro.md

@@ -43,6 +43,8 @@ This requirement may be updated between minor versions of the library.
 The API provided by `yaml` has three layers, depending on how deep you need to go: [Parse & Stringify](#parse-amp-stringify), [Documents](#documents), and the underlying [Lexer/Parser/Composer](#parsing-yaml).
 The first has the simplest API and "just works", the second gets you all the bells and whistles supported by the library along with a decent [AST](#content-nodes), and the third lets you get progressively closer to YAML source, if that's your thing.
 
+A [command-line tool](#command-line-tool) is also included.
+
 <h3>Parse & Stringify</h3>
 
 ```js

docs/09_cli.md

@@ -0,0 +1,26 @@
+# Command-line Tool
+
+Available as `npx yaml` or `npm exec yaml`:
+
+<pre id="cli-help" style="float: none">
+yaml: A command-line YAML processor and inspector
+
+Reads stdin and writes output to stdout and errors & warnings to stderr.
+
+Usage:
+  yaml          Process a YAML stream, outputting it as YAML
+  yaml cst      Parse the CST of a YAML stream
+  yaml lex      Parse the lexical tokens of a YAML stream
+  yaml valid    Validate a YAML stream, returning 0 on success
+
+Options:
+  --help, -h    Show this message.
+  --json, -j    Output JSON.
+
+Additional options for bare "yaml" command:
+  --doc, -d     Output pretty-printed JS Document objects.
+  --single, -1  Require the input to consist of a single YAML document.
+  --strict, -s  Stop on errors.
+  --visit, -v   Apply a visitor to each document (requires a path to import)
+  --yaml 1.1    Set the YAML version. (default: 1.2)
+</pre>

docs/index.html.md

@@ -15,7 +15,8 @@ includes:
   - 06_custom_tags
   - 07_parsing_yaml
   - 08_errors
-  - 09_yaml_syntax
+  - 09_cli
+  - 10_yaml_syntax
 
 search: true
 ---

docs/prepare-docs.mjs

@@ -1,12 +1,30 @@
 #!/usr/bin/env node
 
-import { lstat, mkdir, readdir, readFile, symlink, rm } from 'node:fs/promises'
+import {
+  lstat,
+  mkdir,
+  readdir,
+  readFile,
+  symlink,
+  rm,
+  writeFile
+} from 'node:fs/promises'
 import { resolve } from 'node:path'
+import { help } from '../dist/cli.mjs'
 import { parseAllDocuments } from '../dist/index.js'
 
 const source = 'docs'
 const target = 'docs-slate/source'
 
+// Update CLI help
+const cli = resolve(source, '09_cli.md')
+const docs = await readFile(cli, 'utf-8')
+const update = docs.replace(
+  /(<pre id="cli-help".*?>).*?(<\/pre>)/s,
+  '$1\n' + help + '\n$2'
+)
+if (update !== docs) await writeFile(cli, update)
+
 // Create symlink for index.html.md
 const indexSource = resolve(source, 'index.html.md')
 const indexTarget = resolve(target, 'index.html.md')