Closed
Description
Maintainer notes:
- Blocked on [modular] Decouple help format from help generation #2914 for decoupling help information gathering from formatting
- help2man can be a source of inspiration for how to integrate this into a users process
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 tobin_name \- about
, whereabout
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.
Activity
kbknapp commentedon Jun 30, 2016
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 commentedon Jun 30, 2016
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 commentedon Jul 3, 2016
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 commentedon Nov 2, 2016
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.
143 remaining items