Merge branch 'master' of github.com:domcleal/puppet into master-old

7 files changed, 85 insertions, 96 deletions

diff --git a/lib/puppet/reference/configuration.rb b/lib/puppet/reference/configuration.rb
index bfa2cb802..e6a8dc20f 100644
--- a/lib/puppet/reference/configuration.rb
+++ b/lib/puppet/reference/configuration.rb
@@ -33,7 +33,7 @@ config = Puppet::Util::Reference.newreference(:configuration, :depth => 1, :doc
     # Leave out the section information; it was apparently confusing people.
     #str += "- **Section**: #{object.section}\n"
     unless val == ""
-      str += "- **Default**: #{val}\n"
+      str += "- *Default*: #{val}\n"
     end
     str += "\n"
   end
@@ -42,12 +42,11 @@ config = Puppet::Util::Reference.newreference(:configuration, :depth => 1, :doc
 end
 
 config.header = "
-Specifying Configuration Parameters
------------------------------------
+## Specifying Configuration Parameters
 
-On The Command-Line
-+++++++++++++++++++
-Every Puppet executable (with the exception of ``puppetdoc``) accepts all of
+### On The Command-Line
+
+Every Puppet executable (with the exception of `puppetdoc`) accepts all of
 the parameters below, but not all of the arguments make sense for every executable.
 
 I have tried to be as thorough as possible in the descriptions of the
@@ -55,60 +54,59 @@ arguments, so it should be obvious whether an argument is appropriate or not.
 
 These parameters can be supplied to the executables either as command-line
 options or in the configuration file.  For instance, the command-line
-invocation below would set the configuration directory to ``/private/puppet``::
+invocation below would set the configuration directory to `/private/puppet`:
 
-  $ puppet agent --confdir=/private/puppet
+    $ puppet agent --confdir=/private/puppet
 
 Note that boolean options are turned on and off with a slightly different
-syntax on the command line::
+syntax on the command line:
 
-  $ puppet agent --storeconfigs
+    $ puppet agent --storeconfigs
 
-  $ puppet agent --no-storeconfigs
+    $ puppet agent --no-storeconfigs
 
 The invocations above will enable and disable, respectively, the storage of
 the client configuration.
 
-Configuration Files
-+++++++++++++++++++
+### Configuration Files
+
 As mentioned above, the configuration parameters can also be stored in a
 configuration file, located in the configuration directory.  As root, the
-default configuration directory is ``/etc/puppet``, and as a regular user, the
-default configuration directory is ``~user/.puppet``.  As of 0.23.0, all
-executables look for ``puppet.conf`` in their configuration directory
+default configuration directory is `/etc/puppet`, and as a regular user, the
+default configuration directory is `~user/.puppet`.  As of 0.23.0, all
+executables look for `puppet.conf` in their configuration directory
 (although they previously looked for separate files).  For example,
-``puppet.conf`` is located at ``/etc/puppet/puppet.conf`` as root and
-``~user/.puppet/puppet.conf`` as a regular user by default.
+`puppet.conf` is located at `/etc/puppet/puppet.conf` as `root` and
+`~user/.puppet/puppet.conf` as a regular user by default.
+
+All executables will set any parameters set within the `[main]` section,
+and each executable will also use one of the `[master]`, `[agent]`.
 
-All executables will set any parameters set within the ``main`` section,
-and each executable will also use one of the ``master``, ``agent``, or
-``user`` sections.
+#### File Format
 
-File Format
-'''''''''''
 The file follows INI-style formatting.  Here is an example of a very simple
-``puppet.conf`` file::
+`puppet.conf` file:
 
-  [main]
-    confdir = /private/puppet
-    storeconfigs = true
+    [main]
+      confdir = /private/puppet
+      storeconfigs = true
 
 Note that boolean parameters must be explicitly specified as `true` or
 `false` as seen above.
 
 If you need to change file parameters (e.g., reset the mode or owner), do
-so within curly braces on the same line::
+so within curly braces on the same line:
 
-  [main]
-    myfile = /tmp/whatever {owner = root, mode = 644}
+    [main]
+      myfile = /tmp/whatever {owner = root, mode = 644}
 
 If you're starting out with a fresh configuration, you may wish to let
 the executable generate a template configuration file for you by invoking
 the executable in question with the `--genconfig` command.  The executable
 will print a template configuration to standard output, which can be
-redirected to a file like so::
+redirected to a file like so:
 
-  $ puppet agent --genconfig > /etc/puppet/puppet.conf
+    $ puppet agent --genconfig > /etc/puppet/puppet.conf
 
 Note that this invocation will replace the contents of any pre-existing
 `puppet.conf` file, so make a backup of your present config if it contains
@@ -117,28 +115,28 @@ valuable information.
 Like the `--genconfig` argument, the executables also accept a `--genmanifest`
 argument, which will generate a manifest that can be used to manage all of
 Puppet's directories and files and prints it to standard output.  This can
-likewise be redirected to a file::
+likewise be redirected to a file:
 
-  $ puppet agent --genmanifest > /etc/puppet/manifests/site.pp
+    $ puppet agent --genmanifest > /etc/puppet/manifests/site.pp
 
 Puppet can also create user and group accounts for itself (one `puppet` group
-and one `puppet` user) if it is invoked as `root` with the `--mkusers` argument::
+and one `puppet` user) if it is invoked as `root` with the `--mkusers` argument:
 
-  $ puppet agent --mkusers
+    $ puppet agent --mkusers
 
-Signals
--------
-The ``puppet agent`` and ``puppet master`` executables catch some signals for special
-handling.  Both daemons catch (``SIGHUP``), which forces the server to restart
-tself.  Predictably, interrupt and terminate (``SIGINT`` and ``SIGTERM``) will shut
-down the server, whether it be an instance of ``puppet agent`` or ``puppet master``.
+## Signals
 
-Sending the ``SIGUSR1`` signal to an instance of ``puppet agent`` will cause it to
+The `puppet agent` and `puppet master` executables catch some signals for special
+handling.  Both daemons catch (`SIGHUP`), which forces the server to restart
+tself.  Predictably, interrupt and terminate (`SIGINT` and `SIGTERM`) will shut
+down the server, whether it be an instance of `puppet agent` or `puppet master`.
+
+Sending the `SIGUSR1` signal to an instance of `puppet agent` will cause it to
 immediately begin a new configuration transaction with the server.  This
-signal has no effect on ``puppet master``.
+signal has no effect on `puppet master`.
+
+## Configuration Parameter Reference
 
-Configuration Parameter Reference
----------------------------------
 Below is a list of all documented parameters.  Not all of them are valid with all
 Puppet executables, but the executables will ignore any inappropriate values.
 
diff --git a/lib/puppet/reference/indirection.rb b/lib/puppet/reference/indirection.rb
index d14510c16..e5b076508 100644
--- a/lib/puppet/reference/indirection.rb
+++ b/lib/puppet/reference/indirection.rb
@@ -8,12 +8,12 @@ reference = Puppet::Util::Reference.newreference :indirection, :doc => "Indirect
   Puppet::Indirector::Indirection.instances.sort { |a,b| a.to_s <=> b.to_s }.each do |indirection|
     ind = Puppet::Indirector::Indirection.instance(indirection)
     name = indirection.to_s.capitalize
-    text += indirection.to_s + "\n" + ("-" * name.length) + "\n\n"
+    text += "## " + indirection.to_s + "\n\n"
 
     text += ind.doc + "\n\n"
 
     Puppet::Indirector::Terminus.terminus_classes(ind.name).sort { |a,b| a.to_s <=> b.to_s }.each do |terminus|
-      text += terminus.to_s + "\n" + ("+" * terminus.to_s.length) + "\n\n"
+      text += "### " + terminus.to_s + "\n\n"
 
       term_class = Puppet::Indirector::Terminus.terminus_class(ind.name, terminus)
 
@@ -26,9 +26,8 @@ end
 
 reference.header = "This is the list of all indirections, their associated terminus classes, and how you select between them.
 
-In general, the appropriate terminus class is selected by the application for you (e.g., ``puppet agent`` would always use the ``rest``
-terminus for most of its indirected classes), but some classes are tunable via normal settings.  These will have ``terminus setting``
-documentation listed with them.
+In general, the appropriate terminus class is selected by the application for you (e.g., `puppet agent` would always use the `rest`
+terminus for most of its indirected classes), but some classes are tunable via normal settings.  These will have `terminus setting` documentation listed with them.
 
 
 "
diff --git a/lib/puppet/reference/metaparameter.rb b/lib/puppet/reference/metaparameter.rb
index 6a319f1c2..c16a1d33a 100644
--- a/lib/puppet/reference/metaparameter.rb
+++ b/lib/puppet/reference/metaparameter.rb
@@ -9,16 +9,17 @@ metaparameter = Puppet::Util::Reference.newreference :metaparameter, :doc => "Al
   }
 
   str = %{
-    Metaparameters
-    --------------
-    Metaparameters are parameters that work with any resource type; they are part of the
-    Puppet framework itself rather than being part of the implementation of any
-    given instance.  Thus, any defined metaparameter can be used with any instance
-    in your manifest, including defined components.
 
-    Available Metaparameters
-    ++++++++++++++++++++++++
-    }
+# Metaparameters
+    
+Metaparameters are parameters that work with any resource type; they are part of the 
+Puppet framework itself rather than being part of the implementation of any
+given instance.  Thus, any defined metaparameter can be used with any instance
+in your manifest, including defined components.
+
+## Available Metaparameters
+
+}
   begin
     params = []
     Puppet::Type.eachmetaparam { |param|
@@ -29,14 +30,6 @@ metaparameter = Puppet::Util::Reference.newreference :metaparameter, :doc => "Al
       a.to_s <=> b.to_s
     }.each { |param|
       str += paramwrap(param.to_s, scrub(Puppet::Type.metaparamdoc(param)), :level => 4)
-      #puts "<dt>#{param}</dt>"
-      #puts tab(1) + Puppet::Type.metaparamdoc(param).scrub.indent($tab)gsub(/\n\s*/,' ')
-      #puts "<dd>"
-      #puts indent(scrub(Puppet::Type.metaparamdoc(param)), $tab)
-      #puts scrub(Puppet::Type.metaparamdoc(param))
-      #puts "</dd>"
-
-      #puts ""
     }
   rescue => detail
     puts detail.backtrace
diff --git a/lib/puppet/reference/network.rb b/lib/puppet/reference/network.rb
index 15e4f6769..fda7931fb 100644
--- a/lib/puppet/reference/network.rb
+++ b/lib/puppet/reference/network.rb
@@ -29,11 +29,11 @@ on the server, and the client knows how to call the handler's methods
 appropriately.
 
 Most handlers are meant to be started on the server, usually within
-``puppet master``, and the clients are mostly started on the client,
-usually within ``puppet agent``.
+`puppet master`, and the clients are mostly started on the client,
+usually within `puppet agent`.
 
 You can find the server-side handler for each interface at
-``puppet/network/handler/<name>.rb`` and the client class at
-``puppet/network/client/<name>.rb``.
+`puppet/network/handler/<name>.rb` and the client class at
+`puppet/network/client/<name>.rb`.
 
 "
diff --git a/lib/puppet/reference/providers.rb b/lib/puppet/reference/providers.rb
index ef33a559b..c85ad23ab 100644
--- a/lib/puppet/reference/providers.rb
+++ b/lib/puppet/reference/providers.rb
@@ -47,7 +47,7 @@ providers = Puppet::Util::Reference.newreference :providers, :title => "Provider
 
       # Add the suitability note
       if missing = provider.suitable?(false) and missing.empty?
-        data << "**X**"
+        data << "*X*"
         suit = true
         functional = true
       else
@@ -86,7 +86,7 @@ providers = Puppet::Util::Reference.newreference :providers, :title => "Provider
       # Add a note for every feature
       features.each do |feature|
         if provider.features.include?(feature)
-          data << "**X**"
+          data << "*X*"
         else
           data << ""
         end
@@ -95,7 +95,7 @@ providers = Puppet::Util::Reference.newreference :providers, :title => "Provider
 
     ret += h(type.name.to_s + "_", 2)
 
-    ret += ".. _#{type.name}: #{"http://docs.puppetlabs.com/references/stable/type.html##{type.name}"}\n\n"
+    ret += "[#{type.name}](#{"http://docs.puppetlabs.com/references/stable/type.html##{type.name}"})\n\n"
     ret += option("Default provider", default)
     ret += doctable(headers, table_data)
 
@@ -111,7 +111,7 @@ providers = Puppet::Util::Reference.newreference :providers, :title => "Provider
   ret
 end
 providers.header = "
-Puppet resource types are usually backed by multiple implementations called ``providers``,
+Puppet resource types are usually backed by multiple implementations called `providers`,
 which handle variance between platforms and tools.
 
 Different providers are suitable or unsuitable on different platforms based on things
diff --git a/lib/puppet/reference/report.rb b/lib/puppet/reference/report.rb
index 481ca2dc1..47fc779ab 100644
--- a/lib/puppet/reference/report.rb
+++ b/lib/puppet/reference/report.rb
@@ -7,16 +7,15 @@ end
 report.header = "
 Puppet clients can report back to the server after each transaction.  This
 transaction report is sent as a YAML dump of the
-``Puppet::Transaction::Report`` class and includes every log message that was
+`Puppet::Transaction::Report` class and includes every log message that was
 generated during the transaction along with as many metrics as Puppet knows how
-to collect.  See `ReportsAndReporting Reports and Reporting`:trac:
-for more information on how to use reports.
+to collect.  See [Reports and Reporting](http://projects.puppetlabs.com/projects/puppet/wiki/Reports_And_Reporting) for more information on how to use reports.
 
 Currently, clients default to not sending in reports; you can enable reporting
-by setting the ``report`` parameter to true.
+by setting the `report` parameter to true.
 
-To use a report, set the ``reports`` parameter on the server; multiple
-reports must be comma-separated.  You can also specify ``none`` to disable
+To use a report, set the `reports` parameter on the server; multiple
+reports must be comma-separated.  You can also specify `none` to disable
 reports entirely.
 
 Puppet provides multiple report handlers that will process client reports:
diff --git a/lib/puppet/reference/type.rb b/lib/puppet/reference/type.rb
index be8742edc..b423387e9 100644
--- a/lib/puppet/reference/type.rb
+++ b/lib/puppet/reference/type.rb
@@ -5,34 +5,34 @@ type = Puppet::Util::Reference.newreference :type, :doc => "All Puppet resource
   Puppet::Type.eachtype { |type|
     next if type.name == :puppet
     next if type.name == :component
+    next if type.name == :whit
     types[type.name] = type
   }
 
   str = %{
 
-    Resource Types
-    --------------
+## Resource Types
 
-    - The *namevar* is the parameter used to uniquely identify a type instance.
+- The *namevar* is the parameter used to uniquely identify a type instance.
   This is the parameter that gets assigned when a string is provided before
   the colon in a type declaration.  In general, only developers will need to
-  worry about which parameter is the ``namevar``.
+  worry about which parameter is the `namevar`.
 
-  In the following code::
+  In the following code:
 
-    file { "/etc/passwd":
-      owner => root,
-      group => root,
-      mode => 644
-    }
+      file { "/etc/passwd":
+        owner => root,
+        group => root,
+        mode => 644
+      }
 
-  ``/etc/passwd`` is considered the title of the file object (used for things like
-  dependency handling), and because ``path`` is the namevar for ``file``, that
-  string is assigned to the ``path`` parameter.
+  `/etc/passwd` is considered the title of the file object (used for things like
+  dependency handling), and because `path` is the namevar for `file`, that
+  string is assigned to the `path` parameter.
 
 - *Parameters* determine the specific configuration of the instance.  They either
   directly modify the system (internally, these are called properties) or they affect
-  how the instance behaves (e.g., adding a search path for ``exec`` instances or determining recursion on ``file`` instances).
+  how the instance behaves (e.g., adding a search path for `exec` instances or determining recursion on `file` instances).
 
 - *Providers* provide low-level functionality for a given resource type.  This is
   usually in the form of calling out to external commands.