Selectively disable word wrapping

[nic-hartley]

Please complete the following tasks

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

Clap Version

4.4.4

Describe your use case

I'm trying to write a long help message that looks something like this:

Generate or restore the structure for a new blog.

This will generate a directory structure that looks something like:

$dir/
    .git/
    pages/
        README.md
    posts/
        README.md
    brb.yml
    index.md
    README.md

i.e. I want to selectively not word-wrap certain parts of the help message, while word-wrapping the rest normally.

I could also see this being useful for tables, example shell commands, psuedocode, lists, etc.

Describe the solution you'd like

I'm not sure exactly how this could look, but vaguely inspired by Markdown, perhaps some form of delimiter for the "don't wrap" part that gets deleted:

/// Generate or restore the structure for a new blog.
/// 
/// This will generate a directory structure that looks something like:
/// 
/// ```
/// $dir/
///     .git/
///     pages/
///         README.md
///     posts/
///         README.md
///     brb.yml
///     index.md
///     README.md
/// ```

If you go this route, please please make the delimiter variable/escapable (e.g. "any number of backticks > 3, ended by that number of backticks again", or "3 backticks, unless they start with a backslash" not just "exactly 3") -- granted, "```" might not be especially likely to show up in random text, but I could see it showing up in, say, a command-line Markdown parser.

Alternatives, if applicable

0. Keep the current "all or nothing" approach.

   Obviously I dislike this idea or I wouldn't be writing this issue. I think word-wrapping is generally helpful, and I think it's most helpful when it can be disabled for part of the text.

1. Per-line indicator, e.g.:

   Generate or restore the structure for a new blog.
   
   This will generate a directory structure that looks something like:
   
   ` $dir/
   `     .git/
   `     pages/
   `         README.md
   `     posts/
   `         README.md
   `     brb.yml
   `     index.md
   `     README.md
   

   This would be workable, but probably much more annoying to write and edit. And if you, like me, have your editor render whitespace, it can be hard to see, too.

2. Add another section for a block that shouldn't be word-wrapped.

   This causes two annoyances: You can't use doc comments for it anymore, which makes it much more of a pain to write and edit; and you can't just freely intersperse things like directory trees into your text, you have to make an "appendix" and then stuff everything in there.

Additional Context

No response

[nic-hartley]

Just from what I've seen of the codebase, I think this should be relatively easy to do? I feel like it'd be as easy as adding a bit of code to clap_builder::wrap to find whatever delimiter and just include raw lines? I could probably make this as a PR once the relevant design work is done.

[epage]

Taking unstructured data and adding structure to it would be a breaking change.

When we parse doc comments, we implement a hacked up subset of markdown. #2389 has us expand that and would exist only within the derive layer. This doesn't address unwrapped blocks.

However, it seems like this would be worked around on the users side by deciding on their wrap positions and their help messages. If the unwrappable blocks go past the screen edge, there isn't really any good decision on what should be done.

[nic-hartley]

@epage I'm not sure what you mean by "worked around on the user's side by deciding on their wrap positions", but to be clear I'm explicitly against requiring users to hard-wrap their own text. I like word-wrapping generally; I just don't want it to break certain parts of preformatted text.

As for building this into the pseudo-Markdown support -- that would work for all my use-cases, yep! I wasn't aware that was a thing.

[epage]

I'm not sure what you mean by "worked around on the user's side by deciding on their wrap positions", but to be clear I'm explicitly against requiring users to hard-wrap their own text. I like word-wrapping generally; I just don't want it to break certain parts of preformatted text.

Not quite.

Maybe as a starting point,it'd be good to post a reproduction case

• A minimal reproduction case program
• Example screenshot of it wrapping incorrectly.

I think having that as a baseline will make it easier to explain my thought

[nic-hartley]

Sure! So in the example in my question, I've typed it up like this:

/// Generate or restore the structure for a new blog.
/// 
/// This will generate a directory structure that looks something like:
/// 
/// $dir/
///     .git/
///     pages/
///         README.md
///     posts/
///         README.md
///     brb.yml
///     index.md
///     README.md

Which, in a wide window, renders like this:

Generate or restore the structure for a new blog.

This will generate a directory structure that looks something like:

$dir/ .git/ pages/ README.md posts/ README.md brb.yml index.md README.md

And very narrow, like this:

Generate or restore the structure
for a new blog.

This will generate a "reasonable
default" directory structure for
your new blog.

$dir/ .git/ pages/ README.md posts/
README.md brb.yml index.md
README.md

Whereas I'd like to have a way to make it look like:

Generate or restore the structure
for a new blog.

This will generate a "reasonable
default" directory structure for
your new blog.

$dir/
    .git/
    pages/
        README.md
    posts/
        README.md
    brb.yml
    index.md
    README.md

On an even narrower terminal, too small to fit the text in the tree, then the terminal wraps it how the terminal wraps it, oh well.

[epage]

The core problem here is not word wrapping but when the derive parses your doc comment, it is incorrectly identifying newlines as continuations. This is the same problem as #2389.

Going to close in favor of that issue.