Dean Troyer (dtro...@gmail.com) wrote: > On Mon, Apr 30, 2012 at 11:13 AM, Adam Spiers <aspi...@suse.com> wrote: > > Count me in - by 'build a list' do you mean a new mailing list? > > You're in! For now that's just a list I'm keeping.
OK, great :) > > tweaks. Should we discuss the FIXMEs you marked here or elsewhere? I > > wanted to make a few suggestions before I forget - can always continue > > discussion elsewhere if appropriate: > > This is it for now except for what we may do in the wiki itself while > writing the doc. OK - I boldified the existing FIXMEs and added some new stuff. > There is activity going on that may shift traffic on > the lists. One of the things that will happen is the addition of > prefixes in the subject so we can start by using [client]. Yup I saw Thierry's announcement so [client] is a good idea - have done. > > 1. Regarding "The subject names are always specified in command in > > their singular form. This is contrary to natural language use." > > > > - I didn't understand the second sentence here, but shouldn't the > > HIG should allow for scenarios where the verb can operate both on > > individual objects and on multiple objects in batch? > > I was referring to 'list server' vs 'list servers'. It would be nice > to accept either where plural is natural, but that is a lower priority > thing to solve. Right. > > (Grammatical nitpick: if the verb is acting on the noun, then the > > HIG should refer to the noun as "object" rather than "subject".) > > That was a deliberate choice based on how overloaded the word 'object' > is in programming. My HS English teacher is preparing a detention for > me I'm sure... Hahah, good point :) > > 2. I think it would be good if the HIG gave guidelines on how the > > command should behave when run with no arguments. > > For some commands that is totally valid, for some that is an error > condition. True, so I should have said: I think it would be good if the HIG gave guidelines on how commands which require arguments should behave when run with no arguments. ... and in this case I would suggest that the command behaves as if it was run with the '--help' argument; as I have said elsewhere on this thread, I find commands like svn which do not do this to be needlessly unhelpful: $ svn Type 'svn help' for usage. Why does it insist on making the user type more? Reminds me of parts of this conversation: http://www.youtube.com/watch?v=sr1IXB194aE > > 3. I think it would be good if the HIG recommended that, at least > > when subcommands are permitted, single arguments '--help' and > > 'help' always generate identical output: > > The intent is for '-h' and '--help' to provide global options and how > to get specific command help. A 'help' command should list the > available commands based on installed modules (and ultimately on > permissions?) and 'help command' should display detailed help on > 'command'. I see. Personally I'm not too keen on that, because users are likely to forget which of '--help' and 'help' lists the available commands, or accidentally type the wrong one, and in either case they'd end up having to type two commands rather than one. So why not make both output all the information they need? > > https://bugs.launchpad.net/keystone/+bug/936399 > > Heh. My past catches up with me. I've changed my mind here due to > the potentially long list of commands involved. Simple, obvious, > concise. Pick two. ;) I'll pick all three by taking a leaf out of git's book :-) $ git --help usage: git [--version] [--exec-path[=<path>]] [--html-path] [--man-path] [--info-path] [-p|--paginate|--no-pager] [--no-replace-objects] [--bare] [--git-dir=<path>] [--work-tree=<path>] [--namespace=<name>] [-c name=value] [--help] <command> [<args>] The most commonly used git commands are: add Add file contents to the index bisect Find by binary search the change that introduced a bug [snipped] status Show the working tree status tag Create, list, delete or verify a tag object signed with GPG See 'git help <command>' for more information on a specific command. Presumably the most commonly used commands could be marked out using decorators. BTW exactly the same output as above is generated by running git with no arguments. Another output format worth remembering is the column-based one: $ git help -a usage: git [--version] [--exec-path[=<path>]] [--html-path] [--man-path] [--info-path] [-p|--paginate|--no-pager] [--no-replace-objects] [--bare] [--git-dir=<path>] [--work-tree=<path>] [--namespace=<name>] [-c name=value] [--help] <command> [<args>] available git commands in '/usr/lib/git' ---------------------------------------- add hash-object remote-ext add--interactive help remote-fd [snipped] git commands available from elsewhere on your $PATH --------------------------------------------------- add-prefix head set-upstream annex ls-dir svn-fast-show-ignore [snipped] See 'git help <command>' for more information on a specific command. I think git is a very good example of how to do help options right. Also note that 'git $cmd -h' gives short help whilst 'git $cmd --help' shows the git-$cmd man page, which is another nice idea we could copy if it wasn't for the fact that we are currently planning to have the verb *precede* the thing it's acting on - it wouldn't make sense to group man pages by action rather than by object (or subject ;-). I know that that order matches natural language, but I have a vague hunch that it could make things harder down the road in terms of how the code dispatches to the various command handlers. Could be wildly wrong though. > > 4. I think it would be good if the HIG gave guidelines on how the > > help text should be formatted - in particular that positional > > arguments are covered by the help text (e.g. keystone-manage does > > not currently give any info on positional arguments required > > until you specify too few). > > That's a good idea. I'd propose that it be close to what we can get > out of argparse to minimise the amount of duplicated work. > > Go ahead and start drafting in the wiki. I added some ideas about '--help' and '--version', and will continue tweaking based on the progress of this discussion thread. > BTW, that page is in RST so it can be included in the source docs too. Good plan! > I'm not happy with the formatting though. Me neither :( I fixed the problem where it was generating errors about inconsistent section structure, and still struggled for quite a while to try to stop it missing out <h2> in the hierarchy (because currently it reaches <h5> which is a miniscule font size) but eventually gave up. I spoke to Anne on #openstack-infra who suggested that the wiki's CSS could be improved as a workaround. Thanks! Adam _______________________________________________ Mailing list: https://launchpad.net/~openstack Post to : openstack@lists.launchpad.net Unsubscribe : https://launchpad.net/~openstack More help : https://help.launchpad.net/ListHelp
