Merge pull request #335 from tpo/master

trivial docu fixes
This commit is contained in:
Nico Schottelius 2014-05-04 08:38:54 +02:00
commit 2c54e91df1
5 changed files with 48 additions and 25 deletions

View file

@ -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)

View file

@ -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

View file

@ -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

View file

@ -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,
@ -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
# 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
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
--------------------------------------------------------------------------------
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:

View file

@ -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