From abf1a7cc4b1caada799aa4549f9753b76146e243 Mon Sep 17 00:00:00 2001 From: Stephen Finucane Date: Thu, 24 Nov 2022 12:59:33 +0000 Subject: docs: Small cleanup of human interface guide Before we add more content. Change-Id: I6cf28bdd217326db991466a21221b685124d4b99 Signed-off-by: Stephen Finucane --- doc/source/contributor/humaninterfaceguide.rst | 80 ++++++++++++++------------ 1 file changed, 43 insertions(+), 37 deletions(-) (limited to 'doc/source/contributor') diff --git a/doc/source/contributor/humaninterfaceguide.rst b/doc/source/contributor/humaninterfaceguide.rst index a7db3800..29fba40e 100644 --- a/doc/source/contributor/humaninterfaceguide.rst +++ b/doc/source/contributor/humaninterfaceguide.rst @@ -117,14 +117,14 @@ interface to the user, not the user to the interface. Commands should be discoverable via the interface itself. -To determine a list of available commands, use the :code:`-h` or -:code:`--help` options: +To determine a list of available commands, use the ``-h`` or +``--help`` options: .. code-block:: bash $ openstack --help -For help with an individual command, use the :code:`help` command: +For help with an individual command, use the ``help`` command: .. code-block:: bash @@ -167,7 +167,7 @@ Command Structure OpenStackClient has a consistent and predictable format for all of its commands. -* The top level command name is :code:`openstack` +* The top level command name is ``openstack`` * Sub-commands take the form: .. code-block:: bash @@ -193,50 +193,56 @@ invocation regardless of action to be performed. They include authentication credentials and API version selection. Most global options have a corresponding environment variable that may also be used to set the value. If both are present, the command-line option takes priority. The environment variable names are derived -from the option name by dropping the leading dashes ('--'), converting each embedded -dash ('-') to an underscore ('_'), and converting to upper case. +from the option name by dropping the leading dashes (``--``), converting each embedded +dash (``-``) to an underscore (``_``), and converting to upper case. * Global options shall always have a long option name, certain common options may also have short names. Short names should be reserved for global options to limit the potential for duplication and multiple meanings between commands given the limited set of available short names. -* All long options names shall begin with two dashes ('--') and use a single dash - ('-') internally between words (:code:`--like-this`). Underscores ('_') shall not + +* All long options names shall begin with two dashes (``--``) and use a single dash + (``-`` internally between words (``--like-this``). Underscores (``_``) shall not be used in option names. + * Authentication options conform to the common CLI authentication guidelines in :ref:`authentication`. -For example, :code:`--os-username` can be set from the environment via -:code:`OS_USERNAME`. +For example, ``--os-username`` can be set from the environment via +``OS_USERNAME``. ---help -++++++ +``--help`` +++++++++++ -The standard :code:`--help` global option displays the documentation for invoking +The standard ``--help`` global option displays the documentation for invoking the program and a list of the available commands on standard output. All other options and commands are ignored when this is present. The traditional short -form help option (:code:`-h`) is also available. +form help option (``-h``) is also available. ---version -+++++++++ +``--version`` ++++++++++++++ -The standard :code:`--version` option displays the name and version on standard +The standard ``--version`` option displays the name and version on standard output. All other options and commands are ignored when this is present. Command Object(s) and Action ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Commands consist of an object described by one or more words followed by an action. Commands that require two objects have the primary object ahead of the action and the secondary object after the action. Any positional arguments identifying the objects shall appear in the same order as the objects. In badly formed English it is expressed as "(Take) object1 (and perform) action (using) object2 (to it)." +Commands consist of an object described by one or more words followed by an +action. Commands that require two objects have the primary object ahead of the +action and the secondary object after the action. Any positional arguments +identifying the objects shall appear in the same order as the objects. In +badly formed English it is expressed as "(Take) object-1 (and perform) action +(using) object-2 (to it).":: [] Examples: -* :code:`group add user ` -* :code:`volume type list` # Note that :code:`volume type` is a two-word - single object +* ``group add user `` +* ``volume type list`` (note that ``volume type`` is a two-word single object) -The :code:`help` command is unique as it appears in front of a normal command +The ``help`` command is unique as it appears in front of a normal command and displays the help text for that command rather than execute it. Object names are always specified in command in their singular form. This is @@ -256,21 +262,21 @@ meaning across multiple commands. Option Forms ++++++++++++ -* **boolean**: boolean options shall use a form of :code:`--|--` - (preferred) or :code:`--