Merge "Clarification of option name rules"

2 files changed, 20 insertions, 8 deletions

diff --git a/doc/source/command-options.rst b/doc/source/command-options.rst
index 5cb84684..6260ec32 100644
--- a/doc/source/command-options.rst
+++ b/doc/source/command-options.rst
@@ -14,6 +14,12 @@ for defining and using options in all situations.  The alternative of only
 using it when necessary leads to errors when copy-n-paste is used for a
 new command without understanding why or why not that instance is correct.
 
+The :doc:`Human Interface Guide <humaninterfaceguide>`
+describes the guildelines for option names and usage.  In short:
+  * All option names shall be GNU-style long names (two leading dashes).
+  * Some global options may have short nmaes, generally limited to those defined
+    in support libraries such as ``cliff``.
+
 General Command Options
 =======================
 
diff --git a/doc/source/humaninterfaceguide.rst b/doc/source/humaninterfaceguide.rst
index 5d3c48dc..400ccfcf 100644
--- a/doc/source/humaninterfaceguide.rst
+++ b/doc/source/humaninterfaceguide.rst
@@ -183,14 +183,6 @@ Output formats:
 * user-friendly tables with headers, etc
 * machine-parsable delimited
 
-Notes:
-
-* All long options names shall begin with two dashes ('--') and use a single dash
-  ('-') internally between words (:code:`--like-this`).  Underscores ('_') shall not
-  be used in option names.
-* Authentication options conform to the common CLI authentication guidelines in
-  :doc:`authentication`.
-
 Global Options
 ~~~~~~~~~~~~~~
 
@@ -202,6 +194,16 @@ the command-line option takes priority.  The environment variable names are deri
 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
+  be used in option names.
+* Authentication options conform to the common CLI authentication guidelines in
+  :doc:`authentication`.
+
 For example, :code:`--os-username` can be set from the environment via
 :code:`OS_USERNAME`.
 
@@ -245,6 +247,10 @@ Each command may have its own set of options distinct from the global options.
 They follow the same style as the global options and always appear between
 the command and any positional arguments the command requires.
 
+Command options shall only have long names.  The small range of available
+short names makes it hard for a single short option name to have a consistent
+meaning across multiple commands.
+
 Option Forms
 ++++++++++++