clyops-doc 0.6.0 → 0.8.0

package/README.md

@@ -24,10 +24,47 @@ man -l mytool.1
 | `-V, --version` | Version shown in the header |
 | `-d, --date` | Date shown in the header, YYYY-MM-DD (default today, or `SOURCE_DATE_EPOCH` for reproducible builds) |
 | `--schema FILE` | Read the schema from a file instead of stdin |
+| `-r, --root DIR` | Document every tool in a directory (or dispatcher definition), with an index page (needs `--out-dir` or `--prefix`) |
+| `-o, --out-dir DIR` | Write page files into `DIR` (created if missing) instead of to stdout |
+| `-p, --prefix PREFIX` | Install man pages into `PREFIX/share/man/manN`, and warn if `man` won't find them |
+| `--split` | A page per command, git-style (needs `--out-dir` or `--prefix`) |
+| `-x, --execute` | Write the files; without it, `--out-dir` and `--prefix` only list them |
 
 Each option can also be set as `CLYOPS_DOC_<OPTION>`. Input that isn't a clyops schema (`"clyops": 1`)
 is rejected with exit status 1.
 
+## A page per command
+
+```sh
+mytool --help-json-schema | clyops-doc --split --out-dir man1            # lists the files
+mytool --help-json-schema | clyops-doc --split --out-dir man1 --execute  # writes them
+```
+
+`mytool.1` gets the program's own options and a list of the commands, and each runnable command gets
+its own page, `mytool-db-migrate.1`, with the options it inherits and the nearest declared effects,
+stdin, stdout and roles. They refer to each other under SEE ALSO, as links in Markdown and HTML
+(`.md`, `.html`). A program without commands is one page. Files that already say the same are left
+alone, so a rerun is a no-op. Because it can write files, clyops-doc declares the `idempotent` and
+`destructive` effects, although nothing is written without `--execute`.
+
+## A whole directory of tools
+
+```sh
+clyops-doc --root ~/mytool/scripts --name mytool --prefix ~/.local            # lists the pages
+clyops-doc --root ~/mytool/scripts --name mytool --prefix ~/.local --execute  # installs them
+man mytool-media-to-pcm
+```
+
+`--root` finds tools the way `clyops-dispatch`, `clyops-api` and `clyops-mcp` do (subdirectories
+become command words, `.clyops` files give descriptions and ignores, nested dispatchers are
+followed), asks each for `--help-json-schema`, and writes a page per tool, or with `--split` per
+command, plus an index page named after the dispatcher (`--name`, default the directory's name)
+that lists them all. Executables that aren't clyops tools, or that fail to give a schema, are
+skipped with a warning.
+
+`--prefix` writes into `PREFIX/share/man/man1` (`man8` with `--section 8`) and checks `manpath`
+(or `MANPATH`), saying how to add the directory when `man` won't look there.
+
 ## What goes where
 
 | Section | From the schema |
@@ -39,8 +76,10 @@ is rejected with exit status 1.
 | STREAMS | `stdin`, `stdout` and [roles](https://github.com/wankdanker/clyops/blob/main/spec/SPEC.md#14-roles-on-file-descriptors) with their types |
 | NOTES | effects, option relationships and required commands |
 | ENVIRONMENT | each option's variable, the precedence rule, `CLYOPS_FDS` when there are roles, `CLYOPS_SILENT`, `CLYOPS_MAX_WIDTH` and `NO_COLOR` |
+| FILES | the config file: the option and variable naming it, its default, the line format and prefixes |
 | EXIT STATUS | 0, 1, and the tool's own |
 | EXAMPLES | `epilog` |
+| SEE ALSO | with `--split`, the other pages |
 
 Man pages use the plain `man(7)` macros, which groff and mandoc both render; text is escaped so a
 line can't start a request and option dashes are `\-`, so they copy and paste. The HTML page is
@@ -49,10 +88,11 @@ self-contained, with every value escaped.
 ## As a library
 
 ```js
-import { document, buildDoc, renderMarkdown } from 'clyops-doc';
+import { buildDoc, document, pages, renderMarkdown } from 'clyops-doc';
 
 const page = document(schema, 'man', { name: 'mytool', version: '1.2.0' });
 const md = renderMarkdown(buildDoc(schema)); // or build the document once and render it several ways
+for (const { file, content } of pages(schema, 'man')) { /* mytool.1, mytool-db-migrate.1, ... */ }
 ```
 
 ESM only, Node 20+.

package/dist/cli.js

@@ -1,38 +1,150 @@
 #!/usr/bin/env node
 // clyops-doc: a clyops tool's --help-json-schema on stdin, as a man page, Markdown or HTML.
-import { Cli, die } from 'clyops';
-import { readFileSync } from 'node:fs';
-import { document } from './index.js';
-import { defaultDate } from './model.js';
+import { Cli, die, info, warn } from 'clyops';
+import { commands, discover, loadSchema } from 'clyops-tools';
+import { execFileSync } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { delimiter, join, resolve } from 'node:path';
+import { document, extension, pages } from './index.js';
+import { defaultDate, firstSentence, pageName, toolsetDoc } from './model.js';
+import { render } from './render.js';
 const cli = new Cli({ name: 'clyops-doc' });
 cli.setDescription('Render a clyops tool\'s --help-json-schema as documentation: a man page, Markdown or HTML. It reads the schema on stdin, so it works with any clyops tool, compiled ones included.');
-cli.setEpilog('Examples:\n  mytool --help-json-schema | clyops-doc > mytool.1\n  mytool --help-json-schema | clyops-doc --format markdown > mytool.md\n  clyops-doc --schema schema.json --name "mytool media to-pcm" --format html > to-pcm.html\n  clyops-doc --help-json-schema | clyops-doc | man -l -');
-cli.setEffects('read-only');
-cli.setStdin('The tool\'s --help-json-schema output (unless --schema is given)', 'application/json');
-cli.setStdout('The documentation, in the format --format names', 'text/plain');
+cli.setEpilog('Examples:\n  mytool --help-json-schema | clyops-doc > mytool.1\n  mytool --help-json-schema | clyops-doc --format markdown > mytool.md\n  clyops-doc --schema schema.json --name "mytool media to-pcm" --format html > to-pcm.html\n  clyops-doc --help-json-schema | clyops-doc | man -l -\n  mytool --help-json-schema | clyops-doc --split --out-dir man1 --execute\n  clyops-doc --root ~/mytool/scripts --name mytool --prefix ~/.local --execute');
+// It writes files only with --out-dir or --prefix and --execute, and then only its own pages.
+cli.setEffects('idempotent', 'destructive');
+cli.setStdin('The tool\'s --help-json-schema output (unless --schema or --root is given)', 'application/json');
+// One declared type per program: what it writes is text/troff, text/markdown or text/html by --format.
+cli.setStdout('The documentation as --format says: text/troff, text/markdown or text/html; with --out-dir or --prefix, the files written (or, without --execute, that would be), one per line', 'text/plain');
 cli.opt('CLYOPS_DOC_FORMAT', 'format', 'f', 'man', 'Output format', 'Output', 'choice:man,markdown,html');
-cli.opt('CLYOPS_DOC_NAME', 'name', 'n', 'optional', 'How the tool is run (default: the schema\'s name), e.g. "mytool media to-pcm"', 'Output');
+cli.opt('CLYOPS_DOC_NAME', 'name', 'n', 'optional', 'How the tool is run (default: the schema\'s name), e.g. "mytool media to-pcm"; with --root, the dispatcher\'s name (default: the directory\'s)', 'Output');
 cli.opt('CLYOPS_DOC_SECTION', 'section', 's', '1', 'Manual section for the man page header', 'Output', 'regex:^[1-9][a-z]*$');
 cli.opt('CLYOPS_DOC_VERSION', 'version', 'V', 'optional', 'Version shown in the header', 'Output');
 cli.opt('CLYOPS_DOC_DATE', 'date', 'd', 'optional', 'Date shown in the header (default: today, or SOURCE_DATE_EPOCH)', 'Output', 'date:YYYY-MM-DD');
 cli.opt('CLYOPS_DOC_SCHEMA', 'schema', '', 'optional', 'Read the schema from this file instead of stdin', 'Input', 'file:readable');
+cli.opt('CLYOPS_DOC_ROOT', 'root', 'r', 'optional', 'Document every tool in this directory (or dispatcher definition), found as clyops-dispatch, clyops-api and clyops-mcp find them, with an index page', 'Input', 'path');
+cli.opt('CLYOPS_DOC_OUT_DIR', 'out-dir', 'o', 'optional', 'Write page files into this directory (created if missing) instead of to stdout', 'Files', 'path');
+cli.opt('CLYOPS_DOC_PREFIX', 'prefix', 'p', 'optional', 'Install man pages into PREFIX/share/man/manSECTION and check that man finds them', 'Files', 'path');
+cli.opt('CLYOPS_DOC_SPLIT', 'split', '', 'flag', 'A page per command, git-style: mytool.1 lists them, mytool-db-migrate.1 documents one', 'Files');
+cli.opt('CLYOPS_DOC_EXECUTE', 'execute', 'x', 'flag', 'Write the files; without it, only list them', 'Files');
+cli.exclusive('schema', 'root');
+cli.exclusive('out-dir', 'prefix');
 const args = cli.run();
-let schema;
-try {
-    const text = readFileSync(args.CLYOPS_DOC_SCHEMA ?? 0, 'utf8');
-    schema = JSON.parse(text);
-}
-catch (err) {
-    die(1, 'Could not read the schema: %s', err.message);
+const format = args.CLYOPS_DOC_FORMAT;
+const opts = {
+    name: args.CLYOPS_DOC_NAME ?? undefined,
+    section: args.CLYOPS_DOC_SECTION,
+    version: args.CLYOPS_DOC_VERSION ?? undefined,
+    date: args.CLYOPS_DOC_DATE ?? defaultDate(),
+};
+const root = args.CLYOPS_DOC_ROOT;
+const prefix = args.CLYOPS_DOC_PREFIX;
+const split = args.CLYOPS_DOC_SPLIT;
+const execute = args.CLYOPS_DOC_EXECUTE;
+const manDir = prefix === null ? null : join(prefix, 'share', 'man');
+const outDir = args.CLYOPS_DOC_OUT_DIR ?? (manDir === null ? null : join(manDir, `man${opts.section}`));
+if (prefix !== null && format !== 'man')
+    die(1, '--prefix installs man pages; use --out-dir for --format %s', format);
+if (outDir === null) {
+    // Several pages, or writing them, need somewhere to go.
+    const needs = root !== null ? 'root' : split ? 'split' : execute ? 'execute' : null;
+    if (needs)
+        die(1, '--%s needs --out-dir or --prefix', needs);
 }
 try {
-    process.stdout.write(document(schema, args.CLYOPS_DOC_FORMAT, {
-        name: args.CLYOPS_DOC_NAME ?? undefined,
-        section: args.CLYOPS_DOC_SECTION,
-        version: args.CLYOPS_DOC_VERSION ?? undefined,
-        date: args.CLYOPS_DOC_DATE ?? defaultDate(),
-    }));
+    if (root !== null)
+        writePages(await toolsetPages(root));
+    else {
+        const schema = readSchema();
+        if (outDir === null)
+            process.stdout.write(document(schema, format, opts));
+        else
+            writePages(split ? pages(schema, format, opts) : [{ file: `${pageName(opts.name || schema.script)}.${extension(format, opts.section)}`, content: document(schema, format, opts) }]);
+    }
 }
 catch (err) {
     die(1, '%s', err.message);
 }
+function readSchema() {
+    try {
+        return JSON.parse(readFileSync(args.CLYOPS_DOC_SCHEMA ?? 0, 'utf8'));
+    }
+    catch (err) {
+        return die(1, 'Could not read the schema: %s', err.message);
+    }
+}
+// --root: a page (or, with --split, pages) per tool, and an index page named after the dispatcher.
+async function toolsetPages(dir) {
+    const group = discover(dir, { name: opts.name });
+    const ext = extension(format, opts.section);
+    const out = [];
+    const tools = [];
+    for (const cmd of commands(group)) {
+        if (cmd.kind !== 'tool') {
+            warn('Skipping %s: not a clyops tool', cmd.file);
+            continue;
+        }
+        let schema;
+        try {
+            schema = await loadSchema(cmd.file);
+        }
+        catch (err) {
+            warn('Skipping %s', err.message);
+            continue;
+        }
+        const name = [group.name, ...cmd.words].join(' ');
+        out.push(...(split
+            ? pages(schema, format, { ...opts, name })
+            : [{ file: `${pageName(name)}.${ext}`, content: document(schema, format, { ...opts, name, page: pageName(name) }) }]));
+        tools.push({ words: cmd.words, description: firstSentence(schema.description) });
+    }
+    if (!tools.length)
+        throw new Error(`no clyops tools in ${dir}`);
+    const all = [{ file: `${pageName(group.name)}.${ext}`, content: render(toolsetDoc(group.name, group.description, tools, opts), format) }, ...out];
+    const seen = new Set();
+    for (const p of all) {
+        if (seen.has(p.file))
+            throw new Error(`two pages would be named ${p.file}`);
+        seen.add(p.file);
+    }
+    return all;
+}
+// Each page into the directory, leaving files that already say the same alone.
+function writePages(all) {
+    const dir = outDir;
+    let replaced = 0;
+    let unchanged = 0;
+    if (execute)
+        mkdirSync(dir, { recursive: true });
+    for (const page of all) {
+        const path = join(dir, page.file);
+        const before = existsSync(path) ? readFileSync(path, 'utf8') : null;
+        if (before === page.content)
+            unchanged++;
+        else {
+            if (before !== null)
+                replaced++;
+            if (execute)
+                writeFileSync(path, page.content);
+        }
+        process.stdout.write(`${path}\n`);
+    }
+    const counts = `${all.length - unchanged} page(s)${replaced ? ` (replacing ${replaced})` : ''}${unchanged ? `; ${unchanged} already up to date` : ''}`;
+    info(execute ? `Wrote ${counts} in ${dir}.` : `Would write ${counts} in ${dir}; add --execute to write them.`);
+    if (manDir !== null)
+        checkManPath(manDir);
+}
+// --prefix: say so when man won't look in PREFIX/share/man.
+function checkManPath(dir) {
+    let paths = process.env.MANPATH ?? '';
+    try {
+        paths = execFileSync('manpath', [], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 5000 }).trim();
+    }
+    catch {
+        // No manpath(1): MANPATH is all there is to go on.
+    }
+    const want = resolve(dir);
+    if (!paths.split(delimiter).some((p) => p && resolve(p) === want)) {
+        warn('man won\'t find these pages: %s is not on its search path. Add it with: export MANPATH="%s%s$(manpath)"', want, want, delimiter);
+    }
+}

package/dist/index.d.ts

@@ -5,4 +5,19 @@ import { type DocOptions } from './model.js';
 import { type Format } from './render.js';
 /** A schema's documentation in `format` (default man). Throws for input that isn't a clyops schema. */
 export declare function document(schema: Schema, format?: Format, opts?: DocOptions): string;
+/** One file of a split document. */
+export interface Page {
+    /** File name, e.g. `mytool-db-migrate.1`, `mytool.md`. */
+    file: string;
+    /** The page in its format. */
+    content: string;
+}
+/** A page's file extension: the manual section for man, else the format's. */
+export declare function extension(format: Format, section?: string): string;
+/**
+ * The documentation as a page per runnable command, git-style: `mytool.1` lists the commands and
+ * each has its own, e.g. `mytool-db-migrate.1`, with what it inherits. A program without commands
+ * is one page. Throws for input that isn't a clyops schema, or for two commands with one page name.
+ */
+export declare function pages(schema: Schema, format?: Format, opts?: DocOptions): Page[];
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAE5B,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAY,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AACvD,OAAO,EAAU,KAAK,MAAM,EAAE,MAAM,aAAa,CAAC;AAElD,uGAAuG;AACvG,wBAAgB,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,GAAE,MAAc,EAAE,IAAI,GAAE,UAAe,GAAG,MAAM,CAE9F"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAE5B,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAA0C,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AACrF,OAAO,EAAU,KAAK,MAAM,EAAE,MAAM,aAAa,CAAC;AAElD,uGAAuG;AACvG,wBAAgB,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,GAAE,MAAc,EAAE,IAAI,GAAE,UAAe,GAAG,MAAM,CAE9F;AAED,oCAAoC;AACpC,MAAM,WAAW,IAAI;IACnB,0DAA0D;IAC1D,IAAI,EAAE,MAAM,CAAC;IACb,8BAA8B;IAC9B,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,8EAA8E;AAC9E,wBAAgB,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,SAAM,GAAG,MAAM,CAE/D;AAED;;;;GAIG;AACH,wBAAgB,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,GAAE,MAAc,EAAE,IAAI,GAAE,UAAe,GAAG,IAAI,EAAE,CAgB3F"}

package/dist/index.js

@@ -1,9 +1,37 @@
 // clyops-doc: documentation (man, Markdown, HTML) from a clyops tool's --help-json-schema.
 export * from './model.js';
 export * from './render.js';
-import { buildDoc } from './model.js';
+import { buildDoc, leafSchema, leaves, pageName } from './model.js';
 import { render } from './render.js';
 /** A schema's documentation in `format` (default man). Throws for input that isn't a clyops schema. */
 export function document(schema, format = 'man', opts = {}) {
     return render(buildDoc(schema, opts), format);
 }
+/** A page's file extension: the manual section for man, else the format's. */
+export function extension(format, section = '1') {
+    return format === 'man' ? section : format === 'markdown' ? 'md' : 'html';
+}
+/**
+ * The documentation as a page per runnable command, git-style: `mytool.1` lists the commands and
+ * each has its own, e.g. `mytool-db-migrate.1`, with what it inherits. A program without commands
+ * is one page. Throws for input that isn't a clyops schema, or for two commands with one page name.
+ */
+export function pages(schema, format = 'man', opts = {}) {
+    const name = opts.name || schema?.script || '';
+    const top = buildDoc(schema, { ...opts, split: true, page: pageName(name) });
+    const ext = extension(format, top.section);
+    const out = [{ file: `${top.page}.${ext}`, content: render(top, format) }];
+    const all = leaves(schema);
+    if (all.length === 1 && all[0].words.length === 0)
+        return out;
+    for (const leaf of all) {
+        const page = pageName(name, leaf.words);
+        const doc = buildDoc(leafSchema(schema, leaf), { ...opts, split: false, name: [name, ...leaf.words].join(' '), page });
+        doc.sections.push({ title: 'SEE ALSO', blocks: [{ kind: 'refs', items: [{ page: pageName(name), section: top.section }] }] });
+        const file = `${page}.${ext}`;
+        if (out.some((p) => p.file === file))
+            throw new Error(`two pages would be named ${file}`);
+        out.push({ file, content: render(doc, format) });
+    }
+    return out;
+}

package/dist/model.d.ts

@@ -15,6 +15,12 @@ export type Block = {
 } | {
     kind: 'h';
     text: string;
+} | {
+    kind: 'refs';
+    items: {
+        page: string;
+        section: string;
+    }[];
 };
 /** A top-level section, e.g. OPTIONS. */
 export interface Section {
@@ -27,6 +33,8 @@ export interface Section {
 export interface Doc {
     /** How the program is run, e.g. `mytool` or `mytool media to-pcm`. */
     name: string;
+    /** The page's name in the header and NAME line: `name`, or a split page's, e.g. `mytool-db-migrate`. */
+    page: string;
     /** Manual section, e.g. `1`. */
     section: string;
     /** Version shown in the header, or empty. */
@@ -48,6 +56,10 @@ export interface DocOptions {
     version?: string;
     /** Date for the header, YYYY-MM-DD (default: today). */
     date?: string;
+    /** The page's name (default: `name`); see `Doc.page`. */
+    page?: string;
+    /** Commands get pages of their own (see `pages`): list them, with a SEE ALSO, instead of documenting each. */
+    split?: boolean;
 }
 /** A runnable level: a program without commands, or a leaf command, with what it inherits. */
 export interface Leaf {
@@ -55,6 +67,8 @@ export interface Leaf {
     words: string[];
     /** The level's own description. */
     description: string;
+    /** Text after its help, e.g. examples. */
+    epilog: string;
     /** Positional arguments. */
     arguments: SchemaArgument[];
     /** Its own options, then those it inherits, nearest first. */
@@ -96,4 +110,20 @@ export declare function defaultDate(env?: NodeJS.ProcessEnv): string;
  * description, options and arguments).
  */
 export declare function buildDoc(schema: Schema, opts?: DocOptions): Doc;
+/** A page's name: the invocation's words joined by hyphens, e.g. `mytool-db-migrate`. */
+export declare function pageName(name: string, words?: string[]): string;
+/** A runnable command as a program of its own, with everything it inherits, for a page of its own. */
+export declare function leafSchema(schema: Schema, leaf: Leaf): Schema;
+/** One tool of a toolset, for its index page (see `toolsetDoc`). */
+export interface ToolEntry {
+    /** The words after the toolset's name, e.g. ['media', 'to-pcm']. */
+    words: string[];
+    /** The tool's description. */
+    description: string;
+}
+/**
+ * The index page of a directory of tools (`--root`): what the dispatcher `name` runs, each tool with
+ * a reference to its own page.
+ */
+export declare function toolsetDoc(name: string, description: string, tools: ToolEntry[], opts?: DocOptions): Doc;
 //# sourceMappingURL=model.d.ts.map

package/dist/model.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"model.d.ts","sourceRoot":"","sources":["../src/model.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"model.d.ts","sourceRoot":"","sources":["../src/model.ts"],"names":[],"mappings":"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"}

package/dist/model.js

@@ -26,6 +26,7 @@ export function leaves(schema) {
         out.push({
             words,
             description: node.description,
+            epilog: node.epilog,
             arguments: node.arguments,
             options: [...chain].reverse().flatMap((s) => s.options),
             effects: nearest((s) => s.effects, (v) => v.length === 0) ?? [],
@@ -59,7 +60,7 @@ export function optionText(o) {
     if (o.isArray)
         notes.push('repeatable');
     if (o.secret)
-        notes.push('secret: prefer the environment');
+        notes.push('secret: set it in the environment, never on the command line');
     if (o.default && !o.isFlag)
         notes.push(`default: ${o.default}`);
     if (o.validation)
@@ -100,7 +101,9 @@ function leafParts(leaf) {
         ...leaf.roles.map((r) => ({ term: `${r.direction === 'in' ? 'input' : 'output'} role ${r.name}`, text: stream(r) })),
     ];
     const notes = [
-        ...(leaf.effects.length ? [`Effects: ${leaf.effects.map((e) => `${e} (${EFFECTS[e] ?? e})`).join(', ')}.`] : []),
+        leaf.effects.length
+            ? `Effects: ${leaf.effects.map((e) => `${e} (${EFFECTS[e] ?? e})`).join(', ')}.`
+            : 'Effects: not declared, so treat it as possibly destructive.',
         ...leaf.constraints.map((c) => CONSTRAINT[c.type]?.(c.options) ?? ''),
         ...leaf.requiredCommands.map((r) => `Needs ${r.command} on PATH: ${r.description}${r.installHint ? ` (${r.installHint})` : ''}.`),
     ].filter(Boolean);
@@ -136,7 +139,8 @@ export function buildDoc(schema, opts = {}) {
     const program = all.length === 1 && all[0].words.length === 0;
     const summary = firstSentence(schema.description || '');
     const sections = [];
-    sections.push({ title: 'NAME', blocks: [{ kind: 'p', text: summary ? `${name} - ${summary}` : name }] });
+    const page = opts.page || name;
+    sections.push({ title: 'NAME', blocks: [{ kind: 'p', text: summary ? `${page} - ${summary}` : page }] });
     sections.push({ title: 'SYNOPSIS', blocks: [{ kind: 'pre', text: all.map((l) => synopsis(name, l)).join('\n') }] });
     if (schema.description)
         sections.push({ title: 'DESCRIPTION', blocks: schema.description.split(/\n{2,}/).map((text) => ({ kind: 'p', text })) });
@@ -151,6 +155,16 @@ export function buildDoc(schema, opts = {}) {
         if (notes.length)
             sections.push({ title: 'NOTES', blocks: notes });
     }
+    else if (opts.split) {
+        // The commands have pages of their own: the program's options here, and a list of the commands.
+        const own = schema.options.filter((o) => o.name !== 'help').map((o) => ({ term: optionLabel(o), text: optionText(o) }));
+        if (own.length)
+            sections.push({ title: 'OPTIONS', blocks: [{ kind: 'p', text: 'Accepted by every command.' }, { kind: 'dl', items: own }] });
+        sections.push({
+            title: 'COMMANDS',
+            blocks: [{ kind: 'dl', items: all.map((l) => ({ term: [name, ...l.words].join(' '), text: `${sentence(l.description)}See ${pageName(name, l.words)}(${opts.section || '1'}).` })) }],
+        });
+    }
     else {
         // One subsection per runnable command, with what it inherits.
         const blocks = [];
@@ -170,15 +184,17 @@ export function buildDoc(schema, opts = {}) {
     }
     // Every option's variable, once, in the order first seen.
     const env = new Map();
-    for (const leaf of all)
+    for (const leaf of opts.split && !program ? [{ options: schema.options }] : all)
         for (const o of leaf.options)
             if (o.name !== 'help' && !env.has(o.variableName))
                 env.set(o.variableName, `Sets --${o.name}.${o.secret ? ' A secret: set it here rather than on the command line.' : ''}`);
-    const anyRoles = all.some((l) => l.roles.length);
+    const anyRoles = opts.split && !program ? Boolean(schema.roles?.length) : all.some((l) => l.roles.length);
     sections.push({
         title: 'ENVIRONMENT',
         blocks: [
-            { kind: 'p', text: 'An option given on the command line takes precedence over the config file, which takes precedence over the environment, which takes precedence over the default.' },
+            { kind: 'p', text: schema.config
+                    ? 'An option given on the command line takes precedence over the config file, which takes precedence over the environment, which takes precedence over the default.'
+                    : 'An option given on the command line takes precedence over the environment, which takes precedence over the default.' },
             {
                 kind: 'dl',
                 items: [
@@ -191,6 +207,8 @@ export function buildDoc(schema, opts = {}) {
             },
         ],
     });
+    if (schema.config)
+        sections.push({ title: 'FILES', blocks: files(schema.config, schema.options) });
     sections.push({
         title: 'EXIT STATUS',
         blocks: [{
@@ -204,5 +222,59 @@ export function buildDoc(schema, opts = {}) {
     });
     if (schema.epilog)
         sections.push({ title: 'EXAMPLES', blocks: [{ kind: 'pre', text: schema.epilog.replace(/\n+$/, '') }] });
-    return { name, section: opts.section || '1', version: opts.version || '', date: opts.date || defaultDate(), summary, sections };
+    if (opts.split && !program)
+        sections.push({ title: 'SEE ALSO', blocks: [{ kind: 'refs', items: all.map((l) => ({ page: pageName(name, l.words), section: opts.section || '1' })) }] });
+    return { name, page, section: opts.section || '1', version: opts.version || '', date: opts.date || defaultDate(), summary, sections };
+}
+// The config file (spec section 4): where it comes from and what a line looks like.
+function files(config, options) {
+    const opt = options.find((o) => o.name === config.option);
+    const from = [`--${config.option}`, ...(opt?.variableName ? [opt.variableName] : [])].join(' or ');
+    const where = opt?.default ? `, ${opt.default} by default` : '';
+    const prefixes = config.prefixes.length ? `, on lines starting with ${config.prefixes.join(' or ')}` : '';
+    const example = options.find((o) => o.name !== config.option && o.name !== 'help' && !o.isFlag) ?? options.find((o) => o.name !== config.option && o.name !== 'help');
+    return [
+        { kind: 'p', text: `The config file is the one named by ${from}${where}, resolved against the current directory. An empty value or disabled skips it; a file that doesn't exist is an error.` },
+        { kind: 'p', text: `It sets options with one key=value per line${prefixes}. The key is an option's long name, with or without the leading --. Blank lines and lines starting with # are ignored, and @include PATH reads another file in place, relative to the one including it. Later lines override earlier ones, and an option given on the command line wins over the file.` },
+        ...(example ? [{ kind: 'pre', text: `${config.prefixes[0] ?? ''}${example.name}=${example.isFlag ? 'true' : example.default || 'VALUE'}` }] : []),
+    ];
+}
+// Text as a sentence followed by a space, ending in a full stop unless it has its own; nothing for none.
+function sentence(text) {
+    return text ? `${text}${/[.!?]$/.test(text) ? '' : '.'} ` : '';
+}
+/** A page's name: the invocation's words joined by hyphens, e.g. `mytool-db-migrate`. */
+export function pageName(name, words = []) {
+    return [name, ...words].join(' ').trim().split(/\s+/).join('-');
+}
+/** A runnable command as a program of its own, with everything it inherits, for a page of its own. */
+export function leafSchema(schema, leaf) {
+    return {
+        clyops: 1, script: schema.script, description: leaf.description, epilog: leaf.epilog,
+        arguments: leaf.arguments, options: leaf.options, config: schema.config ?? null,
+        requiredCommands: leaf.requiredCommands, effects: leaf.effects,
+        constraints: leaf.constraints, stdin: leaf.stdin, stdout: leaf.stdout,
+        roles: leaf.roles, commands: [],
+    };
+}
+/**
+ * The index page of a directory of tools (`--root`): what the dispatcher `name` runs, each tool with
+ * a reference to its own page.
+ */
+export function toolsetDoc(name, description, tools, opts = {}) {
+    const section = opts.section || '1';
+    const page = opts.page || pageName(name);
+    const summary = firstSentence(description);
+    const sections = [
+        { title: 'NAME', blocks: [{ kind: 'p', text: summary ? `${page} - ${summary}` : page }] },
+        { title: 'SYNOPSIS', blocks: [{ kind: 'pre', text: tools.map((t) => `${[name, ...t.words].join(' ')} [ARGUMENTS] [OPTIONS]`).join('\n') }] },
+    ];
+    if (description)
+        sections.push({ title: 'DESCRIPTION', blocks: description.split(/\n{2,}/).map((text) => ({ kind: 'p', text })) });
+    sections.push({
+        title: 'TOOLS',
+        blocks: [{ kind: 'dl', items: tools.map((t) => ({ term: [name, ...t.words].join(' '), text: `${sentence(firstSentence(t.description))}See ${pageName(name, t.words)}(${section}).` })) }],
+    });
+    sections.push({ title: 'SEE ALSO', blocks: [{ kind: 'refs', items: tools.map((t) => ({ page: pageName(name, t.words), section })) }] });
+    return { name, page, section, version: opts.version || '', date: opts.date || defaultDate(), summary, sections };
 }

package/dist/render.d.ts

@@ -10,6 +10,8 @@ export declare function renderMan(doc: Doc): string;
  * else, so the Markdown stays readable (`DRY_RUN`, `(default: 1)`).
  */
 export declare function markdownText(text: string): string;
+/** The first line of a Markdown page: a comment, invisible when rendered, saying it is generated. */
+export declare const MARKDOWN_MARKER = "<!-- Generated by clyops-doc from --help-json-schema. Do not edit; regenerate instead. -->";
 /** The document as Markdown. */
 export declare function renderMarkdown(doc: Doc): string;
 /** Text with HTML's special characters escaped. */

package/dist/render.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../src/render.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAS,GAAG,EAAE,MAAM,YAAY,CAAC;AAE7C,sBAAsB;AACtB,MAAM,MAAM,MAAM,GAAG,KAAK,GAAG,UAAU,GAAG,MAAM,CAAC;AAMjD,gGAAgG;AAChG,wBAAgB,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAQ1C;AAoBD,qCAAqC;AACrC,wBAAgB,SAAS,CAAC,GAAG,EAAE,GAAG,GAAG,MAAM,CAgB1C;AAMD;;;GAGG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAWjD;AA4BD,gCAAgC;AAChC,wBAAgB,cAAc,CAAC,GAAG,EAAE,GAAG,GAAG,MAAM,CAS/C;AAMD,mDAAmD;AACnD,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE7C;AAyBD,8CAA8C;AAC9C,wBAAgB,UAAU,CAAC,GAAG,EAAE,GAAG,GAAG,MAAM,CAsB3C;AAED,gCAAgC;AAChC,wBAAgB,MAAM,CAAC,GAAG,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAEvD"}
+{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../src/render.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAS,GAAG,EAAE,MAAM,YAAY,CAAC;AAE7C,sBAAsB;AACtB,MAAM,MAAM,MAAM,GAAG,KAAK,GAAG,UAAU,GAAG,MAAM,CAAC;AAMjD,gGAAgG;AAChG,wBAAgB,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAQ1C;AAsBD,qCAAqC;AACrC,wBAAgB,SAAS,CAAC,GAAG,EAAE,GAAG,GAAG,MAAM,CAgB1C;AAMD;;;GAGG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAWjD;AA8BD,qGAAqG;AACrG,eAAO,MAAM,eAAe,+FAA+F,CAAC;AAE5H,gCAAgC;AAChC,wBAAgB,cAAc,CAAC,GAAG,EAAE,GAAG,GAAG,MAAM,CAS/C;AAMD,mDAAmD;AACnD,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE7C;AA2BD,8CAA8C;AAC9C,wBAAgB,UAAU,CAAC,GAAG,EAAE,GAAG,GAAG,MAAM,CAsB3C;AAED,gCAAgC;AAChC,wBAAgB,MAAM,CAAC,GAAG,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAEvD"}

package/dist/render.js

@@ -25,11 +25,13 @@ function manBlock(b) {
             return ['.PP', '.nf', '.RS 4', troff(b.text), '.RE', '.fi'];
         case 'dl':
             return b.items.flatMap((i) => ['.TP', `\\fB${troff(i.term)}\\fR`, troff(i.text)]);
+        case 'refs':
+            return ['.PP', ...b.items.map((r, n) => `.BR ${arg(r.page)} ${arg(`(${r.section})${n < b.items.length - 1 ? ',' : ''}`)}`)];
     }
 }
 /** The document as a man(7) page. */
 export function renderMan(doc) {
-    const title = doc.name.toUpperCase().replace(/\s+/g, '-');
+    const title = doc.page.toUpperCase().replace(/\s+/g, '-');
     const lines = [
         `.\\" Generated by clyops-doc from ${doc.name} --help-json-schema.`,
         `.TH ${arg(title)} ${arg(doc.section)} ${arg(doc.date)} ${arg([doc.name, doc.version].filter(Boolean).join(' '))} ${arg('User Commands')}`,
@@ -38,7 +40,7 @@ export function renderMan(doc) {
         lines.push(`.SH ${arg(s.title)}`);
         // NAME is one line, "name \- summary", without a paragraph macro (man(7)).
         if (s.title === 'NAME') {
-            lines.push(troff(`${doc.name}${doc.summary ? ` - ${doc.summary}` : ''}`));
+            lines.push(troff(`${doc.page}${doc.summary ? ` - ${doc.summary}` : ''}`));
             continue;
         }
         for (const b of s.blocks)
@@ -85,11 +87,15 @@ function markdownBlock(b) {
             return [...fenced(b.text), ''];
         case 'dl':
             return [...b.items.map((i) => `- ${code(i.term)}: ${markdownText(i.text)}`), ''];
+        case 'refs':
+            return [b.items.map((r) => `[${markdownText(`${r.page}(${r.section})`)}](${encodeURI(r.page)}.md)`).join(', '), ''];
     }
 }
+/** The first line of a Markdown page: a comment, invisible when rendered, saying it is generated. */
+export const MARKDOWN_MARKER = '<!-- Generated by clyops-doc from --help-json-schema. Do not edit; regenerate instead. -->';
 /** The document as Markdown. */
 export function renderMarkdown(doc) {
-    const lines = [`# ${code(doc.name)}`, ''];
+    const lines = [MARKDOWN_MARKER, '', `# ${code(doc.name)}`, ''];
     const header = [doc.version && `Version ${doc.version}`, doc.date].filter(Boolean).join(' · ');
     if (header)
         lines.push(`_${markdownText(header)}_`, '');
@@ -118,6 +124,8 @@ function htmlBlock(b) {
             return `<pre><code>${htmlText(b.text)}</code></pre>`;
         case 'dl':
             return `<dl>\n${b.items.map((i) => `<dt><code>${htmlText(i.term)}</code></dt>\n<dd>${htmlText(i.text)}</dd>`).join('\n')}\n</dl>`;
+        case 'refs':
+            return `<p>${b.items.map((r) => `<a href="${htmlText(encodeURI(r.page))}.html"><code>${htmlText(r.page)}</code>(${htmlText(r.section)})</a>`).join(', ')}</p>`;
     }
 }
 const STYLE = `body{font:16px/1.55 system-ui,sans-serif;max-width:46rem;margin:2rem auto;padding:0 1rem;color:#1d1f21;background:#fff}
@@ -139,7 +147,7 @@ export function renderHtml(doc) {
 <meta charset="utf-8">
 <meta name="viewport" content="width=device-width, initial-scale=1">
 <meta name="generator" content="clyops-doc">
-<title>${htmlText(doc.name)}(${htmlText(doc.section)})</title>
+<title>${htmlText(doc.page)}(${htmlText(doc.section)})</title>
 <style>${STYLE}</style>
 </head>
 <body>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clyops-doc",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "Documentation (man pages, Markdown, HTML) from any clyops tool's --help-json-schema.",
   "license": "MIT",
   "repository": {
@@ -36,8 +36,9 @@
     "src"
   ],
   "dependencies": {
-    "clyops": "0.6.0",
-    "clyops-schema": "0.6.0"
+    "clyops": "0.8.0",
+    "clyops-schema": "0.8.0",
+    "clyops-tools": "0.8.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",

package/src/cli.ts

@@ -1,40 +1,142 @@
 #!/usr/bin/env node
 // clyops-doc: a clyops tool's --help-json-schema on stdin, as a man page, Markdown or HTML.
-import { Cli, die } from 'clyops';
-import { readFileSync } from 'node:fs';
+import { Cli, die, info, warn } from 'clyops';
+import { commands, discover, loadSchema } from 'clyops-tools';
+import { execFileSync } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { delimiter, join, resolve } from 'node:path';
 import type { Schema } from 'clyops-schema';
-import { document } from './index.js';
-import { defaultDate } from './model.js';
-import type { Format } from './render.js';
+import { document, extension, pages, type Page } from './index.js';
+import { defaultDate, firstSentence, pageName, toolsetDoc, type ToolEntry } from './model.js';
+import { render, type Format } from './render.js';
 
 const cli = new Cli({ name: 'clyops-doc' });
 cli.setDescription('Render a clyops tool\'s --help-json-schema as documentation: a man page, Markdown or HTML. It reads the schema on stdin, so it works with any clyops tool, compiled ones included.');
-cli.setEpilog('Examples:\n  mytool --help-json-schema | clyops-doc > mytool.1\n  mytool --help-json-schema | clyops-doc --format markdown > mytool.md\n  clyops-doc --schema schema.json --name "mytool media to-pcm" --format html > to-pcm.html\n  clyops-doc --help-json-schema | clyops-doc | man -l -');
-cli.setEffects('read-only');
-cli.setStdin('The tool\'s --help-json-schema output (unless --schema is given)', 'application/json');
-cli.setStdout('The documentation, in the format --format names', 'text/plain');
+cli.setEpilog('Examples:\n  mytool --help-json-schema | clyops-doc > mytool.1\n  mytool --help-json-schema | clyops-doc --format markdown > mytool.md\n  clyops-doc --schema schema.json --name "mytool media to-pcm" --format html > to-pcm.html\n  clyops-doc --help-json-schema | clyops-doc | man -l -\n  mytool --help-json-schema | clyops-doc --split --out-dir man1 --execute\n  clyops-doc --root ~/mytool/scripts --name mytool --prefix ~/.local --execute');
+// It writes files only with --out-dir or --prefix and --execute, and then only its own pages.
+cli.setEffects('idempotent', 'destructive');
+cli.setStdin('The tool\'s --help-json-schema output (unless --schema or --root is given)', 'application/json');
+// One declared type per program: what it writes is text/troff, text/markdown or text/html by --format.
+cli.setStdout('The documentation as --format says: text/troff, text/markdown or text/html; with --out-dir or --prefix, the files written (or, without --execute, that would be), one per line', 'text/plain');
 cli.opt('CLYOPS_DOC_FORMAT',  'format',  'f', 'man',      'Output format',                                                  'Output', 'choice:man,markdown,html');
-cli.opt('CLYOPS_DOC_NAME',    'name',    'n', 'optional', 'How the tool is run (default: the schema\'s name), e.g. "mytool media to-pcm"', 'Output');
+cli.opt('CLYOPS_DOC_NAME',    'name',    'n', 'optional', 'How the tool is run (default: the schema\'s name), e.g. "mytool media to-pcm"; with --root, the dispatcher\'s name (default: the directory\'s)', 'Output');
 cli.opt('CLYOPS_DOC_SECTION', 'section', 's', '1',        'Manual section for the man page header',                         'Output', 'regex:^[1-9][a-z]*$');
 cli.opt('CLYOPS_DOC_VERSION', 'version', 'V', 'optional', 'Version shown in the header',                                    'Output');
 cli.opt('CLYOPS_DOC_DATE',    'date',    'd', 'optional', 'Date shown in the header (default: today, or SOURCE_DATE_EPOCH)', 'Output', 'date:YYYY-MM-DD');
 cli.opt('CLYOPS_DOC_SCHEMA',  'schema',  '',  'optional', 'Read the schema from this file instead of stdin',               'Input',  'file:readable');
+cli.opt('CLYOPS_DOC_ROOT',    'root',    'r', 'optional', 'Document every tool in this directory (or dispatcher definition), found as clyops-dispatch, clyops-api and clyops-mcp find them, with an index page', 'Input', 'path');
+cli.opt('CLYOPS_DOC_OUT_DIR', 'out-dir', 'o', 'optional', 'Write page files into this directory (created if missing) instead of to stdout', 'Files', 'path');
+cli.opt('CLYOPS_DOC_PREFIX',  'prefix',  'p', 'optional', 'Install man pages into PREFIX/share/man/manSECTION and check that man finds them', 'Files', 'path');
+cli.opt('CLYOPS_DOC_SPLIT',   'split',   '',  'flag',     'A page per command, git-style: mytool.1 lists them, mytool-db-migrate.1 documents one', 'Files');
+cli.opt('CLYOPS_DOC_EXECUTE', 'execute', 'x', 'flag',     'Write the files; without it, only list them',                    'Files');
+cli.exclusive('schema', 'root');
+cli.exclusive('out-dir', 'prefix');
 const args = cli.run();
 
-let schema: Schema;
-try {
-  const text = readFileSync((args.CLYOPS_DOC_SCHEMA as string | null) ?? 0, 'utf8');
-  schema = JSON.parse(text) as Schema;
-} catch (err) {
-  die(1, 'Could not read the schema: %s', (err as Error).message);
+const format = args.CLYOPS_DOC_FORMAT as Format;
+const opts = {
+  name: (args.CLYOPS_DOC_NAME as string | null) ?? undefined,
+  section: args.CLYOPS_DOC_SECTION as string,
+  version: (args.CLYOPS_DOC_VERSION as string | null) ?? undefined,
+  date: (args.CLYOPS_DOC_DATE as string | null) ?? defaultDate(),
+};
+const root = args.CLYOPS_DOC_ROOT as string | null;
+const prefix = args.CLYOPS_DOC_PREFIX as string | null;
+const split = args.CLYOPS_DOC_SPLIT as boolean;
+const execute = args.CLYOPS_DOC_EXECUTE as boolean;
+const manDir = prefix === null ? null : join(prefix, 'share', 'man');
+const outDir = (args.CLYOPS_DOC_OUT_DIR as string | null) ?? (manDir === null ? null : join(manDir, `man${opts.section}`));
+if (prefix !== null && format !== 'man') die(1, '--prefix installs man pages; use --out-dir for --format %s', format);
+if (outDir === null) {
+  // Several pages, or writing them, need somewhere to go.
+  const needs = root !== null ? 'root' : split ? 'split' : execute ? 'execute' : null;
+  if (needs) die(1, '--%s needs --out-dir or --prefix', needs);
 }
+
 try {
-  process.stdout.write(document(schema, args.CLYOPS_DOC_FORMAT as Format, {
-    name: (args.CLYOPS_DOC_NAME as string | null) ?? undefined,
-    section: args.CLYOPS_DOC_SECTION as string,
-    version: (args.CLYOPS_DOC_VERSION as string | null) ?? undefined,
-    date: (args.CLYOPS_DOC_DATE as string | null) ?? defaultDate(),
-  }));
+  if (root !== null) writePages(await toolsetPages(root));
+  else {
+    const schema = readSchema();
+    if (outDir === null) process.stdout.write(document(schema, format, opts));
+    else writePages(split ? pages(schema, format, opts) : [{ file: `${pageName(opts.name || schema.script)}.${extension(format, opts.section)}`, content: document(schema, format, opts) }]);
+  }
 } catch (err) {
   die(1, '%s', (err as Error).message);
 }
+
+function readSchema(): Schema {
+  try {
+    return JSON.parse(readFileSync((args.CLYOPS_DOC_SCHEMA as string | null) ?? 0, 'utf8')) as Schema;
+  } catch (err) {
+    return die(1, 'Could not read the schema: %s', (err as Error).message);
+  }
+}
+
+// --root: a page (or, with --split, pages) per tool, and an index page named after the dispatcher.
+async function toolsetPages(dir: string): Promise<Page[]> {
+  const group = discover(dir, { name: opts.name });
+  const ext = extension(format, opts.section);
+  const out: Page[] = [];
+  const tools: ToolEntry[] = [];
+  for (const cmd of commands(group)) {
+    if (cmd.kind !== 'tool') {
+      warn('Skipping %s: not a clyops tool', cmd.file);
+      continue;
+    }
+    let schema: Schema;
+    try {
+      schema = await loadSchema(cmd.file);
+    } catch (err) {
+      warn('Skipping %s', (err as Error).message);
+      continue;
+    }
+    const name = [group.name, ...cmd.words].join(' ');
+    out.push(...(split
+      ? pages(schema, format, { ...opts, name })
+      : [{ file: `${pageName(name)}.${ext}`, content: document(schema, format, { ...opts, name, page: pageName(name) }) }]));
+    tools.push({ words: cmd.words, description: firstSentence(schema.description) });
+  }
+  if (!tools.length) throw new Error(`no clyops tools in ${dir}`);
+  const all = [{ file: `${pageName(group.name)}.${ext}`, content: render(toolsetDoc(group.name, group.description, tools, opts), format) }, ...out];
+  const seen = new Set<string>();
+  for (const p of all) {
+    if (seen.has(p.file)) throw new Error(`two pages would be named ${p.file}`);
+    seen.add(p.file);
+  }
+  return all;
+}
+
+// Each page into the directory, leaving files that already say the same alone.
+function writePages(all: Page[]): void {
+  const dir = outDir as string;
+  let replaced = 0;
+  let unchanged = 0;
+  if (execute) mkdirSync(dir, { recursive: true });
+  for (const page of all) {
+    const path = join(dir, page.file);
+    const before = existsSync(path) ? readFileSync(path, 'utf8') : null;
+    if (before === page.content) unchanged++;
+    else {
+      if (before !== null) replaced++;
+      if (execute) writeFileSync(path, page.content);
+    }
+    process.stdout.write(`${path}\n`);
+  }
+  const counts = `${all.length - unchanged} page(s)${replaced ? ` (replacing ${replaced})` : ''}${unchanged ? `; ${unchanged} already up to date` : ''}`;
+  info(execute ? `Wrote ${counts} in ${dir}.` : `Would write ${counts} in ${dir}; add --execute to write them.`);
+  if (manDir !== null) checkManPath(manDir);
+}
+
+// --prefix: say so when man won't look in PREFIX/share/man.
+function checkManPath(dir: string): void {
+  let paths = process.env.MANPATH ?? '';
+  try {
+    paths = execFileSync('manpath', [], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 5000 }).trim();
+  } catch {
+    // No manpath(1): MANPATH is all there is to go on.
+  }
+  const want = resolve(dir);
+  if (!paths.split(delimiter).some((p) => p && resolve(p) === want)) {
+    warn('man won\'t find these pages: %s is not on its search path. Add it with: export MANPATH="%s%s$(manpath)"', want, want, delimiter);
+  }
+}

package/src/index.ts

@@ -3,10 +3,46 @@ export * from './model.js';
 export * from './render.js';
 
 import type { Schema } from 'clyops-schema';
-import { buildDoc, type DocOptions } from './model.js';
+import { buildDoc, leafSchema, leaves, pageName, type DocOptions } from './model.js';
 import { render, type Format } from './render.js';
 
 /** A schema's documentation in `format` (default man). Throws for input that isn't a clyops schema. */
 export function document(schema: Schema, format: Format = 'man', opts: DocOptions = {}): string {
   return render(buildDoc(schema, opts), format);
 }
+
+/** One file of a split document. */
+export interface Page {
+  /** File name, e.g. `mytool-db-migrate.1`, `mytool.md`. */
+  file: string;
+  /** The page in its format. */
+  content: string;
+}
+
+/** A page's file extension: the manual section for man, else the format's. */
+export function extension(format: Format, section = '1'): string {
+  return format === 'man' ? section : format === 'markdown' ? 'md' : 'html';
+}
+
+/**
+ * The documentation as a page per runnable command, git-style: `mytool.1` lists the commands and
+ * each has its own, e.g. `mytool-db-migrate.1`, with what it inherits. A program without commands
+ * is one page. Throws for input that isn't a clyops schema, or for two commands with one page name.
+ */
+export function pages(schema: Schema, format: Format = 'man', opts: DocOptions = {}): Page[] {
+  const name = opts.name || (schema as Schema | null)?.script || '';
+  const top = buildDoc(schema, { ...opts, split: true, page: pageName(name) });
+  const ext = extension(format, top.section);
+  const out: Page[] = [{ file: `${top.page}.${ext}`, content: render(top, format) }];
+  const all = leaves(schema);
+  if (all.length === 1 && all[0].words.length === 0) return out;
+  for (const leaf of all) {
+    const page = pageName(name, leaf.words);
+    const doc = buildDoc(leafSchema(schema, leaf), { ...opts, split: false, name: [name, ...leaf.words].join(' '), page });
+    doc.sections.push({ title: 'SEE ALSO', blocks: [{ kind: 'refs', items: [{ page: pageName(name), section: top.section }] }] });
+    const file = `${page}.${ext}`;
+    if (out.some((p) => p.file === file)) throw new Error(`two pages would be named ${file}`);
+    out.push({ file, content: render(doc, format) });
+  }
+  return out;
+}

package/src/model.ts

@@ -1,14 +1,15 @@
 // A clyops schema (spec section 8) as a small document: sections of paragraphs, definition lists
 // and preformatted text, which each output format renders.
 import { describeRule } from 'clyops';
-import type { Schema, SchemaArgument, SchemaBody, SchemaOption, SchemaRole, SchemaStream } from 'clyops-schema';
+import type { Schema, SchemaArgument, SchemaBody, SchemaConfig, SchemaOption, SchemaRole, SchemaStream } from 'clyops-schema';
 
 /** One piece of a section. Terms are option names, commands and the like: code in every format. */
 export type Block =
   | { /** A paragraph of plain text. */ kind: 'p'; text: string }
   | { /** Text shown as is, in a fixed-width font. */ kind: 'pre'; text: string }
   | { /** A list of terms, each with its description. */ kind: 'dl'; items: { term: string; text: string }[] }
-  | { /** A subsection heading, e.g. one per command. */ kind: 'h'; text: string };
+  | { /** A subsection heading, e.g. one per command. */ kind: 'h'; text: string }
+  | { /** Other pages, as SEE ALSO lists them: `page(section)`, linked in Markdown and HTML. */ kind: 'refs'; items: { page: string; section: string }[] };
 
 /** A top-level section, e.g. OPTIONS. */
 export interface Section {
@@ -22,6 +23,8 @@ export interface Section {
 export interface Doc {
   /** How the program is run, e.g. `mytool` or `mytool media to-pcm`. */
   name: string;
+  /** The page's name in the header and NAME line: `name`, or a split page's, e.g. `mytool-db-migrate`. */
+  page: string;
   /** Manual section, e.g. `1`. */
   section: string;
   /** Version shown in the header, or empty. */
@@ -44,6 +47,10 @@ export interface DocOptions {
   version?: string;
   /** Date for the header, YYYY-MM-DD (default: today). */
   date?: string;
+  /** The page's name (default: `name`); see `Doc.page`. */
+  page?: string;
+  /** Commands get pages of their own (see `pages`): list them, with a SEE ALSO, instead of documenting each. */
+  split?: boolean;
 }
 
 /** A runnable level: a program without commands, or a leaf command, with what it inherits. */
@@ -52,6 +59,8 @@ export interface Leaf {
   words: string[];
   /** The level's own description. */
   description: string;
+  /** Text after its help, e.g. examples. */
+  epilog: string;
   /** Positional arguments. */
   arguments: SchemaArgument[];
   /** Its own options, then those it inherits, nearest first. */
@@ -91,6 +100,7 @@ export function leaves(schema: Schema): Leaf[] {
     out.push({
       words,
       description: node.description,
+      epilog: node.epilog,
       arguments: node.arguments,
       options: [...chain].reverse().flatMap((s) => s.options),
       effects: nearest((s) => s.effects, (v) => v.length === 0) ?? [],
@@ -123,7 +133,7 @@ export function optionText(o: SchemaOption): string {
   const notes: string[] = [];
   if (o.required) notes.push('required');
   if (o.isArray) notes.push('repeatable');
-  if (o.secret) notes.push('secret: prefer the environment');
+  if (o.secret) notes.push('secret: set it in the environment, never on the command line');
   if (o.default && !o.isFlag) notes.push(`default: ${o.default}`);
   if (o.validation) notes.push(`accepts: ${describeRule(o.validation)}`);
   notes.push(`environment: ${o.variableName}`);
@@ -164,7 +174,9 @@ function leafParts(leaf: Leaf): { args?: Block; options?: Block; streams?: Block
     ...leaf.roles.map((r) => ({ term: `${r.direction === 'in' ? 'input' : 'output'} role ${r.name}`, text: stream(r) })),
   ];
   const notes = [
-    ...(leaf.effects.length ? [`Effects: ${leaf.effects.map((e) => `${e} (${EFFECTS[e] ?? e})`).join(', ')}.`] : []),
+    leaf.effects.length
+      ? `Effects: ${leaf.effects.map((e) => `${e} (${EFFECTS[e] ?? e})`).join(', ')}.`
+      : 'Effects: not declared, so treat it as possibly destructive.',
     ...leaf.constraints.map((c) => CONSTRAINT[c.type]?.(c.options) ?? ''),
     ...leaf.requiredCommands.map((r) => `Needs ${r.command} on PATH: ${r.description}${r.installHint ? ` (${r.installHint})` : ''}.`),
   ].filter(Boolean);
@@ -204,7 +216,8 @@ export function buildDoc(schema: Schema, opts: DocOptions = {}): Doc {
   const summary = firstSentence(schema.description || '');
   const sections: Section[] = [];
 
-  sections.push({ title: 'NAME', blocks: [{ kind: 'p', text: summary ? `${name} - ${summary}` : name }] });
+  const page = opts.page || name;
+  sections.push({ title: 'NAME', blocks: [{ kind: 'p', text: summary ? `${page} - ${summary}` : page }] });
   sections.push({ title: 'SYNOPSIS', blocks: [{ kind: 'pre', text: all.map((l) => synopsis(name, l)).join('\n') }] });
   if (schema.description) sections.push({ title: 'DESCRIPTION', blocks: schema.description.split(/\n{2,}/).map((text) => ({ kind: 'p', text })) });
 
@@ -214,6 +227,14 @@ export function buildDoc(schema: Schema, opts: DocOptions = {}): Doc {
     if (options) sections.push({ title: 'OPTIONS', blocks: [options] });
     if (streams) sections.push({ title: 'STREAMS', blocks: [streams] });
     if (notes.length) sections.push({ title: 'NOTES', blocks: notes });
+  } else if (opts.split) {
+    // The commands have pages of their own: the program's options here, and a list of the commands.
+    const own = schema.options.filter((o) => o.name !== 'help').map((o) => ({ term: optionLabel(o), text: optionText(o) }));
+    if (own.length) sections.push({ title: 'OPTIONS', blocks: [{ kind: 'p', text: 'Accepted by every command.' }, { kind: 'dl', items: own }] });
+    sections.push({
+      title: 'COMMANDS',
+      blocks: [{ kind: 'dl', items: all.map((l) => ({ term: [name, ...l.words].join(' '), text: `${sentence(l.description)}See ${pageName(name, l.words)}(${opts.section || '1'}).` })) }],
+    });
   } else {
     // One subsection per runnable command, with what it inherits.
     const blocks: Block[] = [];
@@ -232,12 +253,14 @@ export function buildDoc(schema: Schema, opts: DocOptions = {}): Doc {
 
   // Every option's variable, once, in the order first seen.
   const env = new Map<string, string>();
-  for (const leaf of all) for (const o of leaf.options) if (o.name !== 'help' && !env.has(o.variableName)) env.set(o.variableName, `Sets --${o.name}.${o.secret ? ' A secret: set it here rather than on the command line.' : ''}`);
-  const anyRoles = all.some((l) => l.roles.length);
+  for (const leaf of opts.split && !program ? [{ options: schema.options }] : all) for (const o of leaf.options) if (o.name !== 'help' && !env.has(o.variableName)) env.set(o.variableName, `Sets --${o.name}.${o.secret ? ' A secret: set it here rather than on the command line.' : ''}`);
+  const anyRoles = opts.split && !program ? Boolean(schema.roles?.length) : all.some((l) => l.roles.length);
   sections.push({
     title: 'ENVIRONMENT',
     blocks: [
-      { kind: 'p', text: 'An option given on the command line takes precedence over the config file, which takes precedence over the environment, which takes precedence over the default.' },
+      { kind: 'p', text: schema.config
+        ? 'An option given on the command line takes precedence over the config file, which takes precedence over the environment, which takes precedence over the default.'
+        : 'An option given on the command line takes precedence over the environment, which takes precedence over the default.' },
       {
         kind: 'dl',
         items: [
@@ -250,6 +273,7 @@ export function buildDoc(schema: Schema, opts: DocOptions = {}): Doc {
       },
     ],
   });
+  if (schema.config) sections.push({ title: 'FILES', blocks: files(schema.config, schema.options) });
   sections.push({
     title: 'EXIT STATUS',
     blocks: [{
@@ -262,5 +286,70 @@ export function buildDoc(schema: Schema, opts: DocOptions = {}): Doc {
     }],
   });
   if (schema.epilog) sections.push({ title: 'EXAMPLES', blocks: [{ kind: 'pre', text: schema.epilog.replace(/\n+$/, '') }] });
-  return { name, section: opts.section || '1', version: opts.version || '', date: opts.date || defaultDate(), summary, sections };
+  if (opts.split && !program) sections.push({ title: 'SEE ALSO', blocks: [{ kind: 'refs', items: all.map((l) => ({ page: pageName(name, l.words), section: opts.section || '1' })) }] });
+  return { name, page, section: opts.section || '1', version: opts.version || '', date: opts.date || defaultDate(), summary, sections };
+}
+
+// The config file (spec section 4): where it comes from and what a line looks like.
+function files(config: SchemaConfig, options: SchemaOption[]): Block[] {
+  const opt = options.find((o) => o.name === config.option);
+  const from = [`--${config.option}`, ...(opt?.variableName ? [opt.variableName] : [])].join(' or ');
+  const where = opt?.default ? `, ${opt.default} by default` : '';
+  const prefixes = config.prefixes.length ? `, on lines starting with ${config.prefixes.join(' or ')}` : '';
+  const example = options.find((o) => o.name !== config.option && o.name !== 'help' && !o.isFlag) ?? options.find((o) => o.name !== config.option && o.name !== 'help');
+  return [
+    { kind: 'p', text: `The config file is the one named by ${from}${where}, resolved against the current directory. An empty value or disabled skips it; a file that doesn't exist is an error.` },
+    { kind: 'p', text: `It sets options with one key=value per line${prefixes}. The key is an option's long name, with or without the leading --. Blank lines and lines starting with # are ignored, and @include PATH reads another file in place, relative to the one including it. Later lines override earlier ones, and an option given on the command line wins over the file.` },
+    ...(example ? [{ kind: 'pre' as const, text: `${config.prefixes[0] ?? ''}${example.name}=${example.isFlag ? 'true' : example.default || 'VALUE'}` }] : []),
+  ];
+}
+
+// Text as a sentence followed by a space, ending in a full stop unless it has its own; nothing for none.
+function sentence(text: string): string {
+  return text ? `${text}${/[.!?]$/.test(text) ? '' : '.'} ` : '';
+}
+
+/** A page's name: the invocation's words joined by hyphens, e.g. `mytool-db-migrate`. */
+export function pageName(name: string, words: string[] = []): string {
+  return [name, ...words].join(' ').trim().split(/\s+/).join('-');
+}
+
+/** A runnable command as a program of its own, with everything it inherits, for a page of its own. */
+export function leafSchema(schema: Schema, leaf: Leaf): Schema {
+  return {
+    clyops: 1, script: schema.script, description: leaf.description, epilog: leaf.epilog,
+    arguments: leaf.arguments, options: leaf.options, config: schema.config ?? null,
+    requiredCommands: leaf.requiredCommands, effects: leaf.effects as Schema['effects'],
+    constraints: leaf.constraints as Schema['constraints'], stdin: leaf.stdin, stdout: leaf.stdout,
+    roles: leaf.roles, commands: [],
+  };
+}
+
+/** One tool of a toolset, for its index page (see `toolsetDoc`). */
+export interface ToolEntry {
+  /** The words after the toolset's name, e.g. ['media', 'to-pcm']. */
+  words: string[];
+  /** The tool's description. */
+  description: string;
+}
+
+/**
+ * The index page of a directory of tools (`--root`): what the dispatcher `name` runs, each tool with
+ * a reference to its own page.
+ */
+export function toolsetDoc(name: string, description: string, tools: ToolEntry[], opts: DocOptions = {}): Doc {
+  const section = opts.section || '1';
+  const page = opts.page || pageName(name);
+  const summary = firstSentence(description);
+  const sections: Section[] = [
+    { title: 'NAME', blocks: [{ kind: 'p', text: summary ? `${page} - ${summary}` : page }] },
+    { title: 'SYNOPSIS', blocks: [{ kind: 'pre', text: tools.map((t) => `${[name, ...t.words].join(' ')} [ARGUMENTS] [OPTIONS]`).join('\n') }] },
+  ];
+  if (description) sections.push({ title: 'DESCRIPTION', blocks: description.split(/\n{2,}/).map((text) => ({ kind: 'p', text })) });
+  sections.push({
+    title: 'TOOLS',
+    blocks: [{ kind: 'dl', items: tools.map((t) => ({ term: [name, ...t.words].join(' '), text: `${sentence(firstSentence(t.description))}See ${pageName(name, t.words)}(${section}).` })) }],
+  });
+  sections.push({ title: 'SEE ALSO', blocks: [{ kind: 'refs', items: tools.map((t) => ({ page: pageName(name, t.words), section })) }] });
+  return { name, page, section, version: opts.version || '', date: opts.date || defaultDate(), summary, sections };
 }

package/src/render.ts

@@ -34,12 +34,14 @@ function manBlock(b: Block): string[] {
       return ['.PP', '.nf', '.RS 4', troff(b.text), '.RE', '.fi'];
     case 'dl':
       return b.items.flatMap((i) => ['.TP', `\\fB${troff(i.term)}\\fR`, troff(i.text)]);
+    case 'refs':
+      return ['.PP', ...b.items.map((r, n) => `.BR ${arg(r.page)} ${arg(`(${r.section})${n < b.items.length - 1 ? ',' : ''}`)}`)];
   }
 }
 
 /** The document as a man(7) page. */
 export function renderMan(doc: Doc): string {
-  const title = doc.name.toUpperCase().replace(/\s+/g, '-');
+  const title = doc.page.toUpperCase().replace(/\s+/g, '-');
   const lines = [
     `.\\" Generated by clyops-doc from ${doc.name} --help-json-schema.`,
     `.TH ${arg(title)} ${arg(doc.section)} ${arg(doc.date)} ${arg([doc.name, doc.version].filter(Boolean).join(' '))} ${arg('User Commands')}`,
@@ -48,7 +50,7 @@ export function renderMan(doc: Doc): string {
     lines.push(`.SH ${arg(s.title)}`);
     // NAME is one line, "name \- summary", without a paragraph macro (man(7)).
     if (s.title === 'NAME') {
-      lines.push(troff(`${doc.name}${doc.summary ? ` - ${doc.summary}` : ''}`));
+      lines.push(troff(`${doc.page}${doc.summary ? ` - ${doc.summary}` : ''}`));
       continue;
     }
     for (const b of s.blocks) lines.push(...manBlock(b));
@@ -100,12 +102,17 @@ function markdownBlock(b: Block): string[] {
       return [...fenced(b.text), ''];
     case 'dl':
       return [...b.items.map((i) => `- ${code(i.term)}: ${markdownText(i.text)}`), ''];
+    case 'refs':
+      return [b.items.map((r) => `[${markdownText(`${r.page}(${r.section})`)}](${encodeURI(r.page)}.md)`).join(', '), ''];
   }
 }
 
+/** The first line of a Markdown page: a comment, invisible when rendered, saying it is generated. */
+export const MARKDOWN_MARKER = '<!-- Generated by clyops-doc from --help-json-schema. Do not edit; regenerate instead. -->';
+
 /** The document as Markdown. */
 export function renderMarkdown(doc: Doc): string {
-  const lines = [`# ${code(doc.name)}`, ''];
+  const lines = [MARKDOWN_MARKER, '', `# ${code(doc.name)}`, ''];
   const header = [doc.version && `Version ${doc.version}`, doc.date].filter(Boolean).join(' · ');
   if (header) lines.push(`_${markdownText(header)}_`, '');
   for (const s of doc.sections) {
@@ -136,6 +143,8 @@ function htmlBlock(b: Block): string {
       return `<pre><code>${htmlText(b.text)}</code></pre>`;
     case 'dl':
       return `<dl>\n${b.items.map((i) => `<dt><code>${htmlText(i.term)}</code></dt>\n<dd>${htmlText(i.text)}</dd>`).join('\n')}\n</dl>`;
+    case 'refs':
+      return `<p>${b.items.map((r) => `<a href="${htmlText(encodeURI(r.page))}.html"><code>${htmlText(r.page)}</code>(${htmlText(r.section)})</a>`).join(', ')}</p>`;
   }
 }
 
@@ -159,7 +168,7 @@ export function renderHtml(doc: Doc): string {
 <meta charset="utf-8">
 <meta name="viewport" content="width=device-width, initial-scale=1">
 <meta name="generator" content="clyops-doc">
-<title>${htmlText(doc.name)}(${htmlText(doc.section)})</title>
+<title>${htmlText(doc.page)}(${htmlText(doc.section)})</title>
 <style>${STYLE}</style>
 </head>
 <body>