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?