Related issues:
Issue ID 6402
Issue ID 6963
This issue should address the COMMAND_USAGE pattern that appears after "Usage:" when executing a command without parameters (1) or the first line that appears after entering help COMMAND_NAME (2).
(1)
$ COMMAND_NAME
Usage: COMMAND_USAGE
Try "help COMMAND_NAME" for more information.<---For these last two lines see #6402
(2)
$ help COMMAND_NAME
COMMAND_USAGE
EMPTY_LINE
COMMAND_HELP/MANUAL<---For this pattern see #6963
Since ADStudio 12 Dev 34, I noticed that the COMMAND_USAGE pattern mentioned above has changed for some commands in order to be more consistent, this is great!
Actually these changes started this issue.
The COMMAND_USAGE pattern that I could extract from the current usage-messages:
1. first word is the name of the command, all in lowercase
2. if the command can accept parameters:
2.a. make the name of the parameter all uppercase
2.b. make the name of the parameter singular
2.c. replace any spaces from the name of the parameter with underscore
2.d. if that parameter can be passed to the command more than once, add three dots after the name of the parameter
3. if the accepted parameter is optional:
3.a. surround the name of the parameter with square brackets
3.b. leave no space between the square brackets and the name of the parameter
4. if the accepted parameter represents an option, replace that parameter with the keyword OPTION
5. if two or more parameters cannot be used both in the same time
5.A.
5.a. surround them with curly braces
5.b. add a vertical line between the parameters
5.c. use B bellow if A gets too complicated
5.B.
write the COMMAND_USAGE pattern multiple times for each case
6. the order in which to add the elements from above:
6.a. command name
6.b. OPTION keyword parameter
6.c. optional parameters
6.d. non-optional parameters
Of course, additional modifications can be added if necessary.
Currently, not all the commands respect the pattern from above; some of the inadequacies are:
* most notably the 3 dots are either inside the square brackets, either outside; (ie. [OPTION...] or [OPTION]... ) either way it's ok, but it should be consistent, although I would prefer the first variant;
* sometimes the 3 dots are followed by an n, (at commands: \ask, \cli, \more, \touch, \unalias)
* \exec and \run use plural parameter names, it should be singular like at \source
* \sqlexport uses sentence case parameter names, it should be all uppercase like at \sqlimport or \syncdir
* \scp and \sendmail use long listing options format, it should be just OPTION keyword
* \touch uses some curly brackets instead of square brackets
>>>> * most notably the 3 dots are either inside the square brackets, either outside; (ie. [OPTION...] or [OPTION]... ) either way it's ok, but it should be consistent, although I would prefer the first variant;
Went with [OPTION...]
>>>> * sometimes the 3 dots are followed by an n, (at commands: \ask, \cli, \more, \touch, \unalias)
Should be ... but not ...n
>>>> * \exec and \run use plural parameter names, it should be singular like at \source
>>>> * \sqlexport uses sentence case parameter names, it should be all uppercase like at \sqlimport or \syncdir
>>>> * \scp and \sendmail use long listing options format, it should be just OPTION keyword
>>>> * \touch uses some curly brackets instead of square brackets
All fixed.
Verified using ADStudio 12 Dev 139, overall the help usage message looks great, the *'s from above are all fixed.
However, some inconsistencies were found for the \declare command where points 2.b and 2.c are not respected.
Other, maybe debatable, inconsistencies were found at the following commands: \echo, \gzip, \help, \tee, \touch. These commands display the OPTION keyword followed by 3 dots, but they have only a single option, therefor I would eliminate the 3 dots.
Verified using ADStudio 12 Dev 139, overall the help usage message looks great, the *'s from above are all fixed.
However, some inconsistencies were found for the \declare command where points 2.b and 2.c are not respected.
Other, maybe debatable, inconsistencies were found at the following commands: \echo, \gzip, \help, \tee, \touch. These commands display the OPTION keyword followed by 3 dots, but they have only a single option, therefor I would eliminate the 3 dots.
> However, some inconsistencies were found for the \declare command where points 2.b and 2.c are not respected.
> Other, maybe debatable, inconsistencies were found at the following commands: \echo, \gzip, \help, \tee, \touch. These commands display the OPTION keyword followed by 3 dots, but they have only a single option, therefor I would eliminate the 3 dots.
Both are fixed. SVN r28987.
> However, some inconsistencies were found for the \declare command where points 2.b and 2.c are not respected.
> Other, maybe debatable, inconsistencies were found at the following commands: \echo, \gzip, \help, \tee, \touch. These commands display the OPTION keyword followed by 3 dots, but they have only a single option, therefor I would eliminate the 3 dots.
Both are fixed. SVN r28987.
Issue #7082 |
Closed |
Fixed |
Resolved |
Completion |
No due date |
Fixed Build trunk/28108, 28987 |
No time estimate |
>>>> * most notably the 3 dots are either inside the square brackets, either outside; (ie. [OPTION...] or [OPTION]... ) either way it's ok, but it should be consistent, although I would prefer the first variant;
Went with [OPTION...]
>>>> * sometimes the 3 dots are followed by an n, (at commands: \ask, \cli, \more, \touch, \unalias)
Should be ... but not ...n
>>>> * \exec and \run use plural parameter names, it should be singular like at \source
>>>> * \sqlexport uses sentence case parameter names, it should be all uppercase like at \sqlimport or \syncdir
>>>> * \scp and \sendmail use long listing options format, it should be just OPTION keyword
>>>> * \touch uses some curly brackets instead of square brackets
All fixed.