Open Stack

Dean Troyer (dtroyer at gmail.com) wrote:
> On Mon, Apr 30, 2012 at 11:13 AM, Adam Spiers <aspiers at 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