Merge pull request #335 from tpo/master

trivial docu fixes

Makefile

@@ -20,6 +20,13 @@
 
 A2XM=a2x -f manpage --no-xmllint -a encoding=UTF-8
 A2XH=a2x -f xhtml --no-xmllint -a encoding=UTF-8
+# Create cross-links in html man pages
+# We look for something like "cdist-type(7)" and make a href out of it
+# The first matching group is the man page name and the second group
+# is the man page section (1 or 7). The first three lines of the input
+# (xml, DOCTYPE, head tags) are ignored, since the head tags contains
+# the title of the page and should not contain a href.
+CROSSLINK=sed --in-place '1,3!s/\([[:alnum:]_-]*\)(\([17]\))/<a href="..\/man\2\/\1.html">&<\/a>/g'
 helper=./bin/build-helper
 
 MANDIR=docs/man
@@ -86,6 +93,7 @@ MANSTATICALL=$(MANSTATICMAN) $(MANSTATICHTML)
 # Creating the type html page
 %.html: %.text
 	$(A2XH) $^
+	$(CROSSLINK) $@
 
 man: $(MANTYPEALL) $(MANREFALL) $(MANSTATICALL)
 

docs/man/man1/cdist.text

@@ -26,7 +26,7 @@ cdist supports different subcommands as explained below.
 
 GENERAL
 -------
-All commands except the following options:
+All commands accept the following options:
 
 -d, --debug::
     Set log level to debug
@@ -34,7 +34,7 @@ All commands except the following options:
 -h, --help::
    Show the help screen
 
--v, --verbose:
+-v, --verbose::
     Set log level to info, be more verbose
 
 -V, --version::
@@ -72,10 +72,10 @@ Configure one or more hosts
 -s, --sequential::
     Operate on multiple hosts sequentially
 
---remote-copy REMOTE_COPY:
+--remote-copy REMOTE_COPY::
     Command to use for remote copy (should behave like scp)
 
---remote-exec REMOTE_EXEC:
+--remote-exec REMOTE_EXEC::
     Command to use for remote execution (should behave like ssh)
 
 SHELL

docs/man/man7/cdist-bootstrap.text

@@ -25,7 +25,7 @@ location.
 For starters, having cdist (which includes the configuration database) on
 your notebook should be fine.
 Additionally an external copy of the git repository the configuration
-relies in is recommended, for use as backup as well to allow easy collaboration
+relies on is recommended, for use as backup as well as to allow easy collaboration
 with others.
 
 For more sophisticated setups developing cdist configurations with multiple

docs/man/man7/cdist-manifest.text

@@ -13,7 +13,7 @@ DESCRIPTION
 Manifests are used to define which objects to create.
 Objects are instances of **types**, like in object oriented programming languages.
 An object is represented by the combination of
-**type + slash + object name**: **__file/etc/cdist-configured** is an
+**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 **cdist/conf/type/** directory,
@@ -29,7 +29,7 @@ at an example:
 __package apache2 --state absent
 
 # Same with the __directory type
- __directory /tmp/cdist --state present
+__directory /tmp/cdist --state present
 --------------------------------------------------------------------------------
 
 These two lines create objects, which will later be used to realise the 
@@ -89,7 +89,7 @@ SPLITTING UP THE INITIAL MANIFEST
 ---------------------------------
 If you want to split up your initial manifest, you can create other shell
 scripts in **cdist/conf/manifest/** and include them in **cdist/conf/manifest/init**.
-Cdist provides the environment variable ***__manifest*** to reference to
+Cdist provides the environment variable ***__manifest*** to reference
 the directory containing the initial manifest (see cdist-reference(7)).
 
 The following example would include every file with a **.sh** suffix:
@@ -110,24 +110,39 @@ setup the variable "require" to contain the requirements. Multiple
 requirements can be added white space separated.
 
 --------------------------------------------------------------------------------
-# No dependency
-__file /etc/cdist-configured
+ 1 # No dependency
+ 2 __file /etc/cdist-configured
+ 3 
+ 4 # Require above object
+ 5 require="__file/etc/cdist-configured" __link /tmp/cdist-testfile \
+ 6    --source /etc/cdist-configured  --type symbolic
+ 7 
+ 8 # Require two objects
+ 9 require="__file/etc/cdist-configured __link/tmp/cdist-testfile" \
+10    __file /tmp/cdist-another-testfile
 
-# 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
+--------------------------------------------------------------------------------
 
+Above the "require" variable is only set for the command that is 
+immediately following it. Dependencies should allways be declared that way.
 
---------------------------------------------------------------------------------
+On line 4 you can see that the instantion of a type "__link" object needs
+the object "__file/etc/cdist-configured" to be present, before it can proceed.
+
+This also means that the "__link" command must make sure, that either
+"__file/etc/cdist-configured" allready is present, or, if it's not, it needs
+to be created. The task of cdist is to make sure, that the dependency will be
+resolved appropriately and thus "__file/etc/cdist-configured" be created
+if necessary before "__link" proceeds (or to abort execution with an error).
 
 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.
 
+You can find an more in depth description of the flow execution of manifests
+in cdist-stages(7) and of how types work in cdist-type(7).
+
 CREATE DEPENDENCIES FROM EXECUTION ORDER
 -----------------------------------------
 You can tell cdist to execute all types in the order in which they are created 
@@ -149,10 +164,10 @@ If you whish, you can setup the environment variable CDIST_OVERRIDE
 (any value or even empty is ok) to tell cdist, that this object override is 
 wanted and should be accepted.
 ATTENTION: Only use this feature if you are 100% sure in which order 
-cdist encounter the affected objects, otherwhise this results 
-into an undefined situation. 
+cdist encounters the affected objects, otherwhise this results 
+in an undefined situation. 
 
-If CDIST_OVERRIDE and CDIST_ORDER_DEPENDENCY is set for an object,
+If CDIST_OVERRIDE and CDIST_ORDER_DEPENDENCY are set for an object,
 CDIST_ORDER_DEPENDENCY will be ignored, because adding a dependency in case of
 overrides would result in circular dependencies, which is an error.
 
@@ -198,7 +213,7 @@ How to override objects:
 --------------------------------------------------------------------------------
 # for example in the inital manifest
 
-# reate user account foobar with some hash for password
+# create user account foobar with some hash for password
 __user foobar --password 'some_fancy_hash' --home /home/foobarexample
 
 # ... many statements and includes in the manifest later ...
@@ -210,8 +225,8 @@ __user foobar --password 'some_other_hash'
 
 # this tells cdist, that you know that this is an override and should be accepted
 CDIST_OVERRIDE=yes __user foobar --password 'some_other_hash'
-# its only an override, means the parameter --home is not touched 
-# and stay at the original value of /home/foobarexample
+# it's only an override, means the parameter --home is not touched 
+# and stays at the original value of /home/foobarexample
 --------------------------------------------------------------------------------
 
 Dependencies defined by execution order work as following:

docs/man/man7/cdist-type.text

@@ -25,7 +25,7 @@ to use.
 HOW TO USE A TYPE
 -----------------
 You can use types from the initial manifest or the type manifest like a
-normal command:
+normal shell command:
 
 --------------------------------------------------------------------------------
 # Creates empty file /etc/cdist-configured