On Thu, Aug 8, 2013 at 5:13 PM, j. van den hoff <veedeeh...@googlemail.com>wrote:
> well that's sort of difficult for the average user I'd say since he does > not _know_ > what the parser is doing and what the set of valid calls to fossil looks > like. I cannot be sure, > for instance that there are no further undocumented `--word' options > beside `--user' ... > lol! touché. i often forget that not everyone who uses fossil hacks on it :/. fossil ?fossil_option(s)? COMMAND ?command_option(s)? > Because it would be a lie sometimes :/. The ordering of the flags and commands may or may not be important for a given command. _Normally_ it doesn't matter where the flags appear but it can if the one who implements that command isn't aware of the side-effects that argument parsing has on the list of arguments (as i wasn't when i started work on the JSON API). As a rule of thumb, the following syntax should work just about everywhere (if not everywhere): fossil command ?options? where ?options? can be command-specific or (quasi-)global (like -R). looking over the current output now: stephan@tiny:~/cvs/fossil/f2$ f help Usage: f help COMMAND ... i wouldn't expect ?options? to appear there, but that's probably a matter of personal taste (and mine is often in the minority ;). In your opinion, what should the top-level 'help' command say which it does not already? If we then go one level deeper for a specific command: stephan@tiny:~/cvs/fossil/f2$ f help ls Usage: f ls ?OPTIONS? ?VERSION? ?FILENAMES? ... that one has, IMO, pretty good help. There are certainly others which could be improved, but i don't have an example off the top of my head. But i did just discover the 'cat' command - i don't think i knew about that one before now. but more formally, it looks to me that it would be better to eliminate > `fossil_options' altogether and add them as command_options > to the respective command(s). that would make for a clearer and less > unusual syntax overall. would that be difficult? In general that's what currently happens, e.g.: stephan@tiny:~/cvs/fossil/f2$ f help cat Usage: f cat FILENAME ... ?OPTIONS? ... Options: -R|--repository FILE Extract artifacts from repository FILE -R is one of those quasi-global options which is supported almost everywhere, but not all of the commands explicitly mention it (possibly the author of the command doesn't even realize it because it happens one level removed from his command). http://fossil-scm.org/index.html/artifact/0adc1aa79c24d8bc88b32e2ef7a8f29d32619d79?ln=1055 i don't personally hold out much hope of any groundbreaking changes in fossil's help system because it's literally integrated with the source code (the help text and command/page names are extracted from source code comments during the build process) and it works relatively well (and is very non-intrusive on the developers). That said, FWIW, i will certainly take your points to heart when libfossil[1] is far enough along that applications can be built off of it. My plan is to provide a skeleton CLI app mini-framework which does the bootstrap part of handling the -R flag, seeing if $PWD is part of a checkout, processing CLI flags, and exposing the CLI flags to the application in a higher-level form. That's still likely several months away, but maybe it'll give you some hope for a more consistent help system in future fossil-related products :). [1] http://fossil.wanderinghorse.net/repos/f2/ -- ----- stephan beal http://wanderinghorse.net/home/stephan/ http://gplus.to/sgbeal
_______________________________________________ fossil-users mailing list fossil-users@lists.fossil-scm.org http://lists.fossil-scm.org:8080/cgi-bin/mailman/listinfo/fossil-users
