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] 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)