Skip to content

Add man page output for the frontends#1004

Draft
gmipf wants to merge 1 commit into
SabreTools:masterfrom
gmipf:pr/6-manpage-generation
Draft

Add man page output for the frontends#1004
gmipf wants to merge 1 commit into
SabreTools:masterfrom
gmipf:pr/6-manpage-generation

Conversation

@gmipf

@gmipf gmipf commented Jul 1, 2026

Copy link
Copy Markdown
Contributor

This wires up the man page reference feature added to SabreTools.CommandLine
(#2) so the frontends can produce their own man pages, instead of packagers
hand-writing and re-syncing them.

Draft: this depends on a published SabreTools.CommandLine release that
includes #2. The current pin (1.4.0) predates the man API, so CI won't
build until that release is out and the package reference here is bumped to
it. Opening now so the approach and the open questions below can be reviewed;
I'll bump the pin and mark it ready once the release is available.

What it does

  • MPF.CLI man and MPF.Check man write a roff man page to standard output,
    rendered from the same command model that produces --help.
  • The graphical frontend has no command-line model to render from, so a short
    hand-maintained page (MPF.Avalonia/MPF.1) is included for it.

How a man page is produced

The man feature is just another reference feature (like Help), so no new
plumbing: each program registers new Manpage(...) with its name/description
and the library renders the page from the existing feature/input model.

A packager (or anyone) then does:

MPF.CLI man > MPF.CLI.1      # 1. generate roff from the binary
# 2. stamp the .TH date at build time (see below)
# 3. install MPF.CLI.1 into the man path

Two intentional details:

  • The page is emitted before the configuration path and other startup
    output
    , so the redirect above yields clean roff with no leading
    Configuration path: line. Generating it has no side effects: it never writes
    config.json or runs first-run setup, and the content is drawn only from the
    static command model, so the output is identical whether or not a config
    exists.
  • The .TH date is left blank so a distributor stamps it at build time,
    keeping output reproducible (the library documents this). This is the only
    thing mandoc -T lint flags until it's stamped.

Installing the pages is left to distributors; this PR only adds the ability to
produce them.

Verification

  • Builds clean with TreatWarningsAsErrors (spot-checked net20 and net10.0;
    full TFM sweep before merge).
  • Generated pages and the GUI stub pass groff -man -ww -z with no warnings
    and mandoc -T lint clean except the intended "missing date" warning.

Open questions

  • Names in .TH/NAME use the assembly names (MPF.CLI, MPF.Check, MPF).
    Happy to switch to lowercase (mpf-cli, ...) if you prefer.
  • The GUI page sits at MPF.Avalonia/MPF.1; I can move it to a man/ folder.
  • Detailed option descriptions are included (includeVerbose: true). Easy to
    drop to the short form if you'd rather keep the page terse.

Prepared with AI assistance (Claude Opus 4.8) and reviewed before submission.

Register the man page reference feature from SabreTools.CommandLine in
MPF.CLI and MPF.Check so that "MPF.CLI man" and "MPF.Check man" write a
roff man page built from the same command model as the help output. The
page is emitted before any configuration handling so the roff stays clean
for redirection to a file.

Add a hand-maintained man page for the graphical frontend, which has no
command-line model to generate from.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant