From bd0204ecb1fb80cdf36af0f57b72e84445c1a088 Mon Sep 17 00:00:00 2001 From: Sol Jerome Date: Tue, 29 Dec 2009 04:19:02 +0000 Subject: doc: Rearrange plugin document structure Signed-off-by: Sol Jerome git-svn-id: https://svn.mcs.anl.gov/repos/bcfg/trunk/bcfg2@5636 ce84e21b-d406-0410-9b95-82705330c041 --- doc/plugins/generators/tgenshi.txt | 73 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 73 insertions(+) create mode 100644 doc/plugins/generators/tgenshi.txt (limited to 'doc/plugins/generators/tgenshi.txt') 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 + + client is ypbound workstation + client is a desktop, but not an ubuntu desktop + + +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]. -- cgit v1.2.3-1-g7c22