Documentation updates based on Sandra's suggestions

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

5 files changed, 198 insertions, 190 deletions

diff --git a/doc/architecture.xml b/doc/architecture.xml
index 7c54fca45..779b57611 100644
--- a/doc/architecture.xml
+++ b/doc/architecture.xml
@@ -110,100 +110,101 @@
 <!--       <step>foo</step> -->
 <!--     </procedure> -->
 
-    <variablelist>
-      <varlistentry>
-	<term>Probe Execution</term>
-	<listitem>
-	  <para>During the probe execution stage, the client connects to
-	    the server and downloads a series of probes to execute. These
-	    probes reveal local facts to the Bcfg2 server. For example, a
-	    probe could discover the type of video card in a system. The
-	    Bcfg2 client returns this data to the server, where it can
-	    influence the client configuration generation
-	    process. </para>
-	</listitem>
-      </varlistentry>
-      <varlistentry>
-	<term>Configuration Download and Inventory</term>
-	<listitem>
-	  <para>The Bcfg2 client now downloads a configuration
+    <orderedlist>
+      <listitem>
+	<para>Probe Execution</para>
+	<para>During the probe execution stage, the client connects to
+	  the server and downloads a series of probes to execute. These
+	  probes reveal local facts to the Bcfg2 server. For example, a
+	  probe could discover the type of video card in a system. The
+	  Bcfg2 client returns this data to the server, where it can
+	  influence the client configuration generation
+	  process. 
+	</para>
+      </listitem>
+      <listitem>
+	<para>Configuration Download and Inventory</para>
+	<para>
+	  The Bcfg2 client now downloads a configuration
 	  specification from the Bcfg2 server. The configuration
 	  describes the complete target state of the machine. That is,
 	  all aspects of client configuration should be represented in
 	  this specification. For example, all software packages and
 	  services should be represented in the configuration
-	  specification. </para>
+	  specification. 
+	</para>
 	  
-	  <para>The client now performs a local system inventory. This
+	<para>
+	  The client now performs a local system inventory. This
 	  process consists of verifying each entry present in the
 	  configuration specification. After this check is completed,
 	  heuristic checks for configuration not included in the
 	  configuration specification. We refer to this inventory
 	  process as 2-way validation, as first we verify that the
 	  client contains all configuration that is included in the
-	  specification, then we check of the client has any extra
+	  specification, then we check if the client has any extra
 	  configuration that isn't present. This provides a fairly
-	  rigorous notion of client configuration congruence.  </para>
+	  rigorous notion of client configuration congruence.  
+	</para>
 
-	  <para>Once the 2-way verification process has been
+	<para>
+	  Once the 2-way verification process has been
 	  performed, the client has built a list of all configuration
 	  entries that are out of spec. This list has two parts:
 	  specified configuration that is incorrect (or missing) and
-	  unspecified configuration that should be removed.</para>
-	</listitem>
-      </varlistentry>
-      <varlistentry>
-	<term>Configuration Update</term>
-	<listitem>
-	  <para>
-	    The client now attempts to update its configuration to
-	    match the specification. Depending on options, changes may
-	    not (or only partially) be performed. First, if extra
-	    configuration correction is enabled, extra configuration can
-	    be removed. Then the remaining changes are processed. The
-	    Bcfg2 client loops while progress is made in the correction
-	    of these incorrect configuration entries. This loop results
-	    in the client being able to accomplish all it will be able
-	    to during one execution. Once all entries are fixed, or no
-	    progress is being made, the loop terminates.
-	  </para>
+	  unspecified configuration that should be removed.
+	</para>
+      </listitem>
+      <listitem>
+	<para>Configuration Update</para>
+	<para>
+	  The client now attempts to update its configuration to
+	  match the specification. Depending on options, changes may
+	  not (or only partially) be performed. First, if extra
+	  configuration correction is enabled, extra configuration can
+	  be removed. Then the remaining changes are processed. The
+	  Bcfg2 client loops while progress is made in the correction
+	  of these incorrect configuration entries. This loop results
+	  in the client being able to accomplish all it will be able
+	  to during one execution. Once all entries are fixed, or no
+	  progress is being made, the loop terminates.
+	</para>
 	  
