docs: eliminate troff warnings in man page generation

[maliberty]

Summary

The man page (cat) build emitted several classes of troff/groff warnings. This makes the doc build warning-free and improves the rendered tables.

Build tooling (docs/)

• cannot select font 'C'/'V' — Pandoc renders code/verbatim text in the Courier font family, which the nroff/tty device lacks. Added docs/src/man_fontfix.tmac (injected via --include-in-header) to remap those fonts to ones available on devices without Courier. Registered as a Bazel input for //docs:man_pages.
• tbl preprocessor failed — the OPTIONS tables need tbl; added -t.
• character with input code N not defined / mojibake — non-ASCII README content (e.g. accented author names like "Povišer") was decoded as Latin-1. The build now runs in a UTF-8 locale and renders with groff -Kutf8 … -Tutf8.
• table wider than line length — Pandoc sizes tables at nearly full width while the man body is indented; narrowed the body indent with -rIN=4n so they fit.

README content

• Pandoc derives table column widths from the relative number of dashes in the Markdown separator row. The uniform | ----- | ----- | separators forced a 50/50 split, leaving the short Switch Name column half-empty in rendered man pages. Column 1 is now sized per-table to its longest switch name (147 tables).
• Dropped the Check out GitHub discussion FAQ footers, whose long inline URLs were not usable as links in man/cat output.

Verification

Full make doc cat under a CI-like C locale now emits 0 warnings of any class.

[gemini-code-assist]

Code Review

This pull request improves the documentation build system by introducing a font remapping mechanism (man_fontfix.tmac) to silence font selection warnings, running the build in a UTF-8 locale, and using groff with proper encoding and formatting flags for generating cat files. It also removes outdated FAQ sections across multiple tool READMEs and reformats various markdown tables. The review feedback suggests further optimizing the column width allocations in several markdown tables by adjusting the relative number of dashes in the separator rows, which ensures better readability and prevents excessive wrapping of descriptions in the generated man pages.

[maliberty]

Thanks for the review. Addressed the column-width feedback, with one scoping correction:

Most of the flagged tables (pdn, cts, gpl, mpl, grt, rsz, upf, rcx) are in modules listed in EXCLUDE_KEYWORDS in docs/Makefile, so their README tables are not rendered through Pandoc into man pages — and myst (RTD) / GitHub size table columns to content and ignore the dash counts. So the separator ratios in those modules have no effect on any rendered output. I've reverted the separator changes in those modules to keep the diff focused, so those comments are moot.

For the modules that do render man-page tables (cgt, est, ram, syn, tap, web), I reworked the sizing: column 1 is now set to the longest single option name (capped so the description column keeps the majority of the width), rather than the earlier formula that let long/multi-value cells inflate column 1. This gives the descriptions the space the review asked for.

The FAQ footer removals are unrelated to column widths and are kept.

[maliberty]

/gemini review

[maliberty]

@codex review

[gemini-code-assist]

Code Review

This pull request improves documentation generation by running the build in a UTF-8 locale, introducing a font-remapping snippet (man_fontfix.tmac) to prevent font errors on devices lacking Courier, and updating the Makefile to use groff instead of nroff for generating cat files. Additionally, it removes outdated FAQ sections and formats option tables across several tool READMEs. Feedback on the changes suggests defining groff as a customizable variable (GROFF ?= groff) in the Makefile to improve portability, removing the unused NROFF variable, and using $(GROFF) in the recipes instead of hardcoding the executable.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: fdef3d0a09

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[maliberty]

Addressed the Makefile review feedback:

• groff overridable (@gemini): added GROFF ?= groff and switched the three cat recipes to $(GROFF); removed the now-unused NROFF variable.
• Locale portability (@chatgpt-codex): replaced the hard-coded export LC_ALL := C.UTF-8 with detection — it picks an installed UTF-8 locale (locale -a), preferring C/en_US, and only exports LC_ALL if one is found. On hosts without any UTF-8 locale it leaves the user's locale untouched, so no invalid LC_ALL / setlocale diagnostics. groff -Kutf8 still decodes UTF-8 input regardless.

Note: the earlier inline comments on src/{rcx,upf,rsz,grt,cts}/README.md column widths were on the previous synced commit; those modules are excluded from man-page generation, so I reverted their separators to the original | ----- | ----- | — those lines are no longer changed by this PR.

Verified make doc cat remains warning-free (detected locale = C.utf8 here) with the accented author name rendering correctly.

[chatgpt-codex-connector]

To use Codex here, create an environment for this repo.