Module man 

Man-page generation from the live clap definition.

Why this is written here rather than taken from a crate

The obvious options were clap_mangen, help2man, or the roff crate that clap_mangen is built on. All three were considered:

• help2man builds one page from one --help. This CLI has eight subcommands, so it would need eight invocations plus --include files of hand-written prose — reintroducing the second source of truth it was meant to avoid, and adding a perl build dependency.
• clap_mangen cannot express the prose a good page needs: a real DESCRIPTION, worked EXAMPLES, EXIT STATUS.
• roff is small (456 lines, no runtime dependencies, no unsafe, no I/O) and would have served, but it is unaudited against this repository’s cargo vet policy, whose exemption ratchet forbids adding an unreviewed crate. We use a narrow subset of roff — .TH, .SH, .TP, .B, .nf — so emitting it directly costs less than the supply-chain review it avoids.

What cannot drift

SYNOPSIS and OPTIONS are walked out of crate::cmd::Cli’s own clap::Command, so a flag that exists in the parser appears in the page by construction. Only the prose sections are written by hand, and tests/man_page.rs asserts that every flag and subcommand the parser defines is present in the rendered output — so prose cannot fall behind the parser either.

Escaping

A leading . or ' on a line is a roff control line, and \ and - are meaningful mid-text. escape_text neutralises all four. This is the same set the roff crate handles, and for the same reason.

Functions

escape_text

Escapes text for inclusion in a roff text line.

render

Renders the full ssg.1 man page.