Merge remote branch 'nico/master'

Makefile

@@ -9,21 +9,25 @@ WEBDIR=$$HOME/niconetz
 WEBPAGE=software/cdist.mdwn
 
 MANDIR=doc/man
+# Unchecked
 MANSRC=$(MANDIR)/cdist-config-layout.text \
 	$(MANDIR)/cdist-config.text 		\
-	$(MANDIR)/cdist-explorer.text	\
 	$(MANDIR)/cdist-quickstart.text \
 	$(MANDIR)/cdist-stages.text		\
 	$(MANDIR)/cdist-terms.text 		\
 
+# Clean documentation
+MANGENERATED=$(MANDIR)/cdist-reference.text
+
 MANSRC=$(MANDIR)/cdist.text				\
    $(MANDIR)/cdist-bin-transfer.text	\
    $(MANDIR)/cdist-deploy-to.text 		\
+	$(MANDIR)/cdist-explorer.text			\
 	$(MANDIR)/cdist-manifest.text 		\
 	$(MANDIR)/cdist-stages.text			\
 	$(MANDIR)/cdist-type.text				\
 	$(MANDIR)/cdist-type-template.text	\
-	$(MANDIR)/cdist-type__file.text	\
+	$(MANDIR)/cdist-type__file.text		\
 
 
 ################################################################################
@@ -43,13 +47,18 @@ all:
 
 man: doc/man/.marker
 
