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³
_______________________________________________
Freeipa-devel mailing list
Freeipa-devel@redhat.com
https://www.redhat.com/mailman/listinfo/freeipa-devel
