ADR-0027: Keep the hand-written man page renderer¶
- Status: Accepted
- Date: 2026-10-29
- Deciders: @lusoris
- Tags:
clikit,cli,dependencies
Context¶
core/clikit renders roff man pages for every documented command of a cobra tree (core/clikit/man.go). ManPages walks the command tree, and renderMan writes the header, NAME, SYNOPSIS, DESCRIPTION, OPTIONS, inherited OPTIONS and SEE ALSO sections. Golden files under core/clikit/testdata/golden/man/ pin the output. The file is 215 lines, of which the renderer and its roff helpers (renderMan through roffBlock) are about 120.
Issue #1191 proposed replacing the renderer with doc.GenMan from github.com/spf13/cobra/doc. Cobra v1.10.2 is already a direct dependency of the core module.
An implementation of that proposal was built and run against the golden tests. Its diff touched 17 files (418 insertions, 315 deletions). The regenerated pages changed as follows:
- Option names lose roff escaping.
GenManwrites Markdown and converts it withgo-md2man, so\-h,\-\-helpandmyapp\-db\-migratebecome plain-h,--helpandmyapp-db-migrate. In roff a plain-is a hyphen, not a minus sign. man-pages(7) asks for\-in options with a leading dash so that UTF-8 and PDF renderings are correct and options copied from a rendered page paste as real minus signs. - Boolean flags gain
[=false].manPrintFlags(cobradoc/man_docs.go, v1.10.2) appends[=<default>]to every flag withNoOptDefVal, so--helpand--verboseread--help[=false]. This is hard-coded, with no option to turn it off. - The header changes. Without a fixed date, the header date becomes
Jan 0001(from a zeroGenManHeader.Date, needed for deterministic golden files), and the "Code generated ... DO NOT EDIT" marker is lost. AHISTORYsection ("1-Jan-0001 Auto generated by spf13/cobra") appears unless every command setsDisableAutoGenTag. - The lean
coremodule gains two modules.github.com/cpuguy83/go-md2man/v2v2.0.6 is added, and it requiresgithub.com/russross/blackfriday/v2v2.1.0. ADR-0017 keepscoresmall.
Each regression needs its own adapter: post-processing roff output to restore escapes, stripping [=false], injecting the header and generated-code marker. Together the adapters would be about as large as the hand-written section writers they replace, and they would depend on the exact roff that go-md2man emits.
Considered options¶
| Option | Evaluation |
|---|---|
a) Replace the renderer with doc.GenMan plus adapters |
Rejected: four output regressions, two new modules in core, adapters that parse a third party's roff. |
| b) Keep the hand-written renderer | Chosen: correct roff escaping, deterministic header, golden-tested, no new dependencies. |
Decision¶
Keep the hand-written man page renderer in core/clikit/man.go (option b). Do not adopt github.com/spf13/cobra/doc for man pages.
Consequences¶
- Positive: Option names stay copy-pasteable (
\-escaping), and boolean flags render without[=false]. - Positive: The
coremodule keeps its current dependency set. - Negative: Roff escaping and section layout remain code this repository maintains; the golden files are the guard.
- Revisit trigger:
cobra/docemits escaped roff for option names (\-) and can render boolean flags without the[=default]suffix, so thatGenManreproduces the golden files with header settings only.
References¶
- Issue #1191: replace
core/clikitman rendering withcobra/doc.GenMan. - Operator decision recorded under answer-ledger id
golusoris-1191-genman-route(2026-10-29): keep the hand-written renderer (paraphrased). - man-pages(7), section "Generating optimal glyphs".
- cobra v1.10.2
doc/man_docs.go:manPrintFlags,fillHeader,genMan.