simplify variants/combintation explanation doc,

use bash-style substitution for envlist (although it conflicts
with the general {} subsitution which should maybe become ${...}.
IOW, re-use more of bash syntax.

1 files changed, 81 insertions, 68 deletions

diff --git a/doc/config-v2.txt b/doc/config-v2.txt
index 09ace28..eb1339b 100644
--- a/doc/config-v2.txt
+++ b/doc/config-v2.txt
@@ -44,6 +44,7 @@ coming up with its configuration language:
   - no way to check if installing via easy_install works
   - no installs of packages with compiled c-extensions (win32 standard)
 
+
 Goals, resolving those issues
 ------------------------------------
 
@@ -55,76 +56,56 @@ namely these goals:
 - allow platform-specific settings
 - allow to specify platforms against which tests should run
 - allow to run installer-variants (easy_install or pip)
+- try to mimick/re-use bash-style syntax to ease learning curve.
 
  
 Example: Generating and selecting variants
 ----------------------------------------------
  
-Suppose you want to test your package against mypkg-1.3 and mypkg-1.4
-versions, against python2.6, 2.7 interpreters and on ``linux`` and 
-``win32`` platforms.  Today you would have to 
-write down 2*2*2 = 8 ``[testenv*]`` sections and then instruct
+Suppose you want to test your package python2.6, python2.7 and on the
+windows and linux platforms.  Today you would have to 
+write down 2*2 = 4 ``[testenv:*]`` sections and then instruct
 tox to run a specific list of environments on each platform.
  
-With tox-1.X there will be no need to write down such boilerplate stuff.
-Without further ado, here is how a ``tox.ini`` would look like::
+With tox-1.X you can directlys specify combinations::
  
-    # combination syntax gives 2 * 2 * 2 = 8 testenv names
+    # combination syntax gives 2 * 2 = 4 testenv names
     #
-    envlist = [py26,py27]-[mypkg13,mypkg14]-[win,linux]
+    envlist = {py26,py27}-{win,linux}, {py31,py32}-linux
      
     [testenv]
     deps = pytest
-           # variant specific dependencies
-           mypkg13: mypkg<1.4
-           mypkg14: mypkg>=1.4,<1.5
-    platform=
+    platform =
            win: windows
            linux: linux
-    basepython=
+    basepython =
            py26: python2.6
            py27: python2.7
-
     commands = py.test
 
 Let's go through this step by step::
 
-    envlist = [py26,py27]-[mypkg13,mypkg14]-[windows,linux]
+    envlist = {py26,py27}-{windows,linux}
 
-This creates a list of ``2*2*2=8`` environment names.  It is
-a short form for writing the environments down explicitely
+This is bash-style syntax and will create ``2*2=4`` environment names
 like this::
 
-    envlist =  py26-mypkg13-windows, py26-mypkg13-linux,
-               py26-mypkg14-windows, py26-mypkg14-linux,
-               py27-mypkg13-windows, py27-mypkg13-linux,
-               py27-mypkg14-windows, py27-mypkg14-linux,
+    py26-windows
+    py26-linux
+    py27-windows
+    py27-linux
 
-Let's look at the next config item, the declaration of the generic
-testenv.  All the eight test environments will derive from this one.
-Unlike with earlier tox versions, there is no need to write down
-eight different ``[testenv:...]`` sections::
+Our ``[testenv]`` uses a new templating style for the ``platform`` definition::
 
-    [testenv]
-    deps = pytest
-           # variant specific dependencies
-           mypkg13: mypkg<1.4
-           mypkg14: mypkg>=1.4,<1.5
+    platform=
+           windows: windows
+           linux: linux
 
-This defines an unconditional dependency ``pytest`` which is going to be
-installed in all environments.  It also defines two conditional dependencies:
+With 
 
-- if ``mypkg13`` is part of the environment name, the ``mypkg<1.4`` spec 
-  will be used, otherwise the line is empty.
-- if ``mypkg14`` is part of the environment name, the ``mypkg>=1.4,<1.5`` spec 
-  will be used, otherwise the line is empty.
-
-The next configuration item defines the platform, depending on the
+ConcretelyThe next configuration item defines the platform, depending on the
 environment name for which the ``[testenv]`` is used::
 
-    platform=
-           win: windows
-           linux: linux
 
 These two conditional settings will lead to either ``windows`` or
 ``linux`` as the platform string.  When the test environment is run,
@@ -147,38 +128,55 @@ The last config item is simply the invocation of the test runner::
 
 Nothing special here :)
 
-However, as tox provides good defaults for platform and basepython
-settings, we can cut them out from our tox.ini::
+.. note::
 