-	  <para>
-	    Once all configuration changes that can be performed
-	    have been, bundle dependencies are handled. Bundles
-	    groupings result in two different behaviors. Entries are
-	    assumed to be inter-dependant. To address this, the client
-	    re-verifies each entry in any bundle containing an updates
-	    configuration entry. Also, services contained in modified
-	    bundles are restarted.  
-	  </para>
-	</listitem>
-      </varlistentry>
-      <varlistentry>
-	<term>Statistics Upload</term>
-	<listitem>
-	  <para>Once the reconfiguration process has concluded, the
+	<para>
+	  Once all configuration changes that can be performed have
+	  been, bundle dependencies are handled. Bundle groupings
+	  result in two different behaviors. Contained entries are
+	  assumed to be inter-dependant. To address this, the client
+	  re-verifies each entry in any bundle containing an updates
+	  configuration entry. Also, services contained in modified
+	  bundles are restarted.
+	</para>
+      </listitem>
+      <listitem>
+	<para>Statistics Upload</para>
+	<para>
+	  Once the reconfiguration process has concluded, the
 	  client reports information back to the server about the
 	  actions it performed during the reconfiguration
 	  process. Statistics function as a detailed return code from
 	  the client. The server stores statistics
 	  information. Information included in this statistics update
-	  includes (but is not limited to):</para>
+	  includes (but is not limited to):
+	</para>
 
-	  <itemizedlist>
-	    <listitem>
-	      <para>Overall client status (clean/dirty)</para>
-	    </listitem>
-	    <listitem>
-	      <para>List of modified configuration entries</para>
-	    </listitem>
-	    <listitem>
-	      <para>List of uncorrectable configuration entries</para>
-	    </listitem>
-	  </itemizedlist>
-	</listitem>
-      </varlistentry>
-    </variablelist>
+	<itemizedlist>
+	  <listitem>
+	    <para>Overall client status (clean/dirty)</para>
+	  </listitem>
+	  <listitem>
+	    <para>List of modified configuration entries</para>
+	  </listitem>
+	  <listitem>
+	    <para>List of uncorrectable configuration entries</para>
+	  </listitem>
+	</itemizedlist>
+      </listitem>
+    </orderedlist>
 
     <section>
       <title>Architecture Abstraction</title>
@@ -213,12 +214,12 @@
 	apt-get are both supported, allowing operation of Debian,
 	Redhat, SUSE, and Mandriva systems. The client toolset is
 	specified in the configuration specification. The client merely
-	includes a series of libraries while describe how to interact
+	includes a series of libraries which describe how to interact
 	with the system tools on a particular platform.
       </para>
 
       <para>
-	Three of the libraries exist. There is the base set of
+	Three of the libraries exist. There is a base set of
 	functions, which contain definitions describing how to perform
 	POSIX operations. Support for configuration files,
 	directories, and symlinks are included here. Two other
@@ -259,9 +260,10 @@
     <para>
       The Bcfg2 server takes information from two sources when
       generating client configuration specifications. The first is a
-      pool of metadata that describes clients as members of an aspect
-      based classing system. The other is a file system repository
-      that contains mappings from metadata to literal
+      pool of metadata that describes clients as members of an
+      aspect-based classing system. That is, clients are defined in
+      terms of aspects of their behavior. The other is a file system
+      repository that contains mappings from metadata to literal
       configuration. These are combined to form the literal
       configuration specifications for clients.
     </para>
@@ -276,77 +278,71 @@
 	client. This process consists of the following steps:
       </para>
 
