add template for manpage of __file type

Signed-off-by: Nico Schottelius <nico@kr.ethz.ch>

doc/man/cdist-type__file.text

@@ -0,0 +1,166 @@
+cdist-type(7)
+=============
+Nico Schottelius <nico-cdist--@--schottelius.org>
+
+
+NAME
+----
+cdist-type - Functionality bundled
+
+
+SYNOPSIS
+--------
+Other languages name this module or class 
+
+
+DESCRIPTION
+-----------
+Types are the main component of cdist and define functionality. If you
+use cdist, you'll write a type for every functionality you would like
+to use.
+
+
+HOW TO USE A TYPE
+-----------------
+You can use types from the initial manifest or the type manifest like a
+normal command:
+
+--------------------------------------------------------------------------------
+# Creates empty file /etc/cdist-configured
+__file /etc/cdist-configured --type file
+
+# Ensure tree is installed
+__package tree --state installed
+--------------------------------------------------------------------------------
+
+Internally cdist-type-emulator(1) will be called from cdist-manifest-run(1) to
+save the given parameters into a cconfig database, so they can be accessed by
+the manifest and gencode scripts of the type (see below).
+
+
+HOW TO WRITE A NEW TYPE
+-----------------------
+A type consists of
+
+- parameter (optional)
+- manifest  (optional)
+- explorer  (optional)
+- gencode   (optional)
+
+Types are stored below conf/type/. Their name should always be prefixed with
+two underscores (__) to prevent collisions with other binaries in $PATH.
+
+To begin a new type from a template, execute "cdist-type-template __NAME"
+and cd conf/type/__NAME.
+
+
+DEFINING PARAMETERS
+-------------------
+Every type consists of optional and required parameters, which must
+be created in a newline seperated file in parameters/required and
+parameters/optional. If either or both missing, the type will have
+no required, no optional or no parameters at all.
+
+Example:
+--------------------------------------------------------------------------------
+echo servername >> conf/type/__nginx_vhost/parameter/required
+echo logdirectory >> conf/type/__nginx_vhost/parameter/optional
+--------------------------------------------------------------------------------
+
+
+WRITING THE MANIFEST
+--------------------
+In the manifest of a type you can use other types, so your type extends
+their functionality. A good example is the __package type, which in
+a shortened version looks like this:
+
+--------------------------------------------------------------------------------
+os="$(cat "$__global/explorer/os")"
+case "$os" in
+      archlinux) type="pacman" ;;
+      debian|ubuntu) type="apt" ;;
+      gentoo) type="emerge" ;;
+      *)
+         echo "Don't know how to manage packages on: $os" >&2
+         exit 1
+      ;;
+esac
+
+__package_$type "$@"
+--------------------------------------------------------------------------------
+
+As you can see, the type can reference different environment variables,
+which are documented in cdist-environment-variables(7).
+
+Always ensure the manifest is executable, otherwise cdist will not be able
+to execute it.
+
+
+THE TYPE EXPLORERS
+------------------
+If a type needs to explore specific details, it can provide type specific
+explorers, which will be executed on the target for every created object.
+
+The explorers are stored under the "explorer" directory below the type.
+It could for instance contain code to check the md5sum of a file on the
+client, like this (shortened version from real type __file):
+
+--------------------------------------------------------------------------------
+if [ -f "$__object/parameter/destination" ]; then
+   destination="$(cat "$__object/parameter/destination")"
+else
+   destination="/$__object_id"
+fi
+
+if [ -e "$destination" ]; then
+   md5sum < "$destination"
+fi
+--------------------------------------------------------------------------------
+
+
+WRITING THE GENCODE SCRIPT
+--------------------------
+The gencode script can make use of the parameters, the global explorers
+and the type specific explorers. The output (stdout) of this script is
+saved by cdist and will be executed on the target.
+
+If the gencode script encounters an error, it should print diagnostic
+messages to stderr and exit non-zero. If you need to debug the gencode
+script, you can write to stderr:
+
+--------------------------------------------------------------------------------
+# Debug output to stderr
+echo "My fancy debug line" >&2
+
+# Output to be saved by cdist for execution on the target
+echo "touch /etc/cdist-configured"
+--------------------------------------------------------------------------------
+
+
+HINTS FOR TYPEWRITERS
+----------------------
+It must be assumed that the target is pretty dumb and thus does not have high
+level tools like ruby installed. If a type requires specific tools to be present
+on the target, there must be another type that provides this tool and the first
+type should create an object of the specific type.
+
+
+HOW TO INCLUDE A TYPE INTO UPSTREAM CDIST
+-----------------------------------------
+If you think your type may be useful for others, ensure it works with the
+current master branch of cdist and submit the git url containing the type for
+inclusion to the mailinglist **cdist at cdist -- at -- l.schottelius.org**.
+
+Ensure a corresponding manpage named cdist-type__NAME is included.
+
+
+SEE ALSO
+--------
+- cdist-manifest-run(1)
+- cdist-stages(7)
+
+
+COPYING
+-------
+Copyright \(C) 2011 Nico Schottelius. Free use of this software is
+granted under the terms of the GNU General Public License version 3 (GPLv3).