Bad formatting in `rustup toolchain --help`

[brson]

When I run this I see:

$ rustup toolchain --help
rustup.exe-toolchain
Modify or query the installed toolchains

USAGE:
    rustup.exe toolchain [SUBCOMMAND]

FLAGS:
    -h, --help    Prints help information

SUBCOMMANDS:
    list         List installed toolchains
    install      Install or update a given toolchain
    uninstall    Uninstall a toolchain
    link         Create a custom toolchain by symlinking to a directory
    help         Prints this message or the help of the given subcommand(s)


Many `rustup` commands deal with *toolchains*, a single installation
of the Rust compiler. `rustup` supports multiple
types of
toolchains. The most basic track the official release channels:
'stable', 'beta' and 'nightly'; but `rustup`
can also install
toolchains from the official archives, for alternate host platforms,
and from local builds.

Standard
release channel toolchain names have the following form:

    <channel>[-<date>][-<host>]

    <channel>       =
stable|beta|nightly|<version>
    <date>          = YYYY-MM-DD
    <host>          = <target-triple>

'channel' is
either a named release channel or an explicit version
number, such as '1.8.0'. Channel names can be optionally
appended with
an archive date, as in 'nightly-2014-12-18', in which case the
toolchain is downloaded from the archive
for that date.

Finally, the host may be specified as a target triple. This is most
useful for installing a 32-bit
compiler on a 64-bit platform, or for
installing the [MSVC-based toolchain] on Windows. For example:

    rustup
toolchain install stable-x86_64-pc-windows-msvc

For convenience, elements of the target triple that are omitted will
be
inferred, so the above could be written:

    $ rustup default stable-msvc

Toolchain names that don't name a
channel instead can be used to name
custom toolchains with the `rustup toolchain link` command.

Lots of bad line breaks. cc @Diggsey probably from the markdown processing?

[brson]

Hm, actually I don't think this runs through markdown. Is clap doing this?

[Diggsey]

Yeah it looks like it's a feature of clap that it will wrap help text, it's in the 2.6 changelist.

[Boddlnagg]

This also happens for other commands, e.g. part of the output of rustup override:

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

To see the active toolchain use `rustup show`. To remove the override
and use the default toolchain again,
`rustup override unset`.

[kbknapp]

This could be from the default term width being set to 120 in places like Windows where the term width isn't known. There are ways to override that if that is in fact what's happening. I'll look into this once I'm not on mobile and post back with what I find.

[kbknapp]

So I did some checking, and it's because there are hard newlines in the formatted text, which I'm assuming are coming from the markdown or elsewhere. Then clap also inserts newlines every 120 when it can't determine the term width.

So one of three things would fix it

• Remove the hard new lines from the markdown
• Do option 1, but also set clap to wrap at 80 or 100 (which is what I'm assuming the markdown is set for)
• I can add an option to tell clap not to wrap no matter what and just use whatever formatting is provided.

There are pros and cons to each method. The biggest drawback of keeping the hard newlines is that on platforms where the term width can be determined (OSX, Linux, etc.), one could end up with weird formatting on lower resolution terminals, or one is responsible for keeping the formatting correct manually.

[kbknapp]

This has been fixed with clap v2.10.3

One can now use App::set_term_width(0) which won't wrap the help text at all, and just use the source formatting. This should probably only be done on those subcommands which use custom markdown formatting in the before_help or after_help methods. Also note, this setting is propagated down through all child subcommands.

[brson]

@kbknapp Thank you <3

The next step here is to upgrade clap and set the term width per @kbknapp's direction. It looks to me like some of the text in help.rs is wrapped at different columns. Probably best to rewrap everything to ... 70 maybe. Then do a manual check of all the --help commands and see if it looks decent.

But I wonder if this is the right approach and we shouldn't let clap do its wrapping. I suspect if we did the output would look unpleasing on wide screens. Really the best of all world would be for the output to use the wrapping as-written, unless the screen is narrow, then rewrap the paragraphs, but not the examples, or .. I don't know. Gets complicated.

[kbknapp]

@brson I've just put in a PR for clap to help with this issue. See clap-rs/clap#650

This allows clap to ignore hard newlines, or rather treat them like inserted newlines by properly wrapping and aligning text and then restarting it's count until the next newline should be inserted. But it will also still wrap appropriately if the term width is smaller than the hard newlines allow. The one thing it won't change, it won't remove those hard newlines upon wrapping, but it still looks better than it did and I'd say solves this issue for the most part.

Ref See clap-rs/clap#617

Once the PR merges I'll put v2.11.3 on crates.io

[brson]

@kbknapp Thank you!

[kbknapp]

clap v2.11.3 is up on crates.io. Please let me know if this doesn't fix the issue, or something needs to be changed.