fix: Compatibility with help2man #2369

logansquirel · 2021-02-27T08:49:41Z

Fix compatibility with help2man output (see #1432)

Change default help template:
The new template introduce new lines before and after
author/about sections.
Add help template placeholders:
- about-section
- author-section
Documentation of new placeholders in clap::App::help_template
Update all unit tests by incorporating new lines

Issue

When help2man parses standard clap help template, the generated man page unwraps {binary_name} {version} {author} {about} placeholders.

Source code

❯ tree clap_issue_1432
clap_issue_1432
├── Cargo.lock
├── Cargo.toml
├── src
|   └── main.rs
└── test.man

1 directory, 4 files

The main.rs source file:

use clap::App;
use clap::AppSettings;
use clap::Arg;

fn main() {
    let app = App::new("command")
        .author("command author")
        .version("1.2.3")
        .about("command about")
        .setting(AppSettings::DisableHelpSubcommand)
        .arg(
            Arg::new("flag")
                .about("command flag")
                .short('f')
                .long("flag"),
        )
        .arg(
            Arg::new("option")
                .about("command option")
                .short('o')
                .long("option")
                .takes_value(true),
        )
        .arg(
            Arg::new("positional")
                .about("command positional")
                .takes_value(true),
        )
        .subcommand(
            App::new("subcommand")
            .about("subcommand")
        );
    app.get_matches();
}

With version `3.0.0-beta.2`

❯ cargo run --quiet -- --help
command 1.2.3
command author
command about

USAGE:
    clap_issue_1432 [FLAGS] [OPTIONS] [positional] [SUBCOMMAND]

ARGS:
    <positional>    command positional

FLAGS:
    -f, --flag       command flag
    -h, --help       Prints help information
    -V, --version    Prints version information

OPTIONS:
    -o, --option <option>    command option

SUBCOMMANDS:
    subcommand    subcommand

❯ cargo run --quiet -- --version
command 1.2.3

❯ help2man -N 'cargo run --' > test.man

❯ cat test.man
.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.48.1.
.TH COMMAND "1" "February 2021" "command 1.2.3" "User Commands"
.SH NAME
command \- manual page for command 1.2.3
.SH DESCRIPTION
command 1.2.3
command author
command about
.SS "USAGE:"
.IP
clap_issue_1432 [FLAGS] [OPTIONS] [positional] [SUBCOMMAND]
.SS "ARGS:"
.TP
<positional>
command positional
.SS "FLAGS:"
.TP
\fB\-f\fR, \fB\-\-flag\fR
command flag
.TP
\fB\-h\fR, \fB\-\-help\fR
Prints help information
.TP
\fB\-V\fR, \fB\-\-version\fR
Prints version information
.SS "OPTIONS:"
.TP
\fB\-o\fR, \fB\-\-option\fR <option>
command option
.SS "SUBCOMMANDS:"
.TP
subcommand
subcommand

❯ man ./test.man

The man page:

COMMAND(1)                                                                           User Commands                                                                           COMMAND(1)

NAME
       command - manual page for command 1.2.3

DESCRIPTION
       command 1.2.3 command author command about

   USAGE:
              clap_issue_1432 [FLAGS] [OPTIONS] [positional] [SUBCOMMAND]

   ARGS:
       <positional>
              command positional

   FLAGS:
       -f, --flag
              command flag

       -h, --help
              Prints help information

       -V, --version
              Prints version information

   OPTIONS:
       -o, --option <option>
              command option

   SUBCOMMANDS:
       subcommand
              subcommand

command 1.2.3                                                                        February 2021                                                                           COMMAND(1)

Note the description in the man page.

With this pull request

❯ cargo run --quiet -- --help
command 1.2.3

command author

command about

USAGE:
    clap_issue_1432 [FLAGS] [OPTIONS] [positional] [SUBCOMMAND]

ARGS:
    <positional>    command positional

FLAGS:
    -f, --flag       command flag
    -h, --help       Prints help information
    -V, --version    Prints version information

OPTIONS:
    -o, --option <option>    command option

SUBCOMMANDS:
    subcommand    subcommand

❯ cargo run --quiet -- --version
command 1.2.3

❯ help2man -N 'cargo run --' > test.man

❯ cat test.man
.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.48.1.
.TH COMMAND "1" "February 2021" "command 1.2.3" "User Commands"
.SH NAME
command \- manual page for command 1.2.3
.SH DESCRIPTION
command 1.2.3
.PP
command author
.PP
command about
.SS "USAGE:"
.IP
clap_issue_1432 [FLAGS] [OPTIONS] [positional] [SUBCOMMAND]
.SS "ARGS:"
.TP
<positional>
command positional
.SS "FLAGS:"
.TP
\fB\-f\fR, \fB\-\-flag\fR
command flag
.TP
\fB\-h\fR, \fB\-\-help\fR
Prints help information
.TP
\fB\-V\fR, \fB\-\-version\fR
Prints version information
.SS "OPTIONS:"
.TP
\fB\-o\fR, \fB\-\-option\fR <option>
command option
.SS "SUBCOMMANDS:"
.TP
subcommand
subcommand

❯ man ./test.man

The man page:

COMMAND(1)                                                                           User Commands                                                                           COMMAND(1)

NAME
       command - manual page for command 1.2.3

DESCRIPTION
       command 1.2.3

       command author

       command about

   USAGE:
              clap_issue_1432 [FLAGS] [OPTIONS] [positional] [SUBCOMMAND]

   ARGS:
       <positional>
              command positional

   FLAGS:
       -f, --flag
              command flag

       -h, --help
              Prints help information

       -V, --version
              Prints version information

   OPTIONS:
       -o, --option <option>
              command option

   SUBCOMMANDS:
       subcommand
              subcommand

command 1.2.3                                                                        February 2021                                                                           COMMAND(1)

Note:

new lines appeared in --help output and it is the same for -h flag
version output is unchanged
the generated man page output include paragraph separators between command version, command authors and command about (.PP)
the generated man page is correctly formatted

Solution

Following changes were included in this pull request:

Change default template:

from:

{before-help}{bin} {version}\n\
{author-with-newline}{about-with-newline}\n\
{usage-heading}\n    {usage}\n\
\n\
{all-args}{after-help}\

to

{before-help}{bin} {version}\n\
{author-section}\
{about-section}\n\
{usage-heading}\n    {usage}\n\
\n\
{all-args}{after-help}\

Following help template placeholders were added and documented during development:
- {author-section}
- {about-section}
All unit tests relying on --help format were edited to include new lines.

logansquirel · 2021-02-27T09:01:59Z

While editing this pull request I noted that in the man page, the USAGE section is more indented:

   USAGE:
              clap_issue_1432 [FLAGS] [OPTIONS] [positional] [SUBCOMMAND]

   ARGS:
       <positional>
              command positional

if we compare USAGE indentation and ARGS indentation.

It seems, help2man parsing process expect USAGE and arguments/option/flag sections to have different indentations.

ldm0

Looks good. Some minor things.

src/output/help.rs

src/build/app/mod.rs

src/output/help.rs

Change default help template: - The new template introduce new lines before and after author/about sections. - Add help template placeholders: - about-section - author-section - Documentation of new placeholders in clap::App::help_template - Update all unit tests by incorporating new lines

logansquirel · 2021-02-27T19:07:33Z

@pksunkara Feel free to point me to other issues that need my contributions.

When we got clap-rs#3193, we decided in clap-rs#3196 that `--help` will give a summary for other commands (`subcmd --help` in this case) but not show the long version of the output for that other command. Now with clap-rs#3215, I think the case is similar for `--help` not showing the long version but instead preferring the short version and encouraging people to run `--version`. Originally. clap only showed the short version or nothing. This was changed in clap-rs#2369 without fanfare to prefer the long version over short. Now are we preferring short version over the long version always, just like all other help. Fixes clap-rs#3215

ldm0 self-requested a review February 27, 2021 12:13

ldm0 reviewed Feb 27, 2021

View reviewed changes

src/output/help.rs Outdated Show resolved Hide resolved

src/output/help.rs Show resolved Hide resolved

pksunkara requested changes Feb 27, 2021

View reviewed changes

src/build/app/mod.rs Outdated Show resolved Hide resolved

src/output/help.rs Outdated Show resolved Hide resolved

logansquirel added 2 commits February 27, 2021 16:20

Fix App::version/long_version test

52e74fa

pksunkara approved these changes Feb 27, 2021

View reviewed changes

pksunkara merged commit c9e875e into clap-rs:master Feb 27, 2021

epage mentioned this pull request Jul 27, 2021

Rendering doc chapter is confusing rust-cli/book#61

Open

epage mentioned this pull request Dec 14, 2021

Too much whitespace in output #3096

Closed

2 tasks

epage mentioned this pull request Dec 24, 2021

long_help() output includes output from long_version() instead of short_version() #3215

Closed

2 tasks

epage mentioned this pull request Dec 30, 2021

fix(help): Prefer short version over long version #3232

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

fix: Compatibility with help2man #2369

fix: Compatibility with help2man #2369

logansquirel commented Feb 27, 2021 •

edited

Loading

logansquirel commented Feb 27, 2021 •

edited

Loading

ldm0 left a comment

logansquirel commented Feb 27, 2021

fix: Compatibility with help2man #2369

fix: Compatibility with help2man #2369

Conversation

logansquirel commented Feb 27, 2021 • edited Loading

Issue

Source code

With version 3.0.0-beta.2

With this pull request

Solution

logansquirel commented Feb 27, 2021 • edited Loading

ldm0 left a comment

Choose a reason for hiding this comment

logansquirel commented Feb 27, 2021

logansquirel commented Feb 27, 2021 •

edited

Loading

With version `3.0.0-beta.2`

logansquirel commented Feb 27, 2021 •

edited

Loading