[
https://issues.apache.org/jira/browse/SOLR-17357?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Jan Høydahl updated SOLR-17357:
-------------------------------
Summary: Improve default --help formatting for CLI Tools, make configurable
(was: Move usage string from bin/solr[.cmd] to XxxTool, for --help)
> Improve default --help formatting for CLI Tools, make configurable
> ------------------------------------------------------------------
>
> Key: SOLR-17357
> URL: https://issues.apache.org/jira/browse/SOLR-17357
> Project: Solr
> Issue Type: Sub-task
> Components: scripts and tools
> Reporter: Jan Høydahl
> Assignee: Jan Høydahl
> Priority: Major
> Time Spent: 0.5h
> Remaining Estimate: 0h
>
> In 9.6 the Usage help text for each tool is covered by {{{}bin/solr[.cmd]{}}}.
> On main branch many of the Usage strings were moved to RefGuide in
> SOLR-16797. That leaves the tool {{--help}} print somewhat amputatet, e.g.
> {code:java}
> $ bin/solr create -h
> usage: create
> -c,--name <NAME> Name of collection or core to create.
> -d,--confdir <DIR> Configuration directory to copy when
> creating the new collection; default is
> _default.
> -help Print this message
> -n,--confname <NAME> Configuration name; default is the
> collection name.
> -rf,--replicationFactor <#> Number of copies of each document across
> the collection (replicas per shard);
> default is 1.
> -s,--shards <#> Number of shards; default is 1.
> -solrUrl <HOST> Base Solr URL, which can be used to
> determine the zkHost if that's not
> known; defaults to:
> http://localhost:8983.
> -u,--credentials <credentials> Credentials in the format
> username:password. Example:
> --credentials solr:SolrRocks
> -verbose Enable more verbose command output.
> -z,--zkHost <HOST> Zookeeper connection string; unnecessary
> if ZK_HOST is defined in solr.in.sh;
> otherwise, defaults to localhost:9983.
> {code}
> This Jira is to make this a bit better.
> The {{Tool}} interface provides {{{}getName{}}}, {{getOptions}} and
> {{{}runTool{}}}. The {{printHelp}} interface of commons-cli has the ability
> of also printing a {{{}Usage{}}}, header and footer:
> {code:java}
> /**
> * Prints the help for {@code options} with the specified command line
> syntax. This method prints help information
> * to {@link System#out} by default.
> *
> * @param cmdLineSyntax the syntax for this application
> * @param header the banner to display at the beginning of the help
> * @param options the Options instance
> * @param footer the banner to display at the end of the help
> * @param autoUsage whether to print an automatically generated usage
> statement
> */
> public void printHelp(final String cmdLineSyntax, final String header, final
> Options options, final String footer, final boolean autoUsage) {
> printHelp(getWidth(), cmdLineSyntax, header, options, footer, autoUsage);
> } {code}
> I propose the addition of three methods to our {{Tool}} interface:
> {code:java}
> String getUsage();
> String getHeader();
> String getFooter();{code}
> The default behavior will be to auto generate usage string, and use "List of
> options:" as header and a link to Reference guide as footer, e.g for assert
> tool:
> {code:java}
> $ bin/solr assert -h
> usage: bin/solr assert [-c <url>] [-C <url>] [-e] [-m <message>] [-R] [-r]
> [-S <url>] [-s <url>] [--same-user <directory>] [-t <ms>] [-u <credentials>]
> [-x <directory>] [-X <directory>]
> List of options:
> -c,--cloud <url> Asserts that Solr is running in cloud mode.
> Also fails if Solr not running. URL
> should be for root Solr path.
> -C,--not-cloud <url> Asserts that Solr is not running in cloud
> mode. Also fails if Solr not running. URL
> should be for root Solr path.
> -e,--exitcode Return an exit code instead of printing
> error message on assert fail.
> -m,--message <message> Exception message to be used in place of
> the default error message.
> -R,--not-root Asserts that we are NOT the root user.
> -r,--root Asserts that we are the root user.
> -S,--not-started <url> Asserts that Solr is NOT running on a
> certain URL. Default timeout is 1000ms.
> -s,--started <url> Asserts that Solr is running on a certain
> URL. Default timeout is 1000ms.
> --same-user <directory> Asserts that we run as same user that owns
> <directory>.
> -t,--timeout <ms> Timeout in ms for commands supporting a
> timeout.
> -u,--credentials <credentials> Credentials in the format
> username:password. Example: --credentials solr:SolrRocks
> -x,--exists <directory> Asserts that directory <directory> exists.
> -X,--not-exists <directory> Asserts that directory <directory> does NOT
> exist.
> Please see the Reference Guide for more tools documentation:
> https://solr.apache.org/guide/solr/latest/deployment-guide/solr-control-script-reference.html
> {code}
>
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscr...@solr.apache.org
For additional commands, e-mail: issues-h...@solr.apache.org
