-
Notifications
You must be signed in to change notification settings - Fork 120
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Honor single newlines in help text #214
Comments
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 |
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. |
As discussed in #207 and mentioned in #214, passing command and parameter help as function arguments is not always ideal, especially for longer help text. For parameters, you can use `.copy(help="...")`, but this is undocumented, and doesn't apply to command help. It might be better to support this officially. This PR adds `.help()` extensions to options and arguments, and makes `CliktCommand.commandHelp` open so that you can override it rather than passing the command's help to its constructor. This allows you to write your help like this: ```kotlin class Echo : CliktCommand() { override val commandHelp = "Echo the STRING(s) to standard output" val suppressNewline by option("-n").flag() .help("do not output the trailing newline") val strings by argument().multiple() .help("the strings to echo") } ```
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:
This produces
which is okay but not great.
I would prefer it to be
even in the case where the sentence wraps to like
The best I can do now it seems is create a paragraph which puts a blank line between the sentence and the default
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.
Compare that to my desired output
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!
The text was updated successfully, but these errors were encountered: