Allow preserving newlines

[konstin]

The have the following docstring:

    /// Control the platform tag on linux.
    ///
    ///  - `1`: Use the manylinux1 tag and check for compliance
    ///  - `1-unchecked`: Use the manylinux1 tag without checking for compliance
    ///  - `2010`: Use the manylinux2010 tag and check for compliance
    ///  - `2010-unchecked`: Use the manylinux1 tag without checking for compliance
    ///  - `off`: Use the native linux tag (off)
    ///
    /// This option is ignored on all non-linux platforms

This renders fine in rustdoc:

Structopt however collapses those lines:

        --manylinux <manylinux>
            Control the platform tag on linux. - `1`: Use the manylinux1 tag and check for compliance - `1-unchecked`:
            Use the manylinux1 tag without checking for compliance - `2010`: Use the manylinux2010 tag and check for
            compliance - `2010-unchecked`: Use the manylinux1 tag without checking for compliance - `off`: Use the
            native linux tag (off)

            This option is ignored on all non-linux platforms [default: 1]  [possible values: 1, 1-unchecked, 2010,
            2010-unchecked, off]

Since I fear that full markdown to text rendering like pandoc is currently out of scope, it would great to have a way to preserve newlines.

[TeXitoi]

I agree with the feature request, but I don't have any solution. Do you have any proposition?

[konstin]

One idea would be #[structopt(preserve_newlines)] on the field. Another, less rustdoc-friendly would be some thing like clap-rs/clap#617 (comment). i.e. replacing \n or {n} with newlines.

[TeXitoi]

{n} will work out of the box, but will be rendered by rustdoc. \n is irrelevant as that's a string escape.

Now, a workaround is using #[structopt(help = "Some help\nwith\nnew\nlines"). You can even use some statics with raw strings:

use structopt::StructOpt;

static MANYLINUX_HELP: &str = r#"Control the platform tag on linux.

 - `1`: Use the manylinux1 tag and check for compliance
 - `1-unchecked`: Use the manylinux1 tag without checking for compliance
 - `2010`: Use the manylinux2010 tag and check for compliance
 - `2010-unchecked`: Use the manylinux1 tag without checking for compliance
 - `off`: Use the native linux tag (off)

This option is ignored on all non-linux platforms"#;

#[derive(StructOpt, Debug)]
struct Opt {
    #[structopt(long, raw(help = "MANYLINUX_HELP"))]
    manylinux: Option<String>,
}

fn main() {
    let opt = Opt::from_args();
    println!("{:?}", opt);
}

But it will not be used as doc comment.

Something like #[structopt(raw_doc_comment)] or #[structopt(no_doc_comment_reformating) are plausible candidates.

[konstin]

{n} will work out of the box,

Huh I thought I had checked that this doesn't work but apparently it does, so I'll go with that for now. Thanks!

[Geobert]

as raw is only allowed with true or false in structopt 0.3, how do we do the workaround now?

[CreepySkeleton]

Via raw methods:

use structopt::StructOpt;

static MANYLINUX_HELP: &str = r#"Control the platform tag on linux.

 - `1`: Use the manylinux1 tag and check for compliance
 - `1-unchecked`: Use the manylinux1 tag without checking for compliance
 - `2010`: Use the manylinux2010 tag and check for compliance
 - `2010-unchecked`: Use the manylinux1 tag without checking for compliance
 - `off`: Use the native linux tag (off)

This option is ignored on all non-linux platforms"#;

#[derive(StructOpt, Debug)]
struct Opt {
    #[structopt(long, help = MANYLINUX_HELP)] // <---
    manylinux: Option<String>,
}

fn main() {
    let opt = Opt::from_args();
    println!("{:?}", opt);
}

Come on, people, does anyone read docs these days?

[Geobert]

Thanks, I've read the docs, multiple times, but missed it. (English is not my mothertongue, please bear with me)

[CreepySkeleton]

Thanks, I've read the docs, multiple times, but missed it

I believe this is a clear indication that our docs aren't as great as we thought they are. We need to improve them, probably along with the error message.

[CreepySkeleton]

@TeXitoi I propose to implement #[structopt(doc_verbatim)], raw... names too strongly correlate with "raw methods" in my opinion.

cc @TeXitoi

[TeXitoi]

OK for doc_verbatim