updating docs to work with webgen

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

17 files changed, 725 insertions, 752 deletions

diff --git a/documentation/Rakefile b/documentation/Rakefile
index 117c3052f..c87fd468e 100644
--- a/documentation/Rakefile
+++ b/documentation/Rakefile
@@ -1,3 +1,5 @@
+# vim: syntax=ruby
+
 htmlfiles = []
 
 CLEAN = []
diff --git a/documentation/big-picture.rst b/documentation/big-picture.page
index f4965082c..baba0824f 100644
--- a/documentation/big-picture.rst
+++ b/documentation/big-picture.page
@@ -1,5 +1,5 @@
-Big picture
-===========
+# Big picture
+
 Puppet is a **declarative language** for expressing system configuration, a
 **client and server** for distributing it, and a **library** for realizing the
 configuration. 
@@ -14,11 +14,10 @@ used to handling, like ``service`` and ``node``, and Puppet is responsible for
 either achieving the configuration or providing the user enough information to
 fix any encountered problems.
 
-This document is a supplement to the Introduction_ and it is assumed that
+This document is a supplement to the [Introduction](introduction.html) and it is assumed that
 readers are familiar with the contents of that document.
 
-Less Detail, More Information
-=============================
+# Less Detail, More Information
 
 A correct configuration must obviously provide the appropriate details, but a
 configuration tool should understand that the details are generally the easy
@@ -30,10 +29,10 @@ the foreground.
 
 For instance, take a typical Apache web server deployment.  Puppet allows one
 to encapsulate all of the primitives necessary for successful deployment into
-one reusable object, and that object can even be abstractedt to support
+one reusable object, and that object can even be abstracted to support
 multiple apache versions.  Here's how a simple apache definition might look
 for a Debian server (Debian uses ``apache`` for 1.x versions and ``apache2``
-for 2.x versions)::
+for 2.x versions):
 
     define apache(version, conf, user, group) {
         # abstract across apache1 and apache2
@@ -62,7 +61,7 @@ for 2.x versions)::
 Now, with this configuration, one can easily set multiple servers up to run
 different versions of apache.  The key benefit here is that the information
 necessary to run apache correctly is separated from the decision to do so on a
-given host.  For example::
+given host.  For example:
 
     # import our apache definition file
     import "apache"
@@ -77,7 +76,7 @@ given host.  For example::
         }
     }
 
