Ship a man page and shell completions #8

New issue

Open

opened 2026-09-19 16:33:42 +09:00 by natsukium · 0 comments

natsukium commented

2026-09-19 16:33:42 +09:00

Owner

Summary

Generate a man page (clap_mangen) and shell completions (clap_complete) at build time, and
install them from the Nix package.

Why

Principle 4 makes the key binding the whole configuration, which means every piece of
configuration is a CLI flag and --help is the only reference there is. A tool with that shape
should ship spoor(1), and a config-less tool is exactly the one whose flags you want completed
at the prompt rather than looked up.

The doc comments on Cli in src/main.rs are already written as reference prose (the long
long_about about logical sources, the per-flag rationale), so a man page is close to free.

Sketch

A build.rs or a small xtask/--generate path emitting spoor.1 and the bash/zsh/fish
completions from the same clap command.
flake.nix installs them into $out/share/man/man1 and the usual completion directories, so
nix profile install gets them without extra steps.

## Summary Generate a man page (`clap_mangen`) and shell completions (`clap_complete`) at build time, and install them from the Nix package. ## Why Principle 4 makes the key binding the whole configuration, which means **every** piece of configuration is a CLI flag and `--help` is the only reference there is. A tool with that shape should ship `spoor(1)`, and a config-less tool is exactly the one whose flags you want completed at the prompt rather than looked up. The doc comments on `Cli` in `src/main.rs` are already written as reference prose (the long `long_about` about logical sources, the per-flag rationale), so a man page is close to free. ## Sketch - A `build.rs` or a small `xtask`/`--generate` path emitting `spoor.1` and the bash/zsh/fish completions from the same `clap` command. - `flake.nix` installs them into `$out/share/man/man1` and the usual completion directories, so `nix profile install` gets them without extra steps.

natsukium added the

good-first-issue

packaging

labels

2026-09-19 16:34:34 +09:00