Conversation
Add a `pdu-man-page` binary that generates a roff-formatted man page from the clap command definition. The generated `exports/pdu.1` file is kept in sync via a `sync_man_page` test, following the same pattern as completions and help text. Update generate-completions.sh, deploy CI, test matrix, and PKGBUILD templates to include the man page. https://claude.ai/code/session_01CrXuWDMVQsiUBoy6ceACsF
Contributor
There was a problem hiding this comment.
Pull request overview
Adds first-class Unix man page support for pdu by generating a deterministic exports/pdu.1 from the clap CLI definition, validating it in CI, and distributing it in release artifacts and packaging templates.
Changes:
- Introduces a
pdu-man-pagegenerator binary (feature-gated) and wires it intogenerate-completions.sh. - Adds a sync test to ensure
exports/pdu.1stays up to date with CLI definitions; expands local/CI test runs to cover the new feature. - Updates release workflow and AUR PKGBUILD templates to ship/install the man page.
Reviewed changes
Copilot reviewed 10 out of 11 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
cli/man_page.rs |
New binary to render the man page via clap_mangen. |
exports/pdu.1 |
Checked-in generated man page content. |
tests/sync_man_page.rs |
New sync test to enforce regeneration when CLI changes. |
generate-completions.sh |
Regenerates the man page alongside other exported docs. |
run.sh |
Enables the new feature when running generator binaries. |
Cargo.toml |
Adds cli-man feature, clap_mangen dependency, and pdu-man-page bin target. |
Cargo.lock |
Locks new transitive deps (clap_mangen, roff). |
test.sh |
Adds a --features cli-man test pass. |
.github/workflows/deploy.yaml |
Uploads pdu.1 as a release asset. |
template/parallel-disk-usage/PKGBUILD |
Installs exports/pdu.1 into /usr/share/man/man1/. |
template/parallel-disk-usage-bin/PKGBUILD |
Installs the versioned man page file into /usr/share/man/man1/. |
Performance Regression Reportscommit: 03b2f54 There are no regressions. |
…nction Move man page rendering into a shared `src/man_page.rs` module (gated on `cli-man` feature) so both the binary and sync test use the same logic. Replace the `.SH EXTRA` section header with `.SH EXAMPLES` in the generated output. https://claude.ai/code/session_01CrXuWDMVQsiUBoy6ceACsF
KSXGitHub
commented
Mar 28, 2026
KSXGitHub
commented
Mar 28, 2026
Remove the redundant "Examples:" subheading and strip unnecessary 4-space indentation from the examples content in the generated man page. https://claude.ai/code/session_01CrXuWDMVQsiUBoy6ceACsF
Drop the clap_mangen dependency and write a custom man page renderer that produces proper roff output. This fixes several formatting issues: - DESCRIPTION section now uses .PP for paragraph breaks (copyright and sponsor lines no longer merge) - EXAMPLES section uses .TP for description/command pairs with .nf/.fi for literal command rendering - Boolean flags no longer show redundant "Possible values: true, false" - Visible aliases are included in option headers https://claude.ai/code/session_01CrXuWDMVQsiUBoy6ceACsF
The man page module only needs clap (provided by the cli feature), so there is no need for a separate cli-man feature. This matches how pdu-usage-md requires only cli. https://claude.ai/code/session_01CrXuWDMVQsiUBoy6ceACsF
KSXGitHub
force-pushed
the
claude/add-man-page-generation-BKX0M
branch
from
8899187 to
bdd1451
Compare
Replace the simple stdout-only binary with a proper CLI that supports: - `pdu-man-page generate roff 1` — render roff source to stdout - `pdu-man-page generate man 1` — render man page via man(1) to stdout - `pdu-man-page check roff 1` — verify exports/pdu.1 is up-to-date - `pdu-man-page check man 1` — verify exports/pdu.1.man is up-to-date The sync test now spawns the binary with `check` (like sync_ai_instructions), and the `man` test is gated behind a `man-test` feature since it requires man(1) to be installed. https://claude.ai/code/session_01CrXuWDMVQsiUBoy6ceACsF
The man(1) output varies across systems (different groff versions, line breaking, etc.), so the man sync test cannot reliably pass in CI. Make it always #[ignore] instead of gating on a man-test feature, and remove the man-test feature entirely. The pdu.1.man file is a reference file derived from pdu.1 (which IS sync-checked), so CI enforcement is not needed. https://claude.ai/code/session_01CrXuWDMVQsiUBoy6ceACsF
Remove unnecessary deref in string comparison and use descriptive name for `example_command` variable in `render_examples_section`. https://claude.ai/code/session_01CrXuWDMVQsiUBoy6ceACsF
Re-enable the `man` test with a `which` check that panics with a diagnostic message and `TEST_SKIP` hint when `man` is not installed, following the same pattern as `fs_errors` and `cross_device_excludes_mount`. Add `man-db` to CI's external test dependency installation step and document it in CONTRIBUTING.md alongside the existing FUSE dependencies. https://claude.ai/code/session_01CrXuWDMVQsiUBoy6ceACsF
Replace `man` with `groff -man -T utf8` for rendering the man page reference file. This produces consistent output across systems by bypassing system-specific man(1) wrappers and configuration. Also normalize the rendered output to strip trailing whitespace per line and ensure exactly one trailing newline. Update CI to install groff-base, sync test to check for groff, and CONTRIBUTING.md to document the dependency. https://claude.ai/code/session_01CrXuWDMVQsiUBoy6ceACsF
CI only installs groff-base on Linux, so the man test must be skipped on macOS and Windows via cfg_attr ignore. https://claude.ai/code/session_01CrXuWDMVQsiUBoy6ceACsF
The generate subcommand now writes to exports/ files directly instead of printing to stdout, so the shell script no longer needs redirections. https://claude.ai/code/session_01CrXuWDMVQsiUBoy6ceACsF
Add `-K utf8` to handle UTF-8 input correctly (fixes mojibake in non-ASCII characters like © and Vietnamese names) and `-P -c` to disable SGR escape sequences in the output. https://claude.ai/code/session_01CrXuWDMVQsiUBoy6ceACsF
Grotty (groff's terminal output driver) uses char+backspace+char sequences for bold and _+backspace+char for underline. Strip these overstrike sequences in the binary rather than relying on external tools like col(1) or groff's -P -c flag. https://claude.ai/code/session_01CrXuWDMVQsiUBoy6ceACsF
Use GROFF_NO_SGR=1 to prevent SGR (ANSI escape) output, and -P -c/-b/-u to suppress backspace overstrikes for bold/underline. Keep strip_formatting as a safety net for any remaining escape sequences. https://claude.ai/code/session_01CrXuWDMVQsiUBoy6ceACsF
Use `groff -Tutf8 -P-cbou -man` which produces clean plain-text output without ANSI escapes or backspace overstrikes. https://claude.ai/code/session_01CrXuWDMVQsiUBoy6ceACsF
Apply roff_escape to default values so hyphens render consistently (e.g. block-size becomes block\-size). Also fix .TH header to place the version string in the source field instead of the date field per man(7) convention. https://claude.ai/code/session_01CrXuWDMVQsiUBoy6ceACsF
KSXGitHub
commented
Mar 28, 2026
Revert the .TH change that added an empty "" date field. The simpler form `.TH pdu 1 "pdu 0.21.1"` is the conventional approach used by clap_mangen and other tools. https://claude.ai/code/session_01CrXuWDMVQsiUBoy6ceACsF
Append `...` to positional arguments that accept multiple values (e.g. `[FILES]...`), matching the `--help` output. Applies to both the SYNOPSIS and OPTIONS sections. https://claude.ai/code/session_01CrXuWDMVQsiUBoy6ceACsF
Skip hidden args (e.g. --deduplicate-hardlinks on non-Unix) when building the conflict map so the man page doesn't reference options that are not listed on the current platform. https://claude.ai/code/session_01CrXuWDMVQsiUBoy6ceACsF
Previously, need_paragraph was only cleared inside the `need_paragraph && !first` branch, so leading empty lines would leave it set and cause a spurious .PP before the second non-empty line. https://claude.ai/code/session_01CrXuWDMVQsiUBoy6ceACsF
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
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.
This PR adds support for generating and distributing Unix man pages for the
pducommand. The man page is automatically generated from the CLI argument definitions using aclap's introspection APIs.https://claude.ai/code/session_01CrXuWDMVQsiUBoy6ceACsF