further cleanups in the cdist-types manpage

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

doc/man/cdist-types.text

@@ -10,39 +10,35 @@ cdist-types - Functionality bundled
 
 DESCRIPTION
 -----------
-A cdist type describes some kind of functionality, starting from
+A cdist type describes some kind of functionality, starting from simple stuff
-simple stuff like copying files until complex user auth/ldap/
+like copying files until complex user auth/ldap/ kerberos infrastructure
-kerberos infrastructure designs.
+designs. The name of every type is prefixed with two underscores (__), because
-
+types will be executed and the two underscores prevent collisions with real
-The name of every type is prefixed with two underscores (__),
+binaries (like "file").
-because types will be executed and the two underscores prevent
+In general, types should be written independent of hosts (as in reusable
-collisions with real binaries (like "file").
+code), but may be used implement functionality only needed on one host
-
+as well.
-It must be assumed that the clients are pretty dumb
+It must be assumed that the clients are pretty dumb and thus do not have high
-and thus do not have high level tools like python
+level tools like ruby installed. If a type requires specific tools to be present
-installed.
+on the target, there must be another type that provides this tool and the first
-
+type must create an object of the specific type.
-If a type requires specific tools to be present
+If the generated code fails on the client, it must print diagnostistic messages on
-on the target, there must be another type that
+stderr and exit non-zero, so the configuration is aborted.
-provides this tool and the first type must create
+Types may make use of other types to realise a new type or may implement some
-an object of the specific type.
+functionality on their own.
-
+
-If the generated code fails on the client, it must
+Types may consist of 
-print diagnostistic messages on stderr and call
+- a number of required and optional parameters they accept,
-"exit 1", so the configuration is aborted.
+- a manifest script that makes use of the parameters and may create other objects
-
+- explorers that explore type specific information on the target
-   - are independent of hosts in general
+- a gencode script, that may generate code to be executed on the target
-   - may make use of other types to realise a new type
+
-   - can overwrite stuff (HOW?)
+Every time a type is used, a new object is created of the specific type,
-      - overwrite in own tree?
+with a type specific unique id that stores the parameters
-         - needs knowledge of inherited provider
-            - similar to current situation in puppet,
-              but more like reusable defines
-   - or may implement some functionality on their own 
 
 
 HOW TO WRITE A NEW TYPE (TODO)
------------------------
+------------------------------
 Assume you want to create the new type named "coffee":
 
 Create the directory /etc/cdist/types/coffee/
@@ -67,6 +63,8 @@ shell code suitable for running on the client.
 
 SEE ALSO
 --------
+cdist-config-layout(7), cdist-type-manifest(7), cdist-type-explorer(7),
+cdist-type-gencode(7)
 
 
 COPYING