[Freeipa-devel] [PATCHES] 0107-0114 Fix Confusing ipa tool online help organization

[Petr Viktorin]

On 02/01/2013 06:06 PM, Rob Crittenden wrote:
> Petr Viktorin wrote:
>> On 01/31/2013 07:35 PM, Rob Crittenden wrote:
>>> Petr Viktorin wrote:
>>>> On 12/14/2012 01:46 AM, Dmitri Pal wrote:
>>>>> On 12/13/2012 10:21 AM, Petr Viktorin wrote:
>>>>>> https://fedorahosted.org/freeipa/ticket/3060
>>>>>>
>>>>>> Here is a collection of smallish fixes to `ipa help` and `ipa
>>>>>> <something> --help`.
>>>>>> This should address most of Nikolai's proposal.
>>>>>> Additionally, it's now possible to run `ipa <command> --help` without
>>>>>> a Kerberos ticket. And there are some new tests.
>>>>>>
>>>>>> I've not included the "Often used commands" in `ipa help`; I think
>>>>>> that is material for a manual/tutorial, not a help command. Selecting
>>>>>> a topic from `ipa topics` and then choosing a command from `ipa help
>>>>>> <TOPIC>` is a better way to use the help than the verbose `ipa help
>>>>>> commands` or proposed incomplete "Often used commands".
>>>>>
>>>>> Since the ticket has a bit of discussion and you indicate that you did
>>>>> not to address everything can you please extract what have been
>>>>> addressed and put it into a design page.
>>>>> I know it is not RFE but it would help to validate the changes by
>>>>> testers.
>>>>> Please put the wiki link into the ticket.
>>>>>
>>>>
>>>> http://freeipa.org/page/V3/Help
>>>>
>>>>
>>>
>>> What is the purpose of the no-option outfile? Do you anticipate at some
>>> point opening this up as a real option or making it easier to log while
>>> using the api directly?
>>
>> On incorrect invocation (`ipa`, `ipa TOPIC`), the help command is called
>> internally with outfile=sys.stderr.
>
> That's true, but this is a lot of code to abstract writing to
> sys.stderr. I'm just trying to understand the reasoning. Do you imagine
> that some time in the future we'd want to control where the output goes?

I don't think that would be useful, I can't imagine why someone would 
want to log help texts, or use them to script something.
Do you have another idea of how this should be done?

>>> The help for help is a little confusing:
>>>
>>> -----
>>> Purpose: Display help for a command or topic.
>>> Usage: ipa [global-options] help [TOPIC] [options]
>>>
>>> Positional arguments:
>>>    TOPIC       The topic or command name.
>>>
>>> Options:
>>>    -h, --help  show this help message and exit
>>> -----
>>>
>>> Should [TOPIC] be [TOPIC | COMMAND] or something else?
>>
>> I'm trying to discourage `ipa help COMMAND` in favor of `ipa COMMAND
>> --help`, that way you get the proper help for ambiguous words like
>> "ping" (https://fedorahosted.org/freeipa/ticket/3247)
>>
>> I also wanted to keep the help simple and not explain this unimportant
>> detail here.
>>
>> If you have better wording I can of course change it.
>
> Your reasoning is sound. I"m ok with gently pushing users in that
> direction but leaving undocumented the old behavior. Should we create a
> ticket to eventually return an error in that case?

Users will expect `ipa help COMMAND` to get them command help, it's 
pretty standard in tools with subcommands. If it was a part of the API 
I'd be all for enforcing proper usage, but I think a help command 
deserves some slack -- it's not that big a deal if you get topic help 
for ping instead of command help...
Hm. Now I see that I should add a notice to the topic help text, to lead 
users to the right path. Patch attached.

We will want to remove `ipa help COMMAND` from the docs, and note that 
"ipa help" favors topics.
We can turn https://fedorahosted.org/freeipa/ticket/3247 into a doc ticket.


>>> On my fresh F-18 install one of the new unit tests fails:
>>>
>>> ======================================================================
>>> FAIL: Test that `help user-add` & `user-add -h` are equivalent and
>>> contain doc
>>> ----------------------------------------------------------------------
>>> Traceback (most recent call last):
>>>    File "/usr/lib/python2.7/site-packages/nose/case.py", line 197, in
>>> runTest
>>>      self.test(*self.arg)
>>>    File "/home/rcrit/redhat/freeipa/tests/test_cmdline/test_help.py",
>>> line 111, in test_command_help
>>>      assert h_ctx.stdout == help_ctx.stdout
>>> AssertionError
>>
>> This is weird, it works for me. Could you send me the two outputs so I
>> can get some idea what's wrong?
>>

Can you check you didn't leave out patch 111 (Add command summary…)?


-- 
Petr³

-------------- next part --------------
A non-text attachment was scrubbed...
Name: freeipa-pviktori-0175-In-topic-help-text-mention-how-to-get-help-for-comma.patch
Type: text/x-patch
Size: 1053 bytes
Desc: not available
URL: <http://listman.redhat.com/archives/freeipa-devel/attachments/20130204/756b328f/attachment.bin>