diff --git a/Makefile b/Makefile index 9502c989..112b1411 100644 --- a/Makefile +++ b/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>/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) diff --git a/docs/man/man1/cdist.text b/docs/man/man1/cdist.text index e8c12991..c09d8f41 100644 --- a/docs/man/man1/cdist.text +++ b/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 diff --git a/docs/man/man7/cdist-bootstrap.text b/docs/man/man7/cdist-bootstrap.text index 985d0f53..5852bad0 100644 --- a/docs/man/man7/cdist-bootstrap.text +++ b/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 diff --git a/docs/man/man7/cdist-manifest.text b/docs/man/man7/cdist-manifest.text index 057905ea..b28fe94f 100644 --- a/docs/man/man7/cdist-manifest.text +++ b/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 - -# 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: diff --git a/docs/man/man7/cdist-type.text b/docs/man/man7/cdist-type.text index 06026542..323fc130 100644 --- a/docs/man/man7/cdist-type.text +++ b/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