openstack team mailing list archive

[Doug Hellmann <doug.hellmann@xxxxxxxxxxxxx>]

On Wed, May 2, 2012 at 6:01 PM, Doug Hellmann
<doug.hellmann@xxxxxxxxxxxxx>wrote:

>
>
> On Wed, May 2, 2012 at 1:23 PM, Adam Spiers <aspiers@xxxxxxxx> wrote:
>
>> Dean Troyer (dtroyer@xxxxxxxxx) wrote:
>> > On Tue, May 1, 2012 at 2:11 PM, Adam Spiers <aspiers@xxxxxxxx> wrote:
>> > > As of my recent patch, --help is contextual in nova:
>> >
>> > I hadn't seen that yet...
>> >
>> > > and I have started work on some of the other commands too, so it would
>> > > be helpful if we could reach a consensus on this soon ... although
>> > > please let me know if I am wasting my time working on other commands
>> > > due to any imminent rewrites using python-openstack!
>> >
>> > The continued existence of the project-specific commands is really up
>> > to the projects themselves.  I think it would be great to converge
>> > them on things like this, but trying to get them all to work the same
>> > is what led us to openstackclient due to backward compatibility and
>> > all.  My guess would be that the existing client binaries would live
>> > through the 'G' release even if we decided to deprecate them now.
>>
>> OK, thanks for the info.  So what's the goal for this project - to
>> enter the incubation program? to become part of openstack-common?
>> Should it be added to http://wiki.openstack.org/Projects ?
>>
>> > > I agree with Dolph - there is a precedent from other well-known
>> > > programs (git, hg, svn are the first ones I can think of) for --help
>> > > to behave differently depending on whether or not it was preceded by a
>> > > subcommand.  So my vote is that we should definitely aim to adhere to
>> > > this pattern.
>> >
>> > How about detailing it in the HIG and once we get a command or two
>> > implemented with argument parsing we give it a shot?
>>
>> I took a stab at this, but it's beginning to confirm the doubts which
>> I wrote about in https://lists.launchpad.net/openstack/msg10956.html
>> regarding the decision to have the verb preceding the noun:
>>
>>    openstack create --help
>>    openstack help create
>>
>> would require grouping of help for all the creation actions together
>> which doesn't make much sense to me.  These both seem to make more
>> sense:
>>
>>    openstack endpoint --help
>>    openstack help endpoint
>>
> but would lead to overly long output unless they invoked man(1) on a
>> corresponding manual page all about endpoint management, similar to
>> how say, 'git remote --help' invokes the git-remote(1) man page which
>> covers management of git remotes.
>>
>> The other option is to support a more fine-grained approach to help:
>>
>>    openstack create endpoint --help
>>    openstack help create endpoint
>>
>> and then make the help action require both, e.g.
>>
>>    $ openstack help create
>>    Usage: openstack help create OBJECT-TYPE
>>
>>    Which type of object do you want help creating?
>>
>>    Available identity types:
>>        catalog         ec2-credentials endpoint         role
>>        service         tenant          user             user-password
>>        user-role
>>
>>    Available compute types:
>>        absolute-limits actions         aggregate        bash-completion
>>        cloudpipe       console-log     credentials      diagnostics
>>        dns             dns-domain      endpoints        fixed-ip
>>        flavor          floating-ip     floating-ip-pool host
>>        image           keypair         meta(data)       quota
>>        quota-class     rate-limits     resource         root-password
>>        secgroup        secgroup-group  secgroup-rule    usage
>>        vnc-console     volume          volume-snapshot  volume-type
>>        x509-cert       x509-root-cert
>>
>>    [...]
>>
>> and ditto for 'openstack create --help'.  (Of course, this is just a
>> mockup and incorrectly lists some types which you would never create.)
>>
>> Here are the classes of use cases I can think of:
>>
>>  1. User has never/rarely used the (openstack) command before and
>>     needs to know overall structure of possible arguments and/or see
>>     a brief summary of common "get me started" arguments.
>>
>>     Suggested implementation:
>>         openstack --help
>>
>>  2. User has used the (openstack) command before but needs to check
>>     global options.
>>
>>     Suggested implementation:
>>         openstack --help
>>
>
> FTR, both 1 and 2 are implemented today.
>
>
>>
>>  3. User wants to e.g. create something but isn't sure of the exact
>>     name of the type of the object to be created.
>>
>>     Suggested implementation:
>>         openstack help create
>>         openstack create --help
>>
>
> It should be relatively straightforward to have the help command scan all
> available commands using the input as a substring if it doesn't match
> anything exactly. I think we probably just want to produce the list of
> those commands, though, and not go into any more detail than a one-line
> description. Doing much more is going to produce far too much output.
>

https://github.com/dreamhost/cliff/issues/8


>
>
>>
>>  4. User wants to perform one or more actions on a particular type of
>>     object e.g. volume, but isn't sure which actions are available.
>>
>>     Suggested implementation:
>>         ????
>>
>
> See comment above.
>
>
>>
>>  5. User knows both the action and object type but needs to check
>>     details of options / extra positional arguments.
>>
>>     Suggested implementation:
>>         openstack create endpoint --help
>>         openstack help create endpoint
>>
>
> FTR, the second option is how it works today.
>
>
>>
>> Thoughts?
>>
>> _______________________________________________
>> Mailing list: https://launchpad.net/~openstack
>> Post to     : openstack@xxxxxxxxxxxxxxxxxxx
>> Unsubscribe : https://launchpad.net/~openstack
>> More help   : https://help.launchpad.net/ListHelp
>>
>
>