doc: Move some unsorted bundler documentation to the appropriate section

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

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

2 files changed, 88 insertions, 0 deletions

diff --git a/doc/server/plugins/structures/altsrc.txt b/doc/server/plugins/structures/altsrc.txt
new file mode 100644
index 000000000..a84e9c72e
--- /dev/null
+++ b/doc/server/plugins/structures/altsrc.txt
@@ -0,0 +1,54 @@
+.. -*- mode: rst -*-
+
+.. _server-plugins-structures-altsrc:
+
+===========================
+Fun and Profit using altsrc
+===========================
+
+Altsrc is a generic, bcfg2-server-side mechanism for performing
+configuration entry name remapping for the purpose of data binding.
+
+Use Cases
+=========
+
+* Equivalent configuration entries on different architectures with
+  different names
+* Mapping entries with the same name to different bind results in a
+  configuration (two packages with the same name but different types)
+* A single configuration entry across multiple specifications
+  (multi-plugin, or multi-repo)
+
+Examples
+========
+
+* Consider the case of /etc/hosts on linux and /etc/inet/hosts
+  on solaris. These files contain the same data in the same format,
+  and should typically be synchronized, however, exist in different
+  locations. Classically, one would need to create one entry for each in
+  Cfg or TCheetah and perform manual synchronization. Or, you could use
+  symlinks and pray. Altsrc is driven from the bundle side. For example:
+
+  .. code-block:: xml
+
+      <Bundle name='netinfo'>
+         <Group name='solaris'>
+           <Path name='/etc/inet/hosts' altsrc='/etc/hosts'/>
+         </Group>
+         <Group name='linux'>
+           <Path name='/etc/hosts'/>
+         </Group>
+      </Bundle>
+
+  In this case, when a solaris host gets the 'netinfo' bundle, it will
+  get the first Path entry, which includes an altsrc parameter. This
+  will cause the server to bind the entry as if it were a Path
+  called ``/etc/hosts``. This configuration entry is still called
+  ``/etc/inet/hosts``, and is installed as such.
+
+* On encap systems, frequently multiple packages of the same name, but
+  of different types will exist. For example, there might be an openssl
+  encap package, and an openssl rpm package. This can be dealt with
+  using a bundle like:
+
+  .. code-block:: xml
diff --git a/doc/server/plugins/structures/bundler/index.txt b/doc/server/plugins/structures/bundler/index.txt
index fc6e7244a..c5e360423 100644
--- a/doc/server/plugins/structures/bundler/index.txt
+++ b/doc/server/plugins/structures/bundler/index.txt
@@ -140,6 +140,14 @@ format can be used, as the target output format is XML.
 A Genshi template looks much like a Bundler file, except the Bundle tag
 has an additional `xmlns:py` attribute. See the examples.
 
+Altsrc
+======
+
+.. toctree::
+   :maxdepth: 1
+
+   ../altsrc
+
 Examples
 --------
 
@@ -207,6 +215,32 @@ fact be any python statement.
 Other examples
 ==============
 
+Some simple examples of Bundles can be found in the example repository
+at the locations in the following table:
+
++--------------+---------------------+
+| Bundle Name  | Description         |
++==============+=====================+
+| `atxml`_     | At bundle           |
++--------------+---------------------+
+| `bcfgxml`_   | Bcfg2 client bundle |
++--------------+---------------------+
+| `ntpxml`_    | NTP bundle          |
++--------------+---------------------+
+| `sshxml`_    | OpenSSH bundle      |
++--------------+---------------------+
+| `syslogxml`_ | syslog bundle       |
++--------------+---------------------+
+
+.. _atxml: http://trac.mcs.anl.gov/projects/bcfg2/browser/trunk/repository/Bundler/at.xml
+.. _bcfgxml: http://trac.mcs.anl.gov/projects/bcfg2/browser/trunk/repository/Bundler/bcfg.xml
+.. _ntpxml: http://trac.mcs.anl.gov/projects/bcfg2/browser/trunk/repository/Bundler/ntp.xml
+.. _sshxml: http://trac.mcs.anl.gov/projects/bcfg2/browser/trunk/repository/Bundler/ssh.xml
+.. _syslogxml: http://trac.mcs.anl.gov/projects/bcfg2/browser/trunk/repository/Bundler/syslog.xml
+
+In addition to the example repository, the following is a list of some
+more complex example Bundles.
+
 .. toctree::
    :maxdepth: 1