Next-line help is always used despite no long-help being shown (despite long_about being set on a subcommand)

[epage]

Discussed in #3178

clap version

master

rust version

rustc 1.59.0-nightly (404c8471a 2021-12-14)

Minimal Reproducible Code

use clap::StructOpt;

#[derive(StructOpt, Debug)]
pub struct Opts {
    #[structopt(subcommand)]
    pub subcmd: SubCommand,
}

#[derive(StructOpt, Debug)]
pub struct SampleSubcmd {
    testopt: Option<String>,
}

#[derive(StructOpt, Debug)]
pub enum SubCommand {
    /// With just this line everything renders normally
    ///
    /// THIS NEW PARAGRAPH CHANGES FORMATTING
    Subcmd(SampleSubcmd),
}

fn main() {
    let _opts = Opts::from_args();
}

Reproduction steps

$ cargo run -- --help

Expected Behavior

test-clap 0.1.0

USAGE:
    test-clap <SUBCOMMAND>

FLAGS:
    -h, --help       Prints help information
    -V, --version    Prints version information

SUBCOMMANDS:
    help      Prints this message or the help of the given subcommand(s)
    subcmd    With just this line everything renders normally

Actual Behavior

test-clap 

USAGE:
    test-clap <SUBCOMMAND>

OPTIONS:
    -h, --help
            Print help information

SUBCOMMANDS:
    help
            Print this message or the help of the given subcommand(s)
    subcmd
            With just this line everything renders normally

Context

clap2 shows args on next line but not subcommands.

Note that long_about is being set but isn't being shown.

Looks like this is a bug in clap3.

This has levels of fixes

1. Ignore next_line_help for subcommands to get to clap2's behavior
2. Ignore subcommands when calculating whether to use next_line_help since short help has precedence over long help (fixes the issue reported here)
3. Actually respect short vs long with subcommands and show "THIS NEW PARAGRAPH CHANGES FORMATTING" (I worry there is a reason this wasn't done that is eluding me)

The next part to consider is whether

• args and subcommands should infer next_line_help separately
• whether we should stop doing global next_line_help inferring and leave it to the individual args

[epage]

@pksunkara wanted to check in in case you had any extra context on

• why subcommands give precedence to about on --help, unlike args
• why next_line_help is being used by subcommands even if we don't show long_about

If curious, you can see my comment in the discussion for what this looks like in clap2 and clap3 with and without long_about being set (about is always set)

[epage]

I guess the reason to unconditionally give precedence to about over long_about in --help is that the subcommands are just giving you a hint of the help and its expected that you then call --help on that subcommand.