cli: xff --man generates the man page from the registry + globals SOTs - #190
Merged
Conversation
A roff(1) man page rendered on demand from the same single sources of truth the parser and --help use -- cli::Globals() for options, registry::All() for the expression vocabulary -- so the page can never drift from the binary. NAME/SYNOPSIS/DESCRIPTION preamble, OPTIONS grouped like the usage page, EXPRESSION grouped by kind, EXIT STATUS, SEE ALSO; xff-only items tagged "(xff extension)". Wired to `--man` (print and exit). Pipe to `man -l -`. ArgHint moves from help.cc's anonymous namespace to a declared helper so the man page and --help render the primary synopsis from the one grammar source (no duplication). Tests: - manpage_test (unit): the standard man sections, the option/expression subsections, every global + primary documented, xff items marked. - man_test (bashtest): renders `xff --man` through a real roff formatter (mandoc/groff/nroff) and asserts a proper page with no leftover roff control requests (which caught a `.B`-left-mid-line bug during development). The formatter is a REQUIRED test dependency -- mandoc ships on macOS and CI installs it on Linux (test + tsan jobs); a missing formatter fails the test, it is never silently skipped.
helly25
enabled auto-merge (squash)
June 28, 2026 12:46
helly25
added a commit
that referenced
this pull request
Jul 12, 2026
mbo 0.13.0 is now in the Bazel Central Registry, so drop the temporary git_override (pinned at the main commit merging helly25/mbo#234) for a plain bazel_dep version bump. 0.13.0 carries mbo/diff (the rich diff API behind -diff, #88) and mbo/digest (the -hash algorithms, #105), which the override provided; it also keeps the macOS clang+asan verification (#188) and StatusIs code-matcher support (#190) our test conventions rely on. Comment refreshed to match. Test: bazel test //xff/cli:hash_test //xff/cli:diff_test //xff/examples:cookbook_test (mbo/digest + mbo/diff + smoke) pass against the BCR 0.13.0; pre-commit green.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
xff --manrenders a roff(1) man page on demand from the same single sources of truth the parser and--helpuse -cli::Globals()for options,registry::All()for the expression vocabulary - so the page can't drift from the binary. NAME/SYNOPSIS/DESCRIPTION, OPTIONS grouped like the usage page, EXPRESSION by kind, EXIT STATUS, SEE ALSO; xff-only items tagged "(xff extension)". Pipe toman -l -.ArgHintmoves out of help.cc's anonymous namespace to a declared helper so the man page and--helprender the primary synopsis from one grammar source (no duplication).Tests + the tool-dependency decision
xff --manthrough a real roff formatter (mandoc/groff/nroff) and asserts a proper page with no leftover roff control requests - which caught a.B-left-mid-line bug during development.Per our discussion, the formatter is a required test dependency (no skip): mandoc ships on macOS and CI installs it on Linux (added to the
testmatrix +tsanjobs). A missing formatter fails the test - it can never be silently skipped, so there's no skip-collection machinery to maintain. (bashtest has no per-test skip primitive anyway; itsSKIPtally is filter-only.)Verified: full
bazel test //...green; mandoc render checked locally; actionlint/yamllint/shfmt/shellcheck + pinned clang-format clean.