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

[Petr Viktorin]

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.

> 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.

> 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?

> I'm not sure the errors to stderr are working either:
>
> $ ipa user-show foo bar baz 2 > /dev/null
> ipa: ERROR: command 'user_show' takes at most 1 argument

That's just bash being evil, passing 2 as an argument and redirecting 
stdout.

$ ipa user-show foo bar baz 2>/tmp/err
$ cat /tmp/err
ipa: ERROR: command 'user_show' takes at most 1 argument

-- 
Petr³