Re: [Freeipa-devel] [PATCHES] 0107-0114 Fix Confusing ipa tool online help organization
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. Im 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
Re: [Freeipa-devel] [PATCHES] 0107-0114 Fix Confusing ipa tool online help organization
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. Im 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 ___ Freeipa-devel mailing list Freeipa-devel@redhat.com https://www.redhat.com/mailman/listinfo/freeipa-devel
Re: [Freeipa-devel] [PATCHES] 0107-0114 Fix Confusing ipa tool online help organization
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? 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. Im 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? 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 D'oh, yeah I fat-fingered it. Here is the test output: help_ctx.stdout (len 1805) type unicode Purpose: Add a new user. Usage: nosetests [global-options] user-add LOGIN [options] Positional arguments: LOGIN User login Options: -h, --help show this help message and exit --first=STRFirst name --last=STR Last name --cn=STR Full name --displayname=STR Display name --initials=STR Initials --homedir=STR Home directory --gecos=STRGECOS field --shell=STRLogin shell --principal=STRKerberos principal --email=STREmail address --password Prompt to set the user password --random Generate a random user password --uid=INT User ID Number (system will assign one if not provided) --gidnumber=INTGroup ID Number --street=STR Street address --city=STR City --state=STRState/Province --postalcode=STR ZIP --phone=STRTelephone Number --mobile=STR Mobile Telephone Number --pager=STRPager Number --fax=STR Fax Number --orgunit=STR Org. Unit --title=STRJob Title --manager=STR Manager --carlicense=STR Car License --sshpubkey=STRSSH public key --setattr=STR Set an attribute to a name/value pair. Format is attr=value. For multi-valued attributes, the command replaces the values already present.
Re: [Freeipa-devel] [PATCHES] 0107-0114 Fix Confusing ipa tool online help organization
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? 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? 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 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 rob ___ Freeipa-devel mailing list Freeipa-devel@redhat.com https://www.redhat.com/mailman/listinfo/freeipa-devel
Re: [Freeipa-devel] [PATCHES] 0107-0114 Fix Confusing ipa tool online help organization
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 -- Petr³ ___ Freeipa-devel mailing list Freeipa-devel@redhat.com https://www.redhat.com/mailman/listinfo/freeipa-devel
Re: [Freeipa-devel] [PATCHES] 0107-0114 Fix Confusing ipa tool online help organization
On 12/14/2012 06:30 AM, 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 Thanks! -- Thank you, Dmitri Pal Sr. Engineering Manager for IdM portfolio Red Hat Inc. --- Looking to carve out IT costs? www.redhat.com/carveoutcosts/ ___ Freeipa-devel mailing list Freeipa-devel@redhat.com https://www.redhat.com/mailman/listinfo/freeipa-devel
[Freeipa-devel] [PATCHES] 0107-0114 Fix Confusing ipa tool online help organization
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.
--
Petr³
From 869fac2e8a6d402ab2f93dc0a14dcbfa0f40ad1c Mon Sep 17 00:00:00 2001
From: Petr Viktorin pvikt...@redhat.com
Date: Tue, 6 Nov 2012 11:05:41 -0500
Subject: [PATCH] Improve `ipa --help` output
Fix the usage string to match actual usage.
Add command description.
Put information about `ipa help topics` etc. to the epilog,
instead of using empty option groups. Use a custom formatter
to preserve newlines.
Add the -h/--help option manually to ensure consistent case
(capital S).
Part of the effort for https://fedorahosted.org/freeipa/ticket/3060
---
ipalib/plugable.py | 37 ++---
1 files changed, 30 insertions(+), 7 deletions(-)
diff --git a/ipalib/plugable.py b/ipalib/plugable.py
index f3d185e14332f9f97937e2f1bc26069447eab855..46149795431174f8568994bb8db0d56d8510f5e5 100644
--- a/ipalib/plugable.py
+++ b/ipalib/plugable.py
@@ -34,6 +34,8 @@ from os import path
import subprocess
import optparse
import errors
+import textwrap
+
from config import Env
import util
import text
@@ -519,8 +521,23 @@ class API(DictProxy):
Add global options to an optparse.OptionParser instance.
if parser is None:
-parser = optparse.OptionParser()
+parser = optparse.OptionParser(
+add_help_option=False,
+formatter=IPAHelpFormatter(),
+usage='%prog [global-options] COMMAND [command-options]',
+description='Manage an IPA domain',
+epilog='\n'.join([
+'See ipa help topics for available help topics.',
+'See ipa help TOPIC for more information on a '
+'specific topic.',
+'See ipa help commands for the full list of commands.',
+'See ipa help COMMAND for more information on a '
+'specific command.',
+]))
parser.disable_interspersed_args()
+parser.add_option(-h, --help, action=help,
+help='Show this help message and exit')
+
parser.add_option('-e', dest='env', metavar='KEY=VAL', action='append',
help='Set environment variable KEY to VAL',
)
@@ -548,12 +565,6 @@ class API(DictProxy):
dest='fallback',
help='Only use the server configured in /etc/ipa/default.conf'
)
-topics = optparse.OptionGroup(parser, Available help topics,
-ipa help topics)
-cmds = optparse.OptionGroup(parser, Available commands,
-ipa help commands)
-parser.add_option_group(topics)
-parser.add_option_group(cmds)
return parser
@@ -730,3 +741,15 @@ class API(DictProxy):
object.__setattr__(self, 'plugins',
tuple(PluginInfo(p) for p in plugins.itervalues())
)
+
+
+class IPAHelpFormatter(optparse.IndentedHelpFormatter):
+def format_epilog(self, text):
+text_width = self.width - self.current_indent
+indent = * self.current_indent
+lines = text.splitlines()
+result = '\n'.join(
+textwrap.fill(line, text_width, initial_indent=indent,
+subsequent_indent=indent)
+for line in lines)
+return '\n%s\n' % result
--
1.7.7.6
From ab861ae10d270523851a0f05ce0d45fedbff05a7 Mon Sep 17 00:00:00 2001
From: Petr Viktorin pvikt...@redhat.com
Date: Tue, 6 Nov 2012 11:45:50 -0500
Subject: [PATCH] Print help to stderr on error
Whenever a command is used incorrectly, it should output
an error message (and possibly additional help) to stderr.
This patch adds a parameter to a bunch of places to allow
selecting either stdout or stderr for help output, and makes
badly called commands output to stderr only.
Part of the effort for https://fedorahosted.org/freeipa/ticket/3060
---
ipalib/cli.py | 76 ++--
1 files changed, 46 insertions(+), 30 deletions(-)
diff --git a/ipalib/cli.py b/ipalib/cli.py
index ac0eb058912246ef6f2c7aed34299dceae505990..704a75ca3510cfb0b26ffdb57d7f3cded250d8fd 100644
--- a/ipalib/cli.py
+++ b/ipalib/cli.py
@@ -50,7 +50,7 @@ from errors import (PublicError, CommandError, HelpError, InternalError,
NoSuchNamespaceError, ValidationError, NotFound, NotConfiguredError,
Re: [Freeipa-devel] [PATCHES] 0107-0114 Fix Confusing ipa tool online help organization
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. ___ Freeipa-devel mailing list Freeipa-devel@redhat.com https://www.redhat.com/mailman/listinfo/freeipa-devel -- Thank you, Dmitri Pal Sr. Engineering Manager for IdM portfolio Red Hat Inc. --- Looking to carve out IT costs? www.redhat.com/carveoutcosts/ ___ Freeipa-devel mailing list Freeipa-devel@redhat.com https://www.redhat.com/mailman/listinfo/freeipa-devel
