Repository navigation
Man pages drop every angle-bracket placeholder: md2man reads help text as markdown, so <document> and <config> vanish #1016
Description
The man pages lose every angle-bracket placeholder in the help text they are generated from. cobra renders a page as markdown and converts it with go-md2man, and markdown reads <word> as an inline HTML tag, which md2man drops.
From the pages installed on 2026-10-01 (build v0.1.0-dev.20261001193326, 01634491):
| Page | Source | Rendered |
|---|---|---|
writ-workflow-verify(1), SYNOPSIS |
verify [<document>...] (cmd/internal/cli/workflow.go:133) |
writ workflow verify [...] [flags] |
writ-workflow-verify(1), --allowed-signers |
"(default: <config>/devlore/allowed_signers)" (cmd/internal/cli/workflow.go:193) |
"(default: /devlore/allowed_signers)" |
writ-repo-add(1), SYNOPSIS |
<layer> <working-tree-root>|<repository-url> [<working-tree-root>] |
writ repo add | [] [flags] |
A line grep finds 31 help strings that carry placeholders, all four programs together: 30 command synopses (Use:), 16 of them lore's, and one flag usage. Long and Example bodies span lines and are not in that count. Every one of the 30 synopses renders without its operands. The same page also renders workflow verify's signing-policy ladder out of alignment, with one entry wrapped mid-phrase.
Installed and displayed pages are also generated two ways. self install writes the installed pages with doc.GenManTree directly (cmd/internal/cli/selfinstall.go:941), without the withManUsage swap and the tidyManRoff pass that the displayed page gets (cmd/internal/cli/man.go:134).
Found 2026-10-02 at 01634491, reading writ workflow verify's page while planning lane 7 of #916 (#926).
Resolution
Help text reaches md2man as text, not markup: placeholders and indented blocks survive on every page. Installed and displayed pages come from one generator with one set of fixes. A test renders a page for a command whose synopsis and a flag usage carry placeholders, and asserts that they appear.
Plan and design documents
| Kind | Document |
|---|---|
| Plan | No plan yet |
| Design | docs/architecture/10-command-line-interface.md |
Activity