doc test parsing/displaying

[djugei]

Please complete the following tasks

• I have searched the discussions
• I have searched the open and rejected issues

Rust Version

rustc 1.73.0-nightly (8771282d4 2023-07-23)

Clap Version

4.3.19

Minimal reproducible code

/// short
///
/// ```bash
/// $ echo hi
/// $ echo ih
/// ```
#[command(version, about)]
struct Command;

Steps to reproduce the bug with the above code

cargo run -- --help

Actual Behaviour

puts the whole code block on one line, and includes ```bash and ``` in output

Expected Behaviour

puts each line in the code block on its own line, strips the ```bash and ```, possibly specially formats/highlights the code.

Additional Context

using verbatim_doc_comment solves half of this issue

somewhat similar to #2389

sidenote: clap version can not be found with grep clap Cargo.lock as instructed in the bug report form

grep 'name = "clap"' Cargo.lock -C1

works

Debug Output

No response

[epage]

How would you describe this as different than #2389? I'm inclined to close in favor of #2389

[djugei]

#2389 (comment) mentions fenced code blocks, so i somewhat agree (even though i disagree with most of the later suggestions of that specific comment). i simply did not find that part of the discussion when searching for doc test or code example.

as for differences: this is a subset of the full markdown spec that could be implemented without doing the entire thing, so if that is a direction you are interested in pursuing its different, if you intend to have full markdown support then, as i said, its just a subset of that.

i don't know how the actual code is structured, and it would need to check for a backspace in front of ``` too, but basically this does the trick:

let mut strip_newlines = true;
lines.map(|line| {
if line.contains("```") {strip_newlines = !strip_newlines}; (strip_newlines, line)
})
.do_the_strip
.filter(|(_, line)| !line.contains("```")

[epage]

For another project, I've written a code-fence subset of a markdown parser. The overall need is bigger than that in terms of we need to correctly parse hard vs soft newlines. For that, we should use a more general parser than picking at this problem a piece a time.

Closing in favor of #2389