Auto-generate manpage, help docs, etc.

[joshtriplett]

I'd love to have support to generate a manpage. This would use a mechanism and infrastructure similar to #376. Additional functions to override or augment portions of the generated manpage could come later, but I think with relatively few additions this could become an incredibly useful mechanism.

• The manpage title should default to the bin_name value.
• The section should default to 1.
• The NAME section should default to bin_name \- about, where about is the string set by .about.
• The SYNOPSIS section should contain the usage strings for the command and every subcommand.
• The DESCRIPTION section would need some new paragraph-style information provided (also usable as a more structured .before_help).
• The "OPTIONS" section should document the flags and args for the top-level command.
• If the command has subcommands, a "SUBCOMMANDS" section should document each subcommand in a sub-section.
• The AUTHORS section should contain the author information, if provided.
• The SEE ALSO section would need some new mechanism to populate it.

I'd be happy to help with manpage markup, once I see the details of the mechanism used in #376.

[kbknapp]

I like this idea! I'll have a better idea about what all it would take once I finish #376 but I think it could be done. And if nothing else, it'll at least give a really good starting point that one could then tweak manually with little effort.

[joshtriplett]

Absolutely. I'm also hoping that, similar to help2man (which doesn't handle most of what clap can do), this could support providing arbitrary additional documentation to integrate into the generated manpage. That would allow maintaining information in only one place (such as options and their documentation).

[hgrecco]

I was thinking about the same thing recently and I think we can reuse much of the infrastructure done for the templated help. But I would also like to propose a different way to generate the man page (and access the completion). I am opening another issue for this.

[kbknapp]

Addressing this issue soon. I'd like to get the ability to generate man pages, help docs, etc. For the help docs, I'd especially like to be able to generate based off a template exactly like App::template works. Except recursively going through subcommands. The template would allow doing things like markdown, etc.

Also, for help docs I'd like to choice to split the files or use a single document.

[matthiasbeyer]

As far as I can see, this was moved to the 3.x release for clap? Either way, I'd like to pronounce interest in this feature. Not only for git-dit but also for imag.

[kbknapp]

@matthiasbeyer yes, this is a feature I want, but need to get 3.x out the door first because otherwise it'll just keep getting pushed off and pushed off.

[myfreeweb]

Since clap has plenty of information about the structure of commands and args and whatnot, it should be possible to build pages in the mdoc language, which is semantic (i.e. it has entities like "flags" and "commands" instead of just "bold text" etc.)

[yoshuawuyts]

Heya, on the CLI WG repo we've been working on this! It's a bit rough, but I reckon we might be able to create a compelling story!

• https://github.com/killercup/roff-rs/ exists to generate .troff files. It's a bit versose, so we built
• https://github.com/rust-clique/man The goal is to have this generate (structured) man pages. We're mostly just waiting to merge rust-clique/man#6 before it should be usable!
• We also have an initial implementation of clap v3 -> man page. Perhaps it would make sense to move it into a separate repo first, and if it works out alright we could eventually stabilize it and move it into Clap.

Screenshot

Structured man page, generated by the man crate

---

Hope this is all useful. Excited to have man page support for Clap!

[kbknapp]

@yoshuawuyts this is awesome! My thoughts were to place the manpage generation into the clap_generate crate (I'm not opposed to a rename if there is something more fitting) along with the shell completion script generation since they're doing very similar things.

If you'd like I'd be more than willing to add people to the org and repo! So we can make it official.

[yoshuawuyts]

@kbknapp oh awesome, that def seems like the right way forward! Would be happy to join in!

Also cc/ @spacekookie here (she wrote all the clap v3 -> man glue code). Perhaps you would be interested in joining?

[killercup]

@kbknapp not sure if you've seen it yet but I spend an hour yesterday to throw https://github.com/rust-clique/clap-md together -- its goal is to render Markdown documentation for clap applications. Feel free to move this to clap-generate, too! (I'd be sad to see that crate name go, though)

[kbknapp]

@killercup I love it! This is something I've been thinking about in the back of my mind that I'd love to put some time into! I've been passively looking at things like flatdoc and how other projects with large CLIs have provided docs (ones like Docker, etc.) to see if there is something we could use. But it's been on the back burner with this 3.x work 😜

I've sent out the invites to the clap-rs org to the three of you above, and yeah I'd love to move that to the org as well!