-    node server 2 {
+    node server2 {
         # use a config that we pull from elsewhere
         apache {
             version => 2,
@@ -95,95 +94,34 @@ running and that it should be restarted if the configuration file changes),
 then that detail does not have to be specified every time an Apache instance
 is configured.
 
-Describing Configuration
-========================
+# Describing Configuration
 
 Puppet's declarative language separates the "what" of the configuration from
-the "how".
-
-Language Example: Class Hierarchy using Inherit
------------------------------------------------
+the "how".  The "how" is pushed into the library, which generally provides the
+ability to manage a given entity on multiple platforms, isolating the Puppet
+user from platform details.
 
-A Site Configuration is made of high level declarative statements about policy.
-A Policy of having all hosts monitored (to ensure uptime, report
-performance/load, or audit log files) can be implmented with inheritance (as
-with "server_host") or with composition (as in workstation).::
+### Language Example: Class Hierarchy Using Inherit
 
-    define monitored_component (report_server) {
-        #(registers w/ monitoring software)....
-    }
-    class monitored_host {
-         $report_server = "somehost.domain.com"
-         monitored_component { "mon_comp" : 
-                 report_server => $report_server 
-         }
-    }
-    class server_host inherits monitored_host {
-         #(other definitions/classes specific to servers)....
-    }
-    #... or ...
-    class workstation_host {
-         $alt_report_server = "someotherhost.domain.com"
-         monitored_component ( "workstation_mon" :  
-                     report_server => $alt_report_server
-         #(other definitions specific to workstations)....
-    }
+Inheritance can be used to override default values defined in base classes::
 
-Language Example: Type Composition using Function Definitions
--------------------------------------------------------------
-
-The following example describes the services (objects) and relationships
-(definitions) for a simple web site.::
-
-    define webserver (port, htmldoc, default-config-file) {
-        #...(configures httpd to serve files at path "htmldoc")...
-    }
-    define firewall_port (external-port, internal-port) {
-        #...(stores the port aspects for a "firewall" object to
-        #later build a firewall config)...
+    class base {
+        file { "/etc/sudoers":
+            owner => root,
+            group => root,
+            mode => 440
+        }
     }
 
-By defining the Webserver/Firewall objects, the details of behavior not
-relevant to a simple website (such as the default configuration of a httpd
-server or the process of registering the firewall port aspect can be enclosed
-in an abstraction.
-
-One model for a Simple website defines the relationship between two components:
-a webserver to respond to the HTTP requests, and a firewall to limit traffic
-and protect the webserver host. They require two parameters: The external port
-to receive HTTP requests, and the collection of files that the webserver will
-offer as webpages.::
-
-    define simple_web_site_service (external-port,data-filepath) {
-        $internal-port = 80
-        $default_config_file = "...httpd.conf"
-        webserver { "simple_webserver" :
-              port => $internal-port
-              htmldoc => $data-filepath,
-              default-config-file => $default-config-file }
-
-        firewall_port { "simple_firewall_port" : 
-              external-port => $external-port,
-              internal-port => $internal-port }
-
-        requires ( simple_webserver, simple_firewall_port )
+    # FreeBSD has a "wheel" group instead of a "root" group
+    class freebsd inherits base {
+        file { "/etc/sudoers":
+            group => wheel,
+        }
+        
     }
 
-This definition of the service declares the components as related objects. The
-Web Site Service requires a webserver and an open port on the firewall
-component.
-
-As this configuration is deployed to different operating systems (RedHat linux,
-solaris, etc.), the appropriate webserver, web-data, firewall object class can
-be called by the Puppet framework. The lower level details of how each OS
-specific component implements its configuration is separate from site policy. 
-
-You can read more about the Puppet language in the Introduction_.  (Add link to
-user manual, when it's written)
-
-
-Distributing Configuration
-==========================
+# Distributing Configuration
 
 The Puppet framework Library consists of a client and server. 
 
@@ -211,13 +149,12 @@ You can read more about the Puppet language in the Introduction_.  (Add link to
 user manual, when it's written)
 
 
-Realizing the Configuration
-===========================
+# Realizing the Configuration
 
 The Puppet Client Library contains the component knowledge of how to reach
 desired states and configurations for several objects: File, Package, etc.
 
-Example: Puppet Client, library::
+Example: Puppet Client, library:
 
  ...todo: file: transfer, mode, ownership...
 
@@ -231,12 +168,3 @@ component is entirely responsible for implementing its own configuration.
 Much as database applications abstract the mechanics of storing, indexing, and
 searching their data, a component ideally should abstract the specifics of how
 to store, confirm, and implement its requested configuration.
-
-To learn more, review other Puppet Documentation_ and sample Configurations_.
-
-
-.. _Introduction: intro
-
-.. _Documentation: /projects/puppet/documentation/
-
-.. _Configurations: /svn/manifests/
diff --git a/documentation/creating-a-puppet-type.rst b/documentation/creating-a-puppet-type.page
index bcc854711..02f0116a6 100644
--- a/documentation/creating-a-puppet-type.rst
+++ b/documentation/creating-a-puppet-type.page
@@ -1,5 +1,10 @@
-Organizational Principles
-=========================
+---
+inMenu: true
+title: Custom Types
+---
+
+# Organizational Principles
+
 I won't claim that the terminology currently in place is great, but it's
 what's there, so bear with me.
 
@@ -11,27 +16,26 @@ MetaParameters_, and States_.
 Types are created by calling the ``newtype`` method on ``Puppet::Type``, with
 the name of the type as the only required argument (you can optionally specify
 a parent class; otherwise, Puppet::Type is used as the parent class), and you
-must also provide a block of code used to define the type::
+must also provide a block of code used to define the type:
 
     Puppet::Type.newtype(:database) do
         ... the code ...
     end
 
-A normal type would define multiple states_ and zero or more parameters_.
+A normal type would define multiple states and zero or more parameters.
 Once these are defined, you just put the type into ``lib/puppet/type``
 anywhere in Ruby's search path, and Puppet will autoload the type when you use
 it in the language.
 
 All types should also provide inline documention in the ``@doc`` class
-instance variable.  The text format is in `Restructured Text`_.
+instance variable.  The text format is in Restructured Text.
+
+## Parameters
 
-Parameters
-----------
 These are usually simple attributes that can be used to modify function, but
 they don't directly do any work themselves.  Parameters are defined inside the
-block passed to ``newtype``, using the ``newparam`` method::
+block passed to ``newtype``, using the ``newparam`` method:
 
-    
     Puppet::Type.newtype(:database) do
         newparam(:color) do
             desc "Specify the color you want your database to be."
@@ -41,7 +45,8 @@ block passed to ``newtype``, using the ``newparam`` method::
     end
 
 The ``desc`` method provides documentation for your parameter.  This
-documentation is used by ``puppetdoc`` to create the `Type Reference`_.
+documentation is used by ``puppetdoc`` to create the
+[Type Reference](typedocs.html).
 
 The ``newvalues`` method is optional; if you use it, then only those values
 (in string or symbol form) will be considered valid values, and they will
@@ -52,7 +57,7 @@ At least one of your parameters must be the **namevar**, specified using the
 attribute that is considered to uniquely identify a given instance, such as a
 file's path or a user's name.  If a separate name is not provided, then this
 value is returned by the ``name`` method on a type instance, but you can
-specify both a name and the namevar, although it can be confusing internally::
+specify both a name and the namevar, although it can be confusing internally:
 
     file { sshconfig:
         path => "/etc/ssh/ssh_config",
@@ -66,7 +71,7 @@ always use the namevar and not the ``name`` method.
 You can specify regexes in addition to literal values; matches against regexes
 always happen after equality comparisons against literal values, and those
 matches are not converted to symbols.  For instance, given the following
-definition::
+definition:
 
     newparam(:color) do
         desc "Your color, and stuff."
@@ -77,7 +82,7 @@ definition::
 If you provide "blue" as the value, then your parameter will get set to
 ``:blue``, but if you provide "green", then it will get set to "green".
 
-Currently, you set parameters by treating the containing object as a hash::
+Currently, you set parameters by treating the containing object as a hash:
 
     db[:color] = :blue
 
@@ -87,24 +92,24 @@ put into the type instance's ``@parameters`` hash, indexed by parameter name.
 The parameter object gets its ``@parent`` instance variable set so that it
 points back to the containing type instance.
 
-You can similarly retrieve the parameter::
+You can similarly retrieve the parameter:
 
     puts db[:color]
 
 Within the type instance itself (i.e., in instance methods), you can use these
 same methods to set and retrieve the values, or you can call the ``value``
-methods directly, once the object exists::
+methods directly, once the object exists:
 
     # Create the param
     self[:color] = :blue
     color = @parameters[:color].value
     @parameters[:color].value = :red
 
-Validation and Munging
-++++++++++++++++++++++
+### Validation and Munging
+
 If your parameter does not have a defined list of values, or you need to
 convert the values in some way, you can use the ``validate`` and ``munge``
-hooks::
+hooks:
 
     newparam(:color) do
         desc "Your color, and stuff."
@@ -145,8 +150,8 @@ Lastly, validation and munging *only* happen when a value is assigned.  They
 have no role to play at all during use of a given value, only during
 assignment.
 
-MetaParameters
---------------
+## MetaParameters
+
 These are just like parameters in all but two ways.  First, they are defined
 using the ``newmetaparam`` method, and second, when defined they are valid for
 all types, not just a single type.  See the end of type.rb for examples.
@@ -155,15 +160,15 @@ You should never define any of these in an average custom type; if you need a
 new MetaParameter, contact the main developers about getting it added to the
 core.
 
-States
-------
+## States
+
 States are what usually do the actual work on the system.  These are actually
 a subclass of parameters, but with much more functionality.  Without
 exception, every state needs to define at least two methods:  ``retrieve`` and
 ``sync``.
 
-The Variables
-+++++++++++++
+### The Variables
+
 The ``retrieve`` and ``sync`` methods work in tandem with two important
 instance variables, ``@is`` and ``@should``.  The first should reflect the
 current state of the, um, state (I already admitted the nomenclature is bad),
@@ -172,12 +177,12 @@ whatever.  The second reflects what the current state, um, should be, and it
 is *always* an array.
 
 Because there are two variables that contain values, assignment to states is a
-bit odd.  By default, ``@should`` is used when you use the indexing methods::
+bit odd.  By default, ``@should`` is used when you use the indexing methods:
 
     file[:owner] = "root"
 
 This sets ``@should`` to be ``["owner"]``.  You would not normally set the
-``@is`` variable from outside the instance, but sometimes it's necessary::
+``@is`` variable from outside the instance, but sometimes it's necessary:
 
     file.is = [:owner, "root"]
 
@@ -190,7 +195,7 @@ to return the whole array.  You'll see why in a minute.
 I should probably explain why ``@should`` is always an array:  You can always
 specify multiple values for any state, and by default, if the current state is
 in that list of values, then no work is done.  That is, given the following
-definition::
+definition:
 
     file { "/etc/sudoers":
         owner => root, group => [wheel, root], mode => 440
@@ -199,12 +204,11 @@ definition::
 If the group is currently ``wheel`` or ``root``, then the file is considered
 in sync.
 
-The Methods
-+++++++++++
+### The Methods
 
-``retrieve`` is used to get the current value of the state on the machine.
-For instance, here is a trivialized version of how to retrieve a File's
-owner::
+The ``retrieve`` method is used to get the current value of the state on the
+machine.  For instance, here is a trivialized version of how to retrieve a
+File's owner:
 
     newstate(:owner) do
         def retrieve
@@ -219,7 +223,7 @@ that it should not modify the system in any way; if someone runs their
 configuration in ``noop`` mode, then ``retrieve`` is still called, so it's
 important that it not modify the state of the system.
 
-The other critical method is ``sync``, which actually modifies the machine::
+The other critical method is ``sync``, which actually modifies the machine:
 
     newstate(:owner) do
         def retrieve
@@ -242,7 +246,7 @@ subscribe to specific events, rather than all events from a given object.
 There's a third method, ``insync?``, which you will not normally override but
 is important to understand.  This method is used to determine if your state is
 in sync, and thus if any work needs to be done.  The default method looks a
-lot like this::
+lot like this:
 
     def insync?
         @should.include?(@is)
@@ -251,12 +255,12 @@ lot like this::
 Notice that we're checking to see if our current value is anywhere in the
 ``@should`` list.
 
-State Values
-++++++++++++
+### State Values
+
 Just like parameters, you can define allowed values for states, but there's
 one significant change:  With state values, you have to specify the code that
 will achieve that state.  Here is a trivialized version of ``ensure`` state on
-files::
+files:
 
     newstate(:ensure) do
         newvalue(:file) do
@@ -295,18 +299,18 @@ one.  In this example, files have ``set_file``, ``set_directory``, and
 All of these are convenience methods, of course; you can have a single opaque
 all-powerful ``sync`` method, you don't have to split it up using values.
 
-Process
-=======
+# Process
+
 Now that you have an idea of how types are constructed, let's look at the
 process of applying one or more type instances.
 
-Dependency Sorting
-------------------
+## Dependency Sorting
+
 I'll ignore the process of turning Puppet manifests into types; that's handled
-in the `How It Works`_ document.  The collection of objects are always
-contained in a top-level instance of the ``component`` type (this is an
-unfortunate hold-over from some flawed design ideas in the early development
-of Puppet -- expect it to change internally at some point).
+in the [How It Works](howitworks.html) document.  The collection of objects
+are always contained in a top-level instance of the ``component`` type (this
+is an unfortunate hold-over from some flawed design ideas in the early
+development of Puppet -- expect it to change internally at some point).
 
 When work is begun, ``evaluate`` is called on the component (usually by
 client/master.rb); this method does a topological sort based on dependency
@@ -314,8 +318,8 @@ information on all contained objects (components can contain other components,
 so it's a recursive sort), creates a new transaction, and adds the now-sorted
 flat list of objects to the transaction.
 
-Transactions
-------------
+## Transactions
+
 Once the transaction has all of the objects, ``evaluate`` is called on it.
 This method is the heart of action in Puppet; it's relatively short, but
 determines all of the actual function in a given run.
@@ -327,14 +331,14 @@ which will cause it to only run objects that have those tags).  For each of
 those found objects, the transaction calls ``evaluate`` on the object, which
 in turn calls ``statechanges`` on the object.
 
-``statechanges`` iterates across each instantiated state (i.e., file objects
-have many states, but only those states for which you've provided a value have
-instances in a given file object's ``@states`` variables), looking for
-out-of-sync states.  The states are checked in the order they're defined; this
-often does not matter, but for classes like ``file`` it matters a lot.  For
-each state that's out of sync, a ``StateChange`` object is created; it's
-basically an organizational class that knows how to sync a state and log the
-work it's doing.
+The ``statechanges`` method iterates across each instantiated state (i.e.,
+file objects have many states, but only those states for which you've provided
+a value have instances in a given file object's ``@states`` variables),
+looking for out-of-sync states.  The states are checked in the order they're
+defined; this often does not matter, but for classes like ``file`` it matters
+a lot.  For each state that's out of sync, a ``StateChange`` object is
+created; it's basically an organizational class that knows how to sync a state
+and log the work it's doing.
 
 There's one exception to this "all states are checked" rule:  If the instance
 has an ``ensure`` state and that state is out of sync, then Puppet assumes
@@ -367,8 +371,8 @@ sure your ``ensure`` state can completely create or destroy the object, and
 return events if you made a change.  Other than that, you should not have to
 think about transactions or how they work.
 
-Conclusion
-==========
+# Conclusion
+
 That's all you need for your type.  See the existing types for different ways
 to treat this.  You can create methods on your type and call those methods
 from the state (like packages do), or put enough complexity into each state
@@ -376,6 +380,3 @@ that they end up in their own file (like files do).
 
 Comments on this document are appreciated.
 
-.. _type reference: typedocs
-.. _restructured text: http://docutils.sourceforge.net/rst.html
-.. _how it works:  howitworks
diff --git a/documentation/fromsvn.page b/documentation/fromsvn.page
new file mode 100644
index 000000000..e7f9fbd8a
--- /dev/null
+++ b/documentation/fromsvn.page
@@ -0,0 +1,63 @@
+---
+inMenu: true
+title: Using Source
+---
+Puppet is currently implemented in Ruby and uses standard Ruby libraries. You
+should be able to run Puppet on any Unix-style host with Ruby.  Windows
+support is planned but not currently available.
+
+## Before you Begin
+
+Make sure your host has Ruby version 1.8.2:
+
+  $ ruby -v
+
+While Puppet should work with 1.8.1, there have been many reports of problems
+with this version.
+
+Make sure you have Subverion:
+
+    $ svn --version -q
+
+## Get the Source
+
+Puppet currently relies on another Reductive Labs tool, Facter. Create a working
+directory and get them both:
+
+    $ SETUP_DIR=~/svn
+    $ mkdir -p $SETUP_DIR
+    $ cd $SETUP_DIR
+    $ svn checkout https://reductivelabs.com/svn/facter/trunk facter
+    $ svn checkout https://reductivelabs.com/svn/puppet/trunk puppet
+
+
+# Make it Available
+
+Last, we need to put the puppet binaries into our path and make the Puppet and
+Facter libraries available to Ruby:
+
+    $ PATH=$PATH:$SETUP_DIR/facter/bin:$SETUP_DIR/puppet/trunk/bin
+    $ RUBYLIB=$SETUP_DIR/facter/lib:$SETUP_DIR/puppet/trunk/lib
+    $ export PATH RUBYLIB
+
+Facter changes far less often than Puppet and it is very minimal (a single
+library file and a single executable), so it is probably worth just installing
+it:
+
+    $ cd facter
+    $ sudo ruby ./install.rb
+
+## Test That It Works
+
+Now you can test that it is working.  The best way to do that is described in
+the [testing](testing.html) guide, and involves writing a short site manifest.  Another
+option is to run through all of the unit tests that ship with Puppet:
+
+    $ cd $SETUP_DIR/puppet/test
+    $ ./test
+
+This tends to take a long time, however, and is probably only useful if you
+already know there's a problem and want to report a bug or if you are planning
+on doing development.  It is worth noting that some of these tests necessarily
+modify your system, so unless you know what you are doing, **it is unadvisable
+to run them as root**, and certainly not on a production system.
diff --git a/documentation/fromsvn.rst b/documentation/fromsvn.rst
deleted file mode 100644
index 4780faf27..000000000
--- a/documentation/fromsvn.rst
+++ /dev/null
@@ -1,78 +0,0 @@
-Puppet is currently implemented in Ruby and uses standard Ruby libraries. You should be able to run Puppet on any Unix-style host with Ruby.  Windows support is planned but not currently available.
-
-Before you Begin
-----------------
-
-Make sure your host has Ruby version 1.8.2::
-
-  $ ruby -v
-
-Make sure you have Subverion::
-
-    $ svn --version -q
-
-Get the Source
---------------
-
-Puppet currently relies on another ReductiveLabs tool, Facter. Create a working
-directory and download them both::
-
-    $ SETUP_DIR=~/svn
-    $ mkdir -p $SETUP_DIR
-    $ cd $SETUP_DIR
-    $ svn checkout https://reductivelabs.com/svn/facter
-    $ svn checkout https://reductivelabs.com/svn/puppet
-
-
-Make it Available
------------------
-
-Last, we need to put the puppet binaries into our path and make the Puppet and
-Facter libraries available to Ruby::
-
-    $ PATH=$PATH:$SETUP_DIR/facter/bin:$SETUP_DIR/puppet/trunk/bin
-    $ RUBYLIB=$SETUP_DIR/facter/lib:$SETUP_DIR/puppet/trunk/lib
-    $ export PATH RUBYLIB
-
-Facter changes far less often than Puppet and it is very minimal (a single
-library file and a single executable), so it is probably worth just installing
-it::
-
-    $ cd facter/trunk
-    $ sudo ruby ./install.rb
-
-Test it Works
--------------
-Now you can test that it is working.  The best way to do that is described in
-the testing_ guide, and involves writing a short site manifest.  Another
-option is to run through all of the unit tests that ship with Puppet::
-
-    $ cd $SETUP_DIR/puppet/trunk/test
-    $ ./test
-
-This tends to take a long time, however, and is probably only useful if you
-already know there's a problem and want to report a bug or if you are planning
-on doing development.  It is worth noting that some of these tests necessarily
-modify your system, so unless you know what you are doing, **it is unadvisable
-to run them as root**, and certainly not on a production system.
-
-Help with Installing
---------------------
-You can build your first Puppet script by using this Simple Example_.
-
-You can see more documentation about installation of Puppet and its
-prerequisites by looking at Bootstrap-Install_ guide.
-
-
-More documentation
-------------------
-
-You can learn more about Puppet by reading the Documentation_.
-
-.. _Documentation: /projects/puppet/documentation/
-
-.. _Example: https://reductivelabs.com/svn/manifests/project-www/README-www.rst
-
-.. _Bootstrap-Install: https://reductivelabs.com/svn/manifests/project-test/bootstrap-install.rst
-
-.. _testing: testing
diff --git a/documentation/fsconfigref.rst b/documentation/fsconfigref.page
index cd2b30868..ef1cb4036 100644
--- a/documentation/fsconfigref.rst
+++ b/documentation/fsconfigref.page
@@ -1,5 +1,8 @@
-FileServer
-==========
+---
+inMenu: true
+title: Fileserver Configuration Reference
+---
+# FileServer
 
 Puppet comes with both a client and server for copying files around.  The file
 serving function is provided as part of the central Puppet daemon,
@@ -20,11 +23,12 @@ to serve and a name for the path, and clients request it by name instead of by
 path.  This provides the ability to conceal from the client unnecessary
 details like the local filesystem configuration.
 
-File Format
-=============
+# File Format
+
 The default location for the file service is ``/etc/puppet/fileserver.conf``;
 this can be changed using the ``--fsconfig`` flag to ``puppetmasterd``.
-The format of the file is almost exactly like that of rsync_, although it does
+The format of the file is almost exactly like that of
+[rsync](http://samba.anu.edu.au/rsync/), although it does
 not yet support nearly the functionality of rsync.  The configuration file
 resembles INI-style files, but it is not exactly the same::
 
@@ -39,21 +43,21 @@ While the path is the only required option, the default security configuration
 is to deny all access, so if no ``allow`` lines are specified, the module will
 be configured but available to no one.
 
-Security
-========
+# Security
+
 There are two aspects to securing the Puppet file server: Allowing specific
 access, and denying specific access.  By default no access is allowed.  There
 are three ways to specify a class of clients who are allowed or denied access:
 By IP address, by name, or a global allow using ``*``.
 
-Priority
---------
+## Priority
+
 All ``deny`` statements are parsed before all ``allow`` statements, so if any
 ``deny`` statements match a host, then that host will be denied, and if no
 ``allow`` statements match a host, it will be denied.
 
-Host Names
-----------
+## Host Names
+
 Host names can be specified using either a complete hostname, or specifying an
 entire domain using  the ``*`` wildcard::
 
@@ -63,8 +67,8 @@ entire domain using  the ``*`` wildcard::
         allow *.domain2.com
         deny badhost.domain2.com
 
-IP Addresses
-------------
+## IP Addresses
+
 IP address can be specified similarly to host names, using either complete IP
 addresses or wildcarded addresses, but you can also use CIDR-style notation::
 
@@ -74,12 +78,10 @@ addresses or wildcarded addresses, but you can also use CIDR-style notation::
         allow 192.168.0.*
         allow 192.168.1.0/24
 
-Global allow
-------------
+## Global allow
+
 Specifying a single wildcard will let anyone into a module::
 
     [export]
         path /export
         allow *
-
-.. _rsync: http://samba.anu.edu.au/rsync/
diff --git a/documentation/howitworks.rst b/documentation/howitworks.page
index 730d4b04e..0e63e651f 100644
--- a/documentation/howitworks.rst
+++ b/documentation/howitworks.page
@@ -1,5 +1,9 @@
-Introduction
-============
+---
+inMenu: true
+title: How It Works
+---
+# Introduction
+
 The goal of this document is to describe how a manifest you write in Puppet
 gets converted to work being done on the system.  This process is relatively
 complex, but you seldom need to know many of the details; this document only
@@ -7,13 +11,13 @@ exists for those who are pushing the boundaries of what Puppet can do or who
 don't understand why they are seeing a particular error.  It can also help
 those who are hoping to extend Puppet beyond its current abilities.
 
-High Level
-==========
+# High Level
+
 When looked at coarsely, Puppet has three main phases of execution --
 compiling, instantiation, and configuration.
 
-Compiling
----------
+## Compiling
+
 Here is where we convert from a text-based manifest into the actual code we'll
 be executing.  Any code not meant for the host in question is ignored, and any
 code that is meant for that host is fully interpolated, meaning that variables
@@ -28,8 +32,8 @@ In a networked setup, this phase happens entirely on the server.  The output
 of this phase is a collection of very simplistic elements that closely
 resemble basic hashes and arrays.
 
-Instantiation
--------------
+## Instantiation
+
 This phase converts the simple hashes and arrays into Puppet library objects.
 Because this phase requires so much information about the client in order to
 work correctly (e.g., what type of packaging is used, what type of services,
@@ -45,8 +49,8 @@ on the server.
 The output of this phase is the machine's entire configuration in memory and
 in a form capable of modifying the local system.
 
-Configuration
--------------
+## Configuration
+
 This is where the Puppet library elements actually modify the system.  Each of
 them compares their specified state to the state on the machine and make any
 modifications that are necessary.  If the machine exactly matches the
@@ -54,12 +58,12 @@ specified configuration, then no work is done.
 
 The output of this phase is a correctly configured machine, in one pass.
 
-Lower Level
-===========
+# Lower Level
+
 These three high level phases can each be broken down into more steps.
 
-Compile Phase 1: Parsing
-------------------------
+## Compile Phase 1: Parsing
+
 :Inputs: Manifests written in the Puppet language
 :Outputs: Parse trees (instances of AST_ objects)
 :Entry: `Puppet::Parser::Parser#parse`_
@@ -76,10 +80,10 @@ using nodes or no nodes, whether you are using the standalone puppet
 interpreter or the client/server system, parsing happens as soon as Puppet
 starts.
 
-Compile Phase 2: Interpreting
------------------------------
+## Compile Phase 2: Interpreting
+
 :Inputs: Parse trees (instances of AST_ objects) and client information
-    (collection of facts output by Facter_)
+    (collection of facts output by [Facter][])
 :Outputs: Trees of TransObject_ and TransBucket_ instances (from
     transportable.rb)
 :Entry: `Puppet::Parser::AST#evaluate`_
@@ -101,8 +105,8 @@ tree of simple transportable_ objects which maps roughly to the configuration
 as defined in the manifests -- it is still a tree, but it is a tree of classes
 and the elements contained in those classes.
 
-Nodes vs. No Nodes
-''''''''''''''''''
+### Nodes vs. No Nodes
+
 When you use Puppet, you have the option of using `node elements`_ or not.  If
 you do not use node elements, then the entire configuration is interpreted
 every time a client connects, from the top of the parse tree down.  In this
@@ -114,8 +118,8 @@ node-specific code.  When a node connects, the interpreter looks for the code
 associated with that node name (retrieved from the Facter facts) and compiles
 just that bit on demand.
 
-Configuration Transport
------------------------
+## Configuration Transport
+
 :Inputs: Transportable_ objects
 :Outputs: Transportable_ objects
 :Entry: `Puppet::Server::Master#getconfig`_
@@ -132,8 +136,8 @@ receives the configuration, unescapes it, caches it to disk in case the server
 is not available on the next run, and then uses YAML to convert it back to
 normal Ruby Transportable objects.
 
-Instantiation Phase
--------------------
+## Instantiation Phase
+
 :Inputs: Transportable_ objects
 :Outputs: `Puppet::Type`_ instances
 :Entry: `Puppet::Client::MasterClient#getconfig`_
@@ -159,8 +163,8 @@ instantiated after the requiring object.  So, the finalization phase is used
 to actually handle all of these requirements -- Puppet objects use their
 references to objects and verify that the objects actually exist.
 
-Configuration Phase 1: Comparison
----------------------------------
+## Configuration Phase 1: Comparison
+
 :Inputs: `Puppet::Type`_ instances
 :Outputs: `Puppet::StateChange`_ objects collected in a `Puppet::Transaction`_
     instance
@@ -185,8 +189,8 @@ always fixed before the objects that depend on them.
 The top-level component (which is also responsible for this sorting) creates a
 Puppet::Transaction instance and inserts these changes into it.
 
-Notes About Recursion
-'''''''''''''''''''''
+### Notes About Recursion
+
 Recursion muddies this phase considerably.  While it's tempting to merely
 handle recursion in the instantiation phase, the state on disk can (and will)
 change between runs, so the configured state and the on-disk state must be
@@ -203,8 +207,8 @@ not make sense at instantiation time, only at comparison time.
 This might introduce some strangenesses, though, and it is expected that this
 could cause interesting-in-a-not-particularly-good-way edge cases.
 
-Configuration Phase 2: Syncing
-------------------------------
+## Configuration Phase 2: Syncing
+
 :Inputs: `Puppet::Transaction`_ instance containing `Puppet::StateChange`_
     instances
 :Outputs: Completely configured operating system
@@ -248,13 +252,13 @@ and why that would happen.  If this is a critical feature for you or you have
 a brilliant way to go about creating it, I would love to hear it, but it is
 currently a back-burner goal.
 
-Conclusion
-==========
+# Conclusion
+
 That's the entire flow of how a Puppet manifest becomes a complete
 configuration.  There is more to the Puppet system, such as FileBuckets, but
 those are more support staff rather than the main attraction.
 
-.. _facter: /projects/facter
+[facter] /projects/facter
 .. _node elements: /projects/puppet/documentation/structures#nodes
 .. _yaml: http://www.yaml.org/
 .. _Puppet::Parser::Parser#parse: /downloads/puppet/apidocs/classes/Puppet/Parser/Parser.html
diff --git a/documentation/installation.rst b/documentation/installation.page
index be60b360b..9102f90d7 100644
--- a/documentation/installation.rst
+++ b/documentation/installation.page
@@ -1,5 +1,7 @@
-Getting the Files
-=================
+---
+inMenu: true
+---
+# Getting the Files
 
 You will need to install Puppet on all machines that will use it, including
 both clients and servers.
@@ -7,56 +9,57 @@ both clients and servers.
 There are packages_ available for some platforms, but for the rest
 you will have to install using the tarball_ or GEMs_.
 
-Prerequisites
--------------
+## Prerequisites
+
 The only prerequisite for Puppet that doesn't come as part of the Ruby
-standard library is facter_, which is also developed_ by Reductive Labs.  
+standard library is facter_, which is also developed by Reductive Labs.  
 
 All other prerequisites for Puppet are Ruby libraries, and they should all
 come with any standard Ruby 1.8.2 install.  The other prerequisites, should
 your OS not come with the complete standard library, are:
 
-* ``base64``
-* ``cgi``
-* ``digest/md5``
-* ``etc``
-* ``fileutils``
-* ``ipaddr``
-* ``openssl``
-* ``strscan``
-* ``syslog``
-* ``uri``
-* ``webrick``
-* ``webrick/https``
-* ``xmlrpc``
-
-Ruby
-''''
+* **base64**
+* **cgi**
+* **digest/md5**
+* **etc**
+* **fileutils**
+* **ipaddr**
+* **openssl**
+* **strscan**
+* **syslog**
+* **uri**
+* **webrick**
+* **webrick/https**
+* **xmlrpc**
+
+### Ruby
+
 I recommend using whatever Ruby comes with your system, since that's what I've
 tested against in most cases and it's most likely to work correctly.  If you
 feel the particular need to build it manually, you can get the source from
-`the Ruby site`_.  
+[the Ruby site](http://ruby-lang.org/).
+
 
+#### Red Hat
 
-Red Hat
-+++++++
 If you are building on Red Hat (at least on version 3), you
 apparently must build it with ``CPPFLAGS=-I/usr/kerberos/include/``, else you
 will have all kinds of unreasonable problems (thanks to Mario Martelli for
 tracking that one down).
 
-Solaris
-+++++++
-I have had mixed results with the Ruby packages from both Sunfreeware_ and
-BlastWave_.  It might almost be easier to compile it manually for Solaris, but
-Ruby 1.8.3 from Sunfreeware seems to be working right now.
+#### Solaris
+
+I have had mixed results with the Ruby packages from both
+[Sunfreeware](http://sunfreeware.com) and [BlastWave](http://blastwave.org).
+It might almost be easier to compile it manually for Solaris, but Ruby 1.8.3
+from Sunfreeware seems to be working right now.
 
 If you get segfaults, core dumps, or 'library missing ciphers' errors, that is
 almost definitely a problem with that specific ruby package, not Puppet or
 Ruby itself.
 
-Debian and Ubuntu
-+++++++++++++++++
+#### Debian and Ubuntu
+
 The package maintainer for Ruby on these platforms has decided to split
 the Ruby standard library into many packages.  According to Eric Hollensbe,
 this is the package dependency list for Puppet on Debian:
@@ -71,16 +74,10 @@ this is the package dependency list for Puppet on Debian:
 * libsyslog-ruby
 * libwebrick-ruby
 
-.. _sunfreeware: http://sunfreeware.com
-.. _blastwave: http://blastwave.org
-
-.. _the ruby site: http://ruby-lang.org/
-
-Facter
-''''''
+### Facter
 
 First install facter.  Like Puppet, there are packages_ available for
-some platforms, but you might have to use the tarball::
+some platforms, but you might have to use the tarball:
 
     # get the latest tarball
     wget http://reductivelabs.com/downloads/facter/facter-latest.tgz
@@ -92,10 +89,9 @@ some platforms, but you might have to use the tarball::
 
 There are also gems available in the download_ directory.
 
-Install Puppet
---------------
+## Install Puppet
 
-Using the same mechanism, install the puppet libraries and executables::
+Using the same mechanism, install the puppet libraries and executables:
 
     # get the latest tarball
     wget http://reductivelabs.com/downloads/puppet/puppet-latest.tgz
@@ -105,17 +101,17 @@ Using the same mechanism, install the puppet libraries and executables::
     cd puppet-*
     sudo ruby install.rb # or become root and run install.rb
 
-Alternative: Using RubyGems
------------------------------
-You can also use Reductive Labs' Gems server to install Facter and Puppet::
+## Alternative: Using RubyGems
+
+You can also use Reductive Labs' Gems server to install Facter and Puppet:
 
     gem install --remote --source http://reductivelabs.com/downloads facter
     gem install --remote --source http://reductivelabs.com/downloads puppet
 
 For more information on RubyGems, see the `Gems User Guide`_.
 
-Alternative alternative:  Native Packages
------------------------------------------
+## Alternative alternative:  Native Packages
+
 It is our goal to provide as many native packages as possible, but it's been
 slow going.  Until I have official native packages, David Lutterkort used spec
 and init files from Duane Griffin to create native RPMs that should work on
@@ -128,11 +124,9 @@ maintained as the RPMs.
 .. _yum repository: http://people.redhat.com/~dlutter/yum/
 .. _debian packages: /downloads/packages/Debian
 
-Building the Server
-===================
+# Building the Server
 
-Create Your Site Manifest
--------------------------
+## Create Your Site Manifest
 
 Because the Puppet language is declarative, it does not make as much sense to
 speak of "executing" Puppet programs, or to describe them as "scripts".  We
@@ -154,11 +148,11 @@ so create ``/etc/puppet/manifests`` and add your manifest, along with any
 files it includes, to that directory.  It is highly recommended that you use
 some kind of `version control`_ on your manifests.
 
-Example Manifests
-'''''''''''''''''''
+### Example Manifests
+
 The site manifest can be as simple or as complicated as you want.  A good
 starting point is to make sure that your sudoers file has the appropriate
-permissions::
+permissions:
 
     # site.pp
     file { "/etc/sudoers":
@@ -169,7 +163,7 @@ If you want to get more complicated, it's a good idea to split your
 manifest into multiple files.  For instance, you could split it based on
 operating systems (e.g., Solaris and Red Hat) and server classes (e.g.,
 'webserver' and 'logserver').  I also find it useful to have a set of
-functions, in an external file included first::
+functions, in an external file included first:
 
     # site.pp
 
@@ -184,11 +178,11 @@ functions, in an external file included first::
 
 Here's an example of a generically useful function I use; it encapsulates the
 source of files that I copy from a central server, and just saves a little
-typing::
+typing:
 
     # functions.pp
     
-    define remotefile(owner = root, group = root, mode, source, backup = false, recurse = false) {
+    define remotefile(owner = root, server = puppet, group = root, mode, source, backup = false, recurse = false) {
         file {
             $name:
                 mode => $mode,
@@ -199,14 +193,14 @@ typing::
         }
     }
 
-You would use the function like this::
+You would use the function like this:
 
     remotefile { "/etc/sudoers":
         mode => 440, source => "apps/sudo/sudoers"
     }
 
-Start the Central Daemon
-------------------------
+## Start the Central Daemon
+
 Most sites should only need a single central server.  Reductive Labs will
 soon publish a document describing how to build puppet architectures with
 failover capabilities and achitectures that are capable of handling large
@@ -221,7 +215,7 @@ will ship with an appropriate script for each platform, but in the meantime
 you can either create your own, using an existing script as an example, or
 simply run without one (not recommended for production environments).
 
-The daemon should start just fine with no arguments::
+The daemon should start just fine with no arguments:
 
     /usr/bin/puppetmasterd
 
@@ -232,25 +226,32 @@ clients can copy files from it, you will need to create a
 
 If you are still only testing, and do not have node definitions in your
 site manifest (such as with the above example manifest) , tell
-``puppetmasterd`` not to look for them::
+``puppetmasterd`` not to look for them:
 
     /usr/bin/puppetmasterd --nonodes
 
-Verifying Installation
-======================
+Otherwise, you will need to define each of your nodes in your site manifest:
+
+    node culain {
+        include workstation
+    }
+
+# Verifying Installation
+
 To verify that your daemon is working as expected, pick a single client to use
 as a testbed.  Once Puppet is installed on that machine, run a single client
 against the central server to verify that everything is working appropriately.
 You should start the first client in verbose mode, with the ``--waitforcert``
-flag enabled::
+flag enabled:
 
     puppetd --server myserver.domain.com --waitforcert 60 --test
 
 The default server for ``puppetd`` is ``puppet``, so you could just create a
 CNAME of that to whatever server is running ``puppetmasterd``.
 
-Adding the ``--test`` flag here is equivalent to adding ``--verbose --onetime
---no-usecacheonfailure``.  This causes ``puppetd`` to stay in the foreground,
+Adding the ``--test`` flag here is equivalent to
+adding ``--verbose --onetime --no-usecacheonfailure``.
+This causes ``puppetd`` to stay in the foreground,
 print extra output, only run once and then exit, and to just exit if the
 remote configuration fails to compile (by default, ``puppetd`` will use a
 cached configuration if there is a problem with the remote manifests).
@@ -259,31 +260,34 @@ In running the client, you should see a message that the client did not
 receive a certificate (this message will repeat every 60 seconds with the
 above command).  This is normal, since your server is not autosigning
 certificates as a security precaution.  On your server, list the waiting
-certificates::
+certificates:
 
     puppetca --list
 
 You should see the name of the test client.  Now go ahead and sign the
-certificate::
+certificate:
 
     puppetca --sign mytestclient.domain.com
 
 Within 60 seconds, your test client should receive its certificate from the
 server, receive its configuration, apply it locally, and exit normally.
 
-Finishing Installation
-======================
+By default, ``puppetd`` runs with a ``waitforcert`` of five minutes; set the
+value to 0 to disable it entirely.
+
+# Finishing Installation
+
 There are already init scripts available for some platforms (notably, Red Hat
 versions, thanks to David Lutterkort's work on the RPMs_), but for
 not-yet-supported platforms, you will need to create an init script that can
 start and stop ``puppetd``.  The process creates a PID file in its run
 directory (``/var/puppet/run``, by default), so you can use that to stop it.
 
-The process will log to syslog by default.
+The process will log to syslog by default in the daemon facility.
 
 Beta Notes
 ==========
-There are some important notes to keep in mind about using the beta of
+There are some important notes to keep in mind about using the current versions of
 Puppet:
 
 * Files are currently automatically reread when they are changed, within a
diff --git a/documentation/introduction.rst b/documentation/introduction.page
index 2614b4d46..2d1cd680c 100644
--- a/documentation/introduction.rst
+++ b/documentation/introduction.page
@@ -1,5 +1,8 @@
-Introduction
-============
+---
+inMenu: true
+---
+# Introduction
+
 Puppet is a system configuration tool.  It has a library for managing the
 system, a language for specifying the configuration you want, and a set of
 clients and servers for communicating the configuration and other information.
@@ -11,8 +14,8 @@ server (or bank of servers), and all library operations will take place on each
 individual client.  Thus, there is a clear demarcation between language
 operations and library operations, as this document will mention.
 
-Setup
-=====
+# Setup
+
 The vast majority of Puppet architectures will look like a star, with a
 central server running `puppetmasterd`, and each client node running
 `puppetd`, contacting that central server.  Your central manifest, which
@@ -34,17 +37,17 @@ sign.  You can turn on autosigning by creating `/etc/puppet/autosign.conf` and
 put the hosts, domains, or IP addresses or ranges that you want to sign in
 there.
 
-Language
-========
+# Language
+
 The language is declarative, and is modeled somewhat after cfengine's concept
 of actions, action instances, and instance parameters.  Here is how a file
-element would look in puppet::
+element would look in puppet:
 
-  file { "/etc/passwd":
-    owner => root,
-    group => root,
-    mode => 644
-  }
+    file { "/etc/passwd":
+        owner => root,
+        group => root,
+        mode => 644
+    }
 
 Each instance of a low-level element like ``file`` must have a name parameter
 defined, because that is how you uniquely refer to the element you are
@@ -55,34 +58,34 @@ There are two ways for types to be available in the language:  They'll either
 be ``primitive types`` included in the Puppet framework itself, or they'll be
 ``defined types`` resulting from definitions or server classes.
 
-Definitions
------------
+## Definitions
+
 Because experience with cfengine showed that objects of different types are
 often related, puppet focuses on making creation of associations between
 objects of any type easier than making many objects of the same type.  The
-fundamental unit of association is a 'definition': ::
-
-  # currently, the variables don't have '$' attached in the definition prototype
-  # this might change
-  define sudo(source,group) {
-      package { sudo:
-        version => "1.6.7"
-      }
-      file { "/etc/sudoers":
-        source => $source, # parameterization; copy the file from where?
-        mode => 440 # the 'file' type converts this appropriately to
-                    # octal
-      }
-      file { "/usr/sbin/sudo":
-        owner => root,
-        group => $group
-      }
-  }
+fundamental unit of association is a 'definition':
+
+    # currently, the variables don't have '$' attached in the definition prototype
+    # this might change
+    define sudo(source,group) {
+        package { sudo:
+            version => "1.6.7"
+        }
+        file { "/etc/sudoers":
+            source => $source, # parameterization; copy the file from where?
+            mode => 440 # the 'file' type converts this appropriately to
+                        # octal
+        }
+        file { "/usr/sbin/sudo":
+            owner => root,
+            group => $group
+        }
+    }
 
 A definition has its own scope, so variables defined within it are only
 available within the definition itself.
 
-This definition can now be treated as a type::
+This definition can now be treated as a type:
 
     sudo {
         group => root,
@@ -103,63 +106,56 @@ executed with the provided parameters.
 I will likely soon add the ability to provide defaults to definition
 parameters; any other feature requests are welcome.
 
-Classes
--------
-In addition to definitions, the language supports server classes.  At this
-point, the only syntactical or functional difference between the two is that
-server classes can have a parent class::
+## Classes
 
-  class base {
-    sudo { ... } # an existing definition
-  }
+In addition to definitions, the language supports server classes.  Classes are
+different from definitions in two fundamental ways:  They do not (currently)
+support parameterization, and sub classes can override base classes.
 
-  class server inherits base {
-    ssh { ... } # an existing definition
-  }
+Classes can be called using the same syntax as definitions, although always
+without arguments and usually without names, but they are generally called
+with the ``include`` keyword, which is more flexible in that it supports
+variable interpolation and conditional expressions:
 
-  if $hostname == "myhost" {
-    server{} # the braces are mandatory at this point
-  } elsif $hostname == "otherhost" {
-    base{}
-  }
+    class base {
+        include sudo
+    }
 
-The classes also support parameterization, just like definitions. Notice that
-the mechanism for associating nodes with servers is stupid.  I considered the
-following syntax::
+    class server inherits base {
+        include ssh
+    }
+
+    case $hostname {
+        myhost: { include server }
+        default: { include base }
+    }
 
-  node host {
-    server {}
-  }
+    include $operatingsystem
 
-But that doesn't seem much better.  Again, recommendations are accepted.
 
-Having a parent class means that that parent's objects are all operated on
-before any of the subclass's are.  So, in this case, each member of 'server'
-would first verify 'sudo' is set up correctly and then check 'ssh'.
+## Variables
 
-Variables
----------
 Because it is assumed that strings will be used far more than variables, simple
 strings don't have be quoted or otherwise marked, but variables must have the
-``$`` attached::
+``$`` attached:
 
-  $group = "root"
+    $group = "root"
 
-  file { "/etc/sudoers":
-    group => $group
-  }
+    file { "/etc/sudoers":
+        group => $group
+    }
 
 Strings and booleans (``true`` and ``false``) are the only data types; even
 numbers are converted to strings.  Arrays are supported, although their
 behaviour has not been characterized for all cases.  One particular use of
-arrays is for implicit iteration::
+arrays is for implicit iteration:
 
-  $files = ["/etc/passwd","/etc/group","/etc/fstab"]
+    $files = ["/etc/passwd","/etc/group","/etc/fstab"]
 
-  file { $files:
-    owner => root,
-    group => root
-  }
+    file { $files:
+        owner => root,
+        group => root
+    }
 
 This implicitly iterates across the file list and performs all of the
 appropriate checks.
@@ -171,22 +167,22 @@ expect variables like ``$operatingsystem`` and ``$ipaddress``.
 Also, because ``puppet`` is a declarative language, reassigning a variable
 within the same scope is currently an error.  The language is written such that
 this could be disabled (please let me know if you need this feature), but it is
-currently always enabled.  You can override defaults in a lower scope::
+currently always enabled.  You can override defaults in a lower scope:
 
-  $var = default
+    $var = default
 
-  define test {
-    $var = override
-    ...
-  }
+    define test {
+        $var = override
+        ...
+    }
 
 It is expected that parameter passing to definitions will be the primary
 mechanism for variable assignment, so it seems unlikely that this limitation
 will cause much trouble.
 
-Importing
----------
-Files can be imported using the ``import`` command::
+## Importing
+
+Files can be imported using the ``import`` command:
 
     import "filename"
 
@@ -194,58 +190,66 @@ There is currently no search path or anything; files are looked for in the same
 directory as the file doing the importing.  Each file should have its own
 lexical scope, but I haven't yet figured out how to do that.
 
-Control Structures
-------------------
+## Control Structures
+
 There are currently two basic control structures, one meant to return a value
 and the other just a normal 'if/elsif/else' structure.
 
-Selectors
-+++++++++
+### Selectors
+
 One of the primary goals of Puppet is to simplify building a single
 configuration that works across multiple machines and machine classes. One
 mechanism for this is currently called a 'selector'; it is similar to the
-trinary operator ``:?``::
+trinary operator ``:?``:
 
-  $value = $variable ? {
-      value1 => setvalue1,
-      value2 => setvalue2,
-      default => other
-  }
+    $value = $variable ? {
+        value1 => setvalue1,
+        value2 => setvalue2,
+        default => other
+    }
 
 This sets the variable ``$value`` depending on the value of ``$variable``.  If
 it is ``value1``, then ``$value`` gets set to ``setvalue1``, else the value
 gets set to ``other``.
 
-The brackets can be in either part of the expression, or not at all::
+The brackets can be in either part of the expression, or not at all:
 
-  $value = $variable ? "value1" => "setvalue1"
+    $value = $variable ? "value1" => "setvalue1"
 
 A selector that doesn't match a value is a compile error.
 
-These structures are useful for simplistic abstraction across platforms::
+These structures are useful for simplistic abstraction across platforms:
+
+    file { "/etc/sudoers":
+        owner => root,
+        group => $operatingsystem ? {
+            SunOS => root,
+            Linux => root,
+            FreeBSD => wheel
+        }
+    }
+
+Selectors can specify default values using the ``default`` keyword.
+
+### Case Statements
+
+Puppet currently supports a normal Case structure similar to so many other
+languages:
 
-  file { "/etc/sudoers":
-    owner => root,
-    group => $operatingsystem ? {
-      SunOS => root,
-      Linux => root,
-      FreeBSD => wheel
+    case $operatingsystem {
+        solaris: { include sunos }
+        debian: { include linux }
+        default: { include $operatingsystem }
     }
-  }
 
-If
-++
-Puppet currently supports a normal If/Elsif/Else structure, and each statement
-introduces a new lexical scope.  Things that can be tested are currently
-extremely limited (just simple comparisons, e.g., '==', '<=', etc.); it should
-be easy to add &&, ||, and parentheticals for extended tests, but I don't yet
-know how I'll handling testing more complex expressions.
+As you can see, case statements also support defaults.
 
-I expect that this structure will go away, to be replaced with a more
-declarative structure.
+The difference between the case stateements and the selectors is that the
+selectors just return values while the case statements execute arbitrary
+Puppet code.
+
+# Library
 
-Library
-=======
 This section discusses some aspects of the internals of the Puppet library.
 This information can be useful but is not critical for use and understanding
 of Puppet.
@@ -258,12 +262,12 @@ of all of the states available to modify files.
 
 In addition to states, which necessarily modify 'the bits on disk', as it were,
 types can also have non-state parameters which modify how that type instance
-behaves::
+behaves:
 
-  file { "/bin":
-    owner => bin,
-    recurse => true
-  }
+    file { "/bin":
+        owner => bin,
+        recurse => true
+    }
 
 The ``recurse`` parameter to ``file`` does not modify the system itself, it
 modifies how the ``file`` type manages ``/bin``.
@@ -275,41 +279,35 @@ are defined in the language itself are termed ``primitive types`` or just
 
 At this point, all types have a unique name (within the current scope, but it
 probably should actually be global).  This name is set using a class instance
-variable: ::
+variable: :
 
-  # in the library
-  class Mytype < Puppet::Type
-    @name = :mytype
-    ...
-  end
+    # in the library
+    Puppet::Type.newtype(:mytype)
+        ...
+    end
 
-  # in the language
-  mytype { "yay": ... }
+    # in the language
+    mytype { "yay": ... }
 
 The states similarly have unique names, although this uniqueness is only
-per-type.  When a type is defined, all states and parameters are also listed as
-class instance variables; states are listed by class, and parameters with
-symbols.  Here is the File type declaration: ::
-
-    @states = [
-      Puppet::State::FileCreate,
-      Puppet::State::FileUID,
-      Puppet::State::FileGroup,
-      Puppet::State::FileMode,
-      Puppet::State::FileSetUID
-    ]
-
-    @parameters = [
-      :path,
-      :recurse
-    ]
-
-Puppet::Type gets notified of a subclass, and it iterates over the states
-retrieving each name and making a hash from the name to the class.
+per-type.  When a type is defined, all states and parameters are added using
+class methods.  Here is the File type declaration:
+
+    newstate(:ensure) do ... end
+    newstate(:owner) do ... end
+    newstate(:group) do ... end
+    ...
+    newparam(:path) do ... end
 
 Lastly, each type must either provide a state or parameter of ':name', or it
-must set '@namevar' so that the system knows what is considered the name: ::
+must mark a parameter as the namevar so that the system knows what is
+considered the name:
 
-    @namevar = :path
+    newparam(:path) do 
+        isnamevar
+    end
 
 With this declaration, ``file { "/tmp/file": }`` is basically equivalent to ``file { path => "/tmp/file" }``.
+
+See [Creating a Puppet Type](creating-a-puppet-type.html) for more
+information.
diff --git a/documentation/languagetutorial.rst b/documentation/languagetutorial.page
index 018eb4151..3ea7ca1b4 100644
--- a/documentation/languagetutorial.rst
+++ b/documentation/languagetutorial.page
@@ -1,14 +1,19 @@
-Elements and Organization
-=========================
+---
+inMenu: true
+title: Language Tutorial
+---
+
+# Elements and Organization
+
 The entire purpose of the Puppet language is to result in Puppet elements that
 directly model elements on each client being managed.  Because different
 clients have different lists of elements, and some clients vary in the
 configuration of specific elements, Puppet's language supports various
 abstraction, selection, and overriding capabilities.
 
-Naming
-=============
-For simple elements, we just specify the element type, name, and parameters::
+# Naming
+
+For simple elements, we just specify the element type, name, and parameters:
 
     file { "/etc/passwd":
         owner => root,
@@ -23,7 +28,7 @@ field before the colon as the name of the object, so in this case the name is
 details are essentially always the same on all systems.
 
 For files that vary across systems, it makes sense to create a *symbolic name*
-for your element::
+for your element:
 
     file { sshdconfig:
         path => $operatingsystem ? {
@@ -36,7 +41,7 @@ for your element::
     }
 
 Here we create a symbolic name instead of using the path as the name, and now
-we can refer to that element by name elsewhere in the manifest::
+we can refer to that element by name elsewhere in the manifest:
 
     service { sshd:
         subscribe => file[sshdconfig]
@@ -50,7 +55,7 @@ about the objects it is managing; it knows the name and the type, and it has a
 list of parameters, but those parameters mean nothing in the language.  If you
 provide a symbolic name to a given element, you should always use that single
 name, because otherwise the language will assume you are managing separate
-elements, which might result in an error in the library::
+elements, which might result in an error in the library:
 
     file { sshdconfig:
         path => "/usr/local/etc/ssh/sshd_config",
@@ -66,13 +71,13 @@ to manage the same element, because they have different names.  This will
 result in an error on the client when the second element tries to instantiate
 and it is found to conflict with the first element.
 
-Assignment
-==========
+# Assignment
+
 Puppet has a declarative language, which means that its scoping and assignment
 rules are somewhat different than a normal imperative language.  The primary
 difference is that you cannot change the value of a variable within a single
 scope, because that would rely on file order to determine the value of the
-variable.  This will result in an error::
+variable.  This will result in an error:
 
     $user = root
     file { "/etc/passwd":
@@ -85,7 +90,7 @@ variable.  This will result in an error::
     }
 
 You will almost always find that you can avoid resetting variable values using
-the builtin conditionals_::
+the builtin [conditionals](structures.html#conditionals):
 
     $group = $operatingsystem ? {
         solaris => sysadmin,
@@ -94,10 +99,10 @@ the builtin conditionals_::
 
 This is only one assignment, so no errors.
 
-Overriding
-==========
+# Overriding
+
 Puppet provides a separate scope for every class and component, and scope
-trees are created as a manifest is parsed.  Take the following configuration::
+trees are created as a manifest is parsed.  Take the following configuration:
 
     class base {
         file { "/etc/issue":
@@ -117,11 +122,11 @@ and when this manifest is applied, the latter location is used as the source
 for the file.  This allows you to subclass a class and slightly change its
 behaviour.
 
-Defaults
-========
+# Defaults
+
 Puppet elements are normally specified using a lower-case element type.  You
 can specify default values for a given type using the capitalized form of the
-element type, though::
+element type, though:
 
     Exec { path => "/usr/bin:/bin:/usr/sbin:/sbin" }
 
@@ -137,7 +142,7 @@ look for the executable.  This way you can specify a single default path for
 your entire configuration, and then override that value as necessary.
 
 This can be used for any element type.  For instance, CentOS defaults to using
-``rpm`` for its package type, but you can easily change that to ``yum``::
+``rpm`` for its package type, but you can easily change that to ``yum``:
 
     case $operatingsystem {
         centos: {
@@ -146,5 +151,3 @@ This can be used for any element type.  For instance, CentOS defaults to using
     }
 
     ...
-
-.. _conditionals: /projects/puppet/documentation/structures#conditionals
diff --git a/documentation/notcfengine.rst b/documentation/notcfengine.page
index 1fb3ba002..b96448e57 100644
--- a/documentation/notcfengine.rst
+++ b/documentation/notcfengine.page
@@ -1,14 +1,19 @@
-Cfengine_ is currently the most widely deployed configuration management tool.
-In many ways, Puppet_ can be thought of as a next-generation version of
-cfengine, in that many of puppet's design goals are specifically derived from
-experience with cfengine and are meant to overcome many of cfengine's
-weaknesses.
+---
+inMenu: true
+title: Puppet vs. Cfengine
+---
+
+[Cfengine](http://www.cfengine.org) is currently the most widely deployed
+configuration management tool.  In many ways, [Puppet](/projects/puppet) can
+be thought of as a next-generation version of cfengine, in that many of
+puppet's design goals are specifically derived from experience with cfengine
+and are meant to overcome many of cfengine's weaknesses.
 
 This document summarizes the primary advances that Puppet makes over
 cfengine's current state.
 
-Abstraction
------------
+# Abstraction
+
 Cfengine is a great way to scale common administrative practices -- you can
 move from using SSH and a for loop to using Cfengine pretty smoothly.
 However, there is just as much complexity present in either form.  You still
@@ -24,8 +29,8 @@ each system.  Puppet administrators are free to focus on the complexity of
 their networks, rather than being forced to also handle that complexity plus
 the complexity of the differences between the operating systems.
 
-Dedication
-----------
+# Dedication
+
 Puppet will be supported by an organization dedicated to creating
 the best system automation software, and I expect to have a staff of at
 least a few people dedicated to development, support, consulting, and custom
@@ -46,8 +51,8 @@ goal is also to have multiple developers dedicated full time to Puppet
 development, which should significantly accelerate feature development
 compared to cfengine.
 
-Language Power
---------------
+# Language Power
+
 While the two languages are superficially similar, the puppet language already
 supports two critical features that cfengine forces you to hack around.
 Puppet supports building higher level objects out of a set of low-level
@@ -55,37 +60,37 @@ objects including the ability to parameterize, and has a built-in ability to
 express relationships between objects.  For instance, here is how you might
 define an 'apache' component::
 
-  define apache(docroot,htmlsource,configfile) {
-    # make sure the package is installed
-    package { apache: version => "2.0.51", installed => true }
+    define apache(docroot,htmlsource,configfile) {
+        # make sure the package is installed
+        package { apache: version => "2.0.51", installed => true }
 
-    # pull down the data to serve
-    file { $docroot: source => $htmlsource }
+        # pull down the data to serve
+        file { $docroot: source => $htmlsource }
 
-    # and the config file
-    file { "/etc/apache/httpd.conf": source => $configfile }
+        # and the config file
+        file { "/etc/apache/httpd.conf": source => $configfile }
 
-    # restart the apache service if the package is reinstalled or if
-    # the config file changes; notice no need for 'define' statements
-    # or AddInstallable calls
-    service { apache: running => true,
-      requires => [ package[apache], file["/etc/apache/httpd.conf"] ]
+        # restart the apache service if the package is reinstalled or if
+        # the config file changes; notice no need for 'define' statements
+        # or AddInstallable calls
+        service { apache: running => true,
+            requires => [ package[apache], file["/etc/apache/httpd.conf"] ]
+        }
     }
-  }
 
-  # You could now have different versions of this:
+    # You could now have different versions of this:
 
-  apache {
-    docroot => "/var/wwwprod",
-    htmlsource => "nfs://fileserver/web/wwwprod",
-    configfile => "https://webserver/web/prod.conf"
-  }
+    apache {
+        docroot => "/var/wwwprod",
+        htmlsource => "nfs://fileserver/web/wwwprod",
+        configfile => "https://webserver/web/prod.conf"
+    }
 
-  apache {
-    docroot => "/var/wwwdev",
-    htmlsource => "http://tmpserver/web/wwwdev",
-    configfile => "https://webserver/web/dev.conf"
-  }
+    apache {
+        docroot => "/var/wwwdev",
+        htmlsource => "http://tmpserver/web/wwwdev",
+        configfile => "https://webserver/web/dev.conf"
+    }
 
 This simple level of abstraction already puts you far beyond what cfengine
 can do.  The initial goal is to provide ample power to express the true
@@ -95,8 +100,8 @@ configurations within the cfengine community because of how difficult basic
 abstraction is with cfengine, so one of my primary goals with the language was
 to make abstraction, within a network or across one, downright easy.
 
-Decoupling
-----------
+# Decoupling
+
 Puppet is being written with all components decoupled from each other, using
 clean and preferably industry-standard interfaces between them.  Adding a new
 action to cfengine requires modification of the entire functional stack
@@ -108,8 +113,8 @@ Puppet also uses the industry-standard XMLRPC protocol for communication
 between Puppet clients and servers, so the protocol is easy to study and
 either end could be replaced by another service if desired.
 
-Interactivity
--------------
+# Interactivity
+
 Puppet is being designed to make it easy to get information back
 out of it.  For instance, it will be easy to figure out how many changes
 happened on a given node, even in a given time frame and of a given type,
@@ -118,8 +123,8 @@ ships, it will ship with a small add-on that will automatically graph all
 of this info in RRD files so that you can just enable this and
 automatically get graphs of change rates on your network.
 
-Development Methodology
------------------------
+# Development Methodology
+
 Reductive Labs is a big believer in enhancing developer productivity.  Puppet
 is being written in Ruby because it is a high-level language that is easy to
 use yet provides significant productivity enhancements over low-level
@@ -129,8 +134,8 @@ found a bug.  Lastly, we assiduosly unit test our code.  We're always looking
 for more ways to test our code, and every bug we quash gets turned into a unit
 test so we know we'll never release that bug again.
 
-Examples
---------
+# Examples
+
 I've got some small configurations that exemplify some of the differences.
 Here's how a simple centralized Apache configuration would look in the two
 languages, for instance.  The two manifests just download Apache's
@@ -215,6 +220,3 @@ There are a few specific items worth noting in this comparison:
   anywhere, and the 'apacheserver' class must be set before any code is
   associated with it.  Neither of these is a big deal in small doses, but it
   can get quite complicated as the configuration matures.
-
-.. _cfengine: http://www.cfengine.org
-.. _puppet: /projects/puppet
diff --git a/documentation/puppetd-executable-reference.rst b/documentation/puppetd-executable-reference.page
index bfed7e856..9c0286a7b 100644
--- a/documentation/puppetd-executable-reference.rst
+++ b/documentation/puppetd-executable-reference.page
@@ -1,6 +1,8 @@
-===========================
-Puppet Executable Reference
-===========================
+---
+inMenu: true
+title: Executable Reference
+---
+# Puppet Executable Reference
 
 Every Puppet executable (with the exception of ``puppetdoc``) accepts all of
 these arguments, but not all of the arguments make sense for every executable.
@@ -13,6 +15,10 @@ 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 approprite or not.
 
+* **authconfig** (*puppet*)
+
+  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``.
+
 * **autosign** (*ca*)
 
   Whether to enable autosign.  Valid values are true (which autosigns any key request, and is a very bad idea), false (which never autosigns any key request), and the path to a file, which uses that configuration file to determine which keys to sign.
@@ -77,6 +83,30 @@ argument is approprite or not.
 
   Where the CA stores certificate requests
 
+* **dbadapter** (*puppetmaster*)
+
+  The type of database to use.
+
+* **dblocation** (*puppetmaster*)
+
+  The database cache for client configurations.  Used for querying within the language.
+
+* **dbname** (*puppetmaster*)
+
+  The name of the database to use.
+
+* **dbpassword** (*puppetmaster*)
+
+  The database password for Client caching. Only used when networked databases are used.
+
+* **dbserver** (*puppetmaster*)
+
+  The database server for Client caching. Only used when networked databases are used.
+
+* **dbuser** (*puppetmaster*)
+
+  The database user for Client caching. Only used when networked databases are used.
+
 * **fileserverconfig** (*fileserver*)
 
   Where the fileserver configuration is stored.
@@ -133,14 +163,30 @@ argument is approprite or not.
 
   The LDAP server.  Only used if ``ldapnodes`` is enabled.
 
+* **ldapssl** (*ldap*)
+
+  Whether SSL should be used when searching for nodes. Defaults to false because SSL usually requires certificates to be set up on the client side.
+
 * **ldapstring** (*ldap*)
 
   The search string used to find an LDAP node.
 
+* **ldaptls** (*ldap*)
+
+  Whether TLS should be used when searching for nodes. Defaults to false because TLS usually requires certificates to be set up on the client side.
+
 * **ldapuser** (*ldap*)
 
   The user to use to connect to LDAP.  Must be specified as a full DN.
 
+* **lexical** (*puppet*)
+
+  Whether to use lexical scoping (vs. dynamic).
+
+* **listen** (*puppetd*)
+
+  Whether puppetd should listen for connections.  If this is true, then by default only the ``runner`` server is started, which allows remote authorized and authenticated nodes to connect and trigger ``puppetd`` runs.
+
 * **localconfig** (*puppetd*)
 
   Where puppetd caches the local configuration.  An extension indicating the cache format is added automatically.
@@ -217,6 +263,10 @@ argument is approprite or not.
 
   Which port puppetd listens on.
 
+* **railslog** (*puppetmaster*)
+
+  Where Rails-specific logs are sent
+
 * **req_bits** (*ca*)
 
   The bit length of the certificates.
@@ -245,6 +295,10 @@ argument is approprite or not.
 
   The server to which server puppetd should connect
 
+* **setpidfile** (*puppet*)
+
+  Whether to store a PID file for the daemon.
+
 * **signeddir** (*ca*)
 
   Where the CA stores signed certificates.
@@ -261,9 +315,13 @@ argument is approprite or not.
 
   Where puppetd and puppetmasterd store state associated with the running configuration.  In the case of puppetmasterd, this file reflects the state discovered through interacting with clients.
 
+* **storeconfigs** (*puppetmaster*)
+
+  Whether to store each client's configuration.  This requires ActiveRecord from Ruby on Rails.
+
 * **tags** (*transaction*)
 
-  Tags to use to find objects.  If this is set, then only objects tagged with the specified tags will be applied.  Values must be comma-separated.
+  Tags to use to find objects.  If this is set, then only objects tagged with the specified tags will be applied. Values must be comma-separated.
 
 * **typecheck** (*ast*)
 
@@ -286,4 +344,4 @@ argument is approprite or not.
 ----------------
 
 
-*This page autogenerated on Tue Apr 11 18:37:26 CDT 2006*
+*This page autogenerated on Fri Jun 16 14:45:05 PDT 2006*
diff --git a/documentation/rails-puppet-manager.rst b/documentation/rails-puppet-manager.page
index 6cc0b6b8c..977cc2ec4 100644
--- a/documentation/rails-puppet-manager.rst
+++ b/documentation/rails-puppet-manager.page
@@ -1,9 +1,16 @@
-I have begun work on a simplistic web-based Puppet manager based on Rails_,
-called PuppetShow.  It's in a very primitive state -- including having no
-authentication, so use at your own risk -- but it's a good proof of concept.
+---
+inMenu: true
+title: PuppetShow
+---
 
-To get it working, first check out the code_.  Then set up your apache config
-to serve it.  This is what mine looks like::
+I have begun work on a simplistic web-based Puppet manager based on
+[Rails](http://rubyonrails.org), called PuppetShow.  It's in a very primitive
+state -- including having no authentication, so use at your own risk -- but
+it's a good proof of concept.
+
+To get it working, first check out the
+[code](https://reductivelabs.com/svn/puppetshow).  Then set up your apache
+config to serve it.  This is what mine looks like:
 
     <VirtualHost 192.168.0.101:80 192.168.0.102:80 192.168.0.3:80>
         ServerAdmin luke@madstop.com
@@ -26,7 +33,7 @@ Now we just need to get the puppet internal stuff working.  We could use
 either ``rake`` or Puppet to do this, but for whatever reason I decided to use
 Puppet.  I've created a ``setup.pp`` file in the root of the tree, so you just
 need to modify that as appropriate (in particular, I have a Facter lib that
-sets ``$home`` for me, so you'll probably need to set that), then run::
+sets ``$home`` for me, so you'll probably need to set that), then run:
 
     sudo puppet -v setup.pp
 
@@ -34,7 +41,7 @@ At that point you should have a functional app.  Like I said, there's no
 navigation at all, so you need to know what's out there.  The first thing you
 need to do is start a daemon that this app can connect to.  Pick your victim,
 create a namespace auth file (defaults to
-``/etc/puppet/namespaceauth.conf``)::
+``/etc/puppet/namespaceauth.conf``):
     
     [fileserver]
         allow *.madstop.com
@@ -45,7 +52,7 @@ create a namespace auth file (defaults to
     [pelementserver]
         allow puppet.madstop.com
 
-Then start your client::
+Then start your client:
 
     puppetd -v --listen --no-client
 
@@ -59,6 +66,3 @@ want to look at users; this would be your URL:
 http://puppet.domain.com/remote/culain/user/list
 
 Replace as appropriate for your site.
-
-.. _rails: http://rubyonrails.org
-.. _code: https://reductivelabs.com/svn/puppetshow
diff --git a/documentation/security.rst b/documentation/security.page
index 19c72b929..560f170c5 100644
--- a/documentation/security.rst
+++ b/documentation/security.page
@@ -1,5 +1,8 @@
-Overview
-========
+---
+inMenu: true
+---
+# Overview
+
 Puppet relies on standards wherever possible.  In the case of security, it uses 
 standard SSL certificates for client and server verification.  Because of the
 cost of buying signed certificates for every client and the complexity of
@@ -9,17 +12,17 @@ generate certificates for other purposes.  The primary goal in certificate
 management within Puppet has been to keep it simple, and wherever possible to
 not make it even noticeable.
 
-Certificates
-============
+# Certificates
+
+
+## Authentication
 
-Authentication
---------------
 Certificates are the only method of authentication -- if a client's
 certificate can be verified using standard SSL verification mechanisms, then
 it is considered authenticated.
 
-Client Certificate Generation
------------------------------
+## Client Certificate Generation
+
 The Puppet server, ``puppetmasterd``, is normally also the CA.  Clients who
 do not yet have signed certificates will automatically generate a key pair and
 a certificate request, and then will connect to the server and provide it
@@ -38,8 +41,8 @@ This configuration would autosign certificate requests for
 This configuration file is read each time a signature is asked for, so changes
 to it can be short-lived and will be immediately noticed.
 
-Server-Side Certificate Management
-----------------------------------
+# Server-Side Certificate Management
+
 In the normal case, certificate auto-signing will be disabled.  In these
 cases, certificates will have to be signed using the ``puppetca`` utility.
 Prior to the 1.0 release it is expected that there will be email notification
@@ -49,8 +52,8 @@ must be watched or ``puppetca --list`` can be used list waiting requests.
 Once a request arrives, ``puppetca --sign <hostname>`` can be used to sign the
 request.  Adding the ``--all`` flag will sign all outstanding requests.
 
-Access and Authorization
-========================
+# Access and Authorization
+
 Puppet currently has few network functions, so security has so far been
 treated by them individually.  It is expected that there will be some
 system-wide security hooks prior to the 1.0 release, but the certificate
diff --git a/documentation/structures.rst b/documentation/structures.page
index 1c5818d5b..5359330c2 100644
--- a/documentation/structures.rst
+++ b/documentation/structures.page
@@ -1,11 +1,13 @@
+---
+inMenu: true
+---
+
 This is a brief overview of the language structures 
 available for making site configurations in Puppet.
-For futher documentation, visit the `Puppet homepage`_.
+For futher documentation, visit the [Puppet homepage](/projects/puppet).
 
-.. _puppet homepage: /projects/puppet
+# Types
 
-Types
------
 The basic unit of configuration in Puppet are ``types``.  Types model objects
 on the computer being managed, and each builtin type has attributes that
 determine the final type configuration::
@@ -19,13 +21,13 @@ between using builtin types like ``file`` and ``package`` and using defined
 types.  Any operation or syntax that succeeds for builtin types should also
 work for defined types.
 
-See the `Type Reference`_ for the documentation for the
+See the [Type Reference](typedocs.html) for the documentation for the
 Puppet Library's primitive types.
 
-Assignment
------------
+# Assignment
+
 
-``$variable = value``
+    $variable = value
 
 Variables available in the current scope are referenced
 by preceding them with the ``$`` character. 
@@ -35,14 +37,11 @@ within a sub-scope a new assignment can be made for a
 variable name for that sub-scope and any further 
 sub-scopes created within it::
   
-  $x = foo
-  $y = bar
-  $z = "$x$y"
-
-Bringing Config files together
-------------------------------
+    $x = foo
+    $y = bar
+    $z = "$x$y"
 
-::
+# Bringing Config files together
 
     import "filename"
 
@@ -50,14 +49,13 @@ Starts the parsing of the file specified and creates any specified definitions
 and classes at the current scope.  Currently files are only searched for
 within the same directory as the file doing the importing.
 
-Files can also be imported using globbing, as implemented by Ruby's
-``Dir.glob`` method::
+Files can also be imported using globbing, as implemented by
+Ruby's ``Dir.glob`` method::
 
     import "classes/*"
     import "packages/[a-z]*"
 
-Scope
------
+# Scope
 
 Generally speaking, any language structure that involves curly braces creates
 a new scope inside those braces.  This currently includes server and class
@@ -107,10 +105,9 @@ of ``/file_repository/test-httpd.conf`` to ``/etc/httpd/conf/httpd.conf``::
 
     webserver {}
 
-Components
-----------
+# Components
 
-``define <name>(<param1>,<param2>,...) {...}``
+    define <name>(<param1>,<param2>,...) {...}
 
 Definition of fuctions allows the composition of lower level types into higher
 level types.
@@ -150,8 +147,8 @@ similarly to variables, by preceding their names with the ``$`` character::
     }
 
 Note that calling components results in a unique instance of all contained
-objects.  In the above case, each of the calls to ``svnserver`` results in an
-``exec`` and a ``file`` instance.  So, it's important that all of your
+objects.  In the above case, each of the calls to ``svnserver`` results in
+an ``exec`` and a ``file`` instance.  So, it's important that all of your
 components are written that they support this.
 
 A good rule of thumb is that you should only include statements in your
@@ -160,10 +157,9 @@ have a variable in the name, then you are likely to result in a situation
 where multiple components will try to manage the same instance, which will
 result in an error at run time.
 
-Server Classes
---------------
+# Server Classes
 
-``class <class_name> [inherits <super_class_name>] { ... }``
+    class <class_name> [inherits <super_class_name>] { ... }
 
 Class definitions allow the specification of a hierarchy of server classes; a
 host that is a member of a subclass will apply the configuration from the
@@ -174,8 +170,6 @@ is a member of three different classes, each of which share the same parent
 class, then you will get one instance of the parent class and one instance of
 each of the subclasses.
 
-::
-
     # really simple example
     class solaris {
         file {
@@ -193,13 +187,15 @@ each of the subclasses.
 
     include solworkstation
 
-The ``include`` syntax is syntactically equivalent to specifying a class
-with no arguments.  The above statement is equivalent to this statement::
+Because ``include`` is a function, any normal value can be used, including
+variables and selectors:
+
+    include $operatingsystem, $hostname ? {
+        myhost => classA, default classB
+    }
 
-    solworkstation {}
+## Subclassing
 
-Subclassing
-+++++++++++
 The primary benefit of using subclasses instead of just including the parent
 class is that the subclass can override elements in the parent class::
 
@@ -220,8 +216,8 @@ class is that the subclass can override elements in the parent class::
 Including the ``unix`` class sets the group to ``root``, but including the
 ``bsd`` class overrides the vale to ``wheel``.
 
-Using Classes Outside of Puppet
-+++++++++++++++++++++++++++++++
+## Using Classes Outside of Puppet
+
 This isn't really a "language" thing, but it seemed the best place to document
 this.
 
@@ -247,10 +243,9 @@ even though there is no code associated with them.  The syntax is just like
 
     tag $operatingsystem
 
-Nodes
------
+# Nodes
 
-``node <hostname> { ... }``
+    node <hostname> { ... }
 
 Node definitions specify the configuration to apply to a specific node.  By
 default they are looked for by ``puppetmasterd`` but not by ``puppet``.  See
@@ -281,8 +276,8 @@ Nodes can also inherit from other nodes, so it's easy to apply defaults::
         include webserver
     }
 
-Conditionals
-------------
+# Conditionals
+
 Puppet currently supports two types of conditionals: in-statement and around
 statements.  We call the in-statement conditionals ``selectors``, as they are
 essentially a select-style operator, which support the use of ``default`` to
@@ -299,7 +294,7 @@ specify a default value::
 
 
 
-``case`` provides the ability to conditionally apply
+The ``case`` statement provides the ability to conditionally apply
 types::
 
     case $operatingsystem {
@@ -308,15 +303,13 @@ types::
         default:    { generic {} } # apply the generic class
     }
 
-Reserved words
---------------
+# Reserved words
+
 Generally, any word that the syntax uses for special meaning is probably also
 a reserved word, meaning you cannot use it for variable or type names.  Thus,
 words like ``true``, ``define``, ``inherits``, and ``class`` are all reserved.
 
-Comments
---------
+# Comments
+
 Puppet supports sh-style comments; they can either be on their own line or at
 the end of a line (see the Conditionals_ example above).
-
-.. _type reference: /projects/puppet/documentation/typedocs
diff --git a/documentation/testing.rst b/documentation/testing.page
index fb0a1a870..c19c8697c 100644
--- a/documentation/testing.rst
+++ b/documentation/testing.page
@@ -1,3 +1,8 @@
+---
+inMenu: true
+title: Testing
+---
+
 If you want to just test-drive Puppet, making the least commitment possible,
 you can run it directly from the checked-out source_, against a configuration
 in a temporary directory.
@@ -58,9 +63,9 @@ output of ``puppetmasterd`` for details.
 Configuration Testing
 ---------------------
 Once you're successfully running the daemons, there are other useful flags you
-can use to make your life easier.  First is the '--test' flag for ``puppetd`,
-which is the equivalent of running with
-``--onetime --verbose --no-usecacheonfailure``, which means the puppet client
+can use to make your life easier.  First is the '--test' flag for ``puppetd``,
+which is the equivalent of running with ``--onetime --verbose --no-usecacheonfailure``,
+which means the puppet client
 will exit after the first run and will not use the cached configuration if the
 central one is broken somehow (this is useful for those cases where you
 accidentally cause a parsing error in the config).
diff --git a/documentation/typedocs.rst b/documentation/typedocs.page
index 0c35274eb..bae8ac26a 100644
--- a/documentation/typedocs.rst
+++ b/documentation/typedocs.page
@@ -1,12 +1,13 @@
-==============
-Type Reference
-==============
+---
+inMenu: true
+title: Type Reference
+---
+# Type Reference
+
 
     
 
----------------
-Meta-Parameters
----------------
+## Meta-Parameters
 
 Metaparameters are parameters that work with any element; they are part of the
 Puppet framework itself rather than being part of the implementation of any
@@ -144,9 +145,7 @@ in your manifest, including defined components.
     This way, when you're testing a configuration you can run just the
     portion you're testing.
 
------
-Types
------
+## Types
 
 - *namevar* is the parameter used to uniquely identify a type instance.
   This is the parameter that gets assigned when a string is provided before
@@ -176,8 +175,7 @@ Types
 ----------------
 
 
-cron
-========
+## cron
 Installs and manages cron jobs.  All fields except the command 
 and the user are optional, although specifying no periodic
 fields would result in the command being executed every
@@ -201,8 +199,7 @@ Example::
 
 
 
-Cron Parameters
-''''''''''''''''''''''''''''''
+### Cron Parameters
 - **command**
     The command to execute in the cron job.  The environment
     provided to the command varies by local system rules, and it is
@@ -213,7 +210,18 @@ Cron Parameters
     All cron parameters support ``absent`` as a value; this will
     remove any existing values for that field.
 - **ensure**
-    The basic state that the object should be in.  Valid values are ``absent``, ``present``.
+    The basic state that the object should be in.  Valid values are ``present``, ``absent``.
+- **environment**
+    Any environment settings associated with this cron job.  They
+    will be stored between the header and the job in the crontab.  There
+    can be no guarantees that other, earlier settings will not also
+    affect a given cron job.
+    
+    Also, Puppet cannot automatically determine whether an existing,
+    unmanaged environment setting is associated with a given cron
+    job.  If you already have cron jobs with environment settings,
+    then Puppet will keep those settings in the same place in the file,
+    but will not associate them with a specific job.
 - **hour**
     The hour at which to run the cron job. Optional;
     if specified, must be between 0 and 23, inclusive.
@@ -254,8 +262,7 @@ Cron Parameters
 ----------------
 
 
-exec
-========
+## exec
 Executes external commands.  It is critical that all commands
 executed using this mechanism can be run multiple times without
 harm, i.e., they are *idempotent*.  One useful way to create idempotent
@@ -301,8 +308,7 @@ you to get a native element type for the work you are doing.  In general,
 it is a Puppet bug if you need ``exec`` to do your work.
 
 
-Exec Parameters
-''''''''''''''''''''''''''''''
+### Exec Parameters
 - **command** (*namevar*)
     The actual command to execute.  Must either be fully qualified
     or a search path for the command must be provided.  If the command
@@ -399,8 +405,7 @@ Exec Parameters
 ----------------
 
 
-file
-========
+## file
 Manages local files, including setting ownership and
 permissions, creation of both files and directories, and
 retrieving entire files from remote servers.  As Puppet matures, it
@@ -413,13 +418,13 @@ Reductive Labs and we can hopefully work with you to develop a
 native element to support what you are doing.
 
 
-File Parameters
-''''''''''''''''''''''''''''''
+### File Parameters
 - **backup**
     Whether files should be backed up before
     being replaced.  If a filebucket_ is specified, files will be
     backed up there; else, they will be backed up in the same directory
-    with a ``.puppet-bak`` extension.
+    with a ``.puppet-bak`` extension,, and no backups
+    will be made if backup is ``false``.
     
     To use filebuckets, you must first create a filebucket in your
     configuration::
@@ -428,10 +433,10 @@ File Parameters
             server => puppet
         }
     
-    ``puppetmasterd`` creates a filebucket by default, so you can
-    usually back up to your main server with this configuration.  Once
-    you've described the bucket in your configuration, you can use
-    it in any file::
+    The ``puppetmasterd`` daemon creates a filebucket by default,
+    so you can usually back up to your main server with this
+    configuration.  Once you've described the bucket in your
+    configuration, you can use it in any file::
     
         file { "/my/file":
             source => "/path/in/nfs/or/something",
@@ -448,7 +453,7 @@ File Parameters
     filebucketed files.
 - **checksum**
     How to check whether a file has changed.  **md5**/*lite-md5*/
-    *time*/*mtime*  Valid values are ``md5lite``, ``time``, ``timestamp``, ``mtime``, ``nosum``, ``md5``.  Values can also match ``(?-mix:^\{md5|md5lite|timestamp|mtime|time\})``.
+    *time*/*mtime*  Valid values are ``timestamp``, ``md5``, ``mtime``, ``nosum``, ``time``, ``md5lite``.  Values can also match ``(?-mix:^\{md5|md5lite|timestamp|mtime|time\})``.
 - **content**
     Specify the contents of a file as a string.  Newlines, tabs, and spaces
     can be specified using the escaped syntax (e.g., \n for a newline).  The
@@ -497,7 +502,7 @@ File Parameters
     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``, ``file`` (also called ``present``).  Values can also match ``(?-mix:.)``.
+    and links corresponding to each file.  Valid values are ``directory``, ``absent`` (also called ``false``), ``link``, ``file`` (also called ``present``).  Values can also match ``(?-mix:.)``.
 - **group**
     Which group should own the file.  Argument can be either group
     name or group ID.
@@ -563,8 +568,7 @@ File Parameters
 ----------------
 
 
-filebucket
-==============
+## filebucket
 A repository for backing up files.  If no filebucket is
 defined, then files will be backed up in their current directory,
 but the filebucket can be either a host- or site-global repository
@@ -580,8 +584,7 @@ when transactions are fully supported filebuckets will be used to
 undo transactions.
 
 
-Filebucket Parameters
-''''''''''''''''''''''''''''''
+### Filebucket Parameters
 - **name**
     The name of the filebucket.
 - **path**
@@ -601,8 +604,7 @@ Filebucket Parameters
 ----------------
 
 
-group
-=========
+## group
 Manage groups.  This type can only create groups.  Group
 membership must be managed on individual users.  This element type
 uses the prescribed native tools for creating groups and generally
@@ -614,10 +616,9 @@ for Mac OS X, NetInfo is used.  This is currently unconfigurable,
 but if you desperately need it to be so, please contact us.
 
 
-Group Parameters
-''''''''''''''''''''''''''''''
+### Group Parameters
 - **ensure**
-    The basic state that the object should be in.  Valid values are ``absent``, ``present``.
+    The basic state that the object should be in.  Valid values are ``present``, ``absent``.
 - **gid**
     The group ID.  Must be specified numerically.  If not
     specified, a number will be picked, which can result in ID
@@ -634,15 +635,13 @@ Group Parameters
 ----------------
 
 
-host
-========
+## host
 Installs and manages host entries.  For most systems, these
 entries will just be in /etc/hosts, but some systems (notably OS X)
 will have different solutions.
 
 
-Host Parameters
-''''''''''''''''''''''''''''''
+### Host Parameters
 - **alias**
     Any alias the host might have.  Multiple values must be
     specified as an array.  Note that this state has the same name
@@ -650,7 +649,7 @@ Host Parameters
     make those aliases available in your Puppet scripts and also on
     disk.
 - **ensure**
-    The basic state that the object should be in.  Valid values are ``absent``, ``present``.
+    The basic state that the object should be in.  Valid values are ``present``, ``absent``.
 - **ip**
     The host's IP address.
 - **name**
@@ -661,14 +660,12 @@ Host Parameters
 ----------------
 
 
-mount
-=========
+## mount
 Manages mounted mounts, including putting mount
 information into the mount table.
 
 
-Mount Parameters
-''''''''''''''''''''''''''''''
+### Mount Parameters
 - **atboot**
     Whether to mount the mount at boot.  Not all platforms
     support this.
@@ -685,7 +682,7 @@ Mount Parameters
     Whether to dump the mount.  Not all platforms
     support this.
 - **ensure**
-    Create, remove, or mount a filesystem mount.  Valid values are ``mounted``, ``absent``, ``present``.
+    Create, remove, or mount a filesystem mount.  Valid values are ``present``, ``mounted``, ``absent``.
 - **fstype**
     The mount type.  Valid values depend on the
     operating system.
@@ -702,8 +699,7 @@ Mount Parameters
 ----------------
 
 
-package
-===========
+## package
 Manage packages.  There is a basic dichotomy in package
 support right now:  Some package types (e.g., yum and apt) can
 retrieve their own package files, while others (e.g., rpm and
@@ -717,8 +713,7 @@ using the ``type`` parameter; obviously, if you specify that you
 want to use ``rpm`` then the ``rpm`` tools must be available.
 
 
-Package Parameters
-''''''''''''''''''''''''''''''
+### Package Parameters
 - **adminfile**
     A file containing package defaults for installing packages.
     This is currently only used on Solaris.  The value will be
@@ -733,7 +728,7 @@ Package Parameters
     What state the package should be in.
     *latest* only makes sense for those packaging formats that can
     retrieve new packages on their own and will throw an error on
-    those that cannot.  Valid values are ``absent``, ``latest``, ``present`` (also called ``installed``).
+    those that cannot.  Valid values are ``latest``, ``present`` (also called ``installed``), ``absent``.
 - **instance**
     A read-only parameter set by the package.
 - **name**
@@ -800,15 +795,13 @@ Package Parameters
 ----------------
 
 
-port
-========
+## port
 Installs and manages port entries.  For most systems, these
 entries will just be in /etc/services, but some systems (notably OS X)
 will have different solutions.
 
 
-Port Parameters
-''''''''''''''''''''''''''''''
+### Port Parameters
 - **alias**
     Any aliases the port might have.  Multiple values must be
     specified as an array.  Note that this state has the same name as
@@ -817,7 +810,7 @@ Port Parameters
 - **description**
     The port description.
 - **ensure**
-    The basic state that the object should be in.  Valid values are ``absent``, ``present``.
+    The basic state that the object should be in.  Valid values are ``present``, ``absent``.
 - **name**
     The port name.
 - **number**
@@ -834,8 +827,7 @@ Port Parameters
 ----------------
 
 
-schedule
-============
+## schedule
 Defined schedules for Puppet.  The important thing to understand
 about how schedules are currently implemented in Puppet is that they
 can only be used to stop an element from being applied, they never
@@ -880,8 +872,7 @@ This will cause elements to be applied every 30 minutes by default.
 
 
 
-Schedule Parameters
-''''''''''''''''''''''''''''''
+### Schedule Parameters
 - **name**
     The name of the schedule.  This name is used to retrieve the
     schedule when assigning it to an object::
@@ -952,8 +943,7 @@ Schedule Parameters
 ----------------
 
 
-service
-===========
+## service
 Manage running services.  Service support unfortunately varies
 widely by platform -- some platforms have very little if any
 concept of a running service, and some have a very codified and
@@ -965,8 +955,7 @@ can provide the better behaviour you will get.  Or, you can just
 use a platform that has very good service support.
 
 
-Service Parameters
-''''''''''''''''''''''''''''''
+### Service Parameters
 - **binary**
     The path to the daemon.  This is only used for
     systems that do not support init scripts.  This binary will be
@@ -1031,11 +1020,11 @@ Service Parameters
     sense to set this parameter, as the default is based on
     the builtin service facilities.  The service types available are:
     
-    * ``base``: You must specify everything.
-    * ``init``: Assumes ``start`` and ``stop`` commands exist, but you
+    * **base**: You must specify everything.
+    * **init**: Assumes ``start`` and ``stop`` commands exist, but you
       must specify everything else.
-    * ``debian``: Debian's own specific version of ``init``.
-    * ``smf``: Solaris 10's new Service Management Facility.
+    * **debian**: Debian's own specific version of ``init``.
+    * **smf**: Solaris 10's new Service Management Facility.
       Valid values are ``base``, ``init``, ``debian``, ``redhat``, ``smf``.
 
 
@@ -1043,23 +1032,20 @@ Service Parameters
 ----------------
 
 
-sshkey
-==========
-Installs and manages host entries.  For most systems, these
-entries will just be in /etc/hosts, but some systems (notably OS X)
-will have different solutions.
+## sshkey
+Installs and manages ssh host keys.  At this point, this type
+only knows how to install keys into /etc/ssh/ssh_known_hosts, and
+it cannot manage user authorized keys yet.
 
 
-Sshkey Parameters
-''''''''''''''''''''''''''''''
+### Sshkey Parameters
 - **alias**
     Any alias the host might have.  Multiple values must be
     specified as an array.  Note that this state has the same name
     as one of the metaparams; using this state to set aliases will
-    make those aliases available in your Puppet scripts and also on
-    disk.
+    make those aliases available in your Puppet scripts.
 - **ensure**
-    The basic state that the object should be in.  Valid values are ``absent``, ``present``.
+    The basic state that the object should be in.  Valid values are ``present``, ``absent``.
 - **key**
     The key itself; generally a long string of hex digits.
 - **name**
@@ -1072,14 +1058,12 @@ Sshkey Parameters
 ----------------
 
 
-symlink
-===========
+## symlink
 Create symbolic links to existing files.  **This type is deprecated;
 use file_ instead.**
 
 
-Symlink Parameters
-''''''''''''''''''''''''''''''
+### Symlink Parameters
 - **ensure**
     Create a link to another file.  Currently only symlinks
     are supported, and attempts to replace normal files with
@@ -1108,13 +1092,11 @@ Symlink Parameters
 ----------------
 
 
-tidy
-========
+## tidy
 Remove unwanted files based on specific criteria.
 
 
-Tidy Parameters
-''''''''''''''''''''''''''''''
+### Tidy Parameters
 - **age**
     Tidy files whose age is equal to or greater than
     the specified number of days.
@@ -1122,7 +1104,8 @@ Tidy Parameters
     Whether files should be backed up before
     being replaced.  If a filebucket_ is specified, files will be
     backed up there; else, they will be backed up in the same directory
-    with a ``.puppet-bak`` extension.
+    with a ``.puppet-bak`` extension,, and no backups
+    will be made if backup is ``false``.
     
     To use filebuckets, you must first create a filebucket in your
     configuration::
@@ -1131,10 +1114,10 @@ Tidy Parameters
             server => puppet
         }
     
-    ``puppetmasterd`` creates a filebucket by default, so you can
-    usually back up to your main server with this configuration.  Once
-    you've described the bucket in your configuration, you can use
-    it in any file::
+    The ``puppetmasterd`` daemon creates a filebucket by default,
+    so you can usually back up to your main server with this
+    configuration.  Once you've described the bucket in your
+    configuration, you can use it in any file::
     
         file { "/my/file":
             source => "/path/in/nfs/or/something",
@@ -1173,8 +1156,7 @@ Tidy Parameters
 ----------------
 
 
-user
-========
+## user
 Manage users.  Currently can create and modify users, but
 cannot delete them.  Theoretically all of the parameters are
 optional, but if no parameters are specified the comment will
@@ -1190,12 +1172,11 @@ for Mac OS X, NetInfo is used.  This is currently unconfigurable,
 but if you desperately need it to be so, please contact us.
 
 
-User Parameters
-''''''''''''''''''''''''''''''
+### User Parameters
 - **comment**
     A description of the user.  Generally is a user's full name.
 - **ensure**
-    The basic state that the object should be in.  Valid values are ``absent``, ``present``.
+    The basic state that the object should be in.  Valid values are ``present``, ``absent``.
 - **gid**
     The user's primary group.  Can be specified numerically or
     by name.
@@ -1229,4 +1210,4 @@ User Parameters
 ----------------
 
 
-*This page autogenerated on Wed May 10 11:09:04 CDT 2006*
+*This page autogenerated on Fri Jun 16 14:45:03 PDT 2006*