finish manpage for cdist-type__file

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

Makefile

@@ -23,6 +23,7 @@ MANSRC=$(MANDIR)/cdist.text				\
 	$(MANDIR)/cdist-stages.text			\
 	$(MANDIR)/cdist-type.text				\
 	$(MANDIR)/cdist-type-template.text	\
+	$(MANDIR)/cdist-type__file.text	\
 
 
 ################################################################################

doc/man/cdist-type__file.text

@@ -1,163 +1,56 @@
-cdist-type(7)
+cdist-type__file(7)
-=============
+===================
 Nico Schottelius <nico-cdist--@--schottelius.org>
 
 
 NAME
 ----
-cdist-type - Functionality bundled
+cdist-type__file - Create files
-
-
-SYNOPSIS
---------
-Other languages name this module or class 
 
 
 DESCRIPTION
 -----------
-Types are the main component of cdist and define functionality. If you
+This cdist type allows you to create files on the target.
-use cdist, you'll write a type for every functionality you would like
-to use.
 
 
-HOW TO USE A TYPE
+REQUIRED PARAMETERS
------------------
+-------------------
-You can use types from the initial manifest or the type manifest like a
+type::
-normal command:
+   Specifies the type of file to be created. Either "directory" or "file"
+
+
+OPTIONAL PARAMETERS
+-------------------
+destination::
+   If supplied, use this as the destination on the target. Otherwise the
+   object_id is used.
+
+mode::
+   Unix permissions, suitable for chmod.
+
+source::
+   If supplied, copy this file from the host running cdist to the target.
+   If not supplied, an empty file or directory will be created.
+
+
+EXAMPLES
+--------
 
 --------------------------------------------------------------------------------
-# Creates empty file /etc/cdist-configured
+# Create  /etc/cdist-configured as an empty file
 __file /etc/cdist-configured --type file
 
-# Ensure tree is installed
+# Same but with a different object id
-__package tree --state installed
+__file cdist-marker --type file --destination /etc/cdist-configured
+
+# Use __file from another type
+__file /etc/issue --source "$__type/files/archlinux" --type file
 --------------------------------------------------------------------------------
 
-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)
 
 
 COPYING