finish rewrite of cdist-manifest

Signed-off-by: Nico Schottelius <nico@brief.schottelius.org>

doc/man/man7/cdist-manifest.text

@@ -5,14 +5,38 @@ Nico Schottelius <nico-cdist--@--schottelius.org>
 
 NAME
 ----
-cdist-manifest - Using types
+cdist-manifest - (Re-)Use types
+
 
 DESCRIPTION
 -----------
-Manifests exist to define which configurations should be applied to a specific
-host as well as to define which configurations should be applied within a
-type. Manifests are executed locally and the resulting objects are stored in
-an internal database.
+Manifests are used to define which objects to create.
+Objects are instances of **types**, like in object orientated programming languages.
+An object is represented by the combination of
+**type + slash + object name**: **__file/etc/cdist-configured** is an
+object of the type ***__file*** with the name ***etc/cdist-configured***.
+
+All available types can be found in the **conf/type/** directory,
+use **ls conf/type** to get the list of available types. If you have
+setup the MANPATH correctly, you can use **man cdist-reference** to access
+the reference with pointers to the manpages.
+
+
+Types in manifests are used like normal command line tools. Let's have a look
+at an example:
+--------------------------------------------------------------------------------
+# Create object of type __package with the parameter state = removed
+__package apache2 --state removed
+
+# Same with the __directory type
+ __directory /tmp/cdist --state present
+--------------------------------------------------------------------------------
+
+These two lines create objects, which will later be used to realise the 
+configuration on the target host.
+
+Manifests are executed locally as a shell script using **/bin/sh -e**.
+The resulting objects are stored in an internal database.
 
 The same object can be redefined in multiple different manifests as long as
 the parameters are exactly the same.
@@ -21,17 +45,19 @@ In general, manifests are used to define which types are used depending
 on given conditions.
 
 
+INITIAL AND TYPE MANIFESTS
+--------------------------
+Cdist nows about two types of manifests: The initial manifest and type
+manifests. The initial manifest is used to define, which configurations
+to apply to which hosts. The type manifests are used to create objects
+from types. More about manifests in types can be found in cdist-type(7).
+
+
 DEFINE STATE IN THE INITIAL MANIFEST
 ------------------------------------
 The **initial manifest** is the entry point for cdist to find out, which
-**objects** to configure on the selected host. Objects are instances of
-**types**, like in object orientated programming languages.
-An object is represented by the
-type + slash + object name: ***__file/etc/cdist-configured*** is an
-object of the type ***__file*** with the name ***etc/cdist-configured***.
-
-Cdist searches for the initial manifest at **conf/manifest/init** and
-executes it as a shell script using **/bin/sh -e**.
+**objects** to configure on the selected host.
+Cdist searches for the initial manifest at **conf/manifest/init**.
 
 Within this initial manifest, you define, which objects should be
 created on which host. To distinguish between hosts, you can use the
@@ -56,38 +82,26 @@ is only created on the host ***localhost***.
 
 As you can see, there is no magic involved, the manifest is simple shell code that
 utilises cdist types. Every available type can be executed like a normal 
-command. Use **ls conf/type** to get a list of available types. If you have
-setup the MANPATH correctly as, you can use **man cdist-reference** to access
-the reference with pointers to the manpages.
+command.
 
-INITIAL VS. TYPE MANIFEST
--------------------------
 
-MANAGING YOUR OWN CONFIGURATION
+SPLITTING UP THE INITIAL MANIFEST
+---------------------------------
+If you want to split up your initial manifest, you can create other shell
+scripts in **conf/manifest/** and include them in **conf/manifest/init**.
+Cdist provides the environment variable ***__manifest*** to reference to
+the directory containing the initial manifest (see cdist-reference(7)).
 
-
-
-EXAMPLES
---------
-The initial manifest may for instance contain the following code:
+The following example would include every file with a **.sh** suffix:
 
 --------------------------------------------------------------------------------
-# Always create this file, so other sysadmins know cdist is used.
-__file /etc/cdist-configured --type file
-
-case "$__target_host" in
-   my.server.name)
-      __file /root/bin/ --type directory
-      __file /etc/issue.net --type file --source "$__manifest/issue.net
-   ;;
-esac
+# Include *.sh
+for manifest in $__manifest/*.sh; do
+    # And source scripts into our shell environment
+    . "$manifest"
+done
 --------------------------------------------------------------------------------
 
-The manifest of the type "nologin" may look like this:
-
---------------------------------------------------------------------------------
-__file /etc/nologin --type file --source "$__type/files/default.nologin"
---------------------------------------------------------------------------------
 
 DEPENDENCIES
 ------------
@@ -95,7 +109,6 @@ If you want to describe that something requires something else, just
 setup the variable "require" to contain the requirements. Multiple
 requirements can be added white space seperated.
 
-
 --------------------------------------------------------------------------------
 # No dependency
 __file /etc/cdist-configured
@@ -111,14 +124,38 @@ require="__file/etc/cdist-configured __link/tmp/cdist-testfile" \
 
 --------------------------------------------------------------------------------
 
-If you do not specify
+All objects that are created in a type manifest are automatically required
+from the type that is calling them. This is called "autorequirement" in
+cdist jargon.
+
+
+EXAMPLES
+--------
+The initial manifest may for instance contain the following code:
+
+--------------------------------------------------------------------------------
+# Always create this file, so other sysadmins know cdist is used.
+__file /etc/cdist-configured --type file
+
+case "$__target_host" in
+   my.server.name)
+      __file /root/bin/ --type directory
+      __file /etc/issue.net --type file --source "$__manifest/issue.net
+   ;;
+esac
+--------------------------------------------------------------------------------
+
+The manifest of the type "nologin" may look like this:
+
+--------------------------------------------------------------------------------
+__file /etc/nologin --type file --source "$__type/files/default.nologin"
+--------------------------------------------------------------------------------
 
-FIXME: autorequire
 
 SEE ALSO
 --------
-- cdist-type(7)
 - cdist-tutorial(7)
+- cdist-type(7)
 
 
 COPYING