Man generator spec (Proposal)

[max-ishere]

I am basing my suggestions on the mdoc page. There are a lot of different small issues with the generator, I wanted to consolidate them here.

Compile time

• Nearly impossible to use in build.rs unless you want to keep track of 2 different Commands. There is a way to reuse code, but there should be a macro to make it seamless for the user [^1]
• Poor support of Subcommand.
  • They should either have their own page
  • Or there should be a way to incorporate them into the root page at the developer's discretion.
• README does not mention that #[derive(Parser)] users should call Args::command(). (And imo they really should be able to pass anything that is Into<Command> or Into<ManSource> in case there is something that is lost while you convert.)

man page structure

• The DESCRIPTION is duplicated in NAME
• No EXAMPLES[^2], AUTHORS
• Hard to add new sections (e.g. FILES, DIAGNOSTICS, ERRORS, etc)[^2]

Footnotes

1. Using #[path = "src/clap.rs"] mod clap; module annotation you can reimport code, but what I feel this should look like is more of let man = man_from!(clap::Args);.
2. It would be nice if we could write code in /examples and somehow generate both working executables that can be used in cargo test and the man page. One option is to import main() from main.rs, but set up parse() to yield a preprogrammed struct.

---

Any feedback is welcome.

[epage]

Poor support of Subcommand.

Being discussed at #3365

[epage]

EXAMPLES, AUTHORS, FILES, etc I feel like would be part of #3354

[epage]

RE EXAMPLES

It would be nice if we could write code in /examples and somehow generate both working executables that can be used in cargo test and the man page. One option is to import main() from main.rs, but set up parse() to yield a preprogrammed struct.

Another source for inspiration is how trycmd let's us test examples in documentation, see https://docs.rs/trycmd/latest/trycmd/

[max-ishere]

The idea of using /examples seemed like this magical cool way to have cargo test verify that the EXAMPLES section does not become outdated, but the more I think about it the less I understand how this verification should work.

I think you could just make sure that an example compiles.

examples/pull.rs:

// With cargo run --example pull this becomes fn main().
// If included inside mangen file it becomes a piece of content
clap_mangen::example!(
    args(pull origin main -v --force),
    explanation("The pull subcommand requires a remote target (origin) and a branch (main) \
you can also add flags such as -v for verbose and --force because I wanted to demo the macro.")
)

But since there is no test in the example you could just verify that when passing the args!() into parse() it is able to parse them without a panic.

mangen file

examples.push(args!(pull origin main -fv), "The pull command ...");

[epage]

I think there are tiers to testing, like with doctests

• ignore
• no_run (just call parse)
• run (use snapshot testing of the binary)

That said, I think this should move to an issue for us to track but I see this being a lower priority than some of the others we are discussing.

[epage]

Nearly impossible to use in build.rs unless you want to keep track of 2 different Commands. There is a way to reuse code, but there should be a macro to make it seamless for the user [^1]

Using #[path = "src/clap.rs"] mod clap; module annotation you can reimport code, but what I feel this should look like is more of let man = man_from!(clap::Args);.

[max-ishere]

The problem with a macro from this is it requires a very specific layout to make it work while I have programs that have different layouts for valid reasons.

To clarify the macro, it expands something like config::args::Args into:

#[path = "src/config/args.rs"]
mod __clap_mangen__args;

Man::new(__clap_mangen__args::Args);

And then puts that inside a Man::new(). That is for derive structs. If I were to suggest a way to obtain a built Command then it would be some kind of closure/function. But I'm not very familiar with builder clap.

[max-ishere]

Regarding the build.rs, maybe it is indeed not the best idea, but we have a way to tell cargo to only rerun the build.rs if a file has changed. In my case all the clap structs are in a separate module. If that file changes I would like the manpage to be regenerated. So it does make sense to use build.rs, but maybe with the addition of rerun-if-changed.

One reason not to generate the manpage as part of the build process would be if there is also a library in the same crate.

[max-ishere]

First, imo if you are using build.rs for anything but build-environment specific behavior, you are doing it wrong :)

But docs are part of the final package so they dont look much different from compiling code to me

[max-ishere]

Theoretically, you could make a bin/mangen.rs and use cargo run --bin mangen path/ to generate it. I guess for me its about having options.

[epage]

Regarding the build.rs, maybe it is indeed not the best idea, but we have a way to tell cargo to only rerun the build.rs if a file has changed. In my case all the clap structs are in a separate module. If that file changes I would like the manpage to be regenerated. So it does make sense to use build.rs, but maybe with the addition of rerun-if-changed.

This doesn't follow to me. We only have to tell cargo to re-run build.rs if we use it. If we use snapshot testing, then there isn't any issue; the test run fails then you re-run with SNAPSHOTS=true cargo test.

But docs are part of the final package so they dont look much different from compiling code to me

As I said, I recommend build.rs only be used for environment-specific builds. I do all of my codegen using tests; not build.rs. Just because its code-like does not require build.rs