doc: Clean up more documentation

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

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

1 files changed, 92 insertions, 55 deletions

diff --git a/doc/unsorted/writing_specification.txt b/doc/unsorted/writing_specification.txt
index 083065f76..9fe847298 100644
--- a/doc/unsorted/writing_specification.txt
+++ b/doc/unsorted/writing_specification.txt
@@ -12,40 +12,63 @@ Bcfg2 specifications are logically divided in to three areas:
 * Abstract
 * Literal
 
-The metadata portion of the configuration assigns a client to its profile group and to its non profle groups.  The profile group is assigned in Metadata/clients.xml and the non profile group assignments are in Metadata/groups.xml.
-
-The group memberships contained in the metadata are then used to constuct an abstract configuration for the client. An abstract configuration for a client identifies the configuration entities (packages, configuration files, service, etc) that a client requires, but it does not identify them explicitly. For instance an abstract configuration may identify that a client needs the bcfg2 package with
+The metadata portion of the configuration assigns a client to its profile
+group and to its non profle groups. The profile group is assigned
+in Metadata/clients.xml and the non profile group assignments are in
+Metadata/groups.xml.
+
+The group memberships contained in the metadata are then used to constuct
+an abstract configuration for the client. An abstract configuration for
+a client identifies the configuration entities (packages, configuration
+files, service, etc) that a client requires, but it does not identify
+them explicitly. For instance an abstract configuration may identify
+that a client needs the bcfg2 package with
 
 .. code-block:: xml
 
     <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.  The abstract configuration is defined in the xml configuration files for the Base and Bundles plugins.
+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.
+The abstract configuration is defined in the xml configuration files
+for the Base and Bundles plugins.
 
-A combination of a clients metadata (group memberships) and abstract configuration is then used to generate the clients literal configuration.  For instance the above abstract configuration entry may generate a literal configuration of
+A combination of a clients metadata (group memberships) and abstract
+configuration is then used to generate the clients literal configuration.
+For instance the above abstract configuration entry may generate a
+literal configuration of
 
 
 .. code-block:: xml
 
     <Package name='bcfg2' version='0.9.2-0.1' type='yum'/>
 
-A clients literal configuration is generated by a number of plugins that handle the different configuration entities.
+A clients literal configuration is generated by a number of plugins that
+handle the different configuration entities.
 
 .. image:: specification_overview.png
 
 Dynamic Groups
 ==============
 
-Dynamic groups are likewise complex, and are covered on their own [wiki:DynamicGroups page]
+Dynamic groups are likewise complex, and are covered on their own
+[wiki:DynamicGroups page]
 
 Abstract Configuration (Structures)
 ===================================
 
-A clients Abstract Configuration is the inventory of configuration entities that should be installed on a client.  Two plugins provide the basis for the abstract configuration, the Bundler and Base.
+A clients Abstract Configuration is the inventory of configuration
+entities that should be installed on a client. Two plugins provide the
+basis for the abstract configuration, the Bundler and Base.
 
-The plugin Bundler builds descriptions of interrelated configuration entities.  These are typically used for the representation of services, or other complex groups of entities.
+The plugin Bundler builds descriptions of interrelated configuration
+entities. These are typically used for the representation of services,
+or other complex groups of entities.
 
-The Base provides a laundry list of configuration entities that need to be installed on hosts.  These entities are independent from one another, and can be installed individually without worrying about the impact on other entities.
+The Base provides a laundry list of configuration entities that need to
+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
 -----------------------------------
@@ -67,57 +90,39 @@ Group membership maybe negated.  See "Writing Bundles" for an example.
 Configuration Entity Types
 --------------------------
 
-Entities in the abstract configuration (and correspondingly in the literal configuration) can have one of several types.  In the abstract configuration, each of these entities only has a tag and the name attribute set.
+Entities in the abstract configuration (and correspondingly in the
+literal configuration) can have one of several types. In the abstract
+configuration, each of these entities only has a tag and the name
+attribute set.
 
-The types of Configuration Entities that maybe assigned to the abstract configuration are as follows:
+The types of Configuration Entities that maybe assigned to the abstract
+configuration are as follows:
 
-|| '' '''Tag''' '' || '' '''Description''' '' ||
-|| Package || Software Package ||
-|| !ConfigFile || Configuration File ||
-|| Service  || Persistent system services and daemons ||
-|| Directory || File system Directories ||
-|| !SymLink  || Symbolic links ||
-|| Permissions || The permissions (not contents) of a POSIX path ||
-|| Action || Actions to be performed as part of a bundle installation ||
+.. include:: ../server/configurationentries.txt
 
 An example of each entity type is below.
 
 .. code-block:: xml
 
     <Package name='bcfg2'/>
-    <ConfigFile name='/etc/bcfg2.conf'/>
+    <Path name='/etc/bcfg2.conf'/>
     <Service name='ntpd'/>
-    <Directory name='/var/tmp'/>
-    <SymLink name='/dev/MAKEDEV'/>
-    <Permissions name='/etc/passwd'/>
     <Action name='action_name'/>
 
