From 19d3b52d73b05b735994221eae8582b2047800e7 Mon Sep 17 00:00:00 2001 From: Nico Schottelius Date: Wed, 9 Mar 2011 10:16:46 +0100 Subject: [PATCH] finish manpage cdist-explorer Signed-off-by: Nico Schottelius --- Makefile | 2 +- doc/changelog | 2 +- doc/man/cdist-explorer.text | 66 ++++++++++++++++++++++++++++ doc/man/to_check/cdist-explorer.text | 43 ------------------ 4 files changed, 68 insertions(+), 45 deletions(-) create mode 100644 doc/man/cdist-explorer.text delete mode 100644 doc/man/to_check/cdist-explorer.text diff --git a/Makefile b/Makefile index ca86ac4d..adf03e31 100644 --- a/Makefile +++ b/Makefile @@ -12,7 +12,6 @@ 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 \ @@ -23,6 +22,7 @@ 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 \ diff --git a/doc/changelog b/doc/changelog index b39c512d..4c356111 100644 --- a/doc/changelog +++ b/doc/changelog @@ -1,5 +1,5 @@ 1.0.2: upcoming - * Add manpages: cdist-type, cdist-type__file, cdist-reference + * Add manpages: cdist-type, cdist-type__file, cdist-reference, cdist-explorer * Make doc/man/ usable as MANPATH entry 1.0.1: 2011-03-08 diff --git a/doc/man/cdist-explorer.text b/doc/man/cdist-explorer.text new file mode 100644 index 00000000..9e40ca4b --- /dev/null +++ b/doc/man/cdist-explorer.text @@ -0,0 +1,66 @@ +cdist-explorer(7) +================= +Nico Schottelius + + +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/ (general and type explorer) or +$__type_explorer/ (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. + + +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). diff --git a/doc/man/to_check/cdist-explorer.text b/doc/man/to_check/cdist-explorer.text deleted file mode 100644 index 659a01e1..00000000 --- a/doc/man/to_check/cdist-explorer.text +++ /dev/null @@ -1,43 +0,0 @@ -cdist-explorer(7) -================= -Nico Schottelius - - -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 ./ (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).