[Freeipa-devel] [PATCH] Add more sophisticated help interface. Split commands into 'topics'.

[Jason Gerard DeRose]

On Fri, 2009-04-17 at 10:46 +1000, David O'Brien wrote:
> Pavel Zuna wrote:
> > Rob Crittenden wrote:
> >> Pavel Zuna wrote:
> >>> This is more of a suggestion than a real patch. I thought it might 
> >>> be easier to actually show what I had in mind than explaining it. 
> >>> Sometimes code is more than words. :)
> >>>
> >>> Pavel
> >>
> >> I think this is a good start. The output looks like:
> >>
> >> $ ipa
> >> Usage: ipa [global-options] COMMAND ...
> >>
> >> Use `ipa help TOPIC` for command listings.
> >>
> >> Topics:
> >>   general      General IPA management.
> >>   aci          ACI object.
> >>   application  Application object
> >>   automount    Automount object.
> >>   delegation   Delegation object.
> >>   group        group object.
> >>   host         Host object.
> >>   hostgroup    hostgroup object.
> >>   netgroup     netgroup object.
> >>   rolegroup    rolegroup object.
> >>   service      Service object.
> >>   taskgroup    taskgroup object.
> >>   user         User object.
> >>
> >> Try `ipa --help` for a list of global options.
> >>
> >> It looks like you dumped things that aren't related to a top-level 
> >> class into general (things like passwd, the cert commands, and a few 
> >> others). I guess they have to go somewhere, just not sure I'd know to 
> >> look in general if I was a new user.
> >>
> >> Should we mandate an Object for every plugin? Or include the list of 
> >> these general commands in the main topics list? That might be 
> >> confusing too because that would mean that 'env' is on the same level 
> >> as 'user'.
> >>
> >> Any suggestions?
> >>
> >> The patch is good and we could easily just apply this but I don't 
> >> want to forget about these issues. In any case we'll want to go into 
> >> each plugin and set the Object documentation to be more descriptive.
> >>
> >> rob
> > I wrote another version of the help interface today taking into 
> > consideration the issues you mentioned. It's based on plugins this 
> > time instead of objects.
> >
> > The output looks like this:
> >
> > $ ipa
> > Usage: ipa [global-options] COMMAND ...
> >
> > Built-in commands:
> >   console         Start the IPA interactive Python console.
> >   help            Display help for a command or topic.
> >
> > Help topics:
> >   aci             Frontend plugins for managing DS ACIs
> >   application     Frontend plugins for application policy containers.
> >   automount       Frontend plugins for automount.
> >   defaultoptions  Frontend plugin for default options in IPA.
> >   delegation      Frontend plugins for delegations.
> >   dns             Frontend plugin for DNS management.
> >   group           Frontend plugins for groups.
> >   hbac            Frontend plugin for HBAC management.
> >   host            Frontend plugins for host/machine Identity.
> >   hostgroup       Frontend plugins for hostgroups.
> >   join            Machine join
> >   misc            Misc frontend plugins.
> >   netgroup        Frontend plugins for netgroups.
> >   passwd          Frontend plugins for password changes.
> >   pwpolicy        Frontend plugins for password policy.
> >   rolegroup       Frontend plugins for rolegroups.
> >   service         Frontend plugins for service (Identity).
> >   taskgroup       Frontend plugins for taskgroups.
> >   user            Frontend plugins for user (Identity).
> >
> > Try `ipa --help` for a list of global options.

I think these docstrings should not include the phrase "frontend
plugins".  I think changing them to read something like this would be
better:

aci          Commands to manage accesses control ACIs.
application  Commands to manage application policy containers.
automount    Commands to manage automount maps.

Or something like that, perhaps even more concise.

> > Commands not originating from plugins are listed as built-ins. The 
> > short description for topics is taken from the first line of the 
> > module's docstring.
> >
> > The code itself is a bit hacky, because I just couldn't find any 
> > better way to get every plugin module, it's docstring a list of 
> > commands it implements. I'll rewrite it if necessary.
> >
> > Pavel
> > ------------------------------------------------------------------------
> >
> > _______________________________________________
> > Freeipa-devel mailing list
> > Freeipa-devel at redhat.com
> > https://www.redhat.com/mailman/listinfo/freeipa-devel
> How much work is involved in editing the first line of a module's 
> docstring? Is it developer-only territory or straight-forward enough 
> that I could do it?

It's strait-forward.

> I ask because I'm interested in keeping everything related to doc, help, 
> etc., on an even keel and consistent, which in this case means:
> s/plugin/plug-in
> s/backend/back-end
> s/frontend/front-end

As mentioned, in this case I we should use more concise docstrings
instead.  I think it's a great idea to have the CLI help and the
documentation be consistent where possible, but the help docstrings have
very space constrained because ideally the should be short enough as to
not wrap on a 80 character wide terminal.

> I would also review the use of terms like "host/machine", because in IPA 
> 2.0 "host" refers to the host object specifically created to represent 
> the host *machine*, and which exists as a new object in DS. "Machine", 
> on the other hand, refers to the computer itself. (This gets trickier 
> when we start talking about the "host" where a virtual machine is 
> running.) Hopefully my understanding of host objects and machines is 
> correct here.
> 
> So, in the case of "host : Frontend plugins for host/machine Identity." 
> I'd suggest a change to "host : Front-end plug-ins for machine identity."
> 
> 1. front-end (as per style guide)
> 2. plug-ins (as per style guide)
> 3. machine (we're identifying the machine, and using the host object to 
> do it)
> 4. identity (lower case)
> 
> regards,
>