-      <variablelist>
-	<varlistentry>
-	  <term>Metadata Lookup</term>
-	  <listitem>
-	    <para>
-	      The server uses the client's IP address to initiate the
-	      metadata lookup. This initial metadata consists of a
-	      (profile, image) tuple. If the client already has
-	      metadata registered, then it is used. If not, then
-	      default values are used and stored for future use.
-	    </para>
-	    
-	    <para>
-	      This metadata tuple is expanded using some profile and
-	      class definitions also included in the metadata. The end
-	      result of this process is metadata consisting of
-	      hostname, profile, image, a list of classes, a list of
-	      attributes and a list of bundles.
-	    </para>
-	  </listitem>
-	</varlistentry>
-	<varlistentry>
-	  <term>Abstract Configuration Construction</term>
-	  <listitem>
-	    <para>
-	      Once the server has the client metadata, it is used to
-	      create an abstract configuration. An abstract
-	      configuration contains all of the configuration elements
-	      that will exist in the final specification without any
-	      specifics. All entries will be typed (ie the tagname
-	      will be one of Package, ConfigurationFile, Service,
-	      Symlink, or Directory) and will include a name. These
-	      configuration entries are grouped into bundles, which
-	      document installation time interdependencies.
-	    </para>
-	  </listitem>
-	</varlistentry>
-	<varlistentry>
-	  <term>Configuration Binding</term>
-	  <listitem>
-	    <para>
-	      The abstract configuration determines the structure of
-	      the client configuration, however, it doesn't contain
-	      literal configuration information. After the abstract
-	      configuration is created, each configuration entry must
-	      be bound to a client-specific value. The Bcfg2 server
-	      uses plugins to provide these client-specific bindings.
-	    </para>
+      <orderedlist>
+	<listitem>
+	  <para>Metadata Lookup</para>
+	  <para>
+	    The server uses the client's IP address to initiate the
+	    metadata lookup. This initial metadata consists of a
+	    (profile, image) tuple. If the client already has
+	    metadata registered, then it is used. If not, then
+	    default values are used and stored for future use.
+	  </para>
+	  
+	  <para>
+	    This metadata tuple is expanded using some profile and
+	    class definitions also included in the metadata. The end
+	    result of this process is metadata consisting of
+	    hostname, profile, image, a list of classes, a list of
+	    attributes and a list of bundles.
+	  </para>
+	</listitem>
+	<listitem>
+	  <para>Abstract Configuration Construction</para>
+	  <para>
+	    Once the server has the client metadata, it is used to
+	    create an abstract configuration. An abstract
+	    configuration contains all of the configuration elements
+	    that will exist in the final specification without any
+	    specifics. All entries will be typed (ie the tagname
+	    will be one of Package, ConfigurationFile, Service,
+	    Symlink, or Directory) and will include a name. These
+	    configuration entries are grouped into bundles, which
+	    document installation time interdependencies.
+	  </para>
+	</listitem>
+	<listitem>
+	  <para>Configuration Binding</para>
+	  <para>
+	    The abstract configuration determines the structure of
+	    the client configuration, however, it doesn't contain
+	    literal configuration information. After the abstract
+	    configuration is created, each configuration entry must
+	    be bound to a client-specific value. The Bcfg2 server
+	    uses plugins to provide these client-specific bindings.
+	  </para>
 
-	    <para>
-	      The Bcfg2 server core contains a dispatch table that
-	      describes which plugins can handle requests of a
-	      particular type. The responsible plugin is located
-	      for each entry. It is called, passing in the
-	      configuration entry and the client's metadata. The
-	      behavior of plugins is explicitly undefined, so as to
-	      allow maximum flexibility. The behaviors of the stock
-	      plugins are documented elsewhere in this manual.
-	    </para>
+	  <para>
+	    The Bcfg2 server core contains a dispatch table that
+	    describes which plugins can handle requests of a
+	    particular type. The responsible plugin is located
+	    for each entry. It is called, passing in the
+	    configuration entry and the client's metadata. The
+	    behavior of plugins is explicitly undefined, so as to
+	    allow maximum flexibility. The behaviors of the stock
+	    plugins are documented elsewhere in this manual.
+	  </para>
 
-	    <para>
-	      Once this binding process is completed, the server has a
-	      literal, client-specific configuration
-	      specification. This specification is complete and
-	      comprehensive; the client doesn't need to process it at
-	      all in order to use it. It also represents the totality
-	      of the configuration specified for the client.	   
-	    </para>
-	  </listitem>
-	</varlistentry>
-      </variablelist>	    
+	  <para>
+	    Once this binding process is completed, the server has a
+	    literal, client-specific configuration
+	    specification. This specification is complete and
+	    comprehensive; the client doesn't need to process it at
+	    all in order to use it. It also represents the totality
+	    of the configuration specified for the client.	   
+	  </para>
+	</listitem>
+      </orderedlist>
     </section>
   </section>
 
@@ -367,9 +363,11 @@
 	<para>
 	  A small list of configuration element types can be defined,
 	  each of which can have a set of defined semantics. This
-	  allows the server to have a well-formed notion of
+	  allows the server to have a well-formed model of
 	  client-side operations. Without a static lexicon with
-	  defined semantics, this isn't possible. 
+	  defined semantics, this isn't possible. This allows the
+	  server, for example, to record the update of a package as a
+	  coherent event. 
 	</para>
       </listitem>
       <listitem>
diff --git a/doc/deployment.xml b/doc/deployment.xml
index 1114589d3..4c4cc9bf6 100644
--- a/doc/deployment.xml
+++ b/doc/deployment.xml
@@ -87,7 +87,7 @@
     <title>An example application of bcfg2</title>
     <para>
       In my computing environment there are quite a diverse set of machines
-      and requirements for there operation. What this meant is that I needed
+      and requirements for their operation. What this meant was that I needed
       to devise a build system for machines that would allow me to easily
       customize the software and services on the machine while still being
       able to easily manage them and keep them secure. What I came up with
