Added missing section on conditional sections (#360)

Added missing section on conditional sections

Fortunately, I was able to move and update the not-bad doctest here,
because it was more doc than test.

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

@@ -131,6 +131,91 @@ extends-cache buildout option <extends-cache-buildout-option>`.
 When a relative path is used in an extends option, it's interpreted
 relative to the path of the extending configuration.
 
+Conditional configuration sections
+==================================
+
+Sometimes, you need different configuration in different environments
+(different operating systems, or different versions of Python).  To
+make this easier, you can define environment-specific options by
+providing conditional sections:
+
+.. code-block:: ini
+
+    [ctl]
+    suffix =
+
+    [ctl:windows]
+    suffix = .bat
+
+.. -> conf
+
+    >>> import zc.buildout.configparser
+    >>> import six
+    >>> zc.buildout.configparser.parse(
+    ...     six.StringIO(conf), 'test', lambda : dict(windows=True))
+    {'ctl': {'suffix': '.bat'}}
+    >>> zc.buildout.configparser.parse(
+    ...     six.StringIO(conf), 'test', lambda : dict(windows=False))
+    {'ctl': {'suffix': ''}}
+
+In this tiny example, we've defined a ``ctl:suffix`` option that's
+``.bat`` on Windows and an empty string elsewhere.
+
+A conditional section has a colon and then a Python expression after
+the name.  If the Python expression result is true, the section
+options from the section are included.  If the value is false, the
+section is ignored.
+
+Some things to note:
+
+- If there is no exception, then options from the section are
+  included.
+
+- Sections and options can be repeated.  If an option is repeated, the
+  last value is used. In the example above, on Windows, the second
+  ``suffix`` option overrides the first.  If the order of the sections
+  was reversed, the conditional section would have no effect.
+
+In addition to the normal built-ins, the expression has access to
+global variables that make common cases short and descriptive as shown
+below
+
+=============  ====================================================
+Name           Value
+=============  ====================================================
+sys            ``sys`` module
+os             ``os`` module
+platform       ``platform`` module
+re             ``re`` module
+python2        True if running Python 2
+python3        True if running Python 3
+python26       True if running Python 2.6
+python27       True if running Python 2.7
+python32       True if running Python 3.2
+python33       True if running Python 3.3
+python34       True if running Python 3.4
+python35       True if running Python 3.5
+python36       True if running Python 3.6
+sys_version    ``sys.version.lower()``
+pypy           True if running PyPy
+jython         True if running Jython
+iron           True if running Iron Python
+cpython        True if not running PyPy, Jython, or Iron Python
+sys_platform   ``str(sys.platform).lower()``
+linux          True if running on linux
+windows        True if running on Windows
+cygwin         True if running on cygwin
+solaris        True if running on solaris
+macosx         True if running on Mac OS X
+posix          True if running on a POSIX-compatible system
+bits32         True if running on a 32-bit system.
+bits64         True if running on a 64-bit system.
+little_endian  True if running on a little-endian system
+big_endian     True if running on a little-endian system
+=============  ====================================================
+
+Expressions must not contain either the ``#`` or the ``;`` character.
+
 .. _user-default-configuration:
 
 User-default configuration

src/zc/buildout/buildout.txt

@@ -1237,133 +1237,6 @@ Cleanup.
     >>> os.remove(os.path.join(sample_buildout, 'base.cfg'))
     >>> rmdir(sample_buildout, 'demo')
 
-Conditional sections
---------------------
-
-Sometimes, you need different configuration in different environments
-(different operating systems, or different versions of Python).  To
-make this easier, you can define environment-specific options by
-providing conditional sections::
-
-    [ctl]
-    suffix =
-
-    [ctl:windows]
-    suffix = .bat
-
-.. -> conf
-
-    >>> import zc.buildout.configparser
-    >>> zc.buildout.configparser.parse(
-    ...     StringIO.StringIO(conf), 'test', lambda : dict(windows=True))
-    {'ctl': {'suffix': '.bat'}}
-    >>> zc.buildout.configparser.parse(
-    ...     StringIO.StringIO(conf), 'test', lambda : dict(windows=False))
-    {'ctl': {'suffix': ''}}
-
-In this tiny example, we've defined a ``ctl:suffix`` option that's
-``.bat`` on Windows and an empty string elsewhere.
-
-A conditional section has a colon and then a Python expression after
-the name.  If the Python expression result is true, the section
-options from the section are included.  If the value is false, the
-section is ignored.
-
-Some things to note:
-
-- If there is no exception, then options from the section are
-  included.
-
-- Sections and options can be repeated.  If an option is repeated, the
-  last value is used. In the example above, on Windows, the second
-  ``suffix`` option overrides the first.  If the order of the sections
-  was reversed, the conditional section would have no effect.
-
-In addition to the normal built-ins, the expression has access to
-global variables that make common cases short and descriptive as shown
-below
-
-sys
-  the ``sys`` module
-
-os
-  the ``os`` module
-
-platform
-  the ``platform`` module
-
-re
-  The ``re`` module
-
-python2
-  We're running Python 2
-
-python3
-  We're running Python 3
-
-python26
-  We're running Python 2.6
-
-python27
-  We're running Python 2.7
-
-python32
-  We're running Python 3.2
-
-python33
-  We're running Python 3.3
-
-sys_version
-  ``sys.version.lower()``
-
-pypy
-  We're running PyPy
-
-jython
-  We're running Jython
-
-iron
-  We're running Iron Python
-
-cpython
-  We're not running PyPy, Jython, or Iron Python
-
-sys_platform
-  ``str(sys.platform).lower()``
-
-linux
-  We're running on linux
-
-windows
-  We're running on Windows
-
-cygwin
-  We're running on cygwin
-
-solaris
-  We're running on solaris
-
-macosx
-  We're running on Mac OS X
-
-posix
-  We're running on a POSIX-compatible system
-
-bits32
-  We're running on a 32-bit system.
-
-bits64
-  We're running on a 64-bit system.
-
-little_endian
-  We're running on a little-endian system
-
-big_endian
-  We're running on a little-endian system
-
-Expressions must not contain either the ``#`` or the ``;`` character.
-
-
 Adding and removing options
 ---------------------------