-    envlist = [py26,py27]-[mypkg13,mypkg14]-[win,linux]
-     
-    [testenv]
-    deps = pytest
-           # variant specific dependencies
-           mypkg13: mypkg<1.4
-           mypkg14: mypkg>=1.4,<1.5
+    Tox provides good defaults for platform and basepython
+    settings, so the above ini-file can be further reduced::
+
+        [tox]
+        envlist = {py26,py27}-{win,linux}
+         
+        [testenv]
+        deps = pytest
+        commands = py.test
 
-Voila, this ``tox.ini`` file defines 8 environments.
+    Voila, this multi-dimensional ``tox.ini`` configuration 
+    defines 2*2=4 environments.
+
+Adding mypkg13,mypkg14 dependency variants
+--------------------------------------------
+
+XXX
+This defines an unconditional dependency ``pytest`` which is going to be
+installed in all environments.  It also defines two conditional dependencies:
+
+- if ``mypkg13`` is part of the environment name, the ``mypkg<1.4`` spec 
+  will be used, otherwise the line is empty.
+- if ``mypkg14`` is part of the environment name, the ``mypkg>=1.4,<1.5`` spec 
+  will be used, otherwise the line is empty.
 
  
 The new "platform" setting
 --------------------------------------
 
 A testenv can define a new ``platform`` setting.  If its value
-is not contained in the string obtained from calling ``platform.platform()``
-the environment will be skipped.
+is not contained in the string obtained from calling 
+``platform.platform()`` the environment will be skipped.
 
-Generator expressions in the envlist setting
+Expanding the ``envlist`` setting
 ----------------------------------------------------------
  
-The new ``envlist`` setting allows to use ``[CSV]`` expressions
-where ``CSV`` is a list of comma-separated values.  The basic
-generating algorithm works like this:
-                                                                                
-- expand: for each CSV-expression in an environment name in the list            
-  produce an additional environment name for each value in the CSV              
-- repeat: as long as there are CSV-expressions, continue the process            
+The new ``envlist`` setting allows to use ``{}`` bash-style
+expressions.  XXX explanation or pointer to bash-docs
+
+Templating based on environments names
+-------------------------------------------------
 
+For a given environment name, all lines in a testenv section which
+start with "NAME: ..." will be checked for being part in the environment
+name.  If they are part of it, the remainder will be the new line.
+If they are not part of it, the whole line will be left out.
+Parts of an environment name are obtained by ``-``-splitting it.
                                                                                 
 Variant specification with [variant:VARNAME]
 ----------------------------------------------
@@ -225,13 +223,23 @@ Default settings related to environments names/variants
 
 tox comes with predefined settings for certain variants, namely:
 
-* ``[easy,pip]`` use easy_install or pip respectively
-* ``[py24,py25,py26,py27,py31,py32,py33,pypy19]`` use the respective
+* ``{easy,pip}`` use easy_install or pip respectively
+* ``{py24,py25,py26,py27,py31,py32,py33,pypy19]`` use the respective
   pythonNN or PyPy interpreter
-* ``[win32,linux,darwin]`` defines the according ``platform``.
+* ``{win32,linux,darwin}`` defines the according ``platform``.
 
 You can use those in your “envlist” specification 
 without the need to define them yourself.
+
+
+Use more bash-style syntax
+--------------------------------------
+
+tox leverages bash-style syntax if you specify mintoxversion = 1.4:
+
+- $VARNAME or ${...} syntax instead of the older {} substitution.
+- XXX go through config.txt and see how it would need to be changed
+
  
 Transforming the examples: django-rest
 ------------------------------------------------
@@ -242,7 +250,7 @@ file has 159 lines and a lot of repetition, the new one would +have 20
 lines and almost no repetition::
  
      [tox]
-     envlist = [py25,py26,py27]-[django12,django13]-[,example]
+     envlist = {py25,py26,py27}-{django12,django13}{,-example}
  
      [testenv]
      commands = python setup.py test
@@ -253,7 +261,7 @@ lines and almost no repetition::
          django12: django==1.2.4
          django13: django==1.3.1
  
-     [variant:example]
+     [envpart:example]
      commands = python examples/runtests.py
      +deps = 
          wsgiref==0.1.2
@@ -261,12 +269,13 @@ lines and almost no repetition::
          httplib2==0.6.0
          Markdown==2.0.3
  
-Note that ``[,example]`` in the envlist denotes an empty env and the
-"example" variant.  The empty variant means that there are no specific
+Note that ``{,-example}`` in the envlist denotes an empty env and the
+"example" envpart.  The empty envpart means that there are no specific
 settings and thus no need to define a variant name. 
 
 Note also that ``+deps`` means that we are appending to dependencies,
 not substituting them.
+
  
 Transforming the examples: django-treebeard
 ------------------------------------------------
@@ -315,3 +324,7 @@ commands::
                                         --DATABASE_USER=root {posargs}
 
 It's noteworthy here that you can also use conditionals in the commands.
+
+
+
+