Multiline descriptions for options.

[martinklepsch]

Thanks for this library @l3nz, it's really quite fantastic how easy and concise it makes all this stuff, I added an improved CLI interface to cljdoc using it: https://github.com/cljdoc/cljdoc/commit/1ce56b8bb0a085c17ad93894f5b1a8a13dcd10c7

For some subcommands I'd like to specify longer descriptions, spanning a couple of lines. I was wondering if there's any tooling or plans around this?

I could construct a :description string with linebreaks myself but I think cli-matic could help with the following aspects:

• trim leading whitespace in some smart way (maybe codox' approach is sufficient)
• automatically break lines longer than 80 characters
• maintain the one-character indentation under NAME:

FWIW there could also be a new key :usage for longer text, reserving :description for a one-line overview.

Unrelated feedback: it took me a while to spot the :default :present variant in the README when trying to figure out how to make options mandatory. Maybe introducing another key :required? or so would make this easier.

[l3nz]

Hi Martin, we have something similar for the app itself - https://github.com/l3nz/cli-matic/issues/11 - where the idea is that you either have a string or a sequence of strings.

What we could do is something like:

:description [”Lorem ipsum dolor sit amet."
               "Consectetur adipiscing elit, sed do eiusmod tempor" 
               "incididunt ut labore et dolore magna aliqua. Ut enim" 
               "ad minim veniam, quis nostrud exercitation ullamco."] 

That would print:

NAME:
 recap info - Prints general information

USAGE:
 recap [info|i] [command options] querystring ...

OPTIONS:
       --querystring S*  Lorem ipsum dolor sit amet.
               Consectetur adipiscing elit, sed do eiusmod tempor 
               incididunt ut labore et dolore magna aliqua. Ut enim 
               ad minim veniam, quis nostrud exercitation ullamco. 
   -?, --help

Where following lines have a fixed indentation. This would be very easy to implement.

I am not a fan of reformatting over 80 columns, as I usually use larger terminals.

[l3nz]

We also have to decide how to print the environment variable if the option is tied to an environment variable - see mk-env-name - that at the moment would just add it to the last line.

       --querystring S*  Lorem ipsum dolor sit amet. 
               Consectetur adipiscing elit, sed do eiusmod tempor 
               incididunt ut labore et dolore magna aliqua. Ut enim 
               ad minim veniam, quis nostrud exercitation ullamco. [$QUERY]

But maybe the first line is better:

OPTIONS:
       --querystring S*  Lorem ipsum dolor sit amet. [$QUERY]
               Consectetur adipiscing elit, sed do eiusmod tempor 
               incididunt ut labore et dolore magna aliqua. Ut enim 
               ad minim veniam, quis nostrud exercitation ullamco.

[martinklepsch]

I actually mostly cared about longer docstrings for subcommands, not options to those commands (although that may be useful).

The current implementation (joining a list of strings with line breaks) is fine for my uses so feel free to close this 👍

[l3nz]

Thanks for using Cli-matic anyway :-)

[martinklepsch]

Thanks for making it, it's awesome! :clap: