Honor single newlines in help text

[JakeWharton]

I read #67, but I have a slightly different case that I thought I would bring up. I generally understand skipping whitespace and reflowing, but I'm having a hard time justifying the fact that single newlines are also ignored.

I have help text that looks like this:

private val repoUrl by option("--repo", metavar = "URL")
    .copy(help = "URL of maven repository to check (default is Maven Central)")
    .convert { it.toHttpUrl() }
    .default("https://repo1.maven.org/maven2/".toHttpUrl())

This produces

  --repo URL           URL of maven repository to check (default is Maven
                       Central)

which is okay but not great.

I would prefer it to be

  --repo URL           URL of maven repository to check
                       (default is Maven Central)

even in the case where the sentence wraps to like

  --repo URL           URL of maven repository to blah blah blah
                       check
                       (default is Maven Central)

The best I can do now it seems is create a paragraph which puts a blank line between the sentence and the default

  --repo URL           URL of maven repository to check

                       (default is Maven Central)

On its own this looks okay, but when you put it up against a bunch of options the empty lines become visual gaps and your eyes scan and try to group the defaults with the sentence below it.

Options:
  --data PATH          Directory into which already-seen versions are tracked

                       (default in-memory)
  --interval DURATION  Amount of time between checks in ISO6801 duration
                       format

                       (default 1 minute)
  --repo URL           URL of maven repository to check

                       (default is Maven Central)
  -h, --help           Show this message and exit

Compare that to my desired output

Options:
  --data PATH          Directory into which already-seen versions are tracked
                       (default in-memory)
  --interval DURATION  Amount of time between checks in ISO6801 duration
                       format
                       (default 1 minute)
  --repo URL           URL of maven repository to check
                       (default is Maven Central)
  -h, --help           Show this message and exit

So the request here is to honor \n as a single newline when present. I'm wondering if there's something I'm missing the enables this functionality today? Or perhaps any backstory to shed light on why this isn't supported/can't be supported.

Thanks!

[ajalt]

The reason single newlines are ignored is to allow you to wrap paragraphs you write however you want, and have them reflow automatically.

For example, maybe your code style requires hard wraps at 72 characters. You can write your code with line wraps wherever you want, like this:

private val clikt by option(
    help = """
        Clikt (pronounced "clicked") is a multiplatform Kotlin library 
        that makes writing command line interfaces simple and intuitive.

        It is designed to make the process of writing command line tools 
        effortless while supporting a wide variety of use cases and 
        allowing advanced customization when needed.
    """)

And the help output will reflow the individual paragraphs to your terminal width. If we always broke on single newlines, people would be forced to write all paragraphs on a single line for them to reflow properly.

We could support your use-case of a single forced line break by using something other than \n. Maybe one of the other unicode line terminators like NEL or LS? I'm open to suggestions.

[JakeWharton]

Ah, yes. That makes sense. I guess I'm not writing long-enough help text!

Having either NEL or LS would be great. I lean toward NEL since in the ASCII set.