Skip to content
/ clap Public
  • Rate limit · GitHub

    Access has been restricted

    You have triggered a rate limit.

    Please wait a few minutes before you try again;
    in some cases this may take up to an hour.

  • Notifications You must be signed in to change notification settings
  • Fork 1.1k

Auto-generate manpage, help docs, etc. #552

Closed
@joshtriplett

Description

@joshtriplett

Maintainer notes:


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.

Activity

kbknapp

kbknapp commented on Jun 30, 2016

@kbknapp
Member

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

joshtriplett commented on Jun 30, 2016

@joshtriplett
ContributorAuthor

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

hgrecco commented on Jul 3, 2016

@hgrecco
Contributor

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.

changed the title Auto-generate manpage Auto-generate manpage, help docs, etc. on Nov 2, 2016
kbknapp

kbknapp commented on Nov 2, 2016

@kbknapp
Member

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.

added and removed
E-hardCall for participation: Experience needed to fix: Hard / a lot
on Nov 2, 2016

143 remaining items

Loading
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    A-helpArea: documentation, including docs.rs, readme, examples, etc...C-enhancementCategory: Raise on the bar on expectationsS-blockedStatus: Blocked on something else such as an RFC or other implementation work.

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions

      Auto-generate manpage, help docs, etc. · Issue #552 · clap-rs/clap