Skip to content

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. GenMan writes Markdown and converts it with go-md2man, so \-h, \-\-help and myapp\-db\-migrate become plain -h, --help and myapp-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 (cobra doc/man_docs.go, v1.10.2) appends [=<default>] to every flag with NoOptDefVal, so --help and --verbose read --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 zero GenManHeader.Date, needed for deterministic golden files), and the "Code generated ... DO NOT EDIT" marker is lost. A HISTORY section ("1-Jan-0001 Auto generated by spf13/cobra") appears unless every command sets DisableAutoGenTag.
  • The lean core module gains two modules. github.com/cpuguy83/go-md2man/v2 v2.0.6 is added, and it requires github.com/russross/blackfriday/v2 v2.1.0. ADR-0017 keeps core small.

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 core module 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/doc emits escaped roff for option names (\-) and can render boolean flags without the [=default] suffix, so that GenMan reproduces the golden files with header settings only.

References

  • Issue #1191: replace core/clikit man rendering with cobra/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.