From 75a1fcf70a7780691ad6d432e76d6f86933079ff Mon Sep 17 00:00:00 2001 From: Dean Troyer Date: Fri, 22 Jul 2016 12:58:24 -0500 Subject: Clarification of option name rules We never specifcally said anywhere that short names are global only and why. Change-Id: Ia2824cb7ebe7c2e1d116c0a9bc7760de24904c61 --- doc/source/humaninterfaceguide.rst | 22 ++++++++++++++-------- 1 file changed, 14 insertions(+), 8 deletions(-) (limited to 'doc/source/humaninterfaceguide.rst') 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 ++++++++++++ -- cgit v1.2.1