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