Merge 95b7dfc into 543672f

docs/changes.rst

@@ -169,6 +169,12 @@ Released: not yet
 
 * Docs: Increased the width of the help text to 120 (See issue #548).
 
+* Modified the help usage to better reflect the required and optional
+  components of the command line. This includes showing the location
+  in the cmd line for general options where before it was called
+  [COMMAND-OPTIONS] and showing the positioning of both arguments and
+  command arguments. (See issue #446)
+
 **Cleanup:**
 
 * Test: Enabled Python warning suppression for PendingDeprecationWarning

docs/pywbemcli/cmdlineinterface.rst

@@ -28,23 +28,39 @@ The command line can contain the following components:
 * **GENERAL-OPTIONS** - General options; they apply to all commands.
   See :ref:`Using the pywbemcli command line general options` for information
   on the pywbemcli general options.
-* **COMMAND-GROUP** - A name of a group of commands.
-  See :ref:`Pywbemcli command groups and commands`
-* **COMMAND** - A name of a command, normally within a command group.
-  There are however some special commands (``repl`` and ``help``) that are not
-  in any command group.
-* **COMMAND-OPTIONS** - Command options; they apply only to a particular
-  command.
+
+* **COMMAND** - A name of a command which may consist of:
+  * <group name> <command name> for those commands that are defined in
+    groups (ex. `class find`).
+  * Just the group name (ex. `class`).
+  * <command name> for those commands that are not part of a group. (``repl``
+    and ``help``) that are not in any command group.
 * **ARGS** - Arguments for a command.
+* **COMMANDD-OPTIONS** - Command options; they apply only to a particular
+  command.
+
 
 Options are prefixed with the characters ``-`` for the short form or ``--`` for
 the long form (ex. ``-n`` or ``--namespace``). The other components do not
 begin with ``-``.
 
 Command groups are named after the objects the commands operate on
-(ex. ``class``, ``instance``, ``qualifier``, ``server``).
+(ex. ``class``, ``instance``, ``qualifier``, ``server``). Executing
+
+.. code-block::text
+
+   $ pywbemcli --help
+   ...
+   Commands:
+     class       Command group for CIM classes.
+   ...
+
+
+returns the list of command groups under the title `COMMANDS`.
+
 Commands are named after actions on these objects
-(ex. ``get``, ``create``, ``delete``).
+(ex. ``get``, ``create``, ``delete``). The list of commands for each group
+is listed with the command `pywbemcli <group name> --help`.
 
 For example, the command:
 
@@ -61,8 +77,8 @@ and ``--namespace`` is a command option.
    single: auto-completion
    single: auto-suggestion
 
-Pywbemcli supports several modes of tab-completion, auto-completion suggestions 
-and depending on whether it is in command or interactive mode. This is detailed 
+Pywbemcli supports several modes of tab-completion, auto-completion suggestions
+and depending on whether it is in command or interactive mode. This is detailed
 in the following sections.
 
 
@@ -91,7 +107,7 @@ command group name and arguments/options:
 
 .. code-block:: text
 
-    $ pywbemcli [GENERAL-OPTIONS] [COMMAND-GROUP] COMMAND [COMMAND-OPTIONS] [ARGS]
+    $ pywbemcli [GENERAL-OPTIONS] COMMAND [COMMAND-OPTIONS] [ARGS]
 
 The following example enumerates classes in the ``root/cimv2`` namespace of the
 WBEM server on ``localhost``:
@@ -175,7 +191,10 @@ user):
 
 .. code-block:: text
 
-    pywbemcli> [GENERAL-OPTIONS] [COMMAND-GROUP] COMMAND [COMMAND-OPTIONS] [ARGS]
+    pywbemcli> [GENERAL-OPTIONS] COMMAND [ARGS] [COMMAND-OPTIONS]
+
+        where: COMMAND can be either a group name and
+               a command (ex. class find or repl)
 
     pywbemcli> :INTERNAL-COMMAND
 
@@ -232,10 +251,10 @@ list of the supported command groups and commands without command group.
 
     $ pywbemcli
     pywbemcli> --help
-    Usage: pywbemcli [GENERAL-OPTIONS] COMMAND [ARGS]...
+    Usage: pywbemcli [GENERAL-OPTIONS] COMMAND [ARGS] [COMMAND-OPTIONS]
     . . .
 
-    Options:
+    General Options:
       -n, --name NAME                 Use the WBEM server ...
       . . .
 
@@ -247,17 +266,17 @@ list of the supported command groups and commands without command group.
 The usage line in this help text shows the usage in command mode. In
 interactive mode, the ``pywbemcli`` word is omitted.
 
-Typing ``COMMAND-GROUP --help``,  or ``COMMAND-GROUP -h`` in the pywbemcli shell
+Typing ``COMMAND --help``,  or ``COMMAND -h`` in the pywbemcli shell
 displays help information for the specified pywbemcli command group, for
 example:
 
 .. code-block:: text
 
     pywbemcli> class --help
-    Usage: pywbemcli class [COMMAND-OPTIONS] COMMAND [ARGS]...
+    Usage: pywbemcli [GENERAL-OPTIONS] class COMMAND [ARGS] [COMMAND-OPTIONS]
     . . .
 
-    Options:
+    Command Options:
       -h, --help  Show this message and exit.
 
     Commands: