integrate the first type manpage into cdist

Signed-off-by: Nico Schottelius <nico@kr.ethz.ch>

Makefile

@@ -16,6 +16,8 @@ MANSRC=$(MANDIR)/cdist-config-layout.text \
 	$(MANDIR)/cdist-stages.text		\
 	$(MANDIR)/cdist-terms.text 		\
 
+MANGENERATED=$(MANDIR)/cdist-type-listing.text
+
 MANSRC=$(MANDIR)/cdist.text				\
    $(MANDIR)/cdist-bin-transfer.text	\
    $(MANDIR)/cdist-deploy-to.text 		\
@@ -23,7 +25,7 @@ MANSRC=$(MANDIR)/cdist.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,11 +45,16 @@ 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-type-listing.text: $(MANSRC) $(MANDIR)/cdist-type-listing.text.sh
+	$(MANDIR)/cdist-type-listing.text.sh
+	
+
 clean:
 	rm -rf doc/man/*.html doc/man/*.[1-9] doc/man/man[1-9]
 

doc/changelog

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

doc/man/.gitignore

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

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

@@ -30,9 +30,11 @@ __cdist_abs_myname="$__cdist_abs_mydir/$__cdist_myname"
 filename="${__cdist_myname%.sh}"
 dest="$__cdist_abs_mydir/$filename"
 
-exit 0
+cd "$__cdist_abs_mydir"
 
-cat << eof > "$dest"
+exec > "$dest"
+
+cat << eof 
 cdist-type-listing(7)
 =====================
 Nico Schottelius <nico-cdist--@--schottelius.org>
@@ -50,150 +52,32 @@ Types that are included in cdist $(git describe).
 
 DESCRIPTION
 -----------
-Types are the main component of cdist and define functionality. If you
+The following types are available:
-use cdist, you'll write a type for every functionality you would like
-to use.
 
+eof
+for type in cdist-type__*.text; do
+   name_1="${type#cdist-type}"
+   name_2="${name_1%.text}"
 
-HOW TO USE A TYPE
+   name="$name_2"
------------------
+   echo "- $name"
-You can use types from the initial manifest or the type manifest like a
+done
-normal command:
 
---------------------------------------------------------------------------------
+cat << eof
-# 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-type(7)
-- cdist-stages(7)
+eof
+for type in cdist-type__*.text; do
+   name_2="${type%.text}"
 
+   name="$name_2"
+   echo "- ${name}(7)"
+done
+
+cat <<eof
 
 COPYING
 -------