-doc/man/.marker: $(MANSRC)
+doc/man/.marker: $(MANSRC) $(MANGENERATED)
-	for mansrc in $(MANSRC); do $(A2X) $$mansrc; done
+	for mansrc in $^; do $(A2X) $$mansrc; done
 	for manpage in $(MANDIR)/*.[1-9]; do cat=$${manpage##*.}; mandir=$(MANDIR)/man$$cat; mkdir -p $$mandir; mv $$manpage $$mandir; done
 	touch $@
 
+# Only depends on cdist-type__*.text in reality
+$(MANDIR)/cdist-reference.text: $(MANSRC) $(MANDIR)/cdist-reference.text.sh
+	$(MANDIR)/cdist-reference.text.sh
+	
+
 clean:
-	rm -rf doc/man/*.html doc/man/*.[1-9] doc/man/man[1-9]
+	rm -rf doc/man/*.html doc/man/*.[1-9] doc/man/man[1-9] $(MANGENERATED)
 
 ################################################################################
 # Developer targets

doc/changelog

@@ -1,5 +1,5 @@
-1.0.2: upcoming
+1.0.2: 2011-03-09
-	* Add manpages: cdist-type
+	* Add manpages: cdist-type, cdist-type__file, cdist-reference, cdist-explorer
 	* Make doc/man/ usable as MANPATH entry
 
 1.0.1: 2011-03-08

doc/dev/todo/niconext

@@ -1,4 +1 @@
 Documentation cleanup
-   - document environment variables
-   - Reference all types somewhere (on the webpage?)
-   - how to debug explorer

doc/man/.gitignore

@@ -1,3 +1,4 @@
 cdist.7
 *.html
 cdist-design.7
+cdist-reference.text

doc/man/cdist-deploy-to.text

@@ -30,10 +30,10 @@ variables are handled by cdist-config.
 
 SEE ALSO
 --------
-cdist(7),
+- cdist(7)
-cdist-config(1),
+- cdist-config(1)
-cdist-config-layout(7),
+- cdist-reference(7)
-cdist-stages(7)
+- cdist-stages(7)
 
 
 COPYING

doc/man/cdist-explorer.text

@@ -0,0 +1,68 @@
+cdist-explorer(7)
+=================
+Nico Schottelius <nico-cdist--@--schottelius.org>
+
+
+NAME
+----
+cdist-explorer - Explore the target systems
+
+
+DESCRIPTION
+-----------
+Explorer are small shell scripts, which will be executed on the target
+host. The aim of the explorer is to give hints to types on how to act on the
+target system. An explorer outputs the result to stdout, which is usually
+a one liner, but may be empty or multi line especially in the case of
+type explorers.
+
+There are general explorers, which are run in an early stage, and
+type explorers. Both work almost exactly the same way, with the difference
+that the values of the general explorers are stored in a general location and
+the type specific below the object.
+
+Explorers can reuse other explorers on the target system by calling 
+$__explorer/<explorer_name> (general and type explorer) or
+$__type_explorer/<explorer name> (type explorer).
+
+In case of significant errors, the explorer may exit non-zero and return an
+error message on stderr, which will cause the cdist run to abort.
+
+You can also use stderr for debugging purposes while developing a new
+explorer.
+
+EXAMPLES
+--------
+A very simple explorer may look like this:
+
+--------------------------------------------------------------------------------
+hostname
+--------------------------------------------------------------------------------
+
+Which is in practise the "hostname" explorer.
+
+A type explorer, which could check for the status of a package may look like this:
+
+--------------------------------------------------------------------------------
+if [ -f "$__object/parameter/name" ]; then
+   name="$(cat "$__object/parameter/name")"
+else
+   name="$__object_id"
+fi
+
+# Except dpkg failing, if package is not known / installed
+dpkg -s "$name" 2>/dev/null || exit 0
+--------------------------------------------------------------------------------
+
+
+SEE ALSO
+--------
+- cdist(7)
+- cdist-reference(7)
+- cdist-stages(7)
+
+
+COPYING
+-------
+Copyright \(C) 2010-2011 Nico Schottelius. Free use of this software is
+granted under the terms of the GNU General Public License version 3 (GPLv3).

doc/man/cdist-reference.text.sh

@@ -0,0 +1,191 @@
+#!/bin/sh
+#
+# 2010-2011 Nico Schottelius (nico-cdist at schottelius.org)
+#
+# This file is part of cdist.
+#
+# cdist is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# cdist is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with cdist. If not, see <http://www.gnu.org/licenses/>.
+#
+#
+# Generate manpage that lists available types
+#
+
+__cdist_pwd="$(pwd -P)"
+__cdist_mydir="${0%/*}";
+__cdist_abs_mydir="$(cd "$__cdist_mydir" && pwd -P)"
+__cdist_myname=${0##*/};
+__cdist_abs_myname="$__cdist_abs_mydir/$__cdist_myname"
+
+filename="${__cdist_myname%.sh}"
+dest="$__cdist_abs_mydir/$filename"
+
+cd "$__cdist_abs_mydir"
+
+exec > "$dest"
+cat << eof 
+cdist-reference(7)
+==================
+Nico Schottelius <nico-cdist--@--schottelius.org>
+
+NAME
+----
+cdist-reference - Variable, path and type reference for cdist $(git describe)
+
+
+DESCRIPTION
+-----------
+Various scripts which are not in the core need information on how
+to find information. This manpage summarises the available environment
+variables, types and paths and clearifies with part may access which variables.
+
+
+PATHS
+-----
+If not specified otherwise, all paths are relative to the checkout directory.
+
+conf/::
+   Contains the (static) configuration like manifests, types and explorers.  
+
+conf/manifest/init::
+   This is the central entry point used by cdist-manifest-init(1).
+   It is an executable (+x bit set) shell script that can use
+   values from the explorers to decide which configuration to create
+   for the specified target host.
+
+   It should be primary used to define mapping from configurations to hosts.
+
+conf/manifest/*::
+   All other files in this directory are not directly used by cdist, but you
+   can seperate configuration mappings, if you have a lot of code in the
+   manifest/init file. This may also be very helpful to have different admins
+   maintain different groups of hosts.
+
+conf/explorer/<name>::
+   Contains explorers to be run on the target hosts, see cdist-explorer(7).
+
+conf/type/::
+   Contains all available types, which are used to provide
+   some kind of functionality. See cdist-type(7).
+
+conf/type/<name>/::
+   Home of the type <name>.
+
+   This directory is referenced by the variable __type (see below).
+
+conf/type/<name>/manifest::
+   Used to generate additional objects from a type.
+
+conf/type/<name>/gencode::
+   Used to generate code to be executed on the client.
+
+conf/type/<name>/parameters/required::
+   Parameters required by type, \n seperated list.
+
+conf/type/<name>/parameters/optional::
+   Parameters optionally accepted by type, \n seperated list.
+
+conf/type/<name>/explorer::
+   Location of the type specific explorers.
+
+   This directory is referenced by the variable __type_explorer (see below).
+
+   See cdist-explorer(7).
+
+out/::
+   This directory contains output of cdist and is usually located
+   in a temporary directory and thus will be removed after the run.
+
+   This directory is referenced by the variable __global (see below).
+
+out/explorer::
+   Output of general explorers.
+
+out/object::
+   Objects created for the host.
+
+out/object/<object>::
+   Contains all object specific information.
+
+   This directory is referenced by the variable __object (see below).
+
+out/object/<object>/explorers::
+   Output of type specific explorers, per object.
+
+tmp_dir::
+   A tempdir and a tempfile is used by cdist internally,
+   which will be removed when the scripts end automatically.
+   See cdist-config(1).
+
+TYPES
+-----
+The following types are available:
+
+eof
+for type in cdist-type__*.text; do
+   name_1="${type#cdist-type}"
+   name_2="${name_1%.text}"
+
+   name="$name_2"
+   echo "- $name"
+done
+
+cat << eof
+
+
+VARIABLES
+---------
+__explorer::
+   Directory that contains all explorers.
+   Available for: explorer
+__manifest::
+   Directory that contains the initial manifest.
+   Available for: initial manifest
+__global::
+   Directory that contains generic output like explorer.
+   Available for: initial manifest, type manifest, type explorer, type codegen
+__object::
+   Directory that contains the current object.
+   Available for: type manifest, type explorer, type codegen
+__object_id::
+   The type unique object id.
+   Available for: type manifest, type explorer, type codegen
+__target_host::
+   The host we are deploying to.
+   Available for: initial manifest, type manifest, type codegen
+__type::
+   Path to the current type.
+   Available for: type manifest
+__type_explorers::
+   Directory that contains the type explorers.
+   Available for: type explorer
+
+
+SEE ALSO
+--------
+- cdist(7)
+eof
+for type in cdist-type__*.text; do
+   name_2="${type%.text}"
+
+   name="$name_2"
+   echo "- ${name}(7)"
+done
+
+cat <<eof
+
+COPYING
+-------
+Copyright \(C) 2011 Nico Schottelius. Free use of this software is
+granted under the terms of the GNU General Public License version 3 (GPLv3).
+eof

doc/man/cdist-stages.text

@@ -46,10 +46,9 @@ no conflicts may occur, i.e. no object of the same type with the same id may
 be created.
 
 Related manpages: 
+   - cdist-manifest(7)
    - cdist-manifest-run(1)
    - cdist-manifest-run-init(1)
-   - cdist-manifest(7)
-   - cdist-config-layout(7)
 
 
 STAGE 3: EXECUTION OF TYPES
@@ -67,9 +66,9 @@ may occur during the merge. A conflict would mean that two different objects
 try to create the same object, which indicates a broken configuration.
 
 Related manpages:
-   - cdist-type(7) 
    - cdist-manifest-run(1)
    - cdist-manifest-run-all(1)
+   - cdist-type(7) 
 
 
 STAGE 4: CODE GENERATION
@@ -81,9 +80,9 @@ on stdout. If the gencode executable fails, it must print diagnostic messages
 on stderr and exit non-zero.
 
 Related manpages:
-   - cdist-types-gencode(7)
    - cdist-gencode(1)
    - cdist-gencode-all(1)
+   - cdist-type(7) 
 
 
 STAGE 5: CODE EXECUTION
@@ -92,8 +91,8 @@ The resulting code from the previous stage is transferred to the target host
 and executed there to apply the configuration changes,
 
 Related manpages:
-   - cdist-exec-transfer(1)
    - cdist-exec-run(1)
+   - cdist-exec-transfer(1)
 
 
 SUMMARY
@@ -106,7 +105,9 @@ in correct order.
 
 SEE ALSO
 --------
-cdist(7), cdist-deploy-to(1), cdist-config-layout(7)
+- cdist(7)
+- cdist-deploy-to(1)
+- cdist-reference(7)
 
 
 COPYING

doc/man/cdist-type-listing.text.sh

@@ -1,203 +0,0 @@
-#!/bin/sh
-#
-# 2010-2011 Nico Schottelius (nico-cdist at schottelius.org)
-#
-# This file is part of cdist.
-#
-# cdist is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# cdist is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with cdist. If not, see <http://www.gnu.org/licenses/>.
-#
-#
-# Generate manpage that lists available types
-#
-
-__cdist_pwd="$(pwd -P)"
-__cdist_mydir="${0%/*}";
-__cdist_abs_mydir="$(cd "$__cdist_mydir" && pwd -P)"
-__cdist_myname=${0##*/};
-__cdist_abs_myname="$__cdist_abs_mydir/$__cdist_myname"
-
-filename="${__cdist_myname%.sh}"
-dest="$__cdist_abs_mydir/$filename"
-
-exit 0
-
-cat << eof > "$dest"
-cdist-type-listing(7)
-=====================
-Nico Schottelius <nico-cdist--@--schottelius.org>
-
-
-NAME
-----
-cdist-type-listing - Available types in cdist
-
-
-SYNOPSIS
---------
-Types that are included in cdist $(git describe).
-
-
-DESCRIPTION
------------
-Types are the main component of cdist and define functionality. If you
-use cdist, you'll write a type for every functionality you would like
-to use.
-
-
-HOW TO USE A TYPE
------------------
-You can use types from the initial manifest or the type manifest like a
-normal command:
-
---------------------------------------------------------------------------------
-# Creates empty file /etc/cdist-configured
-__file /etc/cdist-configured --type file
-
-# Ensure tree is installed
-__package tree --state installed
---------------------------------------------------------------------------------
-
-Internally cdist-type-emulator(1) will be called from cdist-manifest-run(1) to
-save the given parameters into a cconfig database, so they can be accessed by
-the manifest and gencode scripts of the type (see below).
-
-
-HOW TO WRITE A NEW TYPE
------------------------
-A type consists of
-
-- parameter (optional)
-- manifest  (optional)
-- explorer  (optional)
-- gencode   (optional)
-
-Types are stored below conf/type/. Their name should always be prefixed with
-two underscores (__) to prevent collisions with other binaries in $PATH.
-
-To begin a new type from a template, execute "cdist-type-template __NAME"
-and cd conf/type/__NAME.
-
-
-DEFINING PARAMETERS
--------------------
-Every type consists of optional and required parameters, which must
-be created in a newline seperated file in parameters/required and
-parameters/optional. If either or both missing, the type will have
-no required, no optional or no parameters at all.
-
-Example:
---------------------------------------------------------------------------------
-echo servername >> conf/type/__nginx_vhost/parameter/required
-echo logdirectory >> conf/type/__nginx_vhost/parameter/optional
---------------------------------------------------------------------------------
-
-
-WRITING THE MANIFEST
---------------------
-In the manifest of a type you can use other types, so your type extends
-their functionality. A good example is the __package type, which in
-a shortened version looks like this:
-
---------------------------------------------------------------------------------
-os="$(cat "$__global/explorer/os")"
-case "$os" in
-      archlinux) type="pacman" ;;
-      debian|ubuntu) type="apt" ;;
-      gentoo) type="emerge" ;;
-      *)
-         echo "Don't know how to manage packages on: $os" >&2
-         exit 1
-      ;;
-esac
-
-__package_$type "$@"
---------------------------------------------------------------------------------
-
-As you can see, the type can reference different environment variables,
-which are documented in cdist-environment-variables(7).
-
-Always ensure the manifest is executable, otherwise cdist will not be able
-to execute it.
-
-
-THE TYPE EXPLORERS
-------------------
-If a type needs to explore specific details, it can provide type specific
-explorers, which will be executed on the target for every created object.
-
-The explorers are stored under the "explorer" directory below the type.
-It could for instance contain code to check the md5sum of a file on the
-client, like this (shortened version from real type __file):
-
---------------------------------------------------------------------------------
-if [ -f "$__object/parameter/destination" ]; then
-   destination="$(cat "$__object/parameter/destination")"
-else
-   destination="/$__object_id"
-fi
-
-if [ -e "$destination" ]; then
-   md5sum < "$destination"
-fi
---------------------------------------------------------------------------------
-
-
-WRITING THE GENCODE SCRIPT
---------------------------
-The gencode script can make use of the parameters, the global explorers
-and the type specific explorers. The output (stdout) of this script is
-saved by cdist and will be executed on the target.
-
-If the gencode script encounters an error, it should print diagnostic
-messages to stderr and exit non-zero. If you need to debug the gencode
-script, you can write to stderr:
-
---------------------------------------------------------------------------------
-# Debug output to stderr
-echo "My fancy debug line" >&2
-
-# Output to be saved by cdist for execution on the target
-echo "touch /etc/cdist-configured"
---------------------------------------------------------------------------------
-
-
-HINTS FOR TYPEWRITERS
-----------------------
-It must be assumed that the target is pretty dumb and thus does not have high
-level tools like ruby installed. If a type requires specific tools to be present
-on the target, there must be another type that provides this tool and the first
-type should create an object of the specific type.
-
-
-HOW TO INCLUDE A TYPE INTO UPSTREAM CDIST
------------------------------------------
-If you think your type may be useful for others, ensure it works with the
-current master branch of cdist and submit the git url containing the type for
-inclusion to the mailinglist **cdist at cdist -- at -- l.schottelius.org**.
-
-Ensure a corresponding manpage named cdist-type__NAME is included.
-
-
-SEE ALSO
---------
-- cdist-manifest-run(1)
-- cdist-stages(7)
-
-
-COPYING
--------
-Copyright \(C) 2011-$(date +%Y) Nico Schottelius. Free use of this software is
-granted under the terms of the GNU General Public License version 3 (GPLv3).
-
-eof

