doc: Rearrange plugin document structure

Signed-off-by: Sol Jerome <solj@ices.utexas.edu>


git-svn-id: https://svn.mcs.anl.gov/repos/bcfg/trunk/bcfg2@5636 ce84e21b-d406-0410-9b95-82705330c041

1 files changed, 73 insertions, 0 deletions

diff --git a/doc/plugins/generators/tgenshi.txt b/doc/plugins/generators/tgenshi.txt
new file mode 100644
index 000000000..5794bac25
--- /dev/null
+++ b/doc/plugins/generators/tgenshi.txt
@@ -0,0 +1,73 @@
+.. -*- mode: rst -*-
+
+=======
+TGenshi
+=======
+
+This page documents the TGenshi plugin. This plugin works with version 0.4 and newer of the genshi library.
+
+The TGenshi plugin allows you to use the [http://genshi.edgewall.org Genshi] templating system to create files, instead of the various diff-based methods offered by the Cfg plugin. It also allows you to include the results of probes executed on the client in the created files.
+
+To begin, you will need to download and install the Genshi templating engine.
+
+To install on CentOS or RHEL 5, run::
+
+    sudo yum install python-genshi
+
+Once it is installed, you can enable it by adding TGenshi to the generators line in /etc/bcfg2.conf on your Bcfg server. For example::
+
+    generators = SSHbase,Cfg,Pkgmgr,Svcmgr,Rules,TGenshi
+
+The TGenshi plugin makes use of a Cfg-like directory structure located in in a TGenshi subdirectory of your repository, usually `/var/lib/bcfg2/TGenshi`. Each file has a directory containing two file types, template and info. Templates are named according to the genshi format used; template.txt uses the genshi text format, and template.xml uses the XML format.
+
+If used with Genshi 0.5 or later the plugin also supports the [http://genshi.edgewall.org/wiki/Documentation/0.5.x/text-templates.html new style] text template format for files named template.newtxt. One of the advantages of the new format is that it does not use # as a command delimiter, making it easier to utilize for configuration files that use # as a comment character.
+
+Only one template format may be used per file served. Info files are identical to those used in Cfg, and info.xml files are supported.
+
+Inside of templates
+===================
+
+* metadata is the client's metadata
+* properties.properties is an xml document of unstructured data
+
+See the genshi [http://genshi.edgewall.org/wiki/Documentation documentation] for examples of Genshi syntax.
+
+Examples
+========
+
+See [wiki:Plugins/TGenshi/examples] for some TGenshi template examples, including the great starting point [wiki:Plugins/TGenshi/examples/motd /etc/motd]. They will use the new style of Genshi syntax, unless noted otherwise.
+
+Examples: Old Genshi Syntax
+---------------------------
+
+Genshi's web pages recommend against using this syntax, as it may disappear from future releases.
+
+
+Group Negation
+--------------
+
+Templates are also useful for cases where more sophisticated boolean operations than those supported by Cfg are needed. For example, the template::
+
+    #if "ypbound" in metadata.groups and "workstation" in metadata.groups
+    client is ypbound workstation
+    #end
+    #if "ubuntu" not in metadata.groups and "desktop" in metadata.groups
+    client is a desktop, but not an ubuntu desktop
+    #end
+
+Produces:
+
+.. code-block:: xml
+
+    <Path type="file" name="/bar.conf" owner="root" perms="0644" group="root">client is ypbound workstation
+    client is a desktop, but not an ubuntu desktop
+    </Path>
+
+This flexibility provides the ability to build much more compact and succinct definitions of configuration contents than Cfg can.
+
+FAQs
+====
+
+'''Question:''' How do I escape the $ (dollar sign) in a TGenshi text template? For example, if I want to include SVN (subversion) keywords like $Id$ or $HeadURL$ in TGenshi-generated files, or am templating a bourne shell (sh/bash) script or Makefile (make).
+
+'''Answer:''' Use $$ (double dollar sign) to output a literal $ (dollarsign) in a TGenshi text template. So instead of $Id$, you'd use $$Id$$. See also Genshi tickets [http://genshi.edgewall.org/ticket/282 #282: Document $$ escape convention] and [http://genshi.edgewall.org/ticket/283 #283: Allow for redefinition of template syntax per-file].