Argument description confusing/unreadable in command usage description
| Project: | JNode Shell |
| Component: | User interface |
| Category: | bug report |
| Priority: | normal |
| Assigned: | Stephen Crawley |
| Status: | closed |
Jump to:
Description
Example:
JNode /> help tcpinout
Usage: tcpinout <localPort:port number>
...
Problem: imho human eye will tokenize the above text as:
1st token: localPort:port
2nd token: number
and find a meaning after that. Obviously the result is confusion bacause the intention was:
1st token: localPort
2nd token: port number
Meaning: localPort IS port number
The confusion gets worse when there are more than one parameters, and the usage info is not clean.
This notation 'localPort:port number' has two more problems:
1. in Java type information goes in front of the variable
2. the shell is not only for programmers and other people doesn't know about data types and their syntax
It took me some time to get used to it but I see that many people have trouble with this and that's no surprise beacuse it's so unusual.
I think the Usage section of the command description would be much cleaner if it was:
Usage: tcpinout <localPort>
The omitted 'type info' could be included in the descritpion of the individual parameteres maybe as the first line.
- Login to post comments
#1
Point taken. I'll figure out how to simplify the usage messages, etc.
#2
I've checked in some changes. What do you think?
#3
The usage looks much better now. Maybe the paranthesis in the argument description could be avoided somehow or often the whole thing inside the paranthesis could be left out. For instance in the help of nfsmount tcp and udp are marked with '(flag)' which imo is not relevant for the user. A bigger issue is that in the same example in the usage there is --ro and --rw while in the arguments instead of them there is readOnly and readWrite. This can be rather confusing esepcially when the flag is not an acronym as well known as these.
#4
Dealing with the FlagArgument issue is not simple, but I'm working on it ...
#5
I've checked in some more improvements. Please take another look.
BTW, I've noticed that "help" is currently throwing an exception for classic Java commands; i.e. with not Help.Info and no Syntax. I'm on the case ...
#6
The command description appears to be fine now.
#7
Fixed the bug for commands with no help. I'm marking the entire issue fixed.
#8