What is the idiomatic way of writing man pages for Rust CLI tools?

Question

CLI apps on Unix-like OSes generally provide man pages for reference. I have not yet seen any good guide on how to do this in the Rust ecosystem - what is the idiomatic way of doing this?

I am aware of the Cargo build scripts feature, is this the way it is generally done? If yes, how would it generate man pages and how would it handle man installation on different OSes?

Answer 1

The current best approach I am aware of is to use the man crate. It is still a work in progress, and adding better support for man-page generation is an area that the CLI Working Group is actively working on.

As described in more detail in the README, man lets generate man pages from syntax like:

use man::prelude::*;

fn main() {
    let page = Manual::new("basic")
        .about("A basic example")
        .author(Author::new("Alice Person").email("[email protected]"))
        .author(Author::new("Bob Human").email("[email protected]"))
        .flag(
            Flag::new()
                .short("-d")
                .long("--debug")
                .help("Enable debug mode"),
        )
        .flag(
            Flag::new()
                .short("-v")
                .long("--verbose")
                .help("Enable verbose mode"),
        )
        .option(
            Opt::new("output")
                .short("-o")
                .long("--output")
                .help("The file path to write output to"),
        )
        .example(
            Example::new()
                .text("run basic in debug mode")
                .command("basic -d")
                .output("Debug Mode: basic will print errors to the console")
            )
        .custom(
            Section::new("usage note")
                .paragraph("This program will overwrite any file currently stored at the output path")
        )
        .render();

    println!("{}", page);
}