On Wed, May 2, 2012 at 6:01 PM, Doug Hellmann <doug.hellm...@dreamhost.com>wrote:
> > > On Wed, May 2, 2012 at 1:23 PM, Adam Spiers <aspi...@suse.com> wrote: > >> Dean Troyer (dtro...@gmail.com) wrote: >> > On Tue, May 1, 2012 at 2:11 PM, Adam Spiers <aspi...@suse.com> 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@lists.launchpad.net >> Unsubscribe : https://launchpad.net/~openstack >> More help : https://help.launchpad.net/ListHelp >> > >
_______________________________________________ Mailing list: https://launchpad.net/~openstack Post to : openstack@lists.launchpad.net Unsubscribe : https://launchpad.net/~openstack More help : https://help.launchpad.net/ListHelp
