Rewrote functions documentation to Markdown

7 files changed, 64 insertions, 71 deletions

diff --git a/lib/puppet/reference/configuration.rb b/lib/puppet/reference/configuration.rb
index bfa2cb802..fadd1a423 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
@@ -47,7 +47,7 @@ Specifying Configuration Parameters
 
 On The Command-Line
 +++++++++++++++++++
-Every Puppet executable (with the exception of ``puppetdoc``) accepts all of
+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 +55,61 @@ 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
 +++++++++++++++++++
+
 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``, or
-``user`` sections.
+All executables will set any parameters set within the `[main]` section,
+and each executable will also use one of the `[master]`, `[agent]`.
 
 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 +118,30 @@ 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``.
 
-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
 ---------------------------------
+
 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..0cdbb2510 100644
--- a/lib/puppet/reference/indirection.rb
+++ b/lib/puppet/reference/indirection.rb
@@ -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..39c4b7f5f 100644
--- a/lib/puppet/reference/metaparameter.rb
+++ b/lib/puppet/reference/metaparameter.rb
@@ -29,14 +29,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..b44b26a51 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
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..2378bb83a 100644
--- a/lib/puppet/reference/type.rb
+++ b/lib/puppet/reference/type.rb
@@ -16,25 +16,25 @@ type = Puppet::Util::Reference.newreference :type, :doc => "All Puppet resource
     - 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
+  - *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
+  - *Providers* provide low-level functionality for a given resource type.  This is
   usually in the form of calling out to external commands.
 
   When required binaries are specified for providers, fully qualifed paths
@@ -42,7 +42,7 @@ type = Puppet::Util::Reference.newreference :type, :doc => "All Puppet resource
   binaries indicate that Puppet will search for the binary using the shell
   path.
 
-- *Features* are abilities that some providers might not support.  You can use the list
+  - *Features* are abilities that some providers might not support.  You can use the list
   of supported features to determine how a given provider can be used.
 
   Resource types define features they can use, and providers can be tested to see