doc: clarified Group/Client tag use in xml-common.txt

4 files changed, 63 insertions, 81 deletions

diff --git a/doc/server/plugins/generators/rules.txt b/doc/server/plugins/generators/rules.txt
index a3f29a803..f561b88a6 100644
--- a/doc/server/plugins/generators/rules.txt
+++ b/doc/server/plugins/generators/rules.txt
@@ -28,24 +28,6 @@ Each file in the Rules directory has a priority. This allows the same
 Entities to be served by multiple files. The priorities can be used to
 break ties in the case that multiple files serve data for the same Entity.
 
-
-Usage of Groups in Rules
-========================
-
-Groups are used by the Rules plugin, along with host metadata, for
-selecting the Configuration Entity entries to include in the clients
-literal configuration. They can be thought of as::
-
-    if client is a member of group1 then
-        assign to literal config
-
-Nested groups are conjunctive (logical and).::
-
-    if client is a member of group1 and group2 then
-        assign to literal config
-
-Group membership may be negated.
-
 Tag Attributes in Rules
 =======================
 
diff --git a/doc/server/plugins/structures/bundler/index.txt b/doc/server/plugins/structures/bundler/index.txt
index 67d8963a9..1b88627a5 100644
--- a/doc/server/plugins/structures/bundler/index.txt
+++ b/doc/server/plugins/structures/bundler/index.txt
@@ -19,12 +19,8 @@ will receive.
 Group and Client tags can be used inside of bundles to differentiate
 which entries particular clients will recieve; this is useful for the
 case where entries are named differently across systems; for example,
-one linux distro may have a package called openssh while another uses
-the name ssh. Configuration entries nested inside of Group elements
-only apply to clients who are a member of those groups; multiple
-nested groups must all apply. Also, groups may be negated; entries
-included in such groups will only apply to clients who are not a
-member of said group.  The same applies to Client elements.
+one Linux distro may have a package called ``openssh`` while another
+uses the name ``ssh``. See :ref:`xml-group-client-tags` for details.
 
 The following is an annotated copy of a bundle:
 
@@ -56,7 +52,7 @@ The following is an annotated copy of a bundle:
         <Service name='ssh'/>
       </Group>
       <Client name='trust.example.com'>
-          <Path name='/etc/ssh/shosts.equiv'/>
+        <Path name='/etc/ssh/shosts.equiv'/>
       </Client>
     </Bundle>
 
@@ -119,7 +115,7 @@ generate a bundle.  Genshi templates can be specified one of two ways:
 
 1. Add an XML-style genshi template to the Bundler directory with a
    ``.genshi`` and the associated namespace attribute.  *This is
-   deprecated as of Bcfg2 1.4.0.*
+   deprecated as of Bcfg2 1.4.*
 2. Add the Genshi namespace to your existing XML
    bundle.
 
diff --git a/doc/server/xml-common.txt b/doc/server/xml-common.txt
index cdecf9210..c2c3f34d4 100644
--- a/doc/server/xml-common.txt
+++ b/doc/server/xml-common.txt
@@ -16,9 +16,64 @@ 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.
+tag to only apply to the given client group.  That is, they can be
+thought of as conditionals, where the following are roughly equivalent:
+
+.. code-block:: xml
+
+    <Group name="group1">
+      <Path name="/etc/foo.conf"/>
+    </Group>
+
+And::
+
+    If client is a member of group1 then
+        Manage the abstract path "/etc/foo.conf"
+
+Nested Group and Client tags are conjunctive (logical ``AND``).  For
+instance, the following are roughly equivalent:
+
+.. code-block:: xml
+
+    <Group name="group1">
+      <Client name="foo.example.com">
+        <Package name="bar"/>
+      </Client>
+      <Package name="baz"/>
+    </Group>
+
+And::
+
+    If client is a member of group1 and has hostname "foo.example.com" then
+        Manage the abstract package "bar"
+    If client is a member of group1 then
+        Manage the abstract package "baz"
+
+There is no convenient ``else``; you must specify all conditions
+explicitly.  To do this, Group and Client tags may be negated, as in:
+
+.. code-block:: xml
+
+    <Group name="group1">
+      <Service name="foo"/>
+    </Group>
+    <Group name="group1" negate="true">
+      <Service name="bar"/>
+    </Group>
+
+This is roughly equivalent to::
+
+    If client is a member of group1 then
+        Manage the abstract service "foo"
+    If client is not a member of group 1 then
+        Manage the abstract service "bar"
+
+Or, more compactly:
+
+    If client is a member of group1 then
+        Manage the abstract service "foo"
+    Else
+        Manage the abstract service "bar"
 
 .. _xml-genshi-templating:
 
diff --git a/doc/unsorted/writing_specification.txt b/doc/unsorted/writing_specification.txt
index 378a5af0e..49b11af7b 100644
--- a/doc/unsorted/writing_specification.txt
+++ b/doc/unsorted/writing_specification.txt
@@ -26,7 +26,7 @@ that a client needs the Bcfg2 package with
 
 .. code-block:: xml
 
-    <Package name=bcfg2/>
+    <Package name="bcfg2"/>
 
 but this does not explicitly identify that an RPM package version
 0.9.2 should be loaded from http://rpm.repo.server/bcfg2-0.9.2-0.1.rpm.
@@ -69,23 +69,6 @@ be installed on hosts. These entities are independent from one another,
 and can be installed individually without worrying about the impact on
 other entities.
 
-Usage of Groups in Base and Bundles
------------------------------------
-
-Groups are used by the Base and Bundles plugins for selecting
-Configuration Entity Types for inclusion in a clients abstract
-configuration.  They can be thought of as::
-
-    if client is a member of group1 then
-        assign to abstract config
-
-Nested groups are conjunctive (logical and).::
-
-    if client is a member of group1 and group2 then
-        assign to abstract config
-
-Group membership maybe negated.  See "Writing Bundles" for an example.
-
 Configuration Entity Types
 --------------------------
 
@@ -143,17 +126,6 @@ processed.  Each bundle must be defined in its own file::
     atftp.xml
     ....
 
-Groups can be used inside of bundles to differentiate which entries
-particular clients will receive. This is useful for the case where
-entries are named differently across systems; for example, one linux
-distro may have a package called openssh while another uses the name ssh.
-Configuration entries nested inside of Group elements only apply to
-clients who are a member of those groups; multiply nested groups must
-all apply.
-
-Also, groups may be negated; entries included in such groups will only
-apply to clients who are not a member of said group.
-
 When packages in a bundle are verified by the client toolset, the Paths
 included in the same bundle are taken into consideration.  That is,
 a package will not fail verification from a Bcfg2 perspective if the
@@ -267,26 +239,3 @@ A Generator can take care of a particular configuration element. Any time
 this element is requested by the client, the server dynamically generates
 it either by crunching data and creating new information or by reading
 a file off of disk and passes it down to the client for installation.
-
-Usage of Groups in Generators
------------------------------
-
-Similar to Abstract Configuration plugins, groups are used by generator
-plugins for selecting Configuration Entities for inclusion in a clients
-literal configuration.  They can be thought of as::
-
-    if client is a member of group1 then
-        assign to abstract config
-
-Nested groups are conjunctive (logical and).::
-
-    if client is a member of group1 and group2 then
-        assign to abstract config
-
-How the groups are configured is specific to the plugin, but here are
-two common methods:
-
-* xml configuration file (Pkgmgr, Rules)
-* file name encoding (Cfg, SSHBase)
-
-Details are included on each plugin's page.