doc/man/cdist-type.text

@@ -37,6 +37,8 @@ Internally cdist-type-emulator(1) will be called from cdist-manifest-run(1) to
 save the given parameters into a cconfig database, so they can be accessed by
 the manifest and gencode scripts of the type (see below).
 
+A list of supported types can be found in the cdist-type-listing(7) manpage.
+
 
 HOW TO WRITE A NEW TYPE
 -----------------------

doc/man/cdist.text

@@ -29,12 +29,11 @@ pull mechanism (client requests configuration).
 
 SEE ALSO
 --------
-Website: http://www.nico.schottelius.org/cdist/[],
+- Website: http://www.nico.schottelius.org/cdist/[]
-cdist-deploy-to(1),
+- cdist-deploy-to(1)
-cdist-manifest(7),
+- cdist-manifest(7)
-cdist-quickstart(1),
+- cdist-quickstart(1)
-cdist-type(7),
+- cdist-type(7)
-cdist-type-inclusion(7)
 
 
 COPYING

doc/man/to_check/cdist-config-layout.text

@@ -1,108 +0,0 @@
-cdist-config-layout(7)
-======================
-Nico Schottelius <nico-cdist--@--schottelius.org>
-
-
-NAME
-----
-cdist-config-layout - Usage of paths in cdist
-
-
-DESCRIPTION
------------
-If not specified otherwise, all paths are relative to the configuration
-directory, which is normally /etc/cdist (but can be changed using environment
-variables, see cdist-environment(7)).
-
-- conf_dir/:
-   Contains the (static) configuration like manifests, types and
-   explorers.
-
-- conf_dir/manifest/init:
-   This is the central entry point used by cdist-manifest-init(1).
-   It is an executable (+x bit set) shell script that can use
-   values from the explorers to decide which configuration to create
-   for the specified target host.
-
-   It should be primary used to define mapping from configurations to hosts.
-
-- conf_dir/manifest/*:
-   All other files in this directory are not directly used by Cdist, but you
-   can seperate configuration mappings, if you have a lot of code in the
-   manifest/init file. This may also be very helpful to have different admins
-   maintain different groups of hosts.
-
-- conf_dir/explorer/<name>
-   Contains explorers to be run on the target hosts, see cdist-explorers(7).
-
-- conf_dir/type/
-   Contains all available types, which are used to provide
-   some kind of functionality. See cdist-stages(7).
-
-- conf_dir/type/<name>/manifest:
-   Used to generate additional objects from a type.
-   See cdist-stages(7), cdist-types(7).
-
-- conf_dir/type/<name>/gencode:
-   Used to generate code to be executed on the client.
-   See cdist-types(7).
-
-- conf_dir/type/<name>/parameters/required:
-   Parameters required by type, \n seperated list.
-   See cdist-types(7).
-
-- conf_dir/type/<name>/parameters/optional:
-   Parameters optionally accepted by type, \n seperated list.
-   See cdist-types(7).
-
-- conf_dir/type/<name>/explorer:
-   Location of the type specific explorers.
-   See cdist-explorers(7).
-
-- out_dir/
-   This directory contains output of cdist and is mirrored into the
-   cache after a successful run. This directory may be placed below
-   the tmpdir or at any other location and is also available on the
-   target.
-
-- out_dir/explorer:
-   Output of general explorers.
-
-- out_dir/object:
-   Objects created for the host.
-
-- out_dir/object/<object>/explorers:
-   Output of type specific explorers, per object.
-
-- tmp_dir: Temporary storage
-   A tempdir and a tempfile is provided by cdist-config(1), which
-   will be removed when the scripts ends automatically.
-
-
-FUTURE
-------
-The following functionality may be implemented in one of the next releases:
-
-- cache_dir/
-   The cache contains the out_dir from previous runs, which
-   may also be used in types to gather information about other hosts
-   (like ssh-keys).
-
-- cache_dir/host/<name>:
-   Contains the last out_dir of the specific host.
-
-
-AUTHOR
-------
-Nico Schottelius <mailto:nico-cdist--@--schottelius.org[]>
-
-
-RESOURCES
----------
-Main web site: http://www.nico.schottelius.org/cdist/[]
-
-
-COPYING
--------
-Copyright \(C) 2010-2011 Nico Schottelius. Free use of this software is
-granted under the terms of the GNU General Public License version 3 (GPLv3).

doc/man/to_check/cdist-environment-variables.text

@@ -1,14 +0,0 @@
-Update on env:
-
-   general explorer: __explorer
-   initial manifest: __manifest, __global
-   type manifests  __object, __object_id, __global
-   type explorers:  __object, __object_id, __type_explorers, __global
-   type codegen:  __object, __object_id, __global
-   type code:  -
-
-
-- __object: Path to the object that we are working on
-- __object_id: type unique object id
-- __global: contains global information (see cdist-env
-

doc/man/to_check/cdist-explorer.text

@@ -1,43 +0,0 @@
-cdist-explorer(7)
-=================
-Nico Schottelius <nico-cdist--@--schottelius.org>
-
-
-NAME
-----
-cdist-explorer - Explore the target systems
-
-
-DESCRIPTION
------------
-Cdist explorer are small shell scripts, which will be executed
-on the target host. The aim of the explorer is to give hints
-to types on how to act on the target system.
-The explorer output the result of its investigation
-to stdout and should be a one-liner. The output may be empty,
-though.
-
-Cdist knows about general explorers, which are run in an early
-stage and type specific explorers. Both work exactly the same way,
-with the difference that the values of the general explorers
-are stored in a general location and the type specific below
-the types.
-
-Explorers can reuse other explorers on the target system
-by calling ./<explorer_name> (i.e. explorers are run
-from their location).
-
-In case of significant errors, the shell script may exit
-non-zero and return an error message on stderr, which
-will cause the cdist run to abort.
-
-
-SEE ALSO
---------
-cdist(7), cdist-config-layout(7), cdist-stages(7)
-
-
-COPYING
--------
-Copyright \(C) 2010-2011 Nico Schottelius. Free use of this software is
-granted under the terms of the GNU General Public License version 3 (GPLv3).