doc: Fixes (links/tables) from Thorsten Lockert

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

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

5 files changed, 149 insertions, 53 deletions

diff --git a/doc/plugins/generators/hostbase.txt b/doc/plugins/generators/hostbase.txt
index 20cab349a..18bda9964 100644
--- a/doc/plugins/generators/hostbase.txt
+++ b/doc/plugins/generators/hostbase.txt
@@ -21,7 +21,7 @@ Prerequisites
 
  * mysql
  * python-mysqldb
- * [http://www.djangoproject.com Django] 0.95 or greater
+ * `Django <http://www.djangoproject.com>`_
 
 Install
 -------
@@ -42,11 +42,25 @@ Create the hostbase database and a user.  For MySQL users::
            BY 'password' WITH GRANT OPTION;
     mysql> quit
 
-As of Bcfg2 v0.8.7 configuration options for Hostbase have moved to {{{/etc/bcfg2.conf}}}.  There is an example bcfg2.conf with Hostbase options located at {{{bcfg2-tarball/examples/bcfg2.confHostbase}}}.  Edit the hostbase options to correspond to the database you've initialized and copy the configuration to {{{/etc/bcfg2.conf}}}.  To finish creating the database, from your {{{path to python/Bcfg2/Server/Hostbase}}} directory, run {{{python manage.py syncdb}}} to do all table creation.
+As of Bcfg2 v0.8.7 configuration options for Hostbase have moved to
+``/etc/bcfg2.conf``.  There is an example bcfg2.conf with Hostbase
+options located at ``bcfg2-tarball/examples/bcfg2.confHostbase``.
+Edit the hostbase options to correspond to the database you've
+initialized and copy the configuration to ``/etc/bcfg2.conf``.  To
+finish creating the database, from your ``path to
+python/Bcfg2/Server/Hostbase`` directory, run ``python manage.py
+syncdb`` to do all table creation.
 
 '''Configure the web interface'''
 
-Now it's possible to explore the Hostbase web interface.  For curiosity, you can run Django's built-in development server to take a peek.  Do this by running {{{python manage.py runserver [servername:port]}}} from your Hostbase directory.  Django will default to {{{localhost:8000}}} if no server or port is entered.  Now you can explore the web interface.  Try adding a host and a zone.  You'll see that a ".rev" zone already exists.  This is where information for reverse files will go.
+Now it's possible to explore the Hostbase web interface.  For
+curiosity, you can run Django's built-in development server to take a
+peek.  Do this by running ``python manage.py runserver
+[servername:port]`` from your Hostbase directory.  Django will
+default to ``localhost:8000`` if no server or port is entered.  Now
+you can explore the web interface.  Try adding a host and a zone.
+You'll see that a ".rev" zone already exists.  This is where
+information for reverse files will go.
 
 For production, you'll want to have this configured for Apache with mod_python.  Here is an example of how to configure Hostbase as a virtual host.
 
@@ -113,11 +127,11 @@ For production, you'll want to have this configured for Apache with mod_python.
     </VirtualHost>
 
 
-You'll need to copy the contents of {{{Hostbase/media}}} into {{{/var/www/hostbase/site_media}}} in this configuration to serve the correct css files.
+You'll need to copy the contents of ``Hostbase/media`` into ``/var/www/hostbase/site_media`` in this configuration to serve the correct css files.
 
 '''Enable the Hostbase plugin'''
 
-Now that the database is accessible and there is some data in it, you can enable the Hostbase plugin on your bcfg2 server to start generating some configuration files.  All that needs to be done is to add {{{Hostbase}}} to the end of the list of generators in your bcfg2.conf file.  To see what's being generated by Hostbase, fire up a bcfg2 development server: {{{bcfg2-info}}}.  For more information on how to use the bcfg2 development server, type help at the prompt.  For our purposes, type {{{debug}}}.  This will bring you to an interactive python prompt where you can access bcfg's core data.
+Now that the database is accessible and there is some data in it, you can enable the Hostbase plugin on your bcfg2 server to start generating some configuration files.  All that needs to be done is to add ``Hostbase`` to the end of the list of generators in your bcfg2.conf file.  To see what's being generated by Hostbase, fire up a bcfg2 development server: ``bcfg2-info``.  For more information on how to use the bcfg2 development server, type help at the prompt.  For our purposes, type ``debug``.  This will bring you to an interactive python prompt where you can access bcfg's core data.
 
 .. code-block:: python
 
@@ -125,11 +139,11 @@ Now that the database is accessible and there is some data in it, you can enable
         print each
 
 
-The above loop will print out the name of each file that was generated by Hostbase.  You can see the contents of any of these by typing {{{print bcore.plugins['Hostbase'].filedata[filename]}}}.
+The above loop will print out the name of each file that was generated by Hostbase.  You can see the contents of any of these by typing ``print bcore.plugins['Hostbase'].filedata[filename]``.
 
 '''Create a bundle'''
 
-Bcfg2 needs a way to distribute the files generated by Hostbase.  We'll do this with a bundle.  In bcfg's {{{Bundler}}} directory, touch {{{hostbase.xml}}}.
+Bcfg2 needs a way to distribute the files generated by Hostbase.  We'll do this with a bundle.  In bcfg's ``Bundler`` directory, touch ``hostbase.xml``.
 
 .. code-block:: xml
 
@@ -143,12 +157,12 @@ Bcfg2 needs a way to distribute the files generated by Hostbase.  We'll do this
        <ConfigFile name='/etc/bind/xxx.xxx.xxx.rev'/>
     </Bundle>
 
-The above example is a bundle that will deliver both dhcp and dns files.  This can be trivially split into separate bundles.  It is planned that Hostbase will eventually be able to generate the list of {{{ConfigFiles}}} in its bundles automatically.
+The above example is a bundle that will deliver both dhcp and dns files.  This can be trivially split into separate bundles.  It is planned that Hostbase will eventually be able to generate the list of ``ConfigFiles`` in its bundles automatically.
 
 
 '''Do a Hostbase push'''
 
-You'll want to be able to trigger the Hostbase plugin to rebuild it's config files and push them out when data has been modified in the database.  This can be done through and XMLRPC function available from the Bcfg2 server.  From a client that is configured to receive one or more hostbase bundles, you'll need to first edit your {{{python/site-packages/Bcfg2/Client/Proxy.py}}} file.  Add {{{'Hostbase.rebuildState'}}} to the list of methods in the bcfg2 client proxy object.  The modified list is shown below:
+You'll want to be able to trigger the Hostbase plugin to rebuild it's config files and push them out when data has been modified in the database.  This can be done through and XMLRPC function available from the Bcfg2 server.  From a client that is configured to receive one or more hostbase bundles, you'll need to first edit your ``python/site-packages/Bcfg2/Client/Proxy.py`` file.  Add ``'Hostbase.rebuildState'`` to the list of methods in the bcfg2 client proxy object.  The modified list is shown below:
 
 .. code-block:: python
 
@@ -157,7 +171,7 @@ You'll want to be able to trigger the Hostbase plugin to rebuild it's config fil
         name = 'bcfg2'
         methods = ['AssertProfile', 'GetConfig', 'GetProbes', 'RecvProbeData', 'RecvStats', 'Hostbase.rebuildState']
 
-Now copy the file {{{hostbasepush.py}}} from {{{bcfg2/tools}}} in the bcfg2 source to your machine.  When this command is run as root, it triggers the Hostbase to rebuild it's files, then runs the bcfg2 client on your local machine to grab the new configs.
+Now copy the file ``hostbasepush.py`` from ``bcfg2/tools`` in the bcfg2 source to your machine.  When this command is run as root, it triggers the Hostbase to rebuild it's files, then runs the bcfg2 client on your local machine to grab the new configs.
 
 
 Authentication
@@ -169,8 +183,8 @@ Edit Django settings
 Django allows for custom authentication backends to its login procedure.  Hostbase has an NIS authentication backend that verifies a user to be in the unix group allowed to modify Hostbase.
 
 To enable this feature:
- * first edit your {{{Hostbase/settings.py}}} file and uncomment the line {{{'Hostbase.backends.NISBackend',}}} in the list of {{{AUTHENTICATION_BACKENDS}}}
- * enter the name of the unix group you want to give access to Hostbase in the {{{AUTHORIZED_GROUP}}} variable
- * in your {{{Hostbase/hostbase/views.py}}} file at the very bottom, uncomment the block(s) of lines that give you the desired level of access
+ * first edit your ``Hostbase/settings.py`` file and uncomment the line ``'Hostbase.backends.NISBackend',`` in the list of ``AUTHENTICATION_BACKENDS``
+ * enter the name of the unix group you want to give access to Hostbase in the ``AUTHORIZED_GROUP`` variable
+ * in your ``Hostbase/hostbase/views.py`` file at the very bottom, uncomment the block(s) of lines that give you the desired level of access
 
 Hostbase will now direct the user to a login page if he or she is not authorized to view a certain page.  Users should log in with their regular Unix username and password.
diff --git a/doc/plugins/generators/nagiosgen.txt b/doc/plugins/generators/nagiosgen.txt
index 99e304309..026109f21 100644
--- a/doc/plugins/generators/nagiosgen.txt
+++ b/doc/plugins/generators/nagiosgen.txt
@@ -6,7 +6,9 @@
 NagiosGen
 =========
 
-This page describes the installation and use of the [http://trac.mcs.anl.gov/projects/bcfg2/browser/trunk/bcfg2/src/lib/Server/Plugins/NagiosGen.py NagiosGen] plugin.
+This page describes the installation and use of the `NagiosGen
+<http://trac.mcs.anl.gov/projects/bcfg2/browser/trunk/bcfg2/src/lib/Server/Plugins/NagiosGen.py>`_
+plugin.
 
 Update /etc/bcfg2.conf, adding NagiosGen to plugins::
 
diff --git a/doc/plugins/generators/pkgmgr.txt b/doc/plugins/generators/pkgmgr.txt
index ddd8a0792..89e67e5b7 100644
--- a/doc/plugins/generators/pkgmgr.txt
+++ b/doc/plugins/generators/pkgmgr.txt
@@ -6,7 +6,13 @@
 Pkgmgr
 ======
 
-.. note:: See [wiki:ClientTools/RPMng#PackageTagNewStyleandAttributes RPMng#PackageTagNewStyleandAttributes].''' The way of showing the architecture of the RPM has changed. The new way is "arch". The old way is "multiarch". '''This document needs to be updated and include version of Bcfg2 where change took place.'''
+.. note::
+
+    See [wiki:ClientTools/RPMng#PackageTagNewStyleandAttributes
+    RPMng#PackageTagNewStyleandAttributes].''' The way of showing the
+    architecture of the RPM has changed. The new way is "arch". The
+    old way is "multiarch". '''This document needs to be updated and
+    include version of Bcfg2 where change took place.'''
 
 The Pkgmgr plugin resolves the Abstract Configuration Entity "Package" to a package specification that the client can use to detect, verify and install the specified package.
 
@@ -37,36 +43,75 @@ PackageList Tag
 
 The PackageList Tag may have the following attributes:
 
-|| '' '''Name''' '' || '' '''Description''' '' || '' '''Values''' '' ||
-|| priority || Sets the priority for packages in the package list.The high value wins. || Integer ||
-|| type || Package type that applies to all packages in the list. This value is inherited by all packages without an explicit type attribute. || (deb|rpm|blast|encap|sysv|portage|yum) ||
-|| uri || URI to prepend to filenames to fetch packages in this list. || String ||
-|| multiarch || Comma separated list of architectures that apply to all packages in this list.  Inherited by all package entries in the file that do not have this attribute explicitly. || String ||
-|| srcs || To be used with multiarch support.  Inherited by all Package entries without this attribute. || String ||
++-----------+-----------------------------------------------+----------------+
+| Name      | Description                                   | Values         |
++===========+===============================================+================+
+| priority  | Sets the priority for packages in the package | Integer        |
+|           | list. The higher value wins.                  |                |
++-----------+-----------------------------------------------+----------------+
+| type      | Package type that applies to all packages in  | deb|rpm|blast| |
+|           | the list. This value is inherited by all      | encap|sysv|    |
+|           | packages without an explicit type attribute.  | portage|yum    |
++-----------+-----------------------------------------------+----------------+
+| uri       | URI to prepend to filename sto fetch packages | String         |
+|           | in this list.                                 |                |
++-----------+-----------------------------------------------+----------------+
+| multiarch | Comma-separated list of architectures that    | String         |
+|           | apply to all packages in this list. Inherited |                |
+|           | by all package entries in the file that does  |                |
+|           | not have this attribute explicitly.           |                |
++-----------+-----------------------------------------------+----------------+
+| srcs      | To be used with multiarch support. Inherited  | String         |
+|           | by all Package entries without this attribute |                |
++-----------+-----------------------------------------------+----------------+
 
 Pkgmgr Group Tag
 ----------------
 
 The Pkgmgr Group Tag may have the following attributes:
 
-|| '' '''Name''' '' || '' '''Description''' '' || '' '''Values''' '' ||
-|| name  || Group Name || String ||
-|| negate || Negate group membership (is not a member of) || (True|False) ||
++--------+----------------------------------------------+------------+
+| Name   | Description                                  | Values     |
++========+==============================================+============+
+| name   | Group Name                                   | String     |
++--------+----------------------------------------------+------------+
+| negate | Negate group membership (is not a member of) | True|False |
++--------+----------------------------------------------+------------+
 
 Package Tag
 -----------
 
 The Package Tag may have the following attributes:
 
-|| '' '''Name''' '' || '' '''Description''' '' || '' '''Values''' '' ||
-|| name  || Package Name || String ||
-|| version || Package Version, version='auto' to install the latest version in the client's cache, or version='any' to verify that any version of the package is installed on the client || String ||
-|| file || Package file name.  Several other attributes (name, version) can be automatically defined based on regular expressions defined in the Pkgmgr plugin. || String ||
-|| simplefile || Package file name. No name parsing is performed, so no extra fields get set || String ||
-|| verify || verify='false' - do not do package verification || String ||
-|| multiarch || Comma separated list of the architectures of this package that should be installed. (Temporary Work around) || String ||
-|| srcs || File name creation rules for multiarch packages.  (Temporary Work around) || String ||
-|| type || Package type. (rpm, yum, apt,sysv,blast) || String ||
++------------+----------------------------------------------+------------+
+| Name       | Description                                  | Values     |
++============+==============================================+============+
+| name       | Package Name                                 | String     |
++------------+----------------------------------------------+------------+
+| version    | Package version, set to ``auto`` to install  | String     |
+|            | the latest version in the client's cache, or |            |
+|            | ``any`` to verify that any version of the    |            |
+|            | package is installed on the client           |            |
++------------+----------------------------------------------+------------+
+| file       | Package file name. Several other attributes  | String     |
+|            | (name, version) can be automatically defined |            |
+|            | based on regular expressions defined in the  |            |
+|            | Pkgmgr plugin.                               |            |
++------------+----------------------------------------------+------------+
+| simplefile | Package file name. No name parsing is        | String     |
+|            | performed, so no extra fields get set        |            |
++------------+----------------------------------------------+------------+
+| verify     | Whether package verification should be done  | True|False |
++------------+----------------------------------------------+------------+
+| multiarch  | Comma-separated list of the architectures of | String     |
+|            | this package that should be installed.       |            |
+|            | (Temporary work-around)                      |            |
++------------+----------------------------------------------+------------+
+| srcs       | File name creation rules for multiarch       | String     |
+|            | packages. (Temporary work-around)            |            |
++------------+----------------------------------------------+------------+
+| type       | Package type (rpm, yum, apt, sysv, blast)    | String     |
++------------+----------------------------------------------+------------+
 
 Client Tag
 ----------
@@ -78,9 +123,13 @@ The Client Tag is used in a PackageList for selecting the package entries to inc
 
 The Client Tag may have the following attributes:
 
-|| '' '''Name''' '' || '' '''Description''' '' || '' '''Values''' '' ||
-|| name  || Client Name || String ||
-|| negate || Negate client selection (if not client name) || (True|False) ||
++--------+----------------------------------------------+------------+
+| Name   | Description                                  | Values     |
++========+==============================================+============+
+| name   | Client Name                                  | String     |
++--------+----------------------------------------------+------------+
+| negate | Negate client selection (if not client name) | True|False |
++--------+----------------------------------------------+------------+
 
 Pkgmgr Directory
 ================
diff --git a/doc/plugins/generators/tcheetah.txt b/doc/plugins/generators/tcheetah.txt
index 4c3a8972f..829e25901 100644
--- a/doc/plugins/generators/tcheetah.txt
+++ b/doc/plugins/generators/tcheetah.txt
@@ -6,21 +6,31 @@
 TCheetah
 ========
 
-This document reflects the [source:trunk/bcfg2/src/lib/Server/Plugins/TCheetah.py TCheetah plugin] in bcfg2 0.8.4 and later.
+This document reflects the ``TCheetah`` plugin.
 
-The TCheetah plugin allows you to use the [http://www.cheetahtemplate.org/ cheetah templating system] to create files, instead of the various diff-based methods offered by the Cfg plugin. It also allows you to include the results of probes executed on the client in the created files.
+The ``TCheetah`` plugin allows you to use the `cheetah templating system
+<http://www.cheetahtemplate.org/>`_ to create files, instead of the
+various diff-based methods offered by the ``Cfg`` plugin. It also allows
+you to include the results of probes executed on the client in the
+created files.
 
-To begin, you will need to download and install the Cheetah templating engine from [http://www.cheetahtemplate.org/].  Once it is installed, you can enable it by adding `TCheetah` to the `plugins` line in `/etc/bcfg2.conf` on your Bcfg server.
-For example::
+To begin, you will need to download and install the Cheetah templating
+engine from http://www.cheetahtemplate.org/.  Once it is installed,
+you can enable it by adding ``TCheetah`` to the ``plugins`` line in
+``/etc/bcfg2.conf`` on your Bcfg server.  For example::
 
     generators = SSHbase,Cfg,Pkgmgr,Svcmgr,Rules,TCheetah
 
-The TCheetah plugin makes use of a Cfg-like directory structure located in in a `TCheetah` subdirectory of your repository, usually `/var/lib/bcfg2/TCheetah`. Each file has a directory containing two files, `template` and `info`. The template is a standard Cheetah template with two additions:
+The ``TCheetah`` plugin makes use of a ``Cfg``-like directory structure
+located in in a ``TCheetah`` subdirectory of your repository, usually
+``/var/lib/bcfg2/TCheetah``. Each file has a directory containing two
+files, ``template`` and ``info``. The template is a standard Cheetah
+template with two additions:
 
 * `self.metadata` is the client's metadata
 * `self.properties` is an xml document of unstructured data
 
-The `info` file is formatted like `:info` files from Cfg.
+The ``info`` file is formatted like ``:info`` files from Cfg.
 
 Mostly, people will want to use client metadata.
 
@@ -38,14 +48,16 @@ The following variables are available for self.metadata:
 * uuid
 * password
 
-self.metadata is an instance of the class ClientMetadata of file [http://trac.mcs.anl.gov/projects/bcfg2/browser/trunk/bcfg2/src/lib/Server/Plugins/Metadata.py Bcfg2/Server/Plugins/Metadata.py].
+self.metadata is an instance of the class ClientMetadata of file `Bcfg2/Server/Plugins/Metadata.py <http://trac.mcs.anl.gov/projects/bcfg2/browser/trunk/bcfg2/src/lib/Server/Plugins/Metadata.py>`_.
 
 self.properties
 ===============
 
-properties is a python [http://codespeak.net/lxml/ ElementTree] object, loaded from the data in /var/lib/bcfg2/etc/properties.xml.  That file should have a Properties node at its root.
+properties is a python `ElementTree <http://codespeak.net/lxml/>`_
+object, loaded from the data in ``/var/lib/bcfg2/etc/properties.xml``.
+That file should have a ``Properties`` node at its root.
 
-Example properties.xml:
+Example ``properties.xml``:
 
 .. code-block:: xml
 
diff --git a/doc/plugins/generators/tgenshi.txt b/doc/plugins/generators/tgenshi.txt
index 36b0dd8ea..bc0de8cbc 100644
--- a/doc/plugins/generators/tgenshi.txt
+++ b/doc/plugins/generators/tgenshi.txt
@@ -8,7 +8,11 @@ TGenshi
 
 This page documents the TGenshi plugin. This plugin works with version 0.4 and newer of the genshi library.
 
-The TGenshi plugin allows you to use the [http://genshi.edgewall.org Genshi] templating system to create files, instead of the various diff-based methods offered by the Cfg plugin. It also allows you to include the results of probes executed on the client in the created files.
+The TGenshi plugin allows you to use the `Genshi
+<http://genshi.edgewall.org>`_ templating system to create files,
+instead of the various diff-based methods offered by the Cfg
+plugin. It also allows you to include the results of probes executed
+on the client in the created files.
 
 To begin, you will need to download and install the Genshi templating engine.
 
@@ -16,15 +20,24 @@ To install on CentOS or RHEL 5, run::
 
     sudo yum install python-genshi
 
-Once it is installed, you can enable it by adding TGenshi to the generators line in /etc/bcfg2.conf on your Bcfg server. For example::
+Once it is installed, you can enable it by adding ``TGenshi`` to the
+generators line in ``/etc/bcfg2.conf`` on your Bcfg server. For example::
 
     generators = SSHbase,Cfg,Pkgmgr,Svcmgr,Rules,TGenshi
 
-The TGenshi plugin makes use of a Cfg-like directory structure located in in a TGenshi subdirectory of your repository, usually `/var/lib/bcfg2/TGenshi`. Each file has a directory containing two file types, template and info. Templates are named according to the genshi format used; template.txt uses the genshi text format, and template.xml uses the XML format.
+The TGenshi plugin makes use of a Cfg-like directory structure located in in a TGenshi subdirectory of your repository, usually ``/var/lib/bcfg2/TGenshi``. Each file has a directory containing two file types, template and info. Templates are named according to the genshi format used; template.txt uses the genshi text format, and template.xml uses the XML format.
 
-If used with Genshi 0.5 or later the plugin also supports the [http://genshi.edgewall.org/wiki/Documentation/0.5.x/text-templates.html new style] text template format for files named template.newtxt. One of the advantages of the new format is that it does not use # as a command delimiter, making it easier to utilize for configuration files that use # as a comment character.
+If used with Genshi 0.5 or later the plugin also supports the `new
+style
+<http://genshi.edgewall.org/wiki/Documentation/0.5.x/text-templates.html>`_
+text template format for files named template.newtxt. One of the
+advantages of the new format is that it does not use # as a command
+delimiter, making it easier to utilize for configuration files that
+use # as a comment character.
 
-Only one template format may be used per file served. Info files are identical to those used in Cfg, and info.xml files are supported.
+Only one template format may be used per file served. Info files are
+identical to those used in ``Cfg``, and ``info.xml`` files are
+supported.
 
 Inside of templates
 ===================
@@ -32,7 +45,9 @@ Inside of templates
 * metadata is the client's metadata
 * properties.properties is an xml document of unstructured data
 
-See the genshi [http://genshi.edgewall.org/wiki/Documentation documentation] for examples of Genshi syntax.
+See the genshi `documentation
+<http://genshi.edgewall.org/wiki/Documentation>`_ for examples of
+Genshi syntax.
 
 Examples
 ========
@@ -44,7 +59,6 @@ Examples: Old Genshi Syntax
 
 Genshi's web pages recommend against using this syntax, as it may disappear from future releases.
 
-
 Group Negation
 --------------
 
@@ -72,4 +86,9 @@ FAQs
 
 '''Question:''' How do I escape the $ (dollar sign) in a TGenshi text template? For example, if I want to include SVN (subversion) keywords like $Id$ or $HeadURL$ in TGenshi-generated files, or am templating a bourne shell (sh/bash) script or Makefile (make).
 
-'''Answer:''' Use $$ (double dollar sign) to output a literal $ (dollarsign) in a TGenshi text template. So instead of $Id$, you'd use $$Id$$. See also Genshi tickets [http://genshi.edgewall.org/ticket/282 #282: Document $$ escape convention] and [http://genshi.edgewall.org/ticket/283 #283: Allow for redefinition of template syntax per-file].
+'''Answer:''' Use $$ (double dollar sign) to output a literal $
+(dollarsign) in a TGenshi text template. So instead of $Id$, you'd use
+$$Id$$. See also Genshi tickets `#282: Document $$ escape convention
+<http://genshi.edgewall.org/ticket/282>`_ and `#283: Allow for
+redefinition of template syntax per-file
+<http://genshi.edgewall.org/ticket/283>`_.