Document full use-case (e.g., `build.rs` script) about man HOT 5 OPEN

After experimenting a bit, I think that the method I suggested above (with the build.rs file) isn't a great approach and isn't really using build.rs the way it is intended to be used. It also runs into cross-platform difficulties due to the non-portable nature of the find command. After discussing the issue with @epage a bit, I now think that the best strategy is to use a separate binary and invoke it with cargo run --bin NAME.

Specifically, I think we should suggest that users have a file like this in src/bin/ (basically the build.rs script from above):

// /src/bin/generate-docs.rs
use man::prelude::*;
use std::fs::File;
use std::io::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();
 
    let mut file = File::create('./docs/MY_APP.1)
         .expect("Should be able to open file in project directory");
    file.write_all(page.as_bytes())
        .expect("Should be able to write to file in project directory");
}

And then have something like this in their makefile:

.PHONY : install
install : 
	cargo build --release
	cargo run --bin generate-docs
	sudo install -m 0755 -v ./target/release/MY_APP /usr/local/bin/MY_APP
	# man page
	sudo cp ./docs/MY_APP.1 /usr/local/share/man/man1/MY_APP.1
	# Other install commands (Zsh completions/etc.)


.PHONY : uninstall
uninstall :
	sudo rm -f /usr/local/bin/MY_APP
	sudo rm -f /usr/local/share/man/man1/MY_APP.1

Unless someone thinks this is a bad idea, I'll write it up up as a PR soon.

from man.

@codesections the way I thought of using this is by auto-generating man pages from CLI options (e.g. as per clap-rs/clap_generate#1, example). I guess with fewer steps, and no makefile needed.

There's certainly some open questions about packaging things up, but that also applies to other files such as autocomplete definitions. I think those fall within the scope of the rust-clique packaging issue.

from man.

@yoshuawuyts Yeah, totally agreed that integrating with Clap is the long-term goal. My understanding, though, it that clap integration is blocked pending Clap v3.0.0.

My thought was that we should have some documentation about how to actually go from "I've downloaded man and written my man page using it" to "I've successfully installed the man page so that a user can type man MY_APP and see the man page." Right now, that isn't clear at all (at least not to me), so I was wondering if some documentation would be helpful for the time between now and whenever we can integrate more fully with clap.

But if you don't think that's useful, I'm happy to close this issue.

from man.

Where is Clap integration at now that v3 is out?

BTW I'd be happy to provide docs for how to package a man page using autotools for Rust projects — an arrangement I think provides a lot that cargo can't provide but I realize it's a bit unorthodox.

from man.

In clap-rs/clap#3174,. we are leaning towards calling roff-rs directly rather than going through man .

from man.