diff --git a/doc/manual.xml b/doc/manual.xml
index 878a104fb..6985085ad 100644
--- a/doc/manual.xml
+++ b/doc/manual.xml
@@ -63,6 +63,11 @@
 	<emphasis>fitness for a particular purpose</emphasis>.  See the
 	GNU General Public License for more details.
       </para>
+      <para>
+	Required software packages may require additional
+	terms. Please refer to these individual packages for more
+	information.
+      </para>
     </legalnotice>
 
     <revhistory>
diff --git a/doc/reports.xml b/doc/reports.xml
index 3913a9985..ce49597c9 100644
--- a/doc/reports.xml
+++ b/doc/reports.xml
@@ -40,19 +40,18 @@
       <command>StatReports</command> gets the data it reports from a
       number of sources. <filename>Metadata/clients.xml</filename>
       contains information about if a host is currently pingable or
-      not, and a mapping of short hostnames to
-      FQDNs. <command>GenerateHostInfo</command> will be run
+      not. <command>GenerateHostInfo</command> will be run
       automatically by <command>StatReports</command> if the
       <filename>Metadata/clients.xml</filename> file is older than
-      23.5 hours. This number is chosen, because it is likely an
-      administrator will recieve reports daily about the status of
-      hosts and if they had run BCFG the previous night. It is
-      possible to execute <command>GenerateHostInfo</command> to
-      update the <filename>Metadata/clients.xml</filename> file at any
-      interval via cron, but it does take some time to complete, so be
-      sure to give it a few minutes. This will only likely be of use
-      if your BCFG clients are set to update more often than nightly
-      and you would like reports after each run.
+      23.5 hours. We chose this interval due to our normal use of
+      reports; clients run bcfg2, in general, once a day after which
+      reports are delivered to administrators.  It is possible to
+      execute <command>GenerateHostInfo</command> to update the
+      <filename>Metadata/clients.xml</filename> file at any interval
+      via cron, but it does take some time to complete, so be sure to
+      give it a few minutes. This will only likely be of use if your
+      BCFG clients are set to update more often than nightly and you
+      would like reports after each run.
     </para>
     
     <para>
@@ -60,7 +59,7 @@
       <filename>statistics.xml</filename>
       file. This file is maintained by bcfgd, and is updated whenever a
       client updates, therefore is always up to date, and no
-      maintainence is required on this file.
+      maintainance is required on this file.
     </para>
     
     <para>
@@ -97,7 +96,7 @@
 	  <row><entry>Overview-Stats</entry>
 	    <entry>
 	      <para>
-		This report provides informatoin about a large number of
+		This report provides information about a large number of
 		machines and their states. It is often found to be useful
 		when the group of machines it is connected with is simply
 		All Nodes, which gives an overall outlook on your
@@ -230,10 +229,10 @@
   </example>
 
   <para>
-      Once configured correctly, just wait for the e-mail or check
-      look at the output html files with a web browser. You can run
-      <command>StatReports</command> by hand if you would like
-      in order to try it out immediately. 
+      Once configured correctly, just wait for the e-mail or view the
+      outputed html files with a web browser. You can run
+      <command>StatReports</command> by hand if you would like in
+      order to try it out immediately.
     </para>
     
     <mediaobject>
diff --git a/doc/specs.xml b/doc/specs.xml
index 4f4aa9f33..d1f61c10b 100644
--- a/doc/specs.xml
+++ b/doc/specs.xml
@@ -4,8 +4,8 @@
   <para>
     The Bcfg2 specification is a set of directives that describe how
     hosts should be configured. This information is used to generate
-    client configurations. This section describes the steps taken in 
-    during the composition of bcfg2 specifications. 
+    client configurations. This section describes the steps taken
+    during the composition of bcfg2 specifications.
   </para>
 
   <orderedlist>
@@ -50,15 +50,17 @@
     <title>Interacting with Client Groups in Bcfg2</title>
 
     <para>
-      Bcfg2 uses an aspect based classing mechanism to describe
-      configuration patterns in its specifications. The Bcfg2 metadata
+      Bcfg2 uses an aspect-based classing mechanism to describe
+      configuration patterns in its specifications. Each class
+      describes particular aspects of client configurations. The Bcfg2 metadata
       mechanism has two types of information, client metadata and
       group metadata. Client metadata describes what top level group a
-      client is associated. Its configuration is derived from a
+      client is associated with. Its configuration is derived from a
       combination of its host information and this group. Group
       definitions describe groups in terms of what bundles they
       include and other groups they include. Groups have a set of
-      properties that describe how they can be used. 
+      properties that describe how they can be used. (Starred values
+      are defaults)
     </para>
 
     <table>
