documented which XML files have which features

11 files changed, 219 insertions, 133 deletions

diff --git a/doc/development/cfg.txt b/doc/development/cfg.txt
index 71c455b52..a4360559f 100644
--- a/doc/development/cfg.txt
+++ b/doc/development/cfg.txt
@@ -97,6 +97,5 @@ Other Cfg Objects
 These other objects comprise the remainder of the Cfg plugin, and are
 included for completeness.
 
-.. autoattribute:: Bcfg2.Server.Plugins.Cfg.DEFAULT_INFO
 .. autoclass:: Bcfg2.Server.Plugins.Cfg.CfgEntrySet
 .. autoclass:: Bcfg2.Server.Plugins.Cfg.Cfg
diff --git a/doc/server/encryption.txt b/doc/server/encryption.txt
index 09b1ea183..a701a42ca 100644
--- a/doc/server/encryption.txt
+++ b/doc/server/encryption.txt
@@ -210,6 +210,8 @@ get a list of valid algorithms, you can run::
     openssl list-cipher-algorithms | grep -v ' => ' | \
         tr 'A-Z-' 'a-z_' | sort -u
 
+.. _server-encryption-lax-strict:
+
 Lax vs. Strict decryption
 -------------------------
 
@@ -230,6 +232,9 @@ This can be overridden by individual XML files by setting
 ``decrypt="strict"`` on the top-level tag (or, vice-versa; if strict
 is the default an XML file can specify ``decrypt="lax"``.
 
+Note that you could, for instance, set lax decryption by default, and
+then set strict decryption on individual files.
+
 Encryption API
 ==============
 
diff --git a/doc/server/genshi-xml.txt b/doc/server/genshi-xml.txt
deleted file mode 100644
index 3216cc00d..000000000
--- a/doc/server/genshi-xml.txt
+++ /dev/null
@@ -1,24 +0,0 @@
-.. -*- mode: rst -*-
-
-.. _xml-genshi-reference:
-
-===============================
- Genshi XML Template Reference
-===============================
-
-Genshi's XML templating language is used in
-:ref:`server-plugins-structures-bundler-index` for templated bundles.
-The language is described in depth at `Genshi
-<http://genshi.edgewall.org>`_.  The XML schema reference follows.
-
-Genshi Tags
-===========
-
-.. xml:group:: genshiElements
-   :namespace: py
-
-Genshi Attributes
-=================
-
-.. xml:attributegroup:: genshiAttrs
-   :namespace: py
diff --git a/doc/server/index.txt b/doc/server/index.txt
index 42abb454c..71431b2a8 100644
--- a/doc/server/index.txt
+++ b/doc/server/index.txt
@@ -32,4 +32,4 @@ clients.
    database
    caching
    encryption
-   genshi-xml
+   xml-common
diff --git a/doc/server/plugins/connectors/properties.txt b/doc/server/plugins/connectors/properties.txt
index da511736d..6e53de216 100644
--- a/doc/server/plugins/connectors/properties.txt
+++ b/doc/server/plugins/connectors/properties.txt
@@ -120,6 +120,8 @@ in ``bcfg2.conf``::
     [properties]
     writes_enabled = false
 
+.. _server-plugins-connectors-properties-xml:
+
 XML Property Files
 ------------------
 
@@ -262,47 +264,13 @@ Encrypted Properties data
 .. versionadded:: 1.3.0
 
 You can encrypt selected data in XML Properties files to protect that
-data from other people who need access to the repository.  See
-:ref:`server-encryption-configuration` for details on configuring
-encryption passphrases.  The data is decrypted transparently
-on-the-fly by the server; you never need to decrypt the data in your
-templates.  Encryption is only supported on XML properties files.
-
-.. note::
-
-    This feature is *not* intended to secure the files against a
-    malicious attacker who has gained access to your Bcfg2 server, as
-    the encryption passphrases are held in plaintext in
-    ``bcfg2.conf``.  This is only intended to make it easier to use a
-    single Bcfg2 repository with multiple admins who should not
-    necessarily have access to each other's sensitive data.
-
-Properties files are encrypted on a per-element basis; that is, rather
-than encrypting the whole file, only the character content of
-individual elements is encrypted.  This makes it easier to track
-changes to the file in a VCS, and also lets unprivileged users work
-with the other data in the file.  Only character content of an element
-can be encrypted; attribute content and XML elements themselves cannot
-be encrypted.
-
-By default, decryption is *strict*; that is, if any element cannot be
-decrypted, parsing of the file is aborted.  If you wish for parsing to
-continue, with unencryptable elements simply skipped, then you can set
-decryption to *lax* in one of two ways:
-
-* Set ``decrypt=lax`` in the ``[encryption]`` section of
-  ``bcfg2.conf`` to set lax decryption on all files by default; or
-* Set the ``decrypt="lax"`` attribute on the top-level ``Properties``
-  tag of a Properties file to set lax decryption for a single file.
-
-Note that you could, for instance, set lax decryption by default, and
-then set strict decryption on individual files.
-
-To encrypt or decrypt a file, use :ref:`bcfg2-crypt`.
-
-See :ref:`server-encryption` for more details on encryption in Bcfg2
-in general.
+data from other people who need access to the repository.  The
+data is decrypted transparently on-the-fly by the server; you never
+need to decrypt the data in your templates.  Encryption is only
+supported on XML properties files.
 
+See :ref:`server-encryption` for details on encryption in general, and
+:ref:`xml-encryption` for details on encryption in XML files.
 
 Accessing Properties contents from Genshi Templates
 ===================================================
diff --git a/doc/server/plugins/grouping/metadata.txt b/doc/server/plugins/grouping/metadata.txt
index a6ed37f8e..7fcc83d4c 100644
--- a/doc/server/plugins/grouping/metadata.txt
+++ b/doc/server/plugins/grouping/metadata.txt
@@ -90,6 +90,8 @@ Database Settings <server-database>`.
 
 The `clients.xml`_-based model remains the default.
 
+.. _server-plugins-grouping-metadata-groups-xml:
+
 groups.xml
 ==========
 
@@ -181,38 +183,6 @@ groups:
 
 .. xml:schema:: metadata.xsd
 
-
-XInclude
-========
-
-.. versionadded:: 0.9.0
-
-`XInclude <http://www.w3.org/TR/xinclude/>`_ is a W3C specification
-for the inclusion of external XML documents into XML source files,
-allowing complex definitions to be split into smaller, more manageable
-pieces. The `Metadata`_ plugin supports the use of XInclude
-specifications to split the `clients.xml`_ and `groups.xml`_
-files. This mechanism allows the following specification to produce
-useful results:
-
-.. code-block:: xml
-
-    <Groups version='3.0' xmlns:xi="http://www.w3.org/2001/XInclude">
-     <xi:include href="my-groups.xml" />
-     <xi:include href="their-groups.xml" />
-    </Groups>
-
-Each of the included groups files has the same format. These files are
-properly validated by ``bcfg2-lint``. This mechanism is useful for
-composing group definitions from multiple sources, or setting
-different permissions in an svn repository.
-
-Probes
-======
-
-The metadata plugin includes client-side probing functionality. This
-is fully documented :ref:`here <server-plugins-probes-index>`.
-
 Metadata Caching
 ================
 
diff --git a/doc/server/plugins/probes/fileprobes.txt b/doc/server/plugins/probes/fileprobes.txt
index 0baec2c59..1bee38c5a 100644
--- a/doc/server/plugins/probes/fileprobes.txt
+++ b/doc/server/plugins/probes/fileprobes.txt
@@ -1,3 +1,5 @@
+.. -*- mode: rst -*-
+
 .. _server-plugins-probes-fileprobes:
 
 ==========
diff --git a/doc/server/plugins/structures/bundler/index.txt b/doc/server/plugins/structures/bundler/index.txt
index f6ed1357d..67d8963a9 100644
--- a/doc/server/plugins/structures/bundler/index.txt
+++ b/doc/server/plugins/structures/bundler/index.txt
@@ -123,39 +123,7 @@ generate a bundle.  Genshi templates can be specified one of two ways:
 2. Add the Genshi namespace to your existing XML
    bundle.
 
-The top-level Bundle tag should look like the following::
-
-    <Bundle xmlns:py="http://genshi.edgewall.org/">
-
-Several variables are pre-defined inside templates:
-
-+-------------+--------------------------------------------------------+
-| Name        | Description                                            |
-+=============+========================================================+
-| metadata    | :ref:`Client metadata                                  |
-|             | <server-plugins-grouping-metadata-clientmetadata>`     |
-+-------------+--------------------------------------------------------+
-| repo        | The path to the Bcfg2 repository on the filesystem     |
-+-------------+--------------------------------------------------------+
-
-.. note::
-
-    ``<Group>`` and ``<Client>`` tags are allowed inside of Genshi
-    templates as of Bcfg2 1.2.  However, they do not behave the same
-    as using a Genshi conditional, e.g.::
-
-        <py:if test="'groupname' in metadata.groups">
-	</py:if>
-
-    The conditional is evaluated when the template is rendered, so
-    code inside the conditional is not executed if the conditional
-    fails.  A ``<Group>`` tag is evaluated *after* the template is
-    rendered, so code inside the tag is always executed.  This is an
-    important distinction: if you have code that will fail on some
-    groups, you *must* use a Genshi conditional, not a ``<Group>``
-    tag.  The same caveats apply to ``<Client>`` tags.
-
-See also the :ref:`xml-genshi-reference`.
+See :ref:`xml-genshi-templating` for details.
 
 Troubleshooting
 ---------------
diff --git a/doc/server/xml-common.txt b/doc/server/xml-common.txt
new file mode 100644
index 000000000..44205ed42
--- /dev/null
+++ b/doc/server/xml-common.txt
@@ -0,0 +1,199 @@
+.. -*- mode: rst -*-
+
+.. _xml-features:
+
+=====================
+ Common XML Features
+=====================
+
+Most of the XML files in Bcfg2 have a common set of features that are
+supported.  These are described in some detail below, and a precise
+rundown of which features are supported by which files is provided.
+
+.. _xml-group-client-tags:
+
+Group and Client tags
+=====================
+
+These allow the portions of an XML document inside a Client or Group
+tag to only apply to the given client group.  See
+:ref:`server-plugins-structures-bundler-index` for examples and more
+details.
+
+.. _xml-genshi-templating:
+
+Genshi templating
+=================
+
+Genshi XML templates allow you to use the `Genshi
+<http://genshi.edgewall.org>`_ templating system to dynamically
+generate XML file content for a given client.  Genshi templating can
+be enabled on a file by adding the Genshi namespace to the top-level
+tag, e.g.:
+
+.. code-block:: xml
+
+    <Bundle xmlns:py="http://genshi.edgewall.org/">
+
+Several variables are pre-defined inside Genshi XML templates:
+
++-------------+--------------------------------------------------------+
+| Name        | Description                                            |
++=============+========================================================+
+| metadata    | :ref:`Client metadata                                  |
+|             | <server-plugins-grouping-metadata-clientmetadata>`     |
++-------------+--------------------------------------------------------+
+| repo        | The path to the Bcfg2 repository on the filesystem     |
++-------------+--------------------------------------------------------+
+
+.. note::
+
+    ``<Group>`` and ``<Client>`` tags can be used inside templates as
+    of Bcfg2 1.2, but they do not behave the same as using a Genshi
+    conditional, e.g.::
+
+        <py:if test="'groupname' in metadata.groups">
+	</py:if>
+
+    The conditional is evaluated when the template is rendered, so
+    code inside the conditional is not executed if the conditional
+    fails.  A ``<Group>`` tag is evaluated *after* the template is
+    rendered, so code inside the tag is always executed.  This is an
+    important distinction: if you have code that will fail on some
+    groups, you *must* use a Genshi conditional, not a ``<Group>``
+    tag.  The same caveats apply to ``<Client>`` tags.
+
+.. _xml-genshi-reference:
+
+Genshi XML Template Reference
+-----------------------------
+
+The Genshi XML templating language is described in depth at `Genshi
+<http://genshi.edgewall.org>`_.  The XML schema reference follows.
+
+Genshi Tags
+~~~~~~~~~~~
+
+.. xml:group:: genshiElements
+   :namespace: py
+
+Genshi Attributes
+~~~~~~~~~~~~~~~~~
+
+.. xml:attributegroup:: genshiAttrs
+   :namespace: py
+
+.. _xml-encryption:
+
+Encryption
+==========
+
+You can encrypt data in XML files to protect that data from other
+people who need access to the repository.  The data is decrypted
+transparently on-the-fly by the server.
+
+.. note::
+
+    This feature is *not* intended to secure the files against a
+    malicious attacker who has gained access to your Bcfg2 server, as
+    the encryption passphrases are held in plaintext in
+    ``bcfg2.conf``.  This is only intended to make it easier to use a
+    single Bcfg2 repository with multiple admins who should not
+    necessarily have access to each other's sensitive data.
+
+XML files are encrypted on a per-element basis; that is, rather than
+encrypting the whole file, only the character content of individual
+elements is encrypted.  This makes it easier to track changes to the
+file in a VCS, and also lets unprivileged users work with the other
+data in the file.  Only character content of an element can be
+encrypted; attribute content and XML elements themselves cannot be
+encrypted.
+
+By default, decryption is *strict*; that is, if any element cannot be
+decrypted, parsing of the file is aborted.  See
+:ref:`server-encryption-lax-strict` for information on changing this
+on a global or per-file basis.
+
+To encrypt or decrypt a file, use :ref:`bcfg2-crypt`.
+
+See :ref:`server-encryption` for more details on encryption in Bcfg2
+in general.
+
+XInclude
+========
+
+.. versionadded:: 0.9.0
+
+`XInclude <http://www.w3.org/TR/xinclude/>`_ is a W3C specification
+for the inclusion of external XML documents into XML source files,
+allowing complex definitions to be split into smaller, more manageable
+pieces.  For instance, in the :ref:`server-plugins-grouping-metadata`
+``groups.xml`` file, you might do:
+
+.. code-block:: xml
+
+    <Groups xmlns:xi="http://www.w3.org/2001/XInclude">
+      <xi:include href="my-groups.xml" />
+      <xi:include href="their-groups.xml" />
+    </Groups>
+
+To enable XInclude on a file, you need only add the XInclude namespace
+to the top-level tag.
+
+XInclude can only include whole, well-formed XML files.  In many
+cases, if a file type does not support XInclude it is because the XML
+schema lacks support.
+
+Feature Matrix
+==============
+
++--------------------------------------------------------------+--------------+--------+------------+----------+
+| File                                                         | Group/Client | Genshi | Encryption | XInclude |
++==============================================================+==============+========+============+==========+
+| :ref:`Bundles <server-plugins-structures-bundler-index>`     | Yes          | Yes    | Yes        | Yes      |
++--------------------------------------------------------------+--------------+--------+------------+----------+
+| :ref:`info.xml <server-info>`                                | Yes [#f1]_   | Yes    | No         | No       |
++--------------------------------------------------------------+--------------+--------+------------+----------+
+| :ref:`authorizedkeys.xml, privkey.xml, and pubkey.xml        | Yes          | Yes    | Yes        | No       |
+| <server-plugins-generators-cfg-sshkeys>`                     |              |        |            |          |
++--------------------------------------------------------------+--------------+--------+------------+----------+
+| :ref:`Decisions <server-plugins-generators-decisions>`       | Yes          | Yes    | Yes        | Yes      |
++--------------------------------------------------------------+--------------+--------+------------+----------+
+| :ref:`Defaults <server-plugins-structures-defaults>`         | Yes          | Yes    | Yes        | Yes      |
++--------------------------------------------------------------+--------------+--------+------------+----------+
+| :ref:`FileProbes <server-plugins-probes-fileprobes>`         | Yes          | Yes    | No         | Yes      |
++--------------------------------------------------------------+--------------+--------+------------+----------+
+| :ref:`GroupPatterns <server-plugins-grouping-grouppatterns>` | No           | No     | No         | Yes      |
++--------------------------------------------------------------+--------------+--------+------------+----------+
+| :ref:`Metadata clients.xml                                   | No           | No     | No         | Yes      |
+| <server-plugins-grouping-metadata-clients-xml>`              |              |        |            |          |
++--------------------------------------------------------------+--------------+--------+------------+----------+
+| :ref:`Metadata clients.xml                                   | Yes [#f2]_   | No     | No         | Yes      |
+| <server-plugins-grouping-metadata-groups-xml>`               |              |        |            |          |
++--------------------------------------------------------------+--------------+--------+------------+----------+
+| :ref:`NagiosGen <server-plugins-generators-nagiosgen>`       | Yes          | Yes    | No         | Yes      |
++--------------------------------------------------------------+--------------+--------+------------+----------+
+| :ref:`Pkgmgr <server-plugins-generators-pkgmgr>`             | Yes          | No     | No         | No       |
++--------------------------------------------------------------+--------------+--------+------------+----------+
+| :ref:`Properties <server-plugins-connectors-properties>`     | Yes [#f3]_   | Yes    | Yes        | Yes      |
++--------------------------------------------------------------+--------------+--------+------------+----------+
+| :ref:`Rules <server-plugins-generators-rules>`               | Yes          | Yes    | Yes        | Yes      |
++--------------------------------------------------------------+--------------+--------+------------+----------+
+| :ref:`SSLCA cert.xml and key.xml                             | Yes          | Yes    | Yes        | No       |
+| <server-plugins-generators-sslca>`                           |              |        |            |          |
++--------------------------------------------------------------+--------------+--------+------------+----------+
+
+.. rubric:: Footnotes
+
+.. [#f1] ``info.xml`` also supports conditional Path tags; see
+         :ref:`server-info` for more.
+.. [#f2] The semantics of Group tags in ``groups.xml`` is slightly
+         different; see
+         :ref:`server-plugins-grouping-metadata-groups-xml` for
+         details.
+.. [#f3] Group and Client tags in XML Properties are not automatic by
+         default; they can be resolved by use of either the
+         ``Match()`` or ``XMLMatch()`` methods, or by use of the
+         :ref:`server-plugins-connectors-properties-automatch`
+         feature. See :ref:`server-plugins-connectors-properties-xml`
+         for details.
diff --git a/src/lib/Bcfg2/Server/Plugin/helpers.py b/src/lib/Bcfg2/Server/Plugin/helpers.py
index 6b73ea66a..2daf4e0df 100644
--- a/src/lib/Bcfg2/Server/Plugin/helpers.py
+++ b/src/lib/Bcfg2/Server/Plugin/helpers.py
@@ -509,7 +509,7 @@ class StructFile(XMLFileBacked, Debuggable):
 
     .. -----
     .. autoattribute:: __identifier__
-    .. autofunction:: _include_element
+    .. automethod:: _include_element
     """
 
     #: If ``__identifier__`` is not None, then it must be the name of
diff --git a/src/lib/Bcfg2/Server/Plugins/NagiosGen.py b/src/lib/Bcfg2/Server/Plugins/NagiosGen.py
index fc06be455..c377ca4ef 100644
--- a/src/lib/Bcfg2/Server/Plugins/NagiosGen.py
+++ b/src/lib/Bcfg2/Server/Plugins/NagiosGen.py
@@ -14,7 +14,6 @@ LOGGER = logging.getLogger(__name__)
 
 class NagiosGenConfig(Bcfg2.Server.Plugin.StructFile):
     """ NagiosGen config file handler """
-
     encryption = False
 
     def __init__(self, filename):