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

[David O'Brien]

Jason Gerard DeRose wrote:
> 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.
>
>   
OK, I'm happy to go either way, providing suggestions like I am here, or 
being more actively involved, editing directly and providing patches. 
What's the process?


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


-- 

David O'Brien
IPA Content Author
Red Hat Asia Pacific
+61 7 3514 8189

"The most valuable of all talents is that of never using two words when
one will do."
    Thomas Jefferson