-Configuration Entity Name Attribute
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-With the exception of the Action Entity type, the value of the configuration entity name attribute is not arbitary.  It must map to entities of the same type in the Literal Configuration, which in turn map to physical entities on the client.
-
-For the most part the physical entity being mapped to is intuitive and are listed below.
-
-|| '' '''Tag''' '' || '' '''Description''' '' ||
-|| Package || name of the software package ||
-|| !ConfigFile || Full absolute path of the configuration file ||
-|| Service  || Name of the init script for the service which may not be that same as the name of the daemon started or the package name ||
-|| Directory || Full absolute path of the directories ||
-|| !SymLink  || Full absolute path of the symbolic linkss ||
-|| Permissions || Full absolute path of the file or directory ||
-|| Action || Arbitary name ||
-
 Writing Bundles
 ---------------
 
-Bundles consist of a set of configuration entities.  These entities are grouped together due to a configuration-time interdependency.  Basic services tend to be the simplest example of these.  They normally consist of
+Bundles consist of a set of configuration entities. These entities
+are grouped together due to a configuration-time interdependency.
+Basic services tend to be the simplest example of these. They normally
+consist of
 
 * some software package(s)
 * some configuration files
 * an indication that some service should be activated
 
-If any of these pieces are installed or updated, all should be rechecked and any associated services should be restarted.
+If any of these pieces are installed or updated, all should be rechecked
+and any associated services should be restarted.
 
 All files in the Bundles/ subdirectory of the repository are processed.
 Each bundle must be defined in its own file and the filename must be the
@@ -142,11 +147,22 @@ same as the bundle name with a .xml suffix.::
     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.
+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.
+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 !ConfigFiles included in the same bundle are taken into consideration.  That is, a package will not fail verification from a bcfg2 perspective if the package verification only failed because of configuration files that are defined in the same bundle.
+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
+package verification only failed because of configuration files that
+are defined in the same bundle.
 
 The following is an annotated copy of a bundle:
 
@@ -180,7 +196,15 @@ The following is an annotated copy of a bundle:
       </Group>
     </Bundle>
 
-In this bundle, most of the entries are common to all systems.  Clients in group "deb" get one extra package and service, while clients in group "rpm" get two extra packages and an extra service.  In addition, clients in group "fedora" and group "rpm" get one extra package entries, unless they are not in the fc4 group, in which case, they get an extra package.  Notice that this file doesn't describe which versions of these entries that clients should get, only that they should get them.  (Admittedly, this example is slightly contrived, but demonstrates how group entries can be used in bundles)
+In this bundle, most of the entries are common to all systems. Clients
+in group "deb" get one extra package and service, while clients in group
+"rpm" get two extra packages and an extra service. In addition, clients
+in group "fedora" and group "rpm" get one extra package entries, unless
+they are not in the fc4 group, in which case, they get an extra package.
+Notice that this file doesn't describe which versions of these entries
+that clients should get, only that they should get them. (Admittedly,
+this example is slightly contrived, but demonstrates how group entries
+can be used in bundles)
 
 || '' '''Group ''' '' || '' '''Entry ''' '' ||
 || all  || /etc/ssh/ssh_host_dsa_key  ||
@@ -211,12 +235,14 @@ The Bundle Tag has the following possible attributes:
 || origin || URL of master version (for common repo) || String ||
 || revision || Master version control revision || String ||
 
-As mentioned above the Configuration Entity Tags may only have the name attribute in Bundle definitions.
+As mentioned above the Configuration Entity Tags may only have the name
+attribute in Bundle definitions.
 
 Abstract Group Tag
 ^^^^^^^^^^^^^^^^^^
 
-In the Abstract Configuration plugins (Base and Bundle) the Group Tag may have the following attributes:
+In the Abstract Configuration plugins (Base and Bundle) the Group Tag
+may have the following attributes:
 
 || '' '''Name''' '' || '' '''Description''' '' || '' '''Values''' '' ||
 || name || Name of group. || String ||
@@ -260,32 +286,42 @@ configuration.::
         </Group>
     </Base>
 
-The format of the Base files are similar to those used by the Bundler.  The majority of the elements are usually Packages, but !ConfigFiles, Directories, Services, Permissions,  and !SymLinks may all be defined.  A partial example is below:
+The format of the Base files are similar to those used by the Bundler.
+The majority of the elements are usually Packages, but Paths of any type
+may all be defined. A partial example is below:
 
 Base Tag
 ^^^^^^^^
 
 The Base Tag has no attributes
 
-As mentioned above the Configuration Entity Tags contained in a Base definition may only have the name attribute in Base definitions.
+As mentioned above the Configuration Entity Tags contained in a Base
+definition may only have the name attribute in Base definitions.
 
 Abstract Group Tag
 ^^^^^^^^^^^^^^^^^^
 
-In the Abstract Configuration plugins (Base and Bundle) the Group Tag may have the following attributes:
+In the Abstract Configuration plugins (Base and Bundle) the Group Tag
+may have the following attributes:
 
 || '' '''Name''' '' || '' '''Description''' '' || '' '''Values''' '' ||
 || name || Name of group. || String ||
 || negate || Negate the group association (is not a member of) || (True|False*) ||
 
-An abstract group may contain any of the Configuration Entity types and other groups.
+An abstract group may contain any of the Configuration Entity types and
+other groups.
 
 Literal Configuration (Generators)
 ==================================
 
-A Generator is a bcfg2 piece of code that is run to generate the literal configuration for a host using a combination of the hosts metadata and abstract configuration.
+A Generator is a bcfg2 piece of code that is run to generate the literal
+configuration for a host using a combination of the hosts metadata and
+abstract configuration.
 
-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.
+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
 -----------------------------
@@ -302,7 +338,8 @@ 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:
+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, TCheetah, SSHBase)