Merge remote-tracking branch 'abondis/doc'

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

@@ -153,6 +153,40 @@ implement this scenario with a gateway host and sudo:
 
 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
+
+--------------------------------------------------------------------------------------
+#!/bin/sh
+# in the template, use cat << eof (here document) to output the text
+# and use standard shell variables in the template
+# output everything in the template script to stdout
+cat << EOF
+server {
+  listen                          80;
+  server_name                     $SERVERNAME;
+  root                            $ROOT;
+
+  access_log /var/log/nginx/$SERVERNAME_access.log
+  error_log /var/log/nginx/$SERVERNAME_error.log
+}
+EOF
+--------------------------------------------------------------------------------------
+
+* in the manifest, export the relevant variables and add the following lines in your manifest:
+--------------------------------------------------------------------------------------
+# export variables needed for the template
+  export SERVERNAME='test"
+  export ROOT='/var/www/test'
+# render the template
+  mkdir -p "$__object/files"
+  "$__type/templates/basic.conf.sh" > "$__object/files/basic.conf"
+# send the rendered template 
+  __file /etc/nginx/sites-available/test.conf  --state present   --source "$__object/files/basic.conf"
+--------------------------------------------------------------------------------------
+
 SEE ALSO
 --------
 - cdist(1)