document messaging

Signed-off-by: Nico Schottelius <nico@bento.schottelius.org>

docs/man/man7/cdist-messaging.text

@@ -0,0 +1,72 @@
+cdist-messaging(7)
+==================
+Nico Schottelius <nico-cdist--@--schottelius.org>
+
+NAME
+----
+cdist-messaging - How the initial manifest and types can communication
+
+
+DESCRIPTION
+-----------
+cdist has a simple but powerful way of allowing communication between
+the initial manifest and types as well as types and types.
+
+Whenever execution is passed from cdist to one of the
+scripts described below, cdist generate 2 new temporary files
+and exports the environment variables __messages_in and
+__messages_out to point to them. 
+
+Before handing over the control, the content of the global message 
+file is copied into the file referenced by $__messages_in.
+
+After cdist gained control back, the content of the file referenced
+by $__messages_out is appended to the global message file.
+
+This way overwriting any of the two files by accident does not 
+interfere with other types.
+
+The order of execution is not defined unless you create dependencies 
+between the different objects (see cdist-manifest(7)) and thus you
+can only react reliably on messages by objects that you depend on.
+
+
+AVAILABILITY
+------------
+Messaging is possible between all **local** scripts:
+
+- initial manifest
+- type/manifest
+- type/gencode-local
+- type/gencode-remote
+
+
+EXAMPLES
+--------
+When you want to emit a message use:
+
+--------------------------------------------------------------------------------
+echo "something" >> "$__messages_out"
+--------------------------------------------------------------------------------
+
+When you want to react on a message use:
+
+--------------------------------------------------------------------------------
+if grep -q "^__your_type/object/id:something" "$__messages_in"; then
+    echo "I do something else"
+fi
+--------------------------------------------------------------------------------
+
+
+SEE ALSO
+--------
+- cdist(1)
+- cdist-manifest(7)
+- cdist-reference(7)
+- cdist-type(7)
+
+
+COPYING
+-------
+Copyright \(C) 2013 Nico Schottelius. Free use of this software is
+granted under the terms of the GNU General Public License version 3 (GPLv3).