doc: Migrate some more docs over from the wiki

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

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

2 files changed, 102 insertions, 17 deletions

diff --git a/doc/unsorted/bundler_examples.txt b/doc/unsorted/bundler_examples.txt
new file mode 100644
index 000000000..88db94f56
--- /dev/null
+++ b/doc/unsorted/bundler_examples.txt
@@ -0,0 +1,102 @@
+.. -*- mode: rst -*-
+
+.. _unsorted-bundler_examples:
+
+================
+Bundler 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. To add your own example, create a wiki page called Plugins/Bundler/examples/<examplename>
+
+[[TitleIndex(Plugins/Bundler/examples/)]]
+
+===========================
+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
+
+      <Bundle name='openssl'>
+         <Package name='openssl' altsrc='openssl-encap'/>
+         <Package name='openssl' altsrc='openssl-rpm'/>
+      </Bundle>
+
+  This bundle will bind data for the packages "openssl-encap" and "openssl-rpm", but will be delivered to the client with both packages named "openssl" with different types.
+
+* Finally, consider the case where there exist complicated, but completely independent specifications for the same configuration entry but different groups of clients. The following bundle will allow the use of two different TCheetah templates /etc/firewall-rules-external and /etc/firewall-rules-internal for different clients based on their group membership.
+
+  .. code-block:: xml
+
+      <Bundle name='firewall'>
+         ...
+         <Group name='conduit'>
+           <Path name='/etc/firewall-rules' altsrc='/etc/firewall-rules-external'/>
+         </Group>
+         <Group name='internal'>
+           <Path name='/etc/firewall-rules' altsrc='/etc/firewall-rules-internal'/>
+         </Group>
+      </Bundle>
+
+* Consider the case where a variety of files can be constructed by a single template (TCheetah or TGenshi). It would be possible to copy this template into the proper location for each file, but that requires proper synchronization upon modification and knowing up front what the files will all be called. Instead, the following bundle allows the use of a single template for all proper config file instances.
+
+  .. code-block:: xml
+
+      <Bundle name='netconfig'>
+        <Path name='/etc/sysconfig/network-scripts/ifcfg-eth0' altsrc='/etc/ifcfg-template'/>
+        <Path name='/etc/sysconfig/network-scripts/ifcfg-eth1' altsrc='/etc/ifcfg-template'/>
+        <Path name='/etc/sysconfig/network-scripts/ifcfg-eth2' altsrc='/etc/ifcfg-template'/>
+      </Bundle>
+
+  altsrc can be used as a parameter for any entry type, and can be used in any structure, including Bundler, Base, and SGenshi.
diff --git a/doc/unsorted/index.txt b/doc/unsorted/index.txt
index 17feb13e6..364a10407 100644
--- a/doc/unsorted/index.txt
+++ b/doc/unsorted/index.txt
@@ -16,12 +16,7 @@ list below.
 * `ManualPages`
 * `NewDynamicReports`
 * `NewDynamicReportsInstallation`
-* `News`
-* `Overview`
-* `ParanoidMode`
-* `Plugins/Account`
 * `Plugins/Actions`
-* `Plugins/Bundler/examples`
 * `Plugins/Bundler/examples/kernel.xml`
 * `Plugins/Bundler/examples/moab.xml`
 * `Plugins/Bundler/examples/nagios.xml`
@@ -29,13 +24,7 @@ list below.
 * `Plugins/Bundler/examples/snmpd.xml`
 * `Plugins/Bundler/examples/torque.xml`
 * `Plugins/Bundler/examples/yp.xml`
-* `Plugins/GroupPatterns`
-* `Plugins/Hostbase`
-* `Plugins/Metadata`
-* `Plugins/NagiosGen`
 * `Plugins/Ohai`
-* `Plugins/Probes`
-* `Plugins/Probes/examples`
 * `Plugins/Probes/examples/current-kernel`
 * `Plugins/Probes/examples/group`
 * `Plugins/Probes/examples/grub-serial-order`
@@ -43,10 +32,7 @@ list below.
 * `Plugins/Probes/examples/producttype`
 * `Plugins/Probes/examples/serial-console-speed`
 * `Plugins/Properties`
-* `Plugins/Rules`
-* `Plugins/SSHbase`
 * `Plugins/Snapshots`
-* `Plugins/TGenshi/examples`
 * `Plugins/TGenshi/examples/bcfg2_cron`
 * `Plugins/TGenshi/examples/clients.xml`
 * `Plugins/TGenshi/examples/ganglia`
@@ -62,8 +48,6 @@ list below.
 * `Publications`
 * `QuickStart2`
 * `QuickStart3`
-* `RecentChanges`
-* `RefactorClient`
 * `SchemaEvolution`
 * `SecurityDevPlan`
 * `ServerSideOverview`
@@ -74,7 +58,6 @@ list below.
 * `UpgradeTesting`
 * `UsingRcache`
 * `VimSnippetSupport`
-* `WritingClientToolDrivers`
 
 .. toctree::
    :maxdepth: 2