Can picocli support a short (synopsis) description and a longer detailed description for a subcommand.

[pford19]

Problem:

Support two descriptions for a subcommand,

• a synopsis for use in the parent's usage message commands section,
• a longer description for use it its own usage message description section

I'm new to picocli, so maybe there is a way to do this, but I haven't figured it out yet reading the docs and experimenting. Seems like help parsing and usage message generation happen before any call to the subcommand (my subcommands are annotated classes that implement Callable), and in fact short circuit that call. Hard to see where I can inject control and alter the description in the usage message based on the invocation context.

I was able to crudely approximate this with an additional --long-help option, but it couldn't be usageHelp = true and the command line needed to be fully valid. This crude approximation demonstrated the ability to alter the description in the usage message, albeit too late to be helpful as a help message.

Context:

• root command with subcommands sub1 and CommandLine.HelpCommand.
• sub1 command with various options and parameters
• sub1 has a synopsis description: "Short synopsis."
• sub1 has a longer detailed description: "Longer more detailed description of sub1. Etc., etc."

For root help, expect output along the lines of

> root help
Usage: root <command>
Description:
  Root command.
Commands:
   help         Display help information about the specified command.
   sub1         Short synopsis.

For root help sub1, it would be nice to have ouput that used the long description in the description section

> root help sub1
Usage: root sub1 <options> <parameters>
Description:
  Longer more detailed description of sub1. Etc., etc.
Options: ...
Parameters: ...

[remkop]

From memory: I believe that if you set help=true (instead of usageHelp = true) on your --long-help option, the command line does not need to be valid, but it won't short-circuit and your command will be invoked.
This should give you the chance to print a custom help message.

[pford19]

Will give it a try.

[pford19]

That does the trick. Thanks for the tip.

[pford19]

Rereading picolo.info, I see help = true mentioned in section 12.1 Help Options. Which includes the important fact that its presence turns of full validation of the parse.

But that is the only mention in the documentation. All the examples show usageHelp and versionHelp. The source code nicely documents the full semantics of the help option, once I knew to look for it.

I guess there is an opportunity to provide a bit more explanation to the already very well written and extensive documentation.

[remkop]

Oh that would be great!
If you are able to provide a pull request to improve the examples or documentation that would be very welcome!