[Freeipa-devel] [PATCH] Modified ipa help behavior

[Rob Crittenden]

Jan Zelený wrote:
> Rob Crittenden<rcritten at redhat.com>  wrote:
>> Jan Zelený wrote:
>>> Jan Zelený<jzeleny at redhat.com>   wrote:
>>>> Now each plugin can define its topic as a 2-tuple, where the first
>>>> item is the name of topic it belongs to and the second item is
>>>> a description of such topic. Topic descriptions must be the same
>>>> for all modules belonging to the topic.
>>>>
>>>> By using this topics, it is possible to group plugins as we see fit.
>>>> When asking for help for a particular topic, help for all modules
>>>> in given topic is written.
>>>>
>>>> ipa help - show all topics (until now it showed all plugins)
>>>> ipa help<topic>   - show details to given topic
>>>>
>>>> https://fedorahosted.org/freeipa/ticket/410
>>>
>>> Sorry for the wrong sequence number, sending the correct one now.
>>
>> I think this is a good start but I find the output hard to read, both
>> with a single topic (like user) or multiple (like sudo). The dashed
>> lines and the extra spaces make my eyes cross a bit
>>
>> What I don't have is any good suggestion to change it up. I realize you
>> are jamming together discrete things that may or may not look nice
>> together.
>>
>> I suppose a few suggestions might be:
>>
>> - a SEEALSO-like where you print the topics at the bottom so it is
>> obvious that multiple things are jammed together
>> - A single dashed-line all the way across (more or less) with a single
>> space before and after might be a less jarring separator. IIRC we have
>> some output code that should handle screen sizes for you.
>> - I'm not sure if combining all the commands into a single list is the
>> right thing or not. It may not be necessary with the SEEALSO.
>>
>> So nack for now but this is headed in the right direction.
>>
>> rob
>
> I gave this some thought:
>
> Output for each single-module topic is given by module's doc string. How good
> readability it has is not up to help function, but rather up to the developer
> of that particular module. The only thing I can do is not to display the
> separator.
>
> And as for multiple topics - I can change the concept to support two-level
> topics. That way when asking for the first level, it would display either
> entire single-module topic with its commands or it will only display a brief
> description of the topic and a list of its subtopics (this is based on your
> suggestion with SEEALSO section). Asking for one of these subtopics will
> output the same help as it would for single-module topic. I'm not sure about
> usability of this though. Personally I'd probably be asking who invented a
> help, which needs 4 shell commands to get to a help of IPA command:
> ipa help
> ipa help sudo
> ipa help sudocmd
> ipa help sudocmd-add
>
> I tried your other suggestions and the result doesn't look significantly better
> than the current one.
>
> What do you think is the best way to proceed?
>
> Jan

The multiple commands for a given logical topic weren't really a 
consideration when the framework was created. At that time we were only 
considering very high-level topics like user, group and host.

To example on your comment about the per-module documentation, that 
seems to be key. We have a separate ticket open against hbac-add to 
include per-command documentation on access time format.

So I'm wondering if we need to re-think how we'd documenting things.

Right now we have on the order of 178 commands. That is a LOT of man 
pages even if we used some sort of automated XML system. We just need to 
do the right thing before GA.

Rather than combining the help from all the similar commands just show 
the top-level and include a SEEALSO?

So for example for: ipa help hbac

We would just show the hbac top-level help and include a SEEALSO for 
hbacsvc and hbacsvcgroup rather than including those top-level help as well?

Similarly for sudo.

rob