Default template is incompatible with help2man

[ssokolow]

Rust Version

rustc 1.32.0 (9fda7c223 2019-01-16)

Affected Version of clap

2.32.0

Bug or Feature Request Summary

The lack of a blank line between the <name> <version> line in the --help output and the description block causes help2man to mistake the <name> <version> line for a word-wrapped first line of the about or long_about string.

Expected Behavior Summary

With the example from the README, this is what I get If I add \n to the end of the version string and the beginning of the about string, I get this:

MY(1)                            User Commands                           MY(1)

NAME
       My - manual page for My Super Program 1.0

DESCRIPTION
       My Super Program 1.0

       Kevin K. <kbknapp@gmail.com>

       Does awesome things

   USAGE:
              clap-test [FLAGS] [OPTIONS] <INPUT> [SUBCOMMAND]

   FLAGS:
       -h, --help
              Prints help information

       -v     Sets the level of verbosity

       -V, --version
              Prints version information

   OPTIONS:
       -c, --config <FILE>
              Sets a custom config file

   ARGS:
       <INPUT>
              Sets the input file to use

   SUBCOMMANDS:
       help   Prints this message or the help of the given subcommand(s)

       test   controls testing features

My Super Program 1.0              March 2019                             MY(1)

Ignore the oddity involving "My". help2man assumes that the first word in that line will be the command's name and the rest will be the version string, and that's both easy to accomplish and the default for anyone using StructOpt.

(The ideal solution would be to produce an AUTHORS section in the help2man output, but help2man is designed by people who probably would see author names in --help as unthinkably egotistical, so there's no provision for extracting such a section automatically.)

Actual Behavior Summary

This is help2man's output as rendered by man:

MY(1)                            User Commands                           MY(1)

NAME
       My - manual page for My Super Program 1.0

DESCRIPTION
       My Super Program 1.0 Kevin K. <kbknapp@gmail.com> Does awesome things

   USAGE:
              clap-test [FLAGS] [OPTIONS] <INPUT> [SUBCOMMAND]

   FLAGS:
       -h, --help
              Prints help information

       -v     Sets the level of verbosity

       -V, --version
              Prints version information

   OPTIONS:
       -c, --config <FILE>
              Sets a custom config file

   ARGS:
       <INPUT>
              Sets the input file to use

   SUBCOMMANDS:
       help   Prints this message or the help of the given subcommand(s)

       test   controls testing features

My Super Program 1.0              March 2019                             MY(1)

Steps to Reproduce the issue

1. Install help2man (it's in most Linux distro repositories, which makes that part easy)
2. Choose any Clap-based command which doesn't render a blank line between the about or long_about text and the stuff above it.
3. Run help2man -N 'cargo run --' > test.man; man -l test.man

Sample Code or Link to Sample Code

The code from the README which begins with // (Full example with detailed comments in examples/01b_quick_example.rs)

Debug output

As this appears to be a case of "operating as designed, but the design is flawed", I'll produce debug output on request.

[CreepySkeleton]

But should it be?

[Dylan-DPC-zz]

This might be resolved now. Not sure

[ssokolow]

@CreepySkeleton I think it makes sense for the default output template to follow a formatting convention so common among Linux commands that a tool was written which assumes it.

@Dylan-DPC It's easy to check. Run help2man (available from pretty much any distro repository) on a clap program with the default template and then run man -l <FILENAME> on the resulting file to check whether the DESCRIPTION section is messed up.

[pksunkara]

I agree with @ssokolow. But we might also have an option to just not display version and author when --help is printed.

[CreepySkeleton]

I'm triaging it for 3.0 because if we won't get to it by then, we won't get to it at all.

[pksunkara]

@logansquirel You can try this one next 😄. Really appreciate the contributions.

[logansquirel]

I need some help for this issue !

After reading all the discussion and related issues/pull requests, I do not know what I should implement.

I spent some time on this issue.
I can confirm this issue is still not resolved and the behavior described in original post is still the same with version 3.0.0-beta.2.

I tried to dive into help2man documentation/source code to understand how does it work but I won't be able to understand it deeply.

These are some ideas on top of my head:

• I change the default template to add two new line to obtain the same layout as original post.

• I provide two different templates, the old one and with the new template incorporating the two new lines only applying to --help flag (the one used by help2man). Not sure this one is viable cause it will introduce differences (breaking changes) by default between -h and --help flags.

• Completely remove author from the help output.

• I try to contact help2man authors to understand the parsing process and see if we can obtain a format more suited to help2man parsing.

• We close this issue and decide to not conform to an external tool parsing process. This path reduce maintainability cost because the help template won't be dependent to another tool. Help2man is a "simple" tool providing first generation of man page but nothing will replace the full writing of a well formatted man page by a programmer/author.

I'm opened to other ideas, I just want to know clap authors opinion on this issue.

[ssokolow]

Bear in mind that the fact that help2man exists speaks to the existence of a formatting convention widespread enough to make it practical.

Even if clap doesn't choose to explicitly support help2man, aligning itself with an established formatting convention should be considered.

(I'm assuming it's the GNU convention... just like --long and using -- to mean "end of options" rather than letting - take on a double meaning are both GNU conventions that everyone of any consequence have adopted.)

[logansquirel]

Bear in mind that the fact that help2man exists speaks to the existence of a formatting convention widespread enough to make it practical.

Even if clap doesn't choose to explicitly support help2man, aligning itself with an established formatting convention should be considered.

(I'm assuming it's the GNU convention... just like --long and using -- to mean "end of options" rather than letting - take on a double meaning are both GNU conventions that everyone of any consequence have adopted.)

I concur with this !

In this case we have to find the convention clap should use.

Then I have to find the established convention. The best description I found is directly in man-pages: man-pages
In this page, the convention states that authors is highly discouraged. Removing authors seems to be the path to follow.

@ssokolow If you have other ressources on this convention, can you point me to these ? Did you find how help2man parsed help output ? Is there some convention/well written consensus for help flag output too ?

Thanks !

Relevant links:

• help text format question
• GNU details on --version / --help flags: command line interfaces

[pksunkara]

I think we agreed on doing "I add \n to the end of the version string and the beginning of the about string" and that should fix this issue. Don't need to write any new tests either since many existing tests will be testing this anyway.

[ssokolow]

@logansquirel I haven't had time to dig deeper, so all I have on hand is:

1. The --help Recommendations section of the help2man manual.
2. The knowledge that help2man employs a Markdown-like heuristic for un-wrapping hard-wrapped lines. (That's what clap is currently running afoul of.)

Barring finding something more definitive for GNU conventions, I'd see how well docopt aligns with help2man heuristics since, if they get along, that'd give you a spec people are familiar with from other contexts.