Too much whitespace in output

[epage]

Please complete the following tasks

• I have searched the discussions
• I have searched the existing issues

Rust Version

rustc 1.55.0 (c8dfcfe04 2021-09-06)

Clap Version

3.0.0-rc.0

Minimal reproducible code

use structopt::StructOpt;

#[derive(StructOpt, Debug)]
#[structopt(author, about)]
struct Opt {}

fn main() {
    let opt = Opt::from_args();
    dbg!(opt);
}

Steps to reproduce the bug with the above code

cargo run -- --help

Actual Behaviour

test-clap 0.1.0      
                                                                         
Me                                                                       
                                    
From Cargo.toml
                                                                         
USAGE:                                                                   
    test-clap                       
                                                                         
OPTIONS:             
    -h, --help       Print help information                              
    -V, --version    Print version information                

Expected Behaviour

Note quite but similar to clap2 which is

test-clap 0.1.0                                                          
Me                   
From Cargo.toml
                                                                         
USAGE:                                                                   
    test-clap                       
                                                                         
FLAGS:               
    -h, --help       Prints help information                             
    -V, --version    Prints version information

Maybe

test-clap 0.1.0                                                          
Me                   

From Cargo.toml
                                                                         
USAGE:                                                                   
    test-clap                       
                                                                         
FLAGS:               
    -h, --help       Prints help information                             
    -V, --version    Prints version information

or

test-clap 0.1.0 - From Cargo.toml 
Me                   
                                                                         
USAGE:                                                                   
    test-clap                       
                                                                         
FLAGS:               
    -h, --help       Prints help information                             
    -V, --version    Prints version information

Additional Context

This came from reddit.

Debug Output

No response

[pksunkara]

This is intentional IIRC because of #1432

[epage]

Thanks for the context; I had assumed it was done for a reason but hadn't looked yet.

I still think this is worth having as an issue as it is a regression. We are balancing competing needs and maybe we can find a third way (without just adding a flag)

Granted, once we get proper man generation, it'll lower the reliance on help2man

[joshtriplett]

This seems like a regression to me as well. Vertical space is precious in help output, especially for commands with lots of options or subcommands.

[epage]

Here is an example of what help2man parses

$ foo --version
GNU foo 1.1

Copyright (C) 2011 Free Software Foundation, Inc.
This is free software; see the source for copying conditions.  There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

Written by A. Programmer.
$ foo --help
GNU `foo' does nothing interesting except serve as an example for
`help2man'.

Usage: foo [OPTION]...

Options:
  -a, --option      an option
  -b, --another-option[=VALUE]
                    another option

      --help        display this help and exit
      --version     output version information and exit

Examples:
  foo               do nothing
  foo --option      the same thing, giving `--option'

Report bugs to <bug-gnu-utils@gnu.org>.

From https://www.gnu.org/software/help2man/

[I60R]

Looks ugly enough to stay with the current version of structopt instead.

Also, what is the point in having man page that completely mirrors --help output?

[epage]

Also, what is the point in having man page that completely mirrors --help output?

I don't think the intent is to be exactly --help but to be a superset. help2man supports including additional content. Its fairly standard for man pages to include a --help like output, so its reasonable for wanting to generate that to keep it up to date just like people generate --help output.

[epage]

Random notes as I research help2man to see if there is any way to reconcile the two needs

help2man's docs sound like they want the organization to be

1. usage
2. about
3. args
4. additional help text (our after_long_help)
5. examples
6. contact or bug reporting

I'm also seeing this pattern in docker. vim shows user-facing name - version first with no about. git doesn't seem to provide a name or about. Trying to think of what other programs to look at.

I wonder what we can do to encourage examples

From help2man's docs

Use argv[0] for the program name in these synopses, just as it is, with no directory stripping. This is in contrast to the canonical (constant) name of the program which is used in --version.

Interesting. They want the usage to use argv[0] but everywhere else to the use actual name.

For us, we show the bin name as the application name (see #992). Our bin name is argv[0].file_name() though with #992 I am considering changing it to argv[0].file_stem() or similar.

From help2man's docs

It is usually best to alphabetise (by short option name first, then long) within each section, or the entire list if there are no sections.

Interesting input for #2808

Now in running help2man

clap2 output

.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.47.13.
.TH TEST-CLAP "1" "December 2021" "test-clap 0.1.0" "User Commands"      
.SH NAME
test-clap \- manual page for test-clap 0.1.0
.SH DESCRIPTION                  
test\-clap 0.1.0                                                         
Me                                                                       
From Cargo.toml                     
.SS "USAGE:"                                                             
.IP                                                                      
test\-clap                                                               
.SS "FLAGS:"                       
.TP                                 
\fB\-h\fR, \fB\-\-help\fR
Prints help information
.TP
\fB\-V\fR, \fB\-\-version\fR
Prints version information
.SH "SEE ALSO"
The full documentation for
.B test-clap
is maintained as a Texinfo manual.  If the
.B info
and
.B test-clap
programs are properly installed at your site, the command
.IP
.B info test-clap
.PP
should give you access to the complete manual.

clap3 output

.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.47.13.
.TH TEST-CLAP "1" "December 2021" "test-clap 0.1.0" "User Commands"
.SH NAME
test-clap \- manual page for test-clap 0.1.0
.SH DESCRIPTION
test\-clap 0.1.0
.PP
Me
.PP
From Cargo.toml
.SS "USAGE:"
.IP
test\-clap
.SS "OPTIONS:"
.TP
\fB\-h\fR, \fB\-\-help\fR
Print help information
.TP
\fB\-V\fR, \fB\-\-version\fR
Print version information
.SH "SEE ALSO"
The full documentation for
.B test-clap
is maintained as a Texinfo manual.  If the
.B info
and
.B test-clap
programs are properly installed at your site, the command
.IP
.B info test-clap
.PP
should give you access to the complete manual.

The only difference is the insertion of .PP. It looks like this is just about having paragraph marks between distinct data so it doesn't merge the lines.

Between people being able to override the help template (including when just code-genning their man page) and #3174, I'm inclined to revert the template change in #2369, so we go back to the clap2 output.

That said, I am all for ideas for overall improvement of the help output!