From d8d0c9371149ebdd356d83b2708829519f2e37e7 Mon Sep 17 00:00:00 2001 From: Remko Popma Date: Sun, 30 Dec 2018 18:11:54 +0900 Subject: [PATCH] #530 improve documentation for customizing the usage help message Closes #530 --- RELEASE-NOTES.md | 54 ++++++++++++++++++++++++++++++++++-------------- docs/index.adoc | 41 +++++++++++++++++++++++++++--------- 2 files changed, 69 insertions(+), 26 deletions(-) diff --git a/RELEASE-NOTES.md b/RELEASE-NOTES.md index d66202207..e0b54651b 100644 --- a/RELEASE-NOTES.md +++ b/RELEASE-NOTES.md @@ -5,17 +5,19 @@ The picocli community is pleased to announce picocli 3.9.0. This release contains bugfixes and enhancements in the main picocli module, and adds a new module: `picocli-shell-jline3`. -Picocli Shell JLine3 (`picocli-shell-jline3`) contains components and documentation for building +The new module Picocli Shell JLine3 (`picocli-shell-jline3`) contains components and documentation for building interactive shell command line applications with JLine 3 and picocli. This release contains API enhancements to allow customization of the usage help message: -* help section renderer API -* option order attribute +* help section renderers can be added, replaced or removed +* help section keys to reorder sections in the usage help message +* help factory to create custom `Help` instances +* option order attribute to reorder options in the usage help message option list -This release has improved heuristics to decide whether ANSI escape codes should be emitted or not. +This release also has improved heuristics to decide whether ANSI escape codes should be emitted or not. -Bugfix: Command method options and positional parameter Object values are now cleared correctly when reusing a CommandLine instance. +Finally, this release contains a bugfix: `@Command` method options and positional parameter values are now cleared correctly when reusing a `CommandLine` instance. This is the forty-fifth public release. Picocli follows [semantic versioning](http://semver.org/). @@ -42,16 +44,36 @@ By default this map contains the predefined section renderers: Map map = new HashMap<>(); map.put(SECTION_KEY_HEADER_HEADING, help -> help.headerHeading()); map.put(SECTION_KEY_HEADER, help -> help.header()); -map.put(SECTION_KEY_SYNOPSIS_HEADING, help -> help.synopsisHeading()); //e.g. Usage: -map.put(SECTION_KEY_SYNOPSIS, help -> help.synopsis(help.synopsisHeadingLength())); //e.g. [OPTIONS] [COMMAND-OPTIONS] [ARGUMENTS] -map.put(SECTION_KEY_DESCRIPTION_HEADING, help -> help.descriptionHeading()); //e.g. %nDescription:%n%n -map.put(SECTION_KEY_DESCRIPTION, help -> help.description()); //e.g. {"Converts foos to bars.", "Use options to control conversion mode."} -map.put(SECTION_KEY_PARAMETER_LIST_HEADING, help -> help.parameterListHeading()); //e.g. %nPositional parameters:%n%n -map.put(SECTION_KEY_PARAMETER_LIST, help -> help.parameterList()); //e.g. [FILE...] the files to convert -map.put(SECTION_KEY_OPTION_LIST_HEADING, help -> help.optionListHeading()); //e.g. %nOptions:%n%n -map.put(SECTION_KEY_OPTION_LIST, help -> help.optionList()); //e.g. -h, --help displays this help and exits -map.put(SECTION_KEY_COMMAND_LIST_HEADING, help -> help.commandListHeading()); //e.g. %nCommands:%n%n -map.put(SECTION_KEY_COMMAND_LIST, help -> help.commandList()); //e.g. add adds the frup to the frooble + +//e.g. Usage: +map.put(SECTION_KEY_SYNOPSIS_HEADING, help -> help.synopsisHeading()); + +//e.g. [OPTIONS] [COMMAND-OPTIONS] [ARGUMENTS] +map.put(SECTION_KEY_SYNOPSIS, help -> help.synopsis(help.synopsisHeadingLength())); + +//e.g. %nDescription:%n%n +map.put(SECTION_KEY_DESCRIPTION_HEADING, help -> help.descriptionHeading()); + +//e.g. {"Converts foos to bars.", "Use options to control conversion mode."} +map.put(SECTION_KEY_DESCRIPTION, help -> help.description()); + +//e.g. %nPositional parameters:%n%n +map.put(SECTION_KEY_PARAMETER_LIST_HEADING, help -> help.parameterListHeading()); + +//e.g. [FILE...] the files to convert +map.put(SECTION_KEY_PARAMETER_LIST, help -> help.parameterList()); + +//e.g. %nOptions:%n%n +map.put(SECTION_KEY_OPTION_LIST_HEADING, help -> help.optionListHeading()); + +//e.g. -h, --help displays this help and exits +map.put(SECTION_KEY_OPTION_LIST, help -> help.optionList()); + +//e.g. %nCommands:%n%n +map.put(SECTION_KEY_COMMAND_LIST_HEADING, help -> help.commandListHeading()); + +//e.g. add adds the frup to the frooble +map.put(SECTION_KEY_COMMAND_LIST, help -> help.commandList()); map.put(SECTION_KEY_FOOTER_HEADING, help -> help.footerHeading()); map.put(SECTION_KEY_FOOTER, help -> help.footer()); ``` @@ -96,7 +118,7 @@ See the module's [README](https://github.com/remkop/picocli/blob/master/picocli- ### Improved ANSI Heuristics This release has improved heuristics to decide whether ANSI escape codes should be emitted or not. -Added support for the following environment variables to control enabling ANSI: +Support was added for the following environment variables to control enabling ANSI: * [`NO_COLOR`](https://no-color.org/) * [`CLICOLOR_FORCE`](https://bixense.com/clicolors/) diff --git a/docs/index.adoc b/docs/index.adoc index fa8347d8c..1fa7c4cc3 100644 --- a/docs/index.adoc +++ b/docs/index.adoc @@ -1885,6 +1885,7 @@ Below is the exact sequence of steps picocli uses to determine whether or not to 1. ANSI is enabled when picocli detects the program is running in a non-Windows OS (system property `os.name` does not start with `"Windows"`). 1. ANSI is enabled when picocli _guesses_ the program is running in a https://www.cygwin.com/[Cygwin] or http://www.mingw.org/wiki/MSYS[MSYS] environment (either environment variable `TERM` starts with `xterm` or environment variable `OSTYPE` is defined). +ANSI escape codes are not emitted if none of the above apply. == Usage Help API For further customization of the usage help message, picocli has a Help API. @@ -1908,16 +1909,36 @@ By default this map contains the predefined section renderers: Map map = new HashMap<>(); map.put(SECTION_KEY_HEADER_HEADING, help -> help.headerHeading()); map.put(SECTION_KEY_HEADER, help -> help.header()); -map.put(SECTION_KEY_SYNOPSIS_HEADING, help -> help.synopsisHeading()); //e.g. Usage: -map.put(SECTION_KEY_SYNOPSIS, help -> help.synopsis(help.synopsisHeadingLength())); //e.g. [OPTIONS] [COMMAND-OPTIONS] [ARGUMENTS] -map.put(SECTION_KEY_DESCRIPTION_HEADING, help -> help.descriptionHeading()); //e.g. %nDescription:%n%n -map.put(SECTION_KEY_DESCRIPTION, help -> help.description()); //e.g. {"Converts foos to bars.", "Use options to control conversion mode."} -map.put(SECTION_KEY_PARAMETER_LIST_HEADING, help -> help.parameterListHeading()); //e.g. %nPositional parameters:%n%n -map.put(SECTION_KEY_PARAMETER_LIST, help -> help.parameterList()); //e.g. [FILE...] the files to convert -map.put(SECTION_KEY_OPTION_LIST_HEADING, help -> help.optionListHeading()); //e.g. %nOptions:%n%n -map.put(SECTION_KEY_OPTION_LIST, help -> help.optionList()); //e.g. -h, --help displays this help and exits -map.put(SECTION_KEY_COMMAND_LIST_HEADING, help -> help.commandListHeading()); //e.g. %nCommands:%n%n -map.put(SECTION_KEY_COMMAND_LIST, help -> help.commandList()); //e.g. add adds the frup to the frooble + +//e.g. Usage: +map.put(SECTION_KEY_SYNOPSIS_HEADING, help -> help.synopsisHeading()); + +//e.g. [OPTIONS] [COMMAND-OPTIONS] [ARGUMENTS] +map.put(SECTION_KEY_SYNOPSIS, help -> help.synopsis(help.synopsisHeadingLength())); + +//e.g. %nDescription:%n%n +map.put(SECTION_KEY_DESCRIPTION_HEADING, help -> help.descriptionHeading()); + +//e.g. {"Converts foos to bars.", "Use options to control conversion mode."} +map.put(SECTION_KEY_DESCRIPTION, help -> help.description()); + +//e.g. %nPositional parameters:%n%n +map.put(SECTION_KEY_PARAMETER_LIST_HEADING, help -> help.parameterListHeading()); + +//e.g. [FILE...] the files to convert +map.put(SECTION_KEY_PARAMETER_LIST, help -> help.parameterList()); + +//e.g. %nOptions:%n%n +map.put(SECTION_KEY_OPTION_LIST_HEADING, help -> help.optionListHeading()); + +//e.g. -h, --help displays this help and exits +map.put(SECTION_KEY_OPTION_LIST, help -> help.optionList()); + +//e.g. %nCommands:%n%n +map.put(SECTION_KEY_COMMAND_LIST_HEADING, help -> help.commandListHeading()); + +//e.g. add adds the frup to the frooble +map.put(SECTION_KEY_COMMAND_LIST, help -> help.commandList()); map.put(SECTION_KEY_FOOTER_HEADING, help -> help.footerHeading()); map.put(SECTION_KEY_FOOTER, help -> help.footer()); ----