Merge remote branch 'nico/master'

.gitignore

@@ -1 +1,2 @@
 .*.swp
+doc/man/*.[1-9]

Makefile

@@ -3,6 +3,15 @@ BINDIR=$(PREFIX}/bin
 WEBDIR=$$HOME/niconetz
 WEBPAGE=software/cdist.mdwn
 
+MANSRC=doc/man/cdist-config-layout.text doc/man/cdist-config.text \
+   doc/man/cdist-deploy-to.text doc/man/cdist-design.text			\
+   doc/man/cdist-environment.text doc/man/cdist-explorers.text 	\
+	doc/man/cdist-language.text doc/man/cdist-manifests.text 		\
+	doc/man/cdist-quickstart.text doc/man/cdist-stages.text 			\
+	doc/man/cdist-terms.text doc/man/cdist.text 							\
+	doc/man/cdist-types.text
+
+
 # FIXME: some distro nerd, can you make this more beautiful?
 # I'm just a hacker, I don't really care...
 install:
@@ -23,3 +32,7 @@ web:
 
 pub:
 	git push --mirror
+
+man:
+	echo $(MANSRC)
+	a2x -f manpage --no-xmllint doc/man/cdist-stages.text

doc/man/cdist-stages.text

@@ -11,30 +11,38 @@ cdist-stages - How the configuration is built
 DESCRIPTION
 -----------
 Starting the execution of deployment with cdist-deploy-to(1),
-cdist passes through different stages:
+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.
 
-- First stage: Get information about target
+STAGE 1: TARGET INFORMATION RETRIEVAL
-   Every existing explorer is run on the target and the results
+--------------------------------------
-   are copied back into the local cache.
+In this stage information is collected about target using
-   The results can be used by manifests and types.
+so called explorers.
-   See cdist-explorers(7) and see cdist-cache(7).
+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.
 
-- Second stage: Initial manifest run
+Related manpages are cdist-explorers(7) and cdist-cache(7).
-   The initial manifest (see cdist-manifests(7) is run,
-   which is done by cdist-manifest-init(1).
 
-   This run creates an internal database in cconfig
-   format (see cdist-config-layout(7), that contains all
-   objects configured for the specific host.
 
-   In this stage, no conflicts may occur, i.e. no
+STAGE 2: RUN THE INITIAL MANIFEST
-   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.
 
-   You can trigger the first stage part using
+This stage creates objects in a cconfig database that
-   cdist-manifest-init(1).
+contains as defined in the manifest for the specific host.
 
-- Third stage: Execution of types [TODO]
+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
@@ -50,7 +58,8 @@ cdist passes through different stages:
    objects try to create the same object, which indicates a
    broken configuration.
 
-- Fourth stage: Code generation [TODO]
+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.
 
@@ -62,7 +71,8 @@ cdist passes through different stages:
    A description of what the generated code may/must/should
    do can be found in cdist-types-gencode(7).
 
-- Fifth stage: [TODO]
+STAGE 5: CODE EXECUTION
+-----------------------
    The resulting code is transferred to the target host and executed,
    the run of cdist-deploy-to(1) ends.