[Checkins] SVN: z3c.recipe.mkdir/trunk/z3c/recipe/mkdir/README.txt Extend tests for new functionalities.

[Uli Fouquet]

Log message for revision 102932:
  Extend tests for new functionalities.
  

Changed:
  U   z3c.recipe.mkdir/trunk/z3c/recipe/mkdir/README.txt

-=-
Modified: z3c.recipe.mkdir/trunk/z3c/recipe/mkdir/README.txt
===================================================================
--- z3c.recipe.mkdir/trunk/z3c/recipe/mkdir/README.txt	2009-08-19 00:23:46 UTC (rev 102931)
+++ z3c.recipe.mkdir/trunk/z3c/recipe/mkdir/README.txt	2009-08-19 00:24:32 UTC (rev 102932)
@@ -1,6 +1,25 @@
 Detailed Description
 ********************
 
+.. contents::
+
+
+Recipe Options
+==============
+
+``z3c.recipe.mkdir`` provides the following options:
+
+* ``path``
+    Contains the path(s) of directories created in normalized,
+    absolute form. I.e.:: 
+
+      mydir/../foo/bar
+
+    becomes
+
+      /path/to/buildout-dir/foo/bar
+
+
 Simple creation of directories via buildout
 ===========================================
 
@@ -35,7 +54,8 @@
 
 Lets create a minimal `buildout.cfg` file. This time the directory
 has a name different from section name and we have to tell explicitly,
-that we want it to be created in the ``parts/`` directory:
+that we want it to be created in the ``parts/`` directory. We set the
+``path`` option to do so:
 
   >>> write('buildout.cfg',
   ... '''
@@ -121,6 +141,102 @@
   d  finaldir
 
 
+Paths are normalized
+====================
+
+If we specify a non-normalized path (i.e. one that contains references
+to parent directories or similar), the path will be normalized before
+creating it:
+
+  >>> write('buildout.cfg',
+  ... '''
+  ... [buildout]
+  ... parts = mydir
+  ... offline = true
+  ...
+  ... [mydir]
+  ... recipe = z3c.recipe.mkdir
+  ... path = myroot/foo/../dir1/../bar/.
+  ... ''')
+
+  >>> print system(join('bin', 'buildout')),
+  Uninstalling mydir.
+  Installing mydir.
+
+Only ``bar/`` will be created:
+
+  >>> ls('myroot')
+  d  bar
+
+
+Creating multiple paths in a row
+================================
+
+We can create multiple paths in one buildout section:
+
+  >>> write('buildout.cfg',
+  ... '''
+  ... [buildout]
+  ... parts = mydir
+  ... offline = true
+  ...
+  ... [mydir]
+  ... recipe = z3c.recipe.mkdir
+  ... path = myroot/dir1
+  ...        myroot/dir2
+  ... ''')
+
+  >>> print system(join('bin', 'buildout')),
+  Uninstalling mydir.
+  Installing mydir.
+
+  >>> ls('myroot')
+  d  dir1
+  d  dir2
+
+Note, that in this case you cannot easily reference the set path from
+other recipes or templates. If, for example in a template you
+reference::
+
+  root_dir = ${mydir:path}
+
+the result will become::
+
+  root_dir = /path/to/buildout/dir1
+  path/to/buildout/dir2
+
+If you specify only one path, however, the second line will not appear.
+
+Use several sections using `z3c.recipe.mkdir` if you want to reference
+different created paths from templates or similar.
+
+
+Trailing slashes do not matter
+==============================
+
+It doesn't matter, whether you specify the paths with trailing slash
+or without:
+
+  >>> write('buildout.cfg',
+  ... '''
+  ... [buildout]
+  ... parts = mydir
+  ... offline = true
+  ...
+  ... [mydir]
+  ... recipe = z3c.recipe.mkdir
+  ... path = myroot/dir3/
+  ...        myroot/dir4
+  ... ''')
+
+  >>> print system(join('bin', 'buildout')),
+  Uninstalling mydir.
+  Installing mydir.
+
+  >>> ls('myroot')
+  d  dir3
+  d  dir4
+
 Things to be aware of
 =====================