Improve indentation of help

[colin-kiegel]

I find the indentation of command like rustup override very confusing

$ rustup override
rustup-override 
Modify directory toolchain overrides

USAGE:
    rustup override [SUBCOMMAND]

FLAGS:
    -h, --help    Prints help information

SUBCOMMANDS:
    list     List directory toolchain overrides
    set      Set the override toolchain for a directory
    unset    Remove the override toolchain for a directory
    help     Prints this message or the help of the given subcommand(s)


Overrides configure rustup to use a specific toolchain when
running in a specific directory.

Directories can be assigned their own Rust toolchain with
`rustup override`. When a directory has an override then
any time `rustc` or `cargo` is run inside that directory,
or one of its child directories, the override toolchain
will be invoked.

To pin to a specific nightly:

    rustup override set nightly-2014-12-18

Or a specific stable release:

    rustup override set 1.0.0
$ _

At first glance it looks roughly like this

$ rustup override
      ... something indented
a lot of unindented text. a lot of text. a lot of text.
a lot of unindented text. a lot of text. a lot of text.
      ... something indented again
$ _

I find that extremely unreadable due to the mix of indented and unindented chunks.
I suggest to adopt the structure of a manpage, i.e. everything is indented except for headlines, which are uppercase.

The example above could look like this

$ rustup override
NAME:
    rustup-override

DESCRIPTION:
    Modify directory toolchain overrides

USAGE:
    rustup override [SUBCOMMAND]

FLAGS:
    -h, --help    Prints help information

SUBCOMMANDS:
    list     List directory toolchain overrides
    set      Set the override toolchain for a directory
    unset    Remove the override toolchain for a directory
    help     Prints this message or the help of the given subcommand(s)

DISCUSSION:
    Overrides configure rustup to use a specific toolchain when
    running in a specific directory.

    Directories can be assigned their own Rust toolchain with
    `rustup override`. When a directory has an override then
    any time `rustc` or `cargo` is run inside that directory,
    or one of its child directories, the override toolchain
    will be invoked.

    To pin to a specific nightly:

        rustup override set nightly-2014-12-18

    Or a specific stable release:

        rustup override set 1.0.0
$ _

=> Much better IMO. Now I can immediately see what belongs where. :-)
What do you think about this suggestion?

[brson]

Good idea. Depends on the capabilities of clap. Patches welcome.

[kirillbobyrev]

I agree that this would be more readable.

@kbknapp any chance you would like to adopt such structure and improve output readability in clap? If so, I'd be willing to help.

[rap2hpoutre]

@brson I checked clap docs, and did not found this sort of capability (there is only after_help which is already used). What do you think about just editing src/rustup-cli/help.rs and indent (with a DISCUSSION: title)? (anyway I'm not sure, maybe it's too quick and dirty). I could send a PR for this if you think it's OK.

[kbknapp]

I missed this issue somehow, apologies. clap doesn't support this per-se but this should work fine:

.after_help("\
DISCUSSION:
    Overrides configure rustup to use a specific toolchain when
    running in a specific directory.

    Directories can be assigned their own Rust toolchain with
    `rustup override`. When a directory has an override then
    any time `rustc` or `cargo` is run inside that directory,
    or one of its child directories, the override toolchain
    will be invoked.

    To pin to a specific nightly:

        rustup override set nightly-2014-12-18

    Or a specific stable release:

        rustup override set 1.0.0")