completly finish cdist-stages

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

doc/man/cdist-stages.text

@@ -5,77 +5,82 @@ Nico Schottelius <nico-cdist--@--schottelius.org>
 
 NAME
 ----
-cdist-stages - How the configuration is built
+cdist-stages - Stages used during configuration deployment
 
 
 DESCRIPTION
 -----------
-Starting the execution of deployment with cdist-deploy-to(1),
-cdist passes through different stages, each can be triggered
-and debugged on its own. Reading the source of the
-cdist-deploy-to script shous the binaries being responsible
-for each stage.
+Starting the execution of deployment with cdist-deploy-to(1), cdist passes
+through different stages, each can be triggered and debugged on its own.
+Reading the source of the cdist-deploy-to executable shous the scripts
+responsible for each stage.
+
 
 STAGE 1: TARGET INFORMATION RETRIEVAL
 --------------------------------------
-In this stage information is collected about target using
-so called explorers.
-Every existing explorer is run on the target and the output
-of all explorers are copied back into the local cache.
-The results can be used by manifests and types.
+In this stage information is collected about target using so called explorers.
+Every existing explorer is run on the target and the output of all explorers
+are copied back into the local cache. The results can be used by manifests and
+types.
 
 Related manpages are cdist-explorers(7) and cdist-cache(7).
 
 
 STAGE 2: RUN THE INITIAL MANIFEST
 ---------------------------------
-The initial manifest, which should be used for mappings
-of hosts to types, is executed.
-
-This stage creates objects in a cconfig database that
-contains as defined in the manifest for the specific host.
-
-In this stage, no conflicts may occur, i.e. no object of
-the same type with the same id may be created.
+The initial manifest, which should be used for mappings of hosts to types,
+is executed. This stage creates objects in a cconfig database that contains
+the objects as defined in the manifest for the specific host. In this stage,
+no conflicts may occur, i.e. no object of the same type with the same id may
+be created.
 
 Related manpages are cdist-manifest-init(1), cdist-manifests(7) and
 cdist-config-layout(7).
 
+
 STAGE 3: EXECUTION OF TYPES
 ---------------------------
-Every object is checked whether its type has an init
-script (see cdist-types(7)). If the type of the object
-has an init script, it is run. This init script may
-generate additional objects.
+Every object is checked whether its type has a manifest file. If the type has
+a manifest file and it is executable, it will be executed. The manifest script
+may generate and change the created objects. In other words, one type can reuse
+other types.
+
+For instance the object __apache/www.test.ch is of type __apache, which may 
+contain an manifest script, which creates new objects of type __file.
 
-For instance the object __apache/www.test.ch is of
-type __apache, which may contain an init script, which
-creates new objects of type __file.
+The newly created objects are merged back into the existing tree. No conflicts
+may occur during the merge. A conflict would mean that two different objects
+try to create the same object, which indicates a broken configuration.
+
+Related manpage are cdist-types(7) and cdist-manifest-run-all(1).
 
-The newly created objects are merged back into
-the existing tree. No conflicts may occur during
-the merge. A conflict would mean that two different
-objects try to create the same object, which indicates a
-broken configuration.
 
 STAGE 4: CODE GENERATION
 ------------------------
-The "gencode" binary of the types for every existing object is
-called to generate code that will be executed on the target host.
-
-This binary should create code to be executed on the target on stdout.
+In this stage for every created objects its type is checked whether it has a
+gencode script. If the type has a gencode script and it is executable it will
+be executed. This executable should create code to be executed on the target
+on stdout. If the gencode executable fails, it must print diagnostic messages
+on stderr and exit non-zero.
 
-If the gencode binary fails, it must print diagnostic messages on stderr
-and exit non-zero.
+Related manpages are cdist-types-gencode(7), cdist-gencode(1) and
+cdist-gencode-all(1).
 
-A description of what the generated code may/must/should
-do can be found in cdist-types-gencode(7).
 
 STAGE 5: CODE EXECUTION
 -----------------------
+The resulting code from the previous stage is transferred to the target host
+and executed there to apply the configuration changes,
+
+Related manpages are cdist-exec-transfer(1) and cdist-exec-run(1).
 
-The resulting code is transferred to the target host and executed,
-the run of cdist-deploy-to(1) ends.
+
+SUMMARY
+-------
+If, and only if, all the stages complete without an errors, the configuration
+will be applied to the target. Each stage can also be run individually, though
+dependencies for each stage must be fulfilled and thus the stages must be run
+in correct order.
 
 
 SEE ALSO