No one writes good man¹ pages anymore, myself included.

What is a man page? For the young and uninitiated, it is short for manual page. They are The Sacred Texts of the digital world. They can tell you exactly how to use a program and it works anytime, anywhere, even offline, in your terminal.

To get started, type man man and enjoy your new adventure.

Welcome back. I was looking at cargo --help today and was thinking about how much cleaner it would be if man cargo had this information instead of it all being in the command-line help.

~ ❯ cargo --help
Rust's package manager

Usage: cargo [+toolchain] [OPTIONS] [COMMAND]

Options:
  -V, --version             Print version info and exit
      --list                List installed commands
      --explain <CODE>      Run `rustc --explain CODE`
  -v, --verbose...          Use verbose output (-vv very verbose/build.rs output)
  -q, --quiet               Do not print cargo log messages
      --color <WHEN>        Coloring: auto, always, never
  -C <DIRECTORY>            Change to DIRECTORY before doing anything (nightly-only)
      --frozen              Require Cargo.lock and cache are up to date
      --locked              Require Cargo.lock is up to date
      --offline             Run without accessing the network
      --config <KEY=VALUE>  Override a configuration value
  -Z <FLAG>                 Unstable (nightly-only) flags to Cargo, see 'cargo -Z help' for details
  -h, --help                Print help

Some common cargo commands are (see all commands with --list):
    build, b    Compile the current package
    check, c    Analyze the current package and report errors, but don't build object files
    clean       Remove the target directory
    doc, d      Build this package's and its dependencies' documentation
    new         Create a new cargo package
    init        Create a new cargo package in an existing directory
    add         Add dependencies to a manifest file
    remove      Remove dependencies from a manifest file
    run, r      Run a binary or example of the local package
    test, t     Run the tests
    bench       Run the benchmarks
    update      Update dependencies listed in Cargo.lock
    search      Search registry for crates
    publish     Package and upload this package to the registry
    install     Install a Rust binary. Default location is $HOME/.cargo/bin
    uninstall   Uninstall a Rust binary

See 'cargo help <command>' for more information on a specific command.

A well-written man page would present this without needing extra command line flags (--list or cargo <command> --help), and also without the user needing to scroll up to read the available options. A well-written man page would allow for far greater flexibility in documenting the individual switches and commands, with the ability to provide usage examples, a more in-depth description of each option, and provide recommended defaults (if any).

Since my favourite markup language is Markdown, I did some searching to see how I could create man pages with Markdown and stumbled upon a blog article by Brandon Rozek that utilises Pandoc and also this article by Lars Wirzenius on how to write them by hand without Markdown.

Armed with this knowledge, I'm going to create man pages for my existing projects. I think I will go the Pandoc route. I can't wait! 💖

footnotes