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

[Rob Crittenden]

Petr Viktorin wrote:
> 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.
>

Ok, ACK, pushed these 8 plus 175 to master and ipa-3-1

rob