More doc updates -- I moved the doc headers into separate files, rather than having them in the code

git-svn-id: https://reductivelabs.com/svn/puppet/trunk@1845 980ebf18-57e1-0310-9a29-db15c13687c0

9 files changed, 191 insertions, 33 deletions

diff --git a/documentation/Rakefile b/documentation/Rakefile
index 3da422e6d..640a7cf5d 100644
--- a/documentation/Rakefile
+++ b/documentation/Rakefile
@@ -36,7 +36,22 @@ docs = %w{configref typedocs reports functions}
 
 docs.each do |doc|
     task doc do
-        sh %{puppetdoc --mode %s > documentation/reference/%s.page} % [doc, doc]
+        docs = %x{puppetdoc --mode #{doc}}
+
+        header = "documentation/reference/%s.header" % doc
+        if FileTest.exists?(header)
+            headertext = File.read(header)
+        else
+            headertext = ""
+        end
+
+        file = "documentation/reference/%s.page" % doc
+
+        puts "Creating %s" % file
+        File.open(file, "w") do |f|
+            f.puts headertext
+            f.puts docs
+        end
     end
 end
 
diff --git a/documentation/documentation/reference/configref.header b/documentation/documentation/reference/configref.header
new file mode 100644
index 000000000..854eb1d99
--- /dev/null
+++ b/documentation/documentation/reference/configref.header
@@ -0,0 +1,94 @@
+---
+inMenu: true
+title: Configuration Reference
+orderInfo: 40
+---
+# Puppet Configuration Reference
+
+## Specifying Configuration Parameters
+
+Every Puppet executable (with the exception of ``puppetdoc``) accepts all of
+the arguments below, but not all of the arguments make sense for every executable.
+Each argument has a section listed with it in parentheses; often, that section
+will map to an executable (e.g., ``puppetd``), in which case it probably only
+makes sense for that one executable.  If ``puppet`` is listed as the section,
+it is most likely an option that is valid for everyone.
+
+This will not always be the case.  I have tried to be as thorough as possible
+in the descriptions of the arguments, so it should be obvious whether an
+argument is appropriate or not.
+
+These arguments can be supplied to the executables either as command-line 
+arugments or in the configuration file for the appropriate executable.  For 
+instance, the command-line invocation below would set the configuration directory
+to /private/puppet
+  
+    $ puppetd --confdir=/private/puppet
+  
+Note that boolean options are turned on and off with a slightly different syntax
+on the command line:
+
+    $ puppetd --storeconfigs
+      
+    $ puppetd --no-storeconfigs
+
+The invocations above will enable and disable, respectively, the storage of 
+the client configuration.
+
+As mentioned above, the configuration parameters can also be stored in a 
+configuration file located in the configuration directory (`/etc/puppet` 
+by default).  The file is named for the executable it is intended for, for
+example `/etc/puppetd.conf` is the configuration file for `puppetd`.
+
+The file, which follows INI-style formatting, should contain a bracketed
+heading named for the executable, followed by pairs of parameters with their
+values.  Here is an example of a very simple `puppetd.conf` file:
+
+    [puppetd]
+        confdir = /private/puppet
+        storeconfigs = true
+    
+Note that boolean parameters must be explicitly specified as `true` or
+`false` as seen above.
+
+If you're starting out with a fresh configuration, you may wish to let
+the executable generate a template configuration file for you by invoking
+the executable in question with the `--genconfig` command.  The executable
+will print a template configuration to standard output, which can be
+redirected to a file like so:
+
+    $ puppetd --genconfig > /etc/puppet/puppetd.conf
+  
+Note that this invocation will "clobber" (throw away) the contents of any
+pre-existing `puppetd.conf` file, so make a backup of your present config
+if it contains valuable information.
+  
+Like the `--genconfig` argument, the executables also accept a `--genmanifest`
+argument, which will generate a manifest that can be used to manage all of 
+Puppet's directories and files and prints it to standard output.  This can
+likewise be redirected to a file:
+
+    $ puppetd --genmanifest > /etc/puppet/manifests/site.pp
+
+Puppet can also create user and group accounts for itself (one `puppet` group
+and one `puppet` user) if it is invoked as `root` with the `--mkusers` argument:
+
+    $ puppetd --mkusers
+  
+## Signals
+
+The `puppetd` and `puppetmasterd` executables catch some signals for special 
+handling.  Both daemons catch (`SIGHUP`), which forces the server to restart 
+tself.  Predictably, interrupt and terminate (`SIGINT` and `SIGHUP`) will shut 
+down the server, whether it be an instance of `puppetd` or `puppetmasterd`.
+
+Sending the `SIGUSR1` signal to an instance of `puppetd` will cause it to 
+immediately begin a new configuration transaction with the server.  This 
+signal has no effect on `puppetmasterd`.
+
+
+## Configuration Parameter Reference
+
+Below is a list of all documented parameters.  Any default values are in ``block type`` at the end of the description.
+
+
diff --git a/documentation/documentation/reference/configref.page b/documentation/documentation/reference/configref.page
index 4f7ba3dd6..bb31152e5 100644
--- a/documentation/documentation/reference/configref.page
+++ b/documentation/documentation/reference/configref.page
@@ -91,6 +91,7 @@ signal has no effect on `puppetmasterd`.
 
 Below is a list of all documented parameters.  Any default values are in ``block type`` at the end of the description.
 
+
 #### <a name="authconfig">authconfig</a> (<em>puppet</em>)
 
 The configuration file that defines the rights to the different namespaces and methods.  This can be used as a coarse-grained authorization system for both ``puppetd`` and ``puppetmasterd``.  ``/etc/puppet/namespaceauth.conf``
@@ -508,4 +509,4 @@ Where Puppet stores dynamic and growing data.  ``/var/puppet``
 ----------------
 
 
-*This page autogenerated on Thu Nov 09 14:32:06 CST 2006*
+*This page autogenerated on Thu Nov 09 15:19:05 CST 2006*
diff --git a/documentation/documentation/reference/functions.header b/documentation/documentation/reference/functions.header
new file mode 100644
index 000000000..9c58cd36a
--- /dev/null
+++ b/documentation/documentation/reference/functions.header
@@ -0,0 +1,15 @@
+---
+inMenu: true
+title: Function Reference
+orderInfo: 40 
+---
+        
+There are two types of functions in Puppet: Statements and rvalues.
+Statements stand on their own and do not return arguments; they are used for
+performing stand-alone work like importing.  Rvalues return values and can
+only be used in a statement requiring a value, such as an assignment or a case
+statement. 
+
+Here are the functions available in Puppet:
+                        
+
diff --git a/documentation/documentation/reference/functions.page b/documentation/documentation/reference/functions.page
index 63e664390..aaa6c3a10 100644
--- a/documentation/documentation/reference/functions.page
+++ b/documentation/documentation/reference/functions.page
@@ -1,48 +1,51 @@
+---
 inMenu: true
 title: Function Reference
-orderInfo: 40
-
+orderInfo: 40 
+---
+        
 There are two types of functions in Puppet: Statements and rvalues.
 Statements stand on their own and do not return arguments; they are used for
 performing stand-alone work like importing.  Rvalues return values and can
 only be used in a statement requiring a value, such as an assignment or a case
-statement.
+statement. 
 
 Here are the functions available in Puppet:
+                        
 
-* **alert** *statement*:  Log a message on the server at level alert.
+* **alert** (*statement*):  Log a message on the server at level alert.
 
-* **crit** *statement*:  Log a message on the server at level crit.
+* **crit** (*statement*):  Log a message on the server at level crit.
 
-* **debug** *statement*:  Log a message on the server at level debug.
+* **debug** (*statement*):  Log a message on the server at level debug.
 
-* **defined** *rvalue*:  Determine whether a given type is defined, either as a native type or a defined type.
+* **defined** (*rvalue*):  Determine whether a given type is defined, either as a native type or a defined type.
 
-* **emerg** *statement*:  Log a message on the server at level emerg.
+* **emerg** (*statement*):  Log a message on the server at level emerg.
 
-* **err** *statement*:  Log a message on the server at level err.
+* **err** (*statement*):  Log a message on the server at level err.
 
-* **fail** *statement*:  Fail with a parse error.
+* **fail** (*statement*):  Fail with a parse error.
 
-* **include** *statement*:  Evaluate one or more classes.
+* **include** (*statement*):  Evaluate one or more classes.
 
-* **info** *statement*:  Log a message on the server at level info.
+* **info** (*statement*):  Log a message on the server at level info.
 
-* **notice** *statement*:  Log a message on the server at level notice.
+* **notice** (*statement*):  Log a message on the server at level notice.
 
-* **realize** *statement*:  Make a virtual object real.  This is useful when you want to know the name of the virtual object and don't want to bother with a full collection.  It is slightly faster than a collection, and, of course, is a bit shorter.  You must pass the object using a reference; e.g.: ``realize User[luke]``.
+* **realize** (*statement*):  Make a virtual object real.  This is useful when you want to know the name of the virtual object and don't want to bother with a full collection.  It is slightly faster than a collection, and, of course, is a bit shorter.  You must pass the object using a reference; e.g.: ``realize User[luke]``.
 
-* **tag** *statement*:  Add the specified tags to the containing class or definition.  All contained objects will then acquire that tag, also. 
+* **tag** (*statement*):  Add the specified tags to the containing class or definition.  All contained objects will then acquire that tag, also. 
 
-* **tagged** *rvalue*:  A boolean function that tells you whether the current container is tagged with the specified tags. The tags are ANDed, so thta all of the specified tags must be included for the function to return true.
+* **tagged** (*rvalue*):  A boolean function that tells you whether the current container is tagged with the specified tags. The tags are ANDed, so thta all of the specified tags must be included for the function to return true.
 
-* **template** *rvalue*:  Evaluate a template and return its value.  See [the templating docs](../advanced/templating.html) for more information.
+* **template** (*rvalue*):  Evaluate a template and return its value.  See [the templating docs](../advanced/templating.html) for more information.
 
-* **warning** *statement*:  Log a message on the server at level warning.
+* **warning** (*statement*):  Log a message on the server at level warning.
 
 
 
 ----------------
 
 
-*This page autogenerated on Thu Nov 09 14:32:10 CST 2006*
+*This page autogenerated on Thu Nov 09 15:19:09 CST 2006*
diff --git a/documentation/documentation/reference/reports.header b/documentation/documentation/reference/reports.header
new file mode 100644
index 000000000..f919a1aca
--- /dev/null
+++ b/documentation/documentation/reference/reports.header
@@ -0,0 +1,19 @@
+---
+inMenu: true
+title: Reports Reference
+orderInfo: 40 
+---
+
+Puppet clients can report back to the server after each
+transaction.  This transaction report is sent as a YAML dump and includes every
+log message that was generated during the transaction along with as many metrics
+as Puppet knows how to collect.
+
+Currently, clients default to not sending in reports; you can enable reporting
+by setting the ``report`` parameter to true.
+
+To use a report, set the ``reports`` parameter on the server; multiple
+reports must be comma-separated.
+
+Puppet provides multiple report handlers that will process client reports:
+
diff --git a/documentation/documentation/reference/reports.page b/documentation/documentation/reference/reports.page
index 9493e1e50..2465e436b 100644
--- a/documentation/documentation/reference/reports.page
+++ b/documentation/documentation/reference/reports.page
@@ -1,3 +1,9 @@
+---
+inMenu: true
+title: Reports Reference
+orderInfo: 40 
+---
+
 Puppet clients can report back to the server after each
 transaction.  This transaction report is sent as a YAML dump and includes every
 log message that was generated during the transaction along with as many metrics
@@ -68,4 +74,4 @@ webservers that are not also from mailservers to ``httpadmins@domain.com``.
 ----------------
 
 
-*This page autogenerated on Thu Nov 09 14:47:22 CST 2006*
+*This page autogenerated on Thu Nov 09 15:19:08 CST 2006*
diff --git a/documentation/documentation/reference/typedocs.header b/documentation/documentation/reference/typedocs.header
new file mode 100644
index 000000000..69fabd07c
--- /dev/null
+++ b/documentation/documentation/reference/typedocs.header
@@ -0,0 +1,7 @@
+---
+inMenu: true
+title: Type Reference
+orderInfo: 40
+---
+# Type Reference
+
diff --git a/documentation/documentation/reference/typedocs.page b/documentation/documentation/reference/typedocs.page
index 29d1fd03e..f1d3c178b 100644
--- a/documentation/documentation/reference/typedocs.page
+++ b/documentation/documentation/reference/typedocs.page
@@ -5,8 +5,6 @@ orderInfo: 40
 ---
 # Type Reference
 
-
-    
 ## Table of Contents
 1. <a href='#meta-parameters'>Meta-Parameters</a>
 1. <a href='#cron'>Cron</a>
@@ -559,7 +557,7 @@ for file copying, but it can also be used to monitor files somewhat
 like Tripwire without managing the file contents in any way.  You can
 specify that a file's checksum should be monitored and then subscribe to
 the file from another object and receive events to signify
-checksum changes, for instance.  Valid values are ``timestamp``, ``nosum``, ``md5``, ``mtime``, ``time``, ``md5lite``.  Values can also match ``(?-mix:^\{md5|md5lite|timestamp|mtime|time\})``.
+checksum changes, for instance.  Valid values are ``nosum``, ``md5``, ``mtime``, ``md5lite``, ``time``, ``timestamp``.  Values can also match ``(?-mix:^\{md5|md5lite|timestamp|mtime|time\})``.
 
 #### content
 Specify the contents of a file as a string.  Newlines, tabs, and
@@ -612,7 +610,7 @@ something similar.
 You can also make recursive symlinks, which will create a
 directory structure that maps to the target directory,
 with directories corresponding to each directory
-and links corresponding to each file.  Valid values are ``link``, ``absent`` (also called ``false``), ``directory``, ``present``, ``file``.  Values can also match ``(?-mix:.)``.
+and links corresponding to each file.  Valid values are ``link``, ``absent`` (also called ``false``), ``present``, ``directory``, ``file``.  Values can also match ``(?-mix:.)``.
 
 #### force
 Force the file operation.  Currently only used when replacing
@@ -811,7 +809,7 @@ appropriate provider for your platform.  Available providers are:
 
 * **groupadd**: Group management via ``groupadd`` and its ilk.  The default
         for most platforms    Required binaries: ``groupadd``, ``groupdel``, ``groupmod``.
-* **netinfo**: Group management using NetInfo.  Default for ``operatingsystem`` == ``darwin``.    Required binaries: ``nireport``, ``niutil``.
+* **netinfo**: Group management using NetInfo.  Default for ``operatingsystem`` == ``darwin``.    Required binaries: ``niutil``, ``nireport``.
 * **pw**: Group management via ``pw``.  Only works on FreeBSD.  Default for ``operatingsystem`` == ``freebsd``.    Required binaries: ``/usr/sbin/pw``.
 
 
@@ -1030,8 +1028,8 @@ appropriate provider for your platform.  Available providers are:
 * **apple**: Package management based on OS X's builtin packaging system.  This is
         essentially the simplest and least functional package system in existence --
         it only supports installation; no deletion or upgrades.  Default for ``operatingsystem`` == ``darwin``.    Required binaries: ``/usr/sbin/installer``.
-* **apt**: Package management via ``apt-get``.  Default for ``operatingsystem`` == ``debian``.    Required binaries: ``/usr/bin/apt-cache``, ``/usr/bin/debconf-set-selections``, ``/usr/bin/apt-get``.
-* **aptitude**: Package management via ``aptitude``.    Required binaries: ``/usr/bin/apt-cache``, ``/usr/bin/aptitude``.
+* **apt**: Package management via ``apt-get``.  Default for ``operatingsystem`` == ``debian``.    Required binaries: ``/usr/bin/debconf-set-selections``, ``/usr/bin/apt-get``, ``/usr/bin/apt-cache``.
+* **aptitude**: Package management via ``aptitude``.    Required binaries: ``/usr/bin/aptitude``, ``/usr/bin/apt-cache``.
 * **blastwave**: Package management using Blastwave.org's ``pkg-get`` command on Solaris.    Required binaries: ``pkg-get``.
 * **darwinport**: Package management using DarwinPorts on OS X.    Required binaries: ``/opt/local/bin/port``.
 * **dpkg**: Package management via ``dpkg``.  Because this only uses ``dpkg``
@@ -1278,7 +1276,7 @@ provided.
 Whether a service should be enabled to start at boot.
 This state behaves quite differently depending on the platform;
 wherever possible, it relies on local tools to enable or disable
-a given service.  *true*/*false*/*runlevels*  Valid values are ``true``, ``false``.
+a given service.  *true*/*false*/*runlevels*  Valid values are ``false``, ``true``.
 
 #### ensure
 Whether a service should be running.  **true**/*false*  Valid values are ``running`` (also called ``true``), ``stopped`` (also called ``false``).
@@ -1583,7 +1581,7 @@ The specific backend for provider to use. You will
 seldom need to specify this -- Puppet will usually discover the
 appropriate provider for your platform.  Available providers are:
 
-* **netinfo**: User management in NetInfo.  Default for ``operatingsystem`` == ``darwin``.    Required binaries: ``nireport``, ``niutil``.
+* **netinfo**: User management in NetInfo.  Default for ``operatingsystem`` == ``darwin``.    Required binaries: ``niutil``, ``nireport``.
 * **pw**: User management via ``pw`` on FreeBSD.  Default for ``operatingsystem`` == ``freebsd``.    Required binaries: ``pw``.
 * **useradd**: User management via ``useradd`` and its ilk.    Required binaries: ``useradd``, ``userdel``, ``usermod``.
 
@@ -1701,7 +1699,7 @@ Solaris zones.
 
 ### Zone Parameters
 #### autoboot
-Whether the zone should automatically boot.  Valid values are ``true``, ``false``.
+Whether the zone should automatically boot.  Valid values are ``false``, ``true``.
 
 #### ensure
 The running state of the zone.  The valid states directly reflect
@@ -1782,4 +1780,4 @@ so Puppet only checks for it at that time.
 ----------------
 
 
-*This page autogenerated on Thu Nov 09 14:43:00 CST 2006*
+*This page autogenerated on Thu Nov 09 15:19:07 CST 2006*