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

[Rob Crittenden]

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?

rob