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
+Manifests are used to define which objects to create.
-host as well as to define which configurations should be applied within a
+Objects are instances of **types**, like in object orientated programming languages.
-type. Manifests are executed locally and the resulting objects are stored in
+An object is represented by the combination of
-an internal database.
+**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
+**objects** to configure on the selected host.
-**types**, like in object orientated programming languages.
+Cdist searches for the initial manifest at **conf/manifest/init**.
-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**.
 
 Within this initial manifest, you define, which objects should be
 created on which host. To distinguish between hosts, you can use the
@@ -56,15 +82,51 @@ 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
+command.
-setup the MANPATH correctly as, you can use **man cdist-reference** to access
-the reference with pointers to the manpages.
 
-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)).
 
+The following example would include every file with a **.sh** suffix:
+
+--------------------------------------------------------------------------------
+# Include *.sh
+for manifest in $__manifest/*.sh; do
+    # And source scripts into our shell environment
+    . "$manifest"
+done
+--------------------------------------------------------------------------------
+
+
+DEPENDENCIES
+------------
+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
+
+# Require above object
+require="__file/etc/cdist-configured" __link /tmp/cdist-testfile \
+   --source /etc/cdist-configured  --type symbolic
+
+# Require two objects
+require="__file/etc/cdist-configured __link/tmp/cdist-testfile" \
+   __file /tmp/cdist-another-testfile
+
+
+--------------------------------------------------------------------------------
+
+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
@@ -89,36 +151,11 @@ The manifest of the type "nologin" may look like this:
 __file /etc/nologin --type file --source "$__type/files/default.nologin"
 --------------------------------------------------------------------------------
 
-DEPENDENCIES
-------------
-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
-
-# Require above object
-require="__file/etc/cdist-configured" __link /tmp/cdist-testfile \
-   --source /etc/cdist-configured  --type symbolic
-
-# Require two objects
-require="__file/etc/cdist-configured __link/tmp/cdist-testfile" \
-   __file /tmp/cdist-another-testfile
-
-
---------------------------------------------------------------------------------
-
-If you do not specify
-
-FIXME: autorequire
 
 SEE ALSO
 --------
-- cdist-type(7)
 - cdist-tutorial(7)
+- cdist-type(7)
 
 
 COPYING