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

[Jan Zelený]

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