Open Stack

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.

> 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.  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].

>  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.

>     (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...

>  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.  This probably belongs with the specific command
definitions.

>  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'.

>       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.  ;)

>  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.

BTW, that page is in RST so it can be included in the source docs too.
 I'm not happy with the formatting though.

dt

-- 

Dean Troyer
dtroyer at gmail.com