[ 
https://issues.apache.org/jira/browse/SOLR-11840?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=16440296#comment-16440296
 ] 

ASF subversion and git services commented on SOLR-11840:
--------------------------------------------------------

Commit 7edfd9c41018f16e7b6af1b58e9983e427eff9de in lucene-solr's branch 
refs/heads/master from [~gerlowskija]
[ https://git-wip-us.apache.org/repos/asf?p=lucene-solr.git;h=7edfd9c ]

SOLR-11840: Fix bin/solr help-text inconsistencies


> Inconsistencies in the Usage Messages of bin/solr.cmd
> -----------------------------------------------------
>
>                 Key: SOLR-11840
>                 URL: https://issues.apache.org/jira/browse/SOLR-11840
>             Project: Solr
>          Issue Type: Improvement
>      Security Level: Public(Default Security Level. Issues are Public) 
>    Affects Versions: 7.2
>            Reporter: Jakob Furrer
>            Priority: Major
>              Labels: documentation, easyfix
>             Fix For: 7.2
>
>         Attachments: SOLR-11840.patch, SOLR-11840.patch, SOLR-11840.patch, 
> solr.cmd.txt, solr.txt, solr_start_help_Syntaxfehler.png
>
>   Original Estimate: 2h
>  Remaining Estimate: 2h
>
> I noticed a number of errors/problems/peculiarities in the Usage Messages 
> that are displayed when using *bin/solr.cmd* with the parameter *_-help_*.
> The items are listed in no particular order and may be addressed 
> independantly.
> To spot the differences between the Usage Messages of _bin/solr_ and 
> _bin/solr.cmd_ I compiled an extract of the Usage Messages of the two files 
> so that they can be compared using WinMerge or a similar diff tool.
> See the attached files *solr.cmd.txt* and *solr.txt*.
> Note that I work on a German Windows 10, therefore some error messages I 
> quote here are in German.
> # _solr_ _start_ _-help_ results in a syntax error
> The special characters '<' and '>' are not escaped.
> The line 314 must be changed as follows:
> {noformat}
> CURRENT : ... the default server/<dir>
> SHALL_BE: ... the default server/^<dir^>
> {noformat}
> \\
> # _solr auth -help_ ends is empty
> A goto label ':auth_usage' with the appropriate Usage Messages already exists.
> At line 266 an additional if-statement is required.
> Also, a respective if-statement will be required on line 1858.
> {noformat}
> NEW_CODE: IF "%SCRIPT_CMD%"=="auth" goto auth_usage
> {noformat}
> Some additional bugs in the section ':auth_usage' must then also be addressed.
> The special character '|' is not escaped at a number of locations.
> The lines 568, 569, 570, 577, 580 and 585 must be changed, e.g.
> {noformat}
> CURRENT : echo Usage: solr auth enable [-type basicAuth] -credentials 
> user:pass [-blockUnknown ^<true|false^>] [-updateIncludeFileOnly 
> ^<true|false^>] [-V]
> SHALL_BE: echo Usage: solr auth enable [-type basicAuth] -credentials 
> user:pass [-blockUnknown ^<true^|false^>] [-updateIncludeFileOnly 
> ^<true^|false^>] [-V]
> {noformat}
> The empty 'echo' statement (i.e. 'newline') needs the be written with a dot 
> ('echo.') to avoid "ECHO ist ausgeschaltet (OFF)." statements.
> The lines 571, 573, 576, 577, 579, 584, 587, 589, 591, 594 and 596 must be 
> changed:
> {noformat}
> CURRENT : echo
> SHALL_BE: echo.
> {noformat}
> \\
> # _solr_ _-help_ does not mention the command _status_
> The line 271 must be changed as follows:
> {noformat}
> CURRENT : @echo        where COMMAND is one of: start, stop, restart, 
> healthcheck, create, create_core, create_collection, delete, version, zk, 
> auth, assert
> SHALL_BE: @echo        where COMMAND is one of: start, stop, restart, status, 
> healthcheck, create, create_core, create_collection, delete, version, zk, 
> auth, assert
> {noformat}
> \\
> # In _bin/solr.cmd_ the description of _solr_ _start_ _-p_ _port_ does not 
> mention the STOP_PORT and the RMI_PORT, see line 324 to 326 of _bin/solr_.
> {noformat}
> echo "  -p <port>     Specify the port to start the Solr HTTP listener on; 
> default is 8983"
> echo "                  The specified port (SOLR_PORT) will also be used to 
> determine the stop port"
> echo "                  STOP_PORT=(\$SOLR_PORT-1000) and JMX RMI listen port 
> RMI_PORT=(\$SOLR_PORT+10000). "
> echo "                  For instance, if you set -p 8985, then the 
> STOP_PORT=7985 and RMI_PORT=18985"
> {noformat}
> \\
> # The description of _solr_ _start_ _-s_ _dir_ seems to have been revised in 
> _bin/solr.cmd_ but not in _bin/solr_.
> {noformat}
>                   on which example is run. The default value is server/solr. 
> If passed a relative dir
>                   validation with the current dir will be done before trying 
> the default server/<dir>
> {noformat}
> vs.
> {noformat}              
>                   on which example is run. The default value is server/solr. 
> If passed relative dir,
>                   validation with current dir will be done, before trying 
> default server/<dir>
> {noformat}
> \\
> # The description of _solr_ _start_ _-t_ _dir_ is different
> {noformat}
>   -t dir        Sets the solr.data.home system property, used as root for 
> ^<instance_dir^>/data directories.
>                   If not set, Solr uses solr.solr.home for both config and 
> data.
> {noformat}
> vs.
> {noformat}
>   -t <dir>      Sets the solr.data.home system property, where Solr will 
> store data (index).
>                   If not set, Solr uses solr.solr.home for config and data.
> {noformat}
> \\
> # The description of _solr_ _start_ _-V_ does not mention _-verbose_
> {noformat}
>   -V            Verbose messages from this script
> {noformat}
> vs.
> {noformat}
>   -V or -verbose Verbose messages from this script
> {noformat}
> \\
> # The syntax of _solr_ _stop_ does not mention the parameter _-V_
> {noformat}
> Usage: solr stop [-k key] [-p port]
> {noformat}
> vs.
> {noformat}
> Usage: solr stop [-k key] [-p port] [-V]
> {noformat}
> Note that there is also no description of _-V_ in _bin/solr_, even though the 
> parameter is mentioned in the syntax.
> \\
> \\
> # The description of _solr_ _stop_ does not mention the command _status_
> This additional information is present in _bin/solr_.
> {noformat}
>   NOTE: To see if any Solr servers are running, do: solr status
> {noformat}
> This can be added in the section ':stop_usage' at line 352.
> \\
> \\
> # The syntax of _solr_ _healthcheck_ does not mention the parameter _-V_
> {noformat}
> Usage: solr healthcheck [-c collection] [-z zkHost]
> {noformat}
> vs.
> {noformat}
> Usage: solr healthcheck [-c collection] [-z zkHost] [-V]
> {noformat}
> \\
> # There is no Usage Message for _solr_ _status_.
> The command _solr_ _status_ _-help_ does not output any help message, it 
> actually runs the _solr_ _status_ instead.
> {noformat}
> Usage: solr status
>   NOTE: This command will show the status of all running Solr servers
> {noformat}
> A new goto label ':status_usage' is required, probably right after the label 
> ':start_usage'.
> At line 266 an additional if-statement is required.
> Also, a respective if-statement will be required on line 1858.
> \\
> \\
> # The syntax of _solr_ _stop_ _-deleteConfig_ mentions _boolean_, while 
> everywhere else this is indicated as _true|false_
> {noformat}
> Usage: solr delete [-c name] [-deleteConfig boolean] [-p port] [-V]
> {noformat}
> vs.
> {noformat}
> Usage: solr delete [-c name] [-deleteConfig true|false] [-p port] [-V]
> {noformat}
> \\
> # The description of _solr_ _delete_ _-c_ _name_ is different
> Note: The documentation should say *delete*, not *create* a core.
> {noformat}
>   -c name     Name of core to create
> {noformat}
> vs.
> {noformat}
>   -c <name>               Name of the core / collection to delete
> {noformat}
> \\
> # The description of _solr_ _delete_ _-p_ _port_ is different
> Note: The documentation should say *delete*, not *create* a core.
> {noformat}
>   -p port     Port of a local Solr instance where you want to create the new 
> core
> {noformat}
> vs.
> {noformat}
>   -p <port>               Port of a local Solr instance where you want to 
> delete the core/collection
> {noformat}
> \\
> # The description of _solr_ _delete_ _-V_ is spelt differently
> {noformat}
>   -V            Enable more verbose output.
> {noformat}
> vs.
> {noformat}
>   -V                      Enables more verbose output.
> {noformat}
> \\
> # The description of _solr_ _create_core_ _-c_ uses a different parameter name
> {noformat}
> Usage: solr create_core [-c name] [-d confdir] [-p port] [-V]
>   -c name     Name of core to create
> {noformat}
> vs.
> {noformat}
> Usage: solr create_core [-c core] [-d confdir] [-p port] [-V]
>   -c <core>     Name of core to create
> {noformat}
> \\
> # The description of _solr_ _create_collection_ _-c_ and _-n_ uses a 
> different parameter name
> {noformat}
> Usage: solr create_collection [-c name] [-d confdir] [-n confname] [-shards 
> #] [-replicationFactor #] [-p port] [-V]
>   -c name               Name of collection to create
>   -d confdir            Configuration directory to copy when creating the new 
> collection, built-in options are:
> {noformat}
> vs.
> {noformat}
> Usage: solr create_collection [-c collection] [-d confdir] [-n configName] 
> [-shards #] [-replicationFactor #] [-p port] [-V]
>   -c <collection>         Name of collection to create
>   -d <confdir>            Configuration directory to copy when creating the 
> new collection, built-in options are:
> {noformat}
> \\
> # The description of _solr_ _create_collection_ _-shards_ does not mention 
> the default value
> {noformat}
>   -shards #             Number of shards to split the collection into
> {noformat}
> vs.
> {noformat}
>   -shards <#>             Number of shards to split the collection into; 
> default is 1
> {noformat}
> \\
> # The description of _solr_ _create_collection_ _-replicationFactor_ does not 
> mention the default value
> {noformat}
>   -replicationFactor #  Number of copies of each document in the collection
> {noformat}
> vs.
> {noformat}
>   -replicationFactor <#>  Number of copies of each document in the 
> collection, default is 1 (no replication)
> {noformat}
> \\
> # The description of _solr_ _zk_ _cp_ <src>, <dest> is missing a sentence
> {noformat}
>              ^<src^>, ^<dest^> : [file:][/]path/to/local/file or 
> zk:/path/to/zk/node
>                              NOTE: ^<src^> and ^<dest^> may both be Zookeeper 
> resources prefixed by 'zk:'
>             When ^<src^> is a zk resource, ^<dest^> may be '.'
>             element of the ^<src^> path will be appended unless ^<src^> also 
> ends in a slash. 
>             ^<dest^> may be zk:, which may be useful when using the cp -r 
> form to backup/restore 
> {noformat}
> vs.
> {noformat}
>              <src>, <dest> : [file:][/]path/to/local/file or 
> zk:/path/to/zk/node
>                              NOTE: <src> and <dest> may both be Zookeeper 
> resources prefixed by 'zk:'
>              When <src> is a zk resource, <dest> may be '.'
>              If <dest> ends with '/', then <dest> will be a local folder or 
> parent znode and the last
>              element of the <src> path will be appended unless <src> also 
> ends in a slash. 
>              <dest> may be zk:, which may be useful when using the cp -r form 
> to backup/restore 
> {noformat}
> Also, the fullstop here should be at the end of the sentence, not on the next 
> line.
> {noformat}
>              but 'bin/solr zk cp -r /some/dir/* zk:/ -z localhost:2181' will 
> throw an error
> .
> {noformat}
> The sentence "here's an example of backup/restore ..." should start with a 
> captial letter.
> The paragraph from "... the entire zk state." to "... /some/dir/ zk:/ -z 
> localhost:2181'" has one space too much indentation.
> \\
> \\
> # The description of _solr_ _zk_ _mkroot_ is different
> {noformat}
>         mkroot makes a znode in Zookeeper with no data. Can be used to make a 
> path of arbitrary
> {noformat}
> vs.
> {noformat}
>          mkroot makes a znode on Zookeeper with no data. Can be used to make 
> a path of arbitrary
> {noformat}
> \\
> # The description of _solr_ _auth_ is different
> Basic usage does not mention _-type_ _kerberos_:
> {noformat}
> Usage: solr auth enable [-type basicAuth] -credentials user:pass 
> [-blockUnknown ^<true|false^>] [-updateIncludeFileOnly ^<true|false^>] [-V]
>        solr auth enable [-type basicAuth] -prompt ^<true|false^> 
> [-blockUnknown ^<true|false^>] [-updateIncludeFileOnly ^<true|false^>] [-V]
>        solr auth disable [-updateIncludeFileOnly ^<true|false^>] [-V]
> {noformat}
> vs.
> {noformat}
> Usage: solr auth enable [-type basicAuth] -credentials user:pass 
> [-blockUnknown <true|false>] [-updateIncludeFileOnly <true|false>] [-V]
>        solr auth enable [-type basicAuth] -prompt <true|false> [-blockUnknown 
> <true|false>] [-updateIncludeFileOnly <true|false>] [-V]
>        solr auth enable -type kerberos -config \"<kerberos configs>\" 
> [-updateIncludeFileOnly <true|false>] [-V]
>        solr auth disable [-updateIncludeFileOnly <true|false>] [-V]
> {noformat}
> \\
> The description of the paramter _-type_ is different
> {noformat}
>   -type ^<type^>                 The authentication mechanism to enable. 
> Defaults to 'basicAuth'.
> {noformat}
> vs.
> {noformat}
>   -type <type>                           The authentication mechanism 
> (basicAuth or kerberos) to enable. Defaults to 'basicAuth'.
> {noformat}
> \\
> The description of the paramter _-credentials_ is different
> {noformat}
>   -credentials ^<user:pass^>     The username and password of the initial user
> {noformat}
> vs.
> {noformat}
>   -credentials <user:pass>               The username and password of the 
> initial user. Applicable for basicAuth only.
> {noformat}
> \\
> The description of the paramter _-config_ is missing
> {noformat}
>   -config \"<configs>\"                    Configuration parameters (Solr 
> startup parameters). Required and applicable only for Kerberos
> {noformat}
> \\
> The description of the paramter _-blockUnknown_ is different
> {noformat}
>                                guide for Basic Authentication for more 
> details.
> {noformat}
> vs.
> {noformat}
>                                          guide for Basic Authentication for 
> more details. Applicable for basicAuth only.
> {noformat}
> \\
> The descriptions of the paramters _-updateIncludeFileOnly_, _-d_ and _-s_ 
> contain an annoying double quote at the end of the line
> \\
> The descriptions of the paramters _-d_ and _-s_ do not escape '<' and '>', 
> resulting in error messages in the command line (note that before fixing the 
> call to ':auth_usage' there is no output at all, see point 2 above).
> {panel:bgColor=#000000}
> {color:white}
> C:\solr-7.2.0_test\bin>solr.cmd auth -help
> Usage: ... <blablabla> ...
>   -updateIncludeFileOnly <true|false>    Only update the solr.in.sh or 
> solr.in.cmd file, and skip actual enabling/disabling"
>                                          authentication (i.e. don't update 
> security.json)"
>   -z zkHost                    Zookeeper connection string
> Das System kann die angegebene Datei nicht finden.
> Das System kann die angegebene Datei nicht finden.
>                                configuration files (e.g. basicAuth.conf) 
> would be placed."
>   -V                           Enable more verbose output
> {color}
> {panel}



--
This message was sent by Atlassian JIRA
(v7.6.3#76005)

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@lucene.apache.org
For additional commands, e-mail: dev-h...@lucene.apache.org

Reply via email to