Merge branch 'master' of https://github.com/telmich/cdist into feature__cdist_autodep_try2

Conflicts:
	docs/man/man7/cdist-manifest.text

docs/man/cdist-reference.text.sh

@@ -131,7 +131,8 @@ confdir/type/<name>/explorer::
 
 confdir/type/<name>/files::
     This directory is reserved for user data and will not be used
-    by cdist at any time
+    by cdist at any time. It can be used for storing supplementary
+    files (like scripts to act as a template or configuration files).
 
 out/::
     This directory contains output of cdist and is usually located
@@ -175,13 +176,22 @@ OBJECTS
 For object to object communication and tests, the following paths are
 usable within a object directory:
 
+files::
+    This directory is reserved for user data and will not be used
+    by cdist at any time. It can be used freely by the type 
+    (for instance to store template results).
 changed::
     This empty file exists in an object directory, if the object has
     code to be excuted (either remote or local)
+stdin::
+    This file exists and contains data, if data was provided on stdin 
+    when the type was called.
 
 
-ENVIRONMENT VARIABLES
----------------------
+ENVIRONMENT VARIABLES (FOR READING)
+-----------------------------------
+The following environment variables are exported by cdist:
+
 __explorer::
     Directory that contains all global explorers.
     Available for: initial manifest, explorer, type explorer, shell
@@ -219,6 +229,15 @@ __type_explorer::
     Directory that contains the type explorers.
     Available for: type explorer
 
+ENVIRONMENT VARIABLES (FOR WRITING)
+-----------------------------------
+The following environment variables influence the behaviour of cdist:
+
+require::
+    Setup dependencies between objects (see cdist-manifest(7))
+
+CDIST_ALLOW_OVERRIDE::
+    Allow overwriting type parameters (see cdist-manifest(7))
 
 SEE ALSO
 --------

docs/man/man1/cdist.text

@@ -127,10 +127,16 @@ usage: __git --source SOURCE [--state STATE] [--branch BRANCH]
 ENVIRONMENT
 -----------
 TMPDIR, TEMP, TMP::
-   Setup the base directory for the temporary directory.
-   See http://docs.python.org/py3k/library/tempfile.html for
-   more information. This is rather useful, if the standard
-   directory used does not allow executables.
+    Setup the base directory for the temporary directory.
+    See http://docs.python.org/py3k/library/tempfile.html for
+    more information. This is rather useful, if the standard
+    directory used does not allow executables.
+
+CDIST_LOCAL_SHELL::
+    Selects shell for local script execution, defaults to /bin/sh
+
+CDIST_REMOTE_SHELL::
+    Selects shell for remote scirpt execution, defaults to /bin/sh
 
 
 EXIT STATUS

docs/man/man7/cdist-best-practice.text

@@ -164,8 +164,8 @@ For more details consult sudoers(5)
 
 TEMPLATING
 ----------
-* create directory templates/ in your type (convention)
-* create the template as an executable file like templates/basic.conf.sh, it will output text using shell variables for the values
+* create directory files/ in your type (convention)
+* create the template as an executable file like files/basic.conf.sh, it will output text using shell variables for the values
 
 --------------------------------------------------------------------------------
 #!/bin/sh
@@ -191,7 +191,7 @@ EOF
   export ROOT='/var/www/test'
 # render the template
   mkdir -p "$__object/files"
-  "$__type/templates/basic.conf.sh" > "$__object/files/basic.conf"
+  "$__type/files/basic.conf.sh" > "$__object/files/basic.conf"
 # send the rendered template
   __file /etc/nginx/sites-available/test.conf  \
     --state present

docs/man/man7/cdist-manifest.text

@@ -128,6 +128,19 @@ All objects that are created in a type manifest are automatically required
 from the type that is calling them. This is called "autorequirement" in
 cdist jargon.
 
+OVERRIDES
+---------
+In some special cases, you would like to create an already defined object 
+with different parameters. In normal situations this leads to an error in cdist.
+If you whish, you can setup the environment variable CDIST_ALLOW_OVERRIDE
+(any value or even empty is ok) to tell cdist, that this object override is 
+wanted and should be accepted.
+ATTENTION: Only use this feature if you are 100% sure in which order 
+cdist encounter the affected objects, otherwhise this results 
+into an undefined situation. 
+
+THIS IS A BETA FEATURE AND MAY BE REMOVED AT ANY TIME.
+
 
 EXECUTE_TYPES_IN_CREATION_ORDER is a EXPERIMENTAL FEATURE !
 You can tell cdist to execute all types in the order in which they are created 
@@ -189,6 +202,26 @@ __package lighttpd --state present
 require="__package/lighttpd" __package munin --state present
 --------------------------------------------------------------------------------
 
+How to override objects:
+
+--------------------------------------------------------------------------------
+# for example in the inital manifest
+
+# reate user account foobar with some hash for password
+__user foobar --password 'some_fancy_hash' --home /home/foobarexample
+
+# ... many statements and includes in the manifest later ...
+# somewhere in a conditionaly sourced manifest 
+# (e.g. for example only sourced if a special application is on the target host)
+
+# this leads to an error ...
+__user foobar --password 'some_other_hash' 
+
+# this tells cdist, that you know that this is an override and should be accepted
+CDIST_ALLOW_OVERRIDE=yes __user foobar --password 'some_other_hash'
+# its only an override, means the parameter --home is not touched 
+# and stay at the original value of /home/foobarexample
+--------------------------------------------------------------------------------
 
 
 SEE ALSO