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…)?
--
Petr³
From ed191b233f39adb6298eaf78935b20240bf8ba09 Mon Sep 17 00:00:00 2001
From: Petr Viktorin <pvikt...@redhat.com>
Date: Mon, 4 Feb 2013 07:15:54 -0500
Subject: [PATCH] In topic help text, mention how to get help for commands
This should prevent user confusion when topic help is requested
unintentionally, for example with `ipa help ping`.
See https://fedorahosted.org/freeipa/ticket/3247
---
ipalib/cli.py | 3 +++
1 files changed, 3 insertions(+), 0 deletions(-)
diff --git a/ipalib/cli.py b/ipalib/cli.py
index 173552d5835faed7e6692eed2dcb2854321127d3..c854e2faa86536babb2114f72a28332dda5e68dc 100644
--- a/ipalib/cli.py
+++ b/ipalib/cli.py
@@ -835,6 +835,9 @@ class help(frontend.Local):
for c in commands:
writer(
' %s %s' % (to_cli(c.name).ljust(mcl), c.summary))
+ writer()
+ writer(_('To get command help, use:'))
+ writer(_(' ipa <command> --help'))
writer()
class show_mappings(frontend.Command):
--
1.7.7.6
_______________________________________________
Freeipa-devel mailing list
Freeipa-devel@redhat.com
https://www.redhat.com/mailman/listinfo/freeipa-devel
