From 7b7f17cae5d04970f92c96a7d3d134fe34617e19 Mon Sep 17 00:00:00 2001 From: Tomas Pospisek Date: Tue, 29 Apr 2014 21:33:18 +0200 Subject: [PATCH 01/14] english --- docs/man/man1/cdist.text | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/man/man1/cdist.text b/docs/man/man1/cdist.text index e8c12991..fa91af40 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 From ba0d6e83b2563fba27f348820f30614675053d72 Mon Sep 17 00:00:00 2001 From: Tomas Pospisek Date: Tue, 29 Apr 2014 21:34:03 +0200 Subject: [PATCH 02/14] fix asciidoc --- docs/man/man1/cdist.text | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/man/man1/cdist.text b/docs/man/man1/cdist.text index fa91af40..c09d8f41 100644 --- a/docs/man/man1/cdist.text +++ b/docs/man/man1/cdist.text @@ -34,7 +34,7 @@ All commands accept 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 From 28a734fcc0d2b8f4513cfe2ec4a414fe3224a4ca Mon Sep 17 00:00:00 2001 From: Tomas Pospisek Date: Wed, 30 Apr 2014 11:17:09 +0200 Subject: [PATCH 03/14] asciidoc syntax fix --- docs/man/man7/cdist-manifest.text | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/man/man7/cdist-manifest.text b/docs/man/man7/cdist-manifest.text index 057905ea..369752e6 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, From 8ae9bcfec91251728dce5dd55d547b6825ba5873 Mon Sep 17 00:00:00 2001 From: Tomas Pospisek Date: Wed, 30 Apr 2014 11:28:13 +0200 Subject: [PATCH 04/14] whitespace --- docs/man/man7/cdist-manifest.text | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/man/man7/cdist-manifest.text b/docs/man/man7/cdist-manifest.text index 369752e6..d9cae7cf 100644 --- a/docs/man/man7/cdist-manifest.text +++ b/docs/man/man7/cdist-manifest.text @@ -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 From 9ffdde3646813e3c5891e7a29d89933023c727dd Mon Sep 17 00:00:00 2001 From: Tomas Pospisek Date: Wed, 30 Apr 2014 11:45:13 +0200 Subject: [PATCH 05/14] wording --- docs/man/man7/cdist-manifest.text | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/man/man7/cdist-manifest.text b/docs/man/man7/cdist-manifest.text index d9cae7cf..77b19c4c 100644 --- a/docs/man/man7/cdist-manifest.text +++ b/docs/man/man7/cdist-manifest.text @@ -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: From cdb5b9c82a3e4cd3a7537b58e23097dfe071600f Mon Sep 17 00:00:00 2001 From: Tomas Pospisek Date: Wed, 30 Apr 2014 11:53:04 +0200 Subject: [PATCH 06/14] wording --- docs/man/man7/cdist-manifest.text | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/man/man7/cdist-manifest.text b/docs/man/man7/cdist-manifest.text index 77b19c4c..7c6b820d 100644 --- a/docs/man/man7/cdist-manifest.text +++ b/docs/man/man7/cdist-manifest.text @@ -149,8 +149,8 @@ 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, CDIST_ORDER_DEPENDENCY will be ignored, because adding a dependency in case of From dc7f5ab62899b7c4b2877f4386be4dd5957c46e8 Mon Sep 17 00:00:00 2001 From: Tomas Pospisek Date: Wed, 30 Apr 2014 11:57:10 +0200 Subject: [PATCH 07/14] typo --- docs/man/man7/cdist-manifest.text | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/man/man7/cdist-manifest.text b/docs/man/man7/cdist-manifest.text index 7c6b820d..cc4c0428 100644 --- a/docs/man/man7/cdist-manifest.text +++ b/docs/man/man7/cdist-manifest.text @@ -152,7 +152,7 @@ ATTENTION: Only use this feature if you are 100% sure in which order 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 +198,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 ... From 779374ad948fd00713af275447f30380fadf82c7 Mon Sep 17 00:00:00 2001 From: Tomas Pospisek Date: Wed, 30 Apr 2014 11:59:07 +0200 Subject: [PATCH 08/14] wording --- docs/man/man7/cdist-manifest.text | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/man/man7/cdist-manifest.text b/docs/man/man7/cdist-manifest.text index cc4c0428..a6143ab7 100644 --- a/docs/man/man7/cdist-manifest.text +++ b/docs/man/man7/cdist-manifest.text @@ -210,8 +210,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: From 5b8ab385f2c3a6ebfed781e53766f3f39d3ae089 Mon Sep 17 00:00:00 2001 From: Tomas Pospisek Date: Wed, 30 Apr 2014 15:50:14 +0200 Subject: [PATCH 09/14] clarify docu --- docs/man/man7/cdist-type.text | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 From e5a12803ffd33ac3e08e2ffa56d9bdaeacdc3b7b Mon Sep 17 00:00:00 2001 From: Tomas Pospisek Date: Wed, 30 Apr 2014 15:57:44 +0200 Subject: [PATCH 10/14] expand "Dependencies" paragraph --- docs/man/man7/cdist-manifest.text | 35 ++++++++++++++++++++++--------- 1 file changed, 25 insertions(+), 10 deletions(-) diff --git a/docs/man/man7/cdist-manifest.text b/docs/man/man7/cdist-manifest.text index a6143ab7..b28fe94f 100644 --- a/docs/man/man7/cdist-manifest.text +++ b/docs/man/man7/cdist-manifest.text @@ -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 From e6b26829f4cb9a6fc887eb7d0614dc0e3fb9f248 Mon Sep 17 00:00:00 2001 From: Tomas Pospisek Date: Wed, 30 Apr 2014 16:38:40 +0200 Subject: [PATCH 11/14] crosslink html man pages This is using sed --in-place, which might not be available in all sed versions. If that's a concern, then please replace with awk script or move to build-helper and use temporary files. Also the regex is a heuristic. It works for our man pages here but it might have false positive matches in the future. --- Makefile | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/Makefile b/Makefile index 9502c989..82a774a5 100644 --- a/Makefile +++ b/Makefile @@ -20,6 +20,11 @@ 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) +CROSSLINK=sed --in-place 's/\([[:alnum:]_-]*\)(\([17]\))/&<\/a>/' helper=./bin/build-helper MANDIR=docs/man @@ -86,6 +91,7 @@ MANSTATICALL=$(MANSTATICMAN) $(MANSTATICHTML) # Creating the type html page %.html: %.text $(A2XH) $^ + $(CROSSLINK) $^ man: $(MANTYPEALL) $(MANREFALL) $(MANSTATICALL) From 2ff61d19656f21c794c54633c01afcea1573c53b Mon Sep 17 00:00:00 2001 From: Tomas Pospisek Date: Wed, 30 Apr 2014 16:42:35 +0200 Subject: [PATCH 12/14] wording --- docs/man/man7/cdist-bootstrap.text | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 From 454f955d25221e34c9b13515487c56adc4010d59 Mon Sep 17 00:00:00 2001 From: Tomas Pospisek Date: Wed, 30 Apr 2014 16:53:32 +0200 Subject: [PATCH 13/14] fix error --- Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Makefile b/Makefile index 82a774a5..18e2e67a 100644 --- a/Makefile +++ b/Makefile @@ -91,7 +91,7 @@ MANSTATICALL=$(MANSTATICMAN) $(MANSTATICHTML) # Creating the type html page %.html: %.text $(A2XH) $^ - $(CROSSLINK) $^ + $(CROSSLINK) $@ man: $(MANTYPEALL) $(MANREFALL) $(MANSTATICALL) From 5f147dd845bbfabbd14a6e7bdda7cc6a8828d42c Mon Sep 17 00:00:00 2001 From: Tomas Pospisek Date: Wed, 30 Apr 2014 20:45:05 +0200 Subject: [PATCH 14/14] fix sed pattern * don't add a href to the title tag (3rd line in the html document) * replace multiple instances on a line --- Makefile | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/Makefile b/Makefile index 18e2e67a..112b1411 100644 --- a/Makefile +++ b/Makefile @@ -23,8 +23,10 @@ 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) -CROSSLINK=sed --in-place 's/\([[:alnum:]_-]*\)(\([17]\))/&<\/a>/' +# 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