There are several problems with the "ipa" tool online help.
By "online help" I mean usage messages produced by running the tool itself. By "man pages" I mean manual pages accessed using "man" command.
Both the man page and the online help specify COMMAND as required. However, running ipa without arguments doesn't produce an error. Either COMMAND should be specified as optional maybe with a description of what ipa does when it's not specified, or, better, ipa should produce an error in this case, saying that the command is not specified, followed by the usage message, all output to stderr, followed by an appropriate exit status.
This part of the "ipa" output is very confusing:
Built-in commands: Help subtopics: console Start the IPA interactive Python console. Help subtopics: help Display help for a command or topic. Help subtopics: show-mappings Show mapping of LDAP attributes to command-line option. Help topics:
What are "Built-in commands"? Why there are three "Help subtopics:" headers? Why do they come before "Help topics:" header?
Then, it is not apparent what the user is supposed to do with "Help topics". I.e. there is no description for the "ipa help <COMMAND>" syntax there.
At a first glance, it is easy to mistake the list of help topics for the list of commands. The next attempted command to retrieve online help, for example, quite naturally, "ipa user --help" produces this:
ipa: ERROR: unknown command 'user'
But, in contradiction, "ipa user" produces a usage message with exit status indicating success.
The specific command usage messages are also unsuitable. They include introductory texts more appropriate for man pages than quick online help. Online help is consulted often, but introductory texts are read only once or twice. Those take too much space in the terminal output, pushing previous console output, which the user often needs, too far above.
Having examples in the online help is more useful than introductory texts, but doesn't justify impairing user's ability to view previous console output. A couple of lines would be fine, but probably no more.
The CLI users have come to expect more general help information closer to the top of the output. However, the most general information - the command list - is output at the bottom. This is done, apparently, to have it closer to the prompt after running the command, because otherwise it would be pushed too far above by the other output, i.e. the introductory text and examples. Considering that those are unnecessary, at least in present amount, the order could be reversed.
All-in-all, a good example to follow would be git online help organization with a few exceptions. Namely, "--help" option and "ipa help <COMMAND>" shouldn't invoke man pages, because this is non-standard, thus unexpected and breaks the user's focus.
This also means, that "ipa <COMMAND-PREFIX>" syntax, as in "ipa user", shouldn't be accepted, but "ipa help <COMMAND-PREFIX>", or "man ipa <COMMAND-PREFIX>" should be.
Man pages could also be organized in a manner similar to git man pages. I.e. the main man page listing all the commands and separate man pages for every command.
The online help shouldn't substitute man pages - it is there for a quick lookup as a cheat sheet. A cheat sheet should be accessible with the least effort and the least interference.
This is all nice feedback but we are not going to redesign the whole thing. It is what it is. If you have any specific suggestions of how to make it better without breaking the ABI please list them here.
For now I recommend to put this ticket into the Deferred bucket.
This doesn't require changing the interface apart from the interface used to retrieve online help. And even that not by much. I will prepare description of specific interface design on Monday.
I will let the developers speak here but a lot of thought and effort have been invested into the online help. It is all driven by the main plugin framework and it is not easy to change.
Also any change to the interface is an ABI change. That was a design decision to follow the: ipa help <command> pattern. Think about help as a specific top level command as any other command.
It was a conscious decision and I do not see a value in changing it. AFAIR it is even documented in the man page, but I am not sure about that. If it is not may be this is what we need to do to make it clearer.
I am definitely against any redesign here. We can change text and formatting of the online help and man pages but we will not change the interface.
Replying to [comment:3 dpal]:
Please let me describe specifically what I propose to change and we'll see if it's possible and if it's worth it. I hope it's not that hard.
Also any change to the interface is an ABI change.
I assume you wanted to say that any interface change may affect users and break something. I'd say "ABI" usage here is misplaced. ABI is "Application Binary Interface" and CLI definitely isn't one.
I agree that CLI should be changed carefully, especially in an already widely used product. However, the changes I propose are minimal and the affected interfaces are most likely not used for automation.
That was a design decision to follow the: ipa help <command> pattern. Think about help as a specific top level command as any other command.
Yes, it is fine and I have nothing against it.
It was a conscious decision and I do not see a value in changing it. AFAIR it is even documented in the man page, but I am not sure about that. If it is not may be this is what we need to do to make it clearer. I am definitely against any redesign here. We can change text and formatting of the online help and man pages but we will not change the interface.
First of all, I've changed my opinion on help topics, i.e. the output of "ipa help <TOPIC>" commands. I was confusing commands and topics, not in the least because of the confusing help messages.
However, please see my proposal to change other things below.
Change the ipa -h/--help output
The current output has several problems:
requires invocation of "ipa help commands", which produces a huge list, to find out even most often used commands:
$ ipa --help Usage: ipa [options]
Options: -h, --help show this help message and exit -e KEY=VAL Set environment variable KEY to VAL -c FILE Load configuration from FILE -d, --debug Produce full debuging output --delegate Delegate the TGT to the IPA server -v, --verbose Produce more verbose output. A second -v displays the XML-RPC request -a, --prompt-all Prompt for ALL values (even if optional) -n, --no-prompt Prompt for NO values (even if required) -f, --no-fallback Only use the server configured in /etc/ipa/default.conf
Available help topics: ipa help topics
Available commands: ipa help commands
Instead, output something like this:
$ ipa --help Usage: ipa [global-options] COMMAND [command-options] Manage IPA domain. Global options: -h, --help Show this help message and exit -e KEY=VAL Set environment variable KEY to VAL -c FILE Load configuration from FILE -d, --debug Produce full debuging output --delegate Delegate the TGT to the IPA server -v, --verbose Produce more verbose output. A second -v displays the XML-RPC request -a, --prompt-all Prompt for ALL values (even if optional) -n, --no-prompt Prompt for NO values (even if required) -f, --no-fallback Only use the server configured in /etc/ipa/default.conf Often used commands: help Display help for a command or topic. user-add Add a new user. user-del Delete a user. user-show Display information about a user. host-add Add a new host. host-del Delete a host. host-show Display information about a host. console Start the IPA interactive Python console. 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.
The tool description in the second line and the contents of the "often used commands" list are just examples.
Change the result of executing "ipa"
Current result is identical to "ipa help", which is wrong, because it violates the syntax described in the resulting output itself:
$ ipa Usage: ipa [global-options] COMMAND ... Built-in commands: Help subtopics: console Start the IPA interactive Python console. Help subtopics: help Display help for a command or topic. Help subtopics: show-mappings Show mapping of LDAP attributes to command-line option. Help topics: automember Auto Membership Rule. automount Automount cert IPA certificate operations config Server configuration delegation Group to Group Delegation dns Domain Name System (DNS) group Groups of users hbac Host-based access control commands hbactest Simulate use of Host-based access controls host Hosts/Machines hostgroup Groups of hosts. krbtpolicy Kerberos ticket policy migration Migration to IPA misc Misc plug-ins netgroup Netgroups passwd Set a user's password permission Permissions ping Ping the remote IPA server to ensure it is running. pkinit Kerberos pkinit options privilege Privileges pwpolicy Password policy range Manage ID ranges role Roles selfservice Self-service Permissions selinuxusermap SELinux User Mapping service Services sudo commands for controlling sudo configuration trust Manage trust relationship between realms user Users Try `ipa --help` for a list of global options.
Instead, produce an error message telling COMMAND is missing, followed by the -h/--help output (as proposed above), all done to stderr. Exit with non-zero exit status:
$ ipa ipa: ERROR: command not specified Usage: ipa [global-options] COMMAND [command-options] Manage IPA domain. Global options: -h, --help Show this help message and exit -e KEY=VAL Set environment variable KEY to VAL -c FILE Load configuration from FILE -d, --debug Produce full debuging output --delegate Delegate the TGT to the IPA server -v, --verbose Produce more verbose output. A second -v displays the XML-RPC request -a, --prompt-all Prompt for ALL values (even if optional) -n, --no-prompt Prompt for NO values (even if required) -f, --no-fallback Only use the server configured in /etc/ipa/default.conf Often used commands: help Display help for a command or topic. user-add Add a new user. user-del Delete a user. user-show Display information about a user. host-add Add a new host. host-del Delete a host. host-show Display information about a host. console Start the IPA interactive Python console. 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.
Remove support for "ipa <TOPIC>" invocation syntax
Current result is successful exit status and, "ipa help <TOPIC>" output, like this:
$ ipa pkinit Kerberos pkinit options Enable or disable anonymous pkinit using the principal WELLKNOWN/ANONYMOUS@REALM. The server must have been installed with pkinit support. EXAMPLES: Enable anonymous pkinit: ipa pkinit-anonymous enable Disable anonymous pkinit: ipa pkinit-anonymous disable For more information on anonymous pkinit see: http://k5wiki.kerberos.org/wiki/Projects/Anonymous_pkinit Topic commands: pkinit-anonymous Enable or Disable Anonymous PKINIT.
Instead, produce an error and --help output to stderr, exit with non-zero exit status:
$ ipa pkinit ipa: ERROR: unknown command 'pkinit' Usage: ipa [global-options] COMMAND [command-options] Manage IPA domain. Global options: -h, --help Show this help message and exit -e KEY=VAL Set environment variable KEY to VAL -c FILE Load configuration from FILE -d, --debug Produce full debuging output --delegate Delegate the TGT to the IPA server -v, --verbose Produce more verbose output. A second -v displays the XML-RPC request -a, --prompt-all Prompt for ALL values (even if optional) -n, --no-prompt Prompt for NO values (even if required) -f, --no-fallback Only use the server configured in /etc/ipa/default.conf Often used commands: help Display help for a command or topic. user-add Add a new user. user-del Delete a user. user-show Display information about a user. host-add Add a new host. host-del Delete a host. host-show Display information about a host. console Start the IPA interactive Python console. 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.
Alternative: add help topics to the command list
Alternatively, add help topics to the list of commands (i.e. "ipa help commands" output), like this:
user Output help on user management commands. user-add Add a new user. user-del Delete a user.
Fix error reporting for option usage with such commands. I.e. instead of:
$ ipa user --help ipa: ERROR: unknown command 'user'
Do this:
$ ipa user --help ipa: ERROR: no such option: --foo
However, this would still be confusing in case of typos. For example, a user might have typed "ipa user" instead of "ipa user-mod" in a script and got a succesful exit status. It is better to produce an error in such case.
Also, this is contradictory. If "user" is a valid command, then "ipa help user" should produce help message on that command, i.e. its options, etc., and not a help topic. Note how the option usage error above isn't followed by this command usage message.
So, I would definitely vote for removing "ipa <TOPIC>" syntax altogether.
Change "ipa help topics" output
Current output is mixed with irrelevant and confusing information, making it harder to read:
$ ipa help topics Usage: ipa [global-options] COMMAND ... Built-in commands: Help subtopics: console Start the IPA interactive Python console. Help subtopics: help Display help for a command or topic. Help subtopics: show-mappings Show mapping of LDAP attributes to command-line option. Help topics: automember Auto Membership Rule. automount Automount cert IPA certificate operations config Server configuration delegation Group to Group Delegation dns Domain Name System (DNS) group Groups of users hbac Host-based access control commands hbactest Simulate use of Host-based access controls host Hosts/Machines hostgroup Groups of hosts. krbtpolicy Kerberos ticket policy migration Migration to IPA misc Misc plug-ins netgroup Netgroups passwd Set a user's password permission Permissions ping Ping the remote IPA server to ensure it is running. pkinit Kerberos pkinit options privilege Privileges pwpolicy Password policy range Manage ID ranges role Roles selfservice Self-service Permissions selinuxusermap SELinux User Mapping service Services sudo commands for controlling sudo configuration trust Manage trust relationship between realms user Users Try `ipa --help` for a list of global options.
This is apparently done so the output of "ipa help" makes more sense, which is abuse of the purpose. See also below.
Instead, output just the help topic table, the same way as it is done for "ipa help commands":
$ ipa help topics automember Auto Membership Rule. automount Automount cert IPA certificate operations config Server configuration delegation Group to Group Delegation dns Domain Name System (DNS) group Groups of users hbac Host-based access control commands hbactest Simulate use of Host-based access controls host Hosts/Machines hostgroup Groups of hosts. krbtpolicy Kerberos ticket policy migration Migration to IPA misc Misc plug-ins netgroup Netgroups passwd Set a user's password permission Permissions ping Ping the remote IPA server to ensure it is running. pkinit Kerberos pkinit options privilege Privileges pwpolicy Password policy range Manage ID ranges role Roles selfservice Self-service Permissions selinuxusermap SELinux User Mapping service Services sudo commands for controlling sudo configuration trust Manage trust relationship between realms user Users
Change the result of executing "ipa help"
Current result is identical to "ipa help topics", the latter being "augmented" to be suitable for both purposes. As a result, it isn't very suitable for either.
The output should be short introduction to the tool and the help system instead. Something like this:
$ ipa help ipa - Manage IPA domain. See "ipa --help" for general usage. See "ipa help --help" for "help" command usage. See "ipa help topics" for the list of help topics. See "ipa help commands" for the list of commands.
This output could also contain a list of most often used commands and help topics.
Add command description to the "ipa <COMMAND> -h/--help" output
The current "ipa <COMMAND> -h/--help" output doesn't mention the purpose of the tool, only usage, for example:
$ ipa pkinit-anonymous --help Usage: ipa [global-options] pkinit-anonymous ACTION [options] Positional arguments: ACTION <action> Options: -h, --help show this help message and exit
Add tool description after the "Usage:" line, the one used in the "ipa help commands" output, like this:
$ ipa pkinit-anonymous --help Usage: ipa [global-options] pkinit-anonymous ACTION [options] Enable or Disable Anonymous PKINIT. Positional arguments: ACTION <action> Options: -h, --help show this help message and exit
Closing remarks
Thank you for reading through this long proposal. I hope at least some of the changes could be implemented. Maybe this bug should be split into several bugs to simplify handling.
I'll take this.
I have objection to current 'ipa dnsrecord-mod -h' behaviour:
# ipa dnsrecord-mod -h Usage: ipa [global-options] dnsrecord-mod DNSZONE NAME [options] Positional arguments: DNSZONE Zone name NAME Record name Options: -h, --help show this help message and exit --ttl=INT Time to live --class=['IN', 'CS', 'CH', 'HS'] DNS class
There is no clear pointer to 'ipa help dns' command. At least this pointer + sentence or two about this particular command would be useful.
Ticket has been cloned to Bugzilla: https://bugzilla.redhat.com/show_bug.cgi?id=910545
CLI specific, no UXD input needed
master: [[br]] 614082e [[br]] abe26d5 [[br]] de1c4ee [[br]] 6ac0e9b [[br]] 5ee2216 [[br]] 1e2437e [[br]] 5f5b4c3 [[br]]
ipa-3-1: [[br]] 991f471[[br]] bd8d4ac[[br]] 9da7d1a[[br]] 640c255[[br]] bfb310f[[br]] 6cb8148[[br]] 56659f3[[br]]
Fix component name.
Metadata Update from @nkondras: - Issue assigned to pviktori - Issue set to the milestone: FreeIPA 3.2 - 2013/02
Login to comment on this ticket.