Fenced code blocks in argument documentation

[epage]

Issue by jonhoo
Saturday Mar 02, 2019 at 20:54 GMT
Originally opened as TeXitoi/structopt#166

---

I have an option that I want to include some example code for (TOML specifically), but it seems like structopt (or maybe clap?) eliminates all of the newlines for it. Could we maybe detect fenced code blocks and change the newline handling rules for that segment of the help text?

#[derive(StructOpt, Debug)]
#[structopt(name = "extractor")]
struct Opt {
    /// Meta file describing the sheets.
    ///
    /// The file should be of the form:
    ///
    /// ```toml
    /// [first_file]
    /// left = [
    ///     # this is row 1 of the left-hand side page
    ///     [
    ///         # these are the tokens in row 1
    ///         "first_token",
    ///         "second_token",
    ///         # the number of columns indicates whether they are big or small
    ///         # (5 | 6 is small, <= 4 is big)
    ///         # to ignore an element, use:
    ///         "",
    ///     ],
    ///     # this is row 2 of the left page
    ///     [
    ///         # ...
    ///     ]
    /// ],
    /// right = [
    ///     # rows of right-hand side page ...
    /// ]
    /// ```
    ///
    /// Files (like `first_file`) are expected to reside adjacent to the TOML file and have a `jpg`
    /// extension.
    #[structopt(parse(from_os_str), default_value = "images/meta.toml")]
    meta: PathBuf,
}

[epage]

Comment by TeXitoi
Sunday Mar 03, 2019 at 09:01 GMT

---

Related to #163

You'll find some workaround on this issue.

[pksunkara]

This is a dupe of #2389. There's a lot of context in #2401 too as pointed out in that issue.

[epage]

Closing in favor of #2389