From 20b50ea19fd04d66e153fc4a34fa4d73842a9ace Mon Sep 17 00:00:00 2001
From: Nico Schottelius <nico@kr.ethz.ch>
Date: Tue, 8 Mar 2011 12:18:26 +0100
Subject: [PATCH 1/4] prepend new path, so running HACKERS_README in biased
 environment works

Signed-off-by: Nico Schottelius <nico@kr.ethz.ch>
---
 HACKERS_README | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/HACKERS_README b/HACKERS_README
index fa01666f..0ae1bdcd 100755
--- a/HACKERS_README
+++ b/HACKERS_README
@@ -33,7 +33,7 @@ set -x
 # Tell the user what we do, so this script makes sense during execution
 
 # prepare use (only from top level directory)
-export PATH="$PATH:$(pwd -P)/bin"
+export PATH="$(pwd -P)/bin:$PATH"
 export __cdist_conf_dir="$(pwd -P)/conf"
 
 # Allow user to supply hostname

From 1b3aef7ea35e2e4510817534f9c05acefed80701 Mon Sep 17 00:00:00 2001
From: Nico Schottelius <nico@kr.ethz.ch>
Date: Tue, 8 Mar 2011 12:36:59 +0100
Subject: [PATCH 2/4] how to use a type, how to define parameters

Signed-off-by: Nico Schottelius <nico@kr.ethz.ch>
---
 doc/man/to_check/cdist-type.text | 38 +++++++++++++++++++++++++++++---
 1 file changed, 35 insertions(+), 3 deletions(-)

diff --git a/doc/man/to_check/cdist-type.text b/doc/man/to_check/cdist-type.text
index 9e9642a1..26706ae4 100644
--- a/doc/man/to_check/cdist-type.text
+++ b/doc/man/to_check/cdist-type.text
@@ -53,11 +53,29 @@ Every time a type is used, a new object is created of the specific type,
 with a type specific unique id that stores the parameters
 
 
+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 (required)
+- parameter (optional)
 - manifest  (optional)
 - gencode   (optional)
 - explorer  (optional)
@@ -66,13 +84,25 @@ 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 to conf/type/__NAME.
+and cd conf/type/__NAME.
 
 
 DEFINING PARAMETERS
 -------------------
-Every type consists of optional and 
+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
+--------------------
 
 HOW TO WRITE A NEW TYPE (TODO)
 ------------------------------
@@ -104,6 +134,8 @@ SEE ALSO
 cdist-config-layout(7), cdist-type-manifest(7), cdist-type-explorer(7),
 cdist-type-gencode(7)
 
+- cdist-manifest-run(1)
+
 
 COPYING
 -------

From cc28d4ddbb439138f82fe6331a8a30b5e86ef00f Mon Sep 17 00:00:00 2001
From: Nico Schottelius <nico@kr.ethz.ch>
Date: Tue, 8 Mar 2011 12:39:05 +0100
Subject: [PATCH 3/4] do not exit 0 if __package_$type does not exit 0

Signed-off-by: Nico Schottelius <nico@kr.ethz.ch>
---
 conf/type/__package/manifest | 2 --
 1 file changed, 2 deletions(-)

diff --git a/conf/type/__package/manifest b/conf/type/__package/manifest
index cf085e2f..d8b55814 100755
--- a/conf/type/__package/manifest
+++ b/conf/type/__package/manifest
@@ -49,5 +49,3 @@ for property in $(ls .); do
 done
 
 __package_$type "$@"
-
-exit 0

From bc436c6c5cb0658b53f12f718d11a88cb1789742 Mon Sep 17 00:00:00 2001
From: Nico Schottelius <nico@kr.ethz.ch>
Date: Tue, 8 Mar 2011 12:47:51 +0100
Subject: [PATCH 4/4] describe how to submit a new cdist type for inclusion

Signed-off-by: Nico Schottelius <nico@kr.ethz.ch>
---
 doc/man/to_check/cdist-type.text | 53 +++++++++++++++++++-------------
 1 file changed, 31 insertions(+), 22 deletions(-)

diff --git a/doc/man/to_check/cdist-type.text b/doc/man/to_check/cdist-type.text
index 26706ae4..cd06463e 100644
--- a/doc/man/to_check/cdist-type.text
+++ b/doc/man/to_check/cdist-type.text
@@ -103,37 +103,46 @@ 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:
 
-HOW TO WRITE A NEW TYPE (TODO)
-------------------------------
-Assume you want to create the new type named "coffee", which creates
-files which contain the word "c0ffee".
+--------------------------------------------------------------------------------
+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
 
-Create the directory conf/type/coffee/.
-Create the file /etc/cdist/types/coffee/README containing a description of the 
-type.
-If your type supports attributes, create the directory /etc/cdist/types/coffee/
-attributes.
-For each attribute, create the file
-   /etc/cdist/types/coffee/attributes/$attribute_name which contains
+__package_$type "$@"
+--------------------------------------------------------------------------------
 
-   a short description on the first line
-   then a blank line
-   then a long description (probably over several lines)
+As you can see, the type can reference different environment variables,
+which are documented in cdist-environment-variables(7).
 
-If you think your type may be useful for others, submit it for inclusion
-into cdist at cdist -- at -- l.schottelius.org.
+Always ensure the manifest is executable, otherwise cdist will not be able
+to execute it.
 
-Create /etc/cdist/types/coffee/init which reads $configinput
-(either via cconfig or via environment) and outputs a block of
-shell code suitable for running on the client.
+WRITING THE GENCODE SCRIPT
+--------------------------
+
+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 there is a corresponding manpage named cdist-type-NAME (without
+underscores) included.
 
 
 SEE ALSO
 --------
-cdist-config-layout(7), cdist-type-manifest(7), cdist-type-explorer(7),
-cdist-type-gencode(7)
-
 - cdist-manifest-run(1)