overhaul and extension and improved docs for substitutions in ini files

4 files changed, 49 insertions, 23 deletions

diff --git a/doc/example/pytest.txt b/doc/example/pytest.txt
index 823bbd1..fe0a630 100644
--- a/doc/example/pytest.txt
+++ b/doc/example/pytest.txt
@@ -5,7 +5,8 @@ py.test and tox
 .. _`py.test`: http://pytest.org 
 
 It is easy to integrate `py.test`_ runs with tox.  If you encounter 
-any issues use the :doc:`support` channels. 
+issues, please check if they are `listed as a known issue`_ and/or use 
+the :doc:`support channels <../support>`. 
 
 Basic py.test example for "extra" test directories 
 --------------------------------------------------------------
@@ -45,11 +46,13 @@ to make ``tox`` use this feature::
         --confcutdir=..         # stop looking for conftest files at parent dir
         -n 3                    # use three sub processes
 
+.. _`pytest-xdist`: http://codespeak.net/py/dist/test/plugin/xdist.html
+
 Using tox, py.test and the Hudson CI 
 -------------------------------------------
 
 The Hudson_ continous integration server allows to define "jobs" with 
-"build steps" which can be test invocations.  If you :doc:`install` ``tox`` on your
+"build steps" which can be test invocations.  If you :doc:`install <../install>` ``tox`` on your
 default Python installation on each slave, you can then have a 
 Hudson test build step invoke tox from a Python script like this::
 
@@ -68,12 +71,15 @@ for your ``argv`` parameter::
 and then configure your Hudson job to collect "JUnit test results" with the ``**/junit-*.xml`` pattern. 
 
 For a real-life example see `py.test own Hudson job configuration`_. This actually
-uses a "Parametrized Hudson built" which provides a nice configuration matrix 
+uses a "Parametrized Hudson build" which provides a nice configuration matrix 
 and lets ``tox`` handle all the underlying work of preparing and running things. 
 
 .. _`py.test own Hudson job configuration`: http://hudson.testrun.org/view/pytest/job/pytest-multi/configure
+.. _`Hudson`: http://hudson-ci.org/
+
+.. _`listed as a known issue`:
 
-Issues and limitations 
+Known Issues and limitations 
 -----------------------------
 
 * tox does not work on the Windows/Python3/Virtualenv3 combination due to limitations of the virtualenv3 project  
diff --git a/doc/support.txt b/doc/support.txt
index 84b2ce1..68a0a3e 100644
--- a/doc/support.txt
+++ b/doc/support.txt
@@ -1,17 +1,22 @@
+
+.. _support:
+
 tox contact and support channels 
 =====================================
 
 You are welcome to:
 
 * join `tox-dev`_ for general discussions
+* hang out on the irc.freenode.net #pylib channel 
+* `report on the issue tracker`_
 * join `tox-commit`_ to be notified of source changes
 * `clone the mercurial repository`_ and submit patches
-* hang out on the irc.freenode.net #pylib channel 
 * follow the `tetamap blog`_ or `Holger's twitter presence`_.
 * contact merlinux_ if you want to buy teaching or other support. 
 
 .. _`Holger's twitter presence`: http://twitter.com/hpk42
 .. _merlinux: http://merlinux.eu
+.. _`report on the issue tracker`: http://code.google.com/p/pytox/issues/list
 .. _`tetamap blog`: http://tetamap.wordpress.com
 .. _`tox-dev`: http://codespeak.net/mailman/listinfo/execnet-dev
 .. _`tox-commit`: http://codespeak.net/mailman/listinfo/execnet-commit
diff --git a/doc/toxini.txt b/doc/toxini.txt
index d162295..81e3d9e 100644
--- a/doc/toxini.txt
+++ b/doc/toxini.txt
@@ -14,9 +14,9 @@ Global settings
 List of optional global options::
 
     [global]
-    toxdir=path      # tox directory, defaults to .tox
+    toxworkdir=path      # tox directory, defaults to .tox
     packagedir=path  # defaults to dirpath of tox.ini file
-    logdir=path      # defaults to {toxdir}/log
+    logdir=path      # defaults to {toxworkdir}/log
 
 Test environment settings 
 ------------------------------
@@ -35,27 +35,28 @@ testenvironment default section.
 
 Complete list of settings that you can put into ``testenv*`` sections:
 
-python=NAME-OR-PATH
-    name or path to a Python interpreter which will be used for creating the virtual 
-    environment. 
+``python=NAME-OR-PATH``
+    name or path to a Python interpreter which will be used for creating
+    the virtual environment. 
 
-argv=MULTI-LINE
+``argv=MULTI-LINE``
     the test command to be called for testing. Each line defines one 
     item of a list that will be passed to ``subprocess.Popen``. 
 
-tmpdir=path
+``tmpdir=path``
     XXX defines a temporary directory of the virtualenv, 
     available via the ``envtmpdir`` substition, defaults to 
 
-deps=MULTI-LINE-LIST
-    dependencies to be installed into the environment prior to project package installation.
-    Each line defines a dependency, which will be passed to easy_install/pip for processing. 
+``deps=MULTI-LINE-LIST``
+    dependencies to be installed into the environment prior to project
+    package installation.  Each line defines a dependency, which will be
+    passed to easy_install/pip for processing. 
 
-changedir=path 
+``changedir=path``
     change to this working directory when executing the test command. 
     **default**: package setup directory. 
 
-downloadcache=path 
+``downloadcache=path``
     (pip only) use this directory for caching downloads - this defaults to the 
     environment variable ``PIP_DOWNLOAD_CACHE`` if it is set. 
     **default**: no download cache will be used. 
@@ -65,7 +66,7 @@ downloadcache=path
     [testenv:NAME]   # a section defininig a virtualenv test environment
     python=name-or-path   # name of Python intepreter, to be found on system path
 
-distribute=BOOL
+``distribute=BOOL``
     Set to ``True`` if you want to use distribute in the virtual environment. 
     **default:** False. (setuptools will be used)
 
@@ -74,11 +75,25 @@ Substitutions
 
 Settings can generally use string-substitution like this::
 
-    CHANGEDIR={envtmpdir} 
+    changedir={envtmpdir} 
 
-Possible substitions::
+Global substitutions
++++++++++++++++++++++++++++++
 
-envname
+``{toxinidir}`` 
+    the directory where tox.ini is located 
+``{toxworkdir}`` 
+    the directory where virtual environments are created and sub directories
+    for packaging reside. 
+    
+substitions related to virtualenvs
+++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+``{envname}``
     the name of the virtual environment 
-envtmpdir
+``{envdir}``
+    directory of the the virtualenv hierarchy
+``{envbindir}``
+    directory where executables are located 
+``{envtmpdir}``
     the environment temporary directory 
diff --git a/doc/usecases.txt b/doc/usecases.txt
index 643e54f..b03a438 100644
--- a/doc/usecases.txt
+++ b/doc/usecases.txt
@@ -61,7 +61,7 @@ This would Driven by a section of the ``tox.ini`` file::
     search_executeable = *
 
     [setup]
-    envbasedir = toxdir 
+    toxworkdir = toxworkdir 
     virtualenv = 
 
 Effectively