@@ -81,7 +83,7 @@
 	    make configuration
 	    changes</entry><entry>(rh|debian|solaris)</entry></row>
 	  <row><entry>category</entry>
-	    <entry>A group can only contain one instance of a group of
+	    <entry>A group can only contain one instance of a group in
 	    any category. This provides the basis for representing
 	    groups which are conjugates of one another in a rigorous
 	    way. It also provides the basis for negation.</entry><entry>string</entry></row>
@@ -91,7 +93,7 @@
   </section>
 
   <para>
-    When a client's configuration is generated, its metadata is the
+    When a client's configuration is generated, its metadata is
     fetched. This includes a list of all groups recursively
     dereferenced, and all bundles included by those groups. This
     collection has already been processed using the group category
@@ -99,7 +101,7 @@
     included. This metadata is used throughout the rest of the
     configuration generation process; it defines the client's abstract
     configuration and specifies all literal contents of all
-    configuration entities. 
+    configuration entities.
   </para>
 
   <section>
@@ -269,10 +271,10 @@
       <example>
 	<title>Cfg/etc/passwd/</title>
 	<programlisting>	  $ ls
-	  :info            passwd	  passwd.G99_chiba-login
-	  passwd.H_bio-debian  passwd.H_cvstest   passwd.H_foxtrot  
-	  passwd.H_reboot  passwd.H_rudy2    passwd.G98_netserv
-	  passwd.G99_tacacs-server.cat  passwd.H_adenine</programlisting>
+	  passwd.H_adenine     passwd            passwd.G99_chiba
+	  passwd.H_bio-debian  passwd.H_cvstest  passwd.H_foxtrot  
+	  passwd.H_reboot      passwd.H_rudy2    passwd.G98_netserv
+	  passwd.G99_tacacs-server.cat           :info</programlisting>
       </example>
       
       <para>
@@ -295,13 +297,13 @@
 	format to the files used by Base and Bundler, but with a few
 	differences. First, each file has a priority. This allows the
 	same entity to be served by multiple files. The priorities can
-	be used to disambiguate in the case that multiple files serve
+	be used to break ties in the case that multiple files serve
 	data for the same package. The other difference is that
 	automatic deriviation of package information from the file
-	attribute. The Pkgmgr has a set of regexes that can split
-	package names for several formats. The filenames are used to
-	construct installation URLs, and set several important fields
-	like package name and version. 
+	attribute. The Pkgmgr has a set of regular expressions that
+	can split package names for several formats. The filenames are
+	used to construct installation URLs, and set several important
+	fields like package name and version.
       </para>
 
       <table>
@@ -319,9 +321,11 @@
 	      <entry>URL-style location of file repository (typically http)</entry></row>
 	    <row><entry>file</entry><entry>Package file name. Several
 	    other attributes (name, version, url) can be automatically
-	    defined based on regexes definied in the Pkgmgr plugin.</entry></row>
+	    defined based on regular expressions definied in the
+	    Pkgmgr plugin.</entry></row>
 	    <row><entry>simplefile</entry><entry>Package file name. No
-	    name parsing is performed, so no extra fields get set</entry></row>
+	    name parsing is performed, so no extra fields get
+	    set</entry></row>
 	  </tbody>
 	</tgroup>
       </table>
@@ -348,7 +352,8 @@
 	conditions as well. For example, the following declaration
 	turns ssh on by default, disables it if the client is a part
 	of group a, and reenables it if the client is a part of both
-	groups a and b.
+	groups a and b. Group nesting provides a conjunctive
+	function. 
       </para>
 
             <example>
@@ -436,7 +441,7 @@
 
       <orderedlist>
 	<listitem><para>
-	    In this case, the target group is global, since we want
+	    In this case, the target group is all clients, since we want
 	    this version of <filename>/etc/motd</filename>. As
 	    mentioned earlier, the global group is handled specially,
 	    so that all new clients, even newly created ones, are in it.
@@ -458,7 +463,7 @@
 	  </para></listitem>
 	<listitem><para>
 	    Since this change is globally scoped, there are not any
-	    clients that shoud not be affected.
+	    clients that should not be affected.
 	</para></listitem>
 	<listitem><para>
 	    Finally, <command>bcfg2-repo-validate</command> should be
@@ -472,9 +477,10 @@
       
       <para>
 	The goal for this example is to configure NTP for an entire
-	network. This means several things. All clients should run NTP
-	as clients. One client should run NTP as a server, and
-	ntp clients should use it instead of an external server.
+	network. This implies several things. All clients should run
+	NTP as clients. Some hosts should run NTP as a server, and
+	other hosts should use local NTP service instead of an
+	external server.
       </para>
 
       <orderedlist>