Added reference documentation for command-line options (#354)

* Added reference documentation for command-line options

- Intentionally didn't document -o, -O and -n

  Offline mode is an attractive nuisance.

  -n is unlikely to be needed and can be spelled newest=true

- Removed -o, -O and -n from command help.

- Sorted options alphabetically in the reference doc and command help.

- Removed documentation of the log-level option.  It just confuses things.
  I seriously doubt that anyone uses it.

doc/reference.rst

@@ -11,35 +11,95 @@ A Buildout execution is of the form:
 
 .. code-block:: console
 
-  buildout [buildout-options] [settings] [subcommand [subcommand-arguments]]
+  buildout [buildout-options] [assignments] [command [command arguments]]
 
-Settings take the form ``section:option=value`` and override (or
-augment) settings in configuration files.  For example, to pin a
+Assignments take the form ``section:option=value`` and override (or
+augment) options in configuration files.  For example, to pin a
 version of ZEO you could use ``versions:ZEO=4.3.1``.  The section
 defaults to the ``buildout`` section.  So, for example: ``parts=test``
 sets the ``buildout`` section ``parts`` option.
 
-Command-line settings overrides can use ``+=`` and ``-=`` to
+Command-line assignments can use ``+=`` and ``-=`` to
 :ref:`merge values with existing values <merge-values-with-existing-values>`
 
-Buildout options
-----------------
+Buildout command-line options
+-----------------------------
 
-Buildout subcommands
---------------------
+.. _-c-option:
 
-.. _bootstrap-subcommand:
+``-c config_file``
+  Specify the path (or URL) to the buildout configuration file to be used.
+  This defaults to the file named ``buildout.cfg`` in the current
+  working directory.
+
+``-D``
+  Debug errors.  If an error occurs, then the post-mortem debugger
+  will be started. This is especially useful for debugging recipe
+  problems.
+
+``-h``, ``--help``
+  Print basic usage information and exit.
+
+``-N``
+  Run in :ref:`non-newest mode <non-newest-mode>`.  This is equivalent
+  to the command-line assignment ``newest=false``.
+
+``-q``
+  Decrease the level of verbosity.  This option can be used multiple
+  times.
+
+  Using a single ``-q`` suppresses normal output, but still shows
+  warnings and errors.
+
+  Doubling the option ``-qq`` (or equivalently ``-q -q``) suppresses
+  normal output and warnings.
+
+  Using the option more than twice suppresses errors, which is a bad idea.
+
+``-t socket_timeout``
+  Specify the socket timeout in seconds. See the
+  :ref:`socket-timeout option <socket-timeout-option>` for details.
+
+``-U``
+  Don't use :ref:`user-default configuration <user-default-configuration>`.
+
+``-v``
+  Increase the level of verbosity.  This option can be used multiple
+  times.
+
+  At the default verbosity, buildout prints messages about significant
+  activities.  It also prints warning and error messages.
+
+  At the next, "verbose", level (``-v``), it prints much
+  more information. In particular, buildout will show when and why
+  it's installing specific distribution versions.
+
+  At the next, "debugging", level, ``-vv`` (or equivalently ``-v
+  -v``), buildout prints low-level debugging information, including a
+  listing of all configuration options, including: default options,
+  computed options and the results of :ref:`value substitutions
+  <value-substitutions>` and :ref:`macros <macros-label>`.
+
+  Using this option more than twice has no effect.
+
+``--version``
+  Print buildout version number and exit.
+
+Buildout commands
+-----------------
+
+.. _bootstrap-command:
 
 bootstrap
 _________
 
-Install a local ``bootstrap`` script.  The ``bootstrap`` subcommand
+Install a local ``bootstrap`` script.  The ``bootstrap`` command
 doesn't take any arguments.
 
 See :doc:`Bootstrapping <topics/bootstrapping>` for information on why
 you might want to do this.
 
-.. _init-subcommand:
+.. _init-command:
 
 init [requirements]
 ____________________
@@ -248,16 +308,6 @@ log-format, default: ''
   If ``log-format`` is non-blank, then it will be used for the root logger
   [#root-logger]_ (and for Buildout's messages).
 
-log-level, default: 'INFO'
-  The `logging level
-  <https://docs.python.org/3/library/logging.html#logging-levels>`_.
-
-  This may be adjusted with the :ref:`-v option <-v-option>` or the
-  :ref:`-q option <-q-option>`, which are the more common ways to control
-  the logging level.
-
-  The ``log-level`` option is rarely used.
-
 .. _newest-mode:
 
 .. _non-newest-mode:
@@ -276,11 +326,13 @@ offline, default: 'false'
 
   .. Warning:: Offline mode is deprecated.
 
-     Its purpose has evolved over time and the end result doesn't
-     make much sense, but it is retained for backward compatibility.
+     Its purpose has evolved over time and the end result doesn't make
+     much sense, but it is retained (indefinitely) for backward
+     compatibility.
 
-     If you think you want an offline mode, you probably want the
-     :ref:`install-from-cache <install-from-cache-mode>` mode instead.
+     If you think you want an offline mode, you probably want either
+     the :ref:`non-newest mode <non-newest-mode>` or the
+     :ref:`install-from-cache mode <install-from-cache-mode>` instead.
 
   In offline mode, no network requests should be made.  It's the
   responsibility of recipes to adhere to this.  Recipes that would
@@ -310,6 +362,8 @@ show-picked-versions, default: 'false'
   lines it would write to a versions configuration if the
   :ref:`update-versions-file <update-versions-file>` option was used.
 
+.. _socket-timeout-option:
+
 socket-timeout, default: ''
   Specify a socket timeout [#socket-timeout]_, in seconds, to use when
   downloading distributions and other artifacts.  If non-blank, the

doc/topics/bootstrapping.rst

@@ -30,10 +30,10 @@ Avoid modifying the python environment.
   Unfortunately, doing this requires :ref:`using a bootstrap script
   <using-a-bootstrap-script>`.
 
-Local bootstrapping using the ``buildout`` subcommand
-=====================================================
+Local bootstrapping using the ``bootstrap`` command
+===================================================
 
-You can use the :ref:`bootstrap subcommand <bootstrap-subcommand>` of a
+You can use the :ref:`bootstrap command <bootstrap-command>` of a
 ``buildout`` script installed in your Python environment to boostrap
 the buildout in the current directory:
 
@@ -129,8 +129,8 @@ Bootstrapping requires a ``buildout.cfg``, ``init`` creates one
 Normally, when bootstrapping, the local directory must have a
 ``buildout.cfg`` file.
 
-If you don't have one, you can use the :ref:`init subcommand
-<init-subcommand>` instead:
+If you don't have one, you can use the :ref:`init command
+<init-command>` instead:
 
 .. code-block:: console
 

doc/topics/variables-extending-and-substitutions.rst

@@ -67,8 +67,8 @@ user default values
 options from one or more configuration files
   These override user defaults and each other, as described below.
 
-option values in the :ref:`buildout command line <buildout-command-line>`
-  These override configuration-file settings.
+option assignments in the :ref:`buildout command line <buildout-command-line>`
+  These override configuration-file options.
 
 .. _extends_option:
 
@@ -345,7 +345,7 @@ original *lines*. This is a bit delicate.  In the example above,
 we were careful to put the base values on separate lines, in
 anticipation of using ``-=``.
 
-Merging values also works with option settings provided via the
+Merging values also works with option assignments provided via the
 :ref:`buildout command line <buildout-command-line>`.  For example, if
 you want to temporarily use a :ref:`development version
 <python-development-projects>` of another project, you can augment the

src/zc/buildout/buildout.py

@@ -1777,27 +1777,32 @@ Usage: buildout [options] [assignments] [command [command arguments]]
 
 Options:
 
-  -h, --help
+  -c config_file
 
-     Print this message and exit.
+    Specify the path to the buildout configuration file to be used.
+    This defaults to the file named "buildout.cfg" in the current
+    working directory.
 
-  --version
+  -D
 
-     Print buildout version number and exit.
+    Debug errors.  If an error occurs, then the post-mortem debugger
+    will be started. This is especially useful for debuging recipe
+    problems.
 
-  -v
+  -h, --help
 
-     Increase the level of verbosity.  This option can be used multiple times.
+    Print this message and exit.
 
-  -q
+  -N
 
-     Decrease the level of verbosity.  This option can be used multiple times.
+    Run in non-newest mode.  This is equivalent to the assignment
+    buildout:newest=false.  With this setting, buildout will not seek
+    new distributions if installed distributions satisfy it's
+    requirements.
 
-  -c config_file
+  -q
 
-     Specify the path to the buildout configuration file to be used.
-     This defaults to the file named "buildout.cfg" in the current
-     working directory.
+    Decrease the level of verbosity.  This option can be used multiple times.
 
   -t socket_timeout
 
@@ -1807,37 +1812,13 @@ Options:
 
     Don't read user defaults.
 
-  -o
-
-    Run in off-line mode.  This is equivalent to the assignment
-    buildout:offline=true.
-
-  -O
-
-    Run in non-off-line mode.  This is equivalent to the assignment
-    buildout:offline=false.  This is the default buildout mode.  The
-    -O option would normally be used to override a true offline
-    setting in a configuration file.
-
-  -n
-
-    Run in newest mode.  This is equivalent to the assignment
-    buildout:newest=true.  With this setting, which is the default,
-    buildout will try to find the newest versions of distributions
-    available that satisfy its requirements.
-
-  -N
+  -v
 
-    Run in non-newest mode.  This is equivalent to the assignment
-    buildout:newest=false.  With this setting, buildout will not seek
-    new distributions if installed distributions satisfy it's
-    requirements.
+    Increase the level of verbosity.  This option can be used multiple times.
 
-  -D
+  --version
 
-    Debug errors.  If an error occurs, then the post-mortem debugger
-    will be started. This is especially useful for debuging recipe
-    problems.
+    Print buildout version number and exit.
 
 Assignments are of the form: section:option=value and are used to
 provide configuration options that override those given in the
@@ -1888,7 +1869,6 @@ Commands:
     alphabetically. For each section, all key-value pairs are displayed,
     sorted alphabetically, along with the origin of the value (file name or
     COMPUTED_VALUE, DEFAULT_VALUE, COMMAND_LINE_VALUE).
-
 """
 
 def _help():

src/zc/buildout/tests.py

@@ -615,6 +615,12 @@ def test_help():
     <BLANKLINE>
     Options:
     <BLANKLINE>
+      -c config_file
+    <BLANKLINE>
+         Specify the path to the buildout configuration file to be used.
+         This defaults to the file named "buildout.cfg" in the current
+         working directory.
+    ...
       -h, --help
     ...
 
@@ -625,6 +631,12 @@ def test_help():
     <BLANKLINE>
     Options:
     <BLANKLINE>
+      -c config_file
+    <BLANKLINE>
+         Specify the path to the buildout configuration file to be used.
+         This defaults to the file named "buildout.cfg" in the current
+         working directory.
+    ...
       -h, --help
     ...
     """