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

[Petr Viktorin]

On 02/06/2013 11:00 PM, Rob Crittenden wrote:
> Petr Viktorin wrote:
>> 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…)?
>>
>>
>
> Yeah, I missed 110 and 111. Tests are passing now.
>
> I still don't understand the purpose of outfile. What do we gain by
> making this configurable and who or what would ever change it?
>

The mechanism in the patch changes it. For `ipa help`, the output goes 
to stdout. For `ipa` (invalid invocation), there's an error and the help 
is written to stderr. So the place where the output ends up needs to be 
configurable.

-- 
Petr³