colin-kiegel · GitHub

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?

Read the original on github.com ↗