Jan Høydahl created SOLR-17357:
----------------------------------
Summary: Move usage string from bin/solr[.cmd] to XxxTool, for
--help
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
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
