[Freeipa-devel] [PATCH] Add more sophisticated help interface. Split commands into 'topics'.
David O'Brien
davido at redhat.com
Fri Apr 17 00:46:15 UTC 2009
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.
>
> 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?
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
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
More information about the Freeipa-devel
mailing list