further work on converting from rst to markdown

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

5 files changed, 208 insertions, 88 deletions

diff --git a/documentation/fsconfigref.page b/documentation/fsconfigref.page
index ef1cb4036..1a4ff84f1 100644
--- a/documentation/fsconfigref.page
+++ b/documentation/fsconfigref.page
@@ -2,12 +2,13 @@
 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,
 ``puppetmasterd``, and the client function is used through the ``source``
-attribute of ``file`` objects::
+attribute of ``file`` objects:
 
     # copy a remove file to /etc/sudoers
     file { "/etc/sudoers":
@@ -30,7 +31,7 @@ this can be changed using the ``--fsconfig`` flag to ``puppetmasterd``.
 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::
+resembles INI-style files, but it is not exactly the same:
 
     [module]
         path /path/to/files
@@ -59,7 +60,7 @@ All ``deny`` statements are parsed before all ``allow`` statements, so if any
 ## Host Names
 
 Host names can be specified using either a complete hostname, or specifying an
-entire domain using  the ``*`` wildcard::
+entire domain using  the ``*`` wildcard:
 
     [export]
         path /export
@@ -70,7 +71,7 @@ entire domain using  the ``*`` wildcard::
 ## 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::
+addresses or wildcarded addresses, but you can also use CIDR-style notation:
 
     [export]
         path /export
@@ -80,7 +81,7 @@ addresses or wildcarded addresses, but you can also use CIDR-style notation::
 
 ## Global allow
 
-Specifying a single wildcard will let anyone into a module::
+Specifying a single wildcard will let anyone into a module:
 
     [export]
         path /export
diff --git a/documentation/howitworks.page b/documentation/howitworks.page
index 0e63e651f..65a9602d5 100644
--- a/documentation/howitworks.page
+++ b/documentation/howitworks.page
@@ -64,9 +64,9 @@ These three high level phases can each be broken down into more steps.
 
 ## Compile Phase 1: Parsing
 
-:Inputs: Manifests written in the Puppet language
-:Outputs: Parse trees (instances of AST_ objects)
-:Entry: `Puppet::Parser::Parser#parse`_
+* *Inputs* Manifests written in the Puppet language
+* *Outputs* Parse trees (instances of [AST][ast] objects)
+* *Entry* [Puppet::Parser::Parser#parse][parse]
 
 At this point, all Puppet manifests start out as text documents, and it's the
 parser's job to understand those documents.  The parser (defined in
@@ -82,15 +82,15 @@ starts.
 
 ## Compile Phase 2: Interpreting
 
-:Inputs: Parse trees (instances of AST_ objects) and client information
+* *Inputs* Parse trees (instances of [AST][] objects) and client information
     (collection of facts output by [Facter][])
-:Outputs: Trees of TransObject_ and TransBucket_ instances (from
+* *Outputs* Trees of [TransObject][] and [TransBucket][] instances (from
     transportable.rb)
-:Entry: `Puppet::Parser::AST#evaluate`_
-:Exit: `Puppet::Parser::Scope#to_trans`_
+* *Entry* [Puppet::Parser::AST#evaluate][ast_evaluate]
+* *Exit* [Puppet::Parser::Scope#to_trans][]
 
 Most configurations will rely on client information to make decisions.  When
-the Puppet client starts, it loads the Facter_ library, collects all of the
+the Puppet client starts, it loads the [Facter][] library, collects all of the
 facts that it can, and passes those facts to the interpreter.  When you use
 Puppet over a network, these facts are passed over the network to the server
 and the server uses them to compile the client's configuration.
@@ -100,14 +100,14 @@ decisions about the client based on things like operating system and hardware
 architecture, and it also enables the server to insert information about the
 client into the configuration, information like IP address and MAC address.
 
-The interpreter_ combines the parse trees and the client information into a
-tree of simple transportable_ objects which maps roughly to the configuration
+The [interpreter][] combines the parse trees and the client information into a
+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
 
-When you use Puppet, you have the option of using `node elements`_ or not.  If
+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
 case, you must have some kind of explicit selection mechanism for specifying
@@ -120,17 +120,17 @@ just that bit on demand.
 
 ## Configuration Transport
 
-:Inputs: Transportable_ objects
-:Outputs: Transportable_ objects
-:Entry: `Puppet::Server::Master#getconfig`_
-:Exit: `Puppet::Client::MasterClient#getconfig`_
+* *Inputs* [Transportable][] objects
+* *Outputs* [Transportable][] objects
+* *Entry* [Puppet::Server::Master#getconfig][]
+* *Exit* [Puppet::Client::MasterClient#getconfig][]
 
 If you are using the stand-alone puppet executable, there is no configuration
 transport because the client and server are in the same process.  If you are
 using the networked puppetd client and puppetmasterd server, though, the
 configuration must be sent to the client once it is entirely compiled.
 
-Puppet currently converts the Transportable objects to YAML_, which it then
+Puppet currently converts the Transportable objects to [YAML][], which it then
 CGI-escapes and sends over the wire using XMLRPC over HTTPS.  The client
 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
@@ -138,14 +138,14 @@ normal Ruby Transportable objects.
 
 ## Instantiation Phase
 
-:Inputs: Transportable_ objects
-:Outputs: `Puppet::Type`_ instances
-:Entry: `Puppet::Client::MasterClient#getconfig`_
-:Exit: `Puppet::Type#finalize`_
+* *Inputs* [Transportable][] objects
+* *Outputs* [Puppet::Type][] instances
+* *Entry* [Puppet::Client::MasterClient#getconfig][]
+* *Exit* [Puppet::Type#finalize][]
 
-To create Puppet library objects (all of which are instances of `Puppet::Type`_
+To create Puppet library objects (all of which are instances of [Puppet::Type][]
 subclasses), ``to_trans`` is called on the top-level transportable object.
-All container objects get converted to `Puppet::Type::Component`_ instances,
+All container objects get converted to [Puppet::Type::Component][] instances,
 and all normal objects get converted into the appropriate Puppet type
 instance.
 
@@ -165,15 +165,15 @@ references to objects and verify that the objects actually exist.
 
 ## Configuration Phase 1: Comparison
 
-:Inputs: `Puppet::Type`_ instances
-:Outputs: `Puppet::StateChange`_ objects collected in a `Puppet::Transaction`_
+* *Inputs* [Puppet::Type][] instances
+* *Outputs* [Puppet::StateChange][] objects collected in a [Puppet::Transaction][]
     instance
-:Entry: `Puppet::Client::MasterClient#apply`_
-:Exit: `Puppet::Type::Component#evaluate`_
+* *Entry* [Puppet::Client::MasterClient#apply][]
+* *Exit* [Puppet::Type::Component#evaluate][component_evaluate]
 
 Before Puppet does any work at all, it compares its entire configuration to
 the state on disk (or in memory, or whatever).  To do this, it recursively
-iterates across the tree of `Puppet::Type`_ instances (which, again, still
+iterates across the tree of [Puppet::Type][] instances (which, again, still
 roughly maps to the class structure defined in the manifest) and calls
 ``evaluate``.
 
@@ -209,11 +209,11 @@ could cause interesting-in-a-not-particularly-good-way edge cases.
 
 ## Configuration Phase 2: Syncing
 
-:Inputs: `Puppet::Transaction`_ instance containing `Puppet::StateChange`_
+* *Inputs* [Puppet::Transaction][] instance containing [Puppet::StateChange][]
     instances
-:Outputs: Completely configured operating system
-:Entry: `Puppet::Type::Component#evaluate`_
-:Exit: `Puppet::Transaction#evaluate`_
+* *Outputs* Completely configured operating system
+* *Entry* [Puppet::Type::Component#evaluate][component_evaluate]
+* *Exit* [Puppet::Transaction#evaluate][]
 
 The transaction's job is just to execute each change.  The changes themselves
 are responsible for logging everything that happens (one of the reasons that
@@ -258,24 +258,25 @@ 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
-.. _node elements: /projects/puppet/documentation/structures#nodes
-.. _yaml: http://www.yaml.org/
-.. _Puppet::Parser::Parser#parse: /downloads/puppet/apidocs/classes/Puppet/Parser/Parser.html
-.. _Puppet::Parser::AST#evaluate: /downloads/puppet/apidocs/classes/Puppet/Parser/AST.html
-.. _Puppet::Parser::Scope#to_trans: /downloads/puppet/apidocs/classes/Puppet/Parser/Scope.html
-.. _AST: /downloads/puppet/apidocs/classes/Puppet/Parser/AST.html
-.. _TransObject: /downloads/puppet/apidocs/classes/Puppet/TransObject.html
-.. _TransBucket: /downloads/puppet/apidocs/classes/Puppet/TransBucket.html
-.. _Puppet::Server::Master#getconfig: /downloads/puppet/apidocs/classes/Puppet/Server/Master.html
-.. _Puppet::Client::MasterClient#getconfig: /downloads/puppet/apidocs/classes/Puppet/Client/MasterClient.html
-.. _Transportable: /downloads/puppet/apidocs/classes/Puppet/TransBucket.html
-.. _Puppet::StateChange: /downloads/puppet/apidocs/classes/Puppet/StateChange.html
-.. _Puppet::Transaction: /downloads/puppet/apidocs/classes/Puppet/Transaction.html
-.. _Puppet::Client::MasterClient#apply: /downloads/puppet/apidocs/classes/Puppet/Client/MasterClient.html
-.. _Puppet::Type::Component#evaluate: /downloads/puppet/apidocs/classes/Puppet/Type/Component.html
-.. _Puppet::Type::Component: /downloads/puppet/apidocs/classes/Puppet/Type/Component.html
-.. _Puppet::Transaction#evaluate: /downloads/puppet/apidocs/classes/Puppet/Transaction.html
-.. _interpreter: /downloads/puppet/apidocs/classes/Puppet/Parser/Interpreter.html
-.. _Puppet::Type: /downloads/puppet/apidocs/classes/Puppet/Type.html
-.. _Puppet::Type#finalize: /downloads/puppet/apidocs/classes/Puppet/Type.html
+[facter]: /projects/facter
+[parse]: /downloads/puppet/apidocs/classes/Puppet/Parser/Parser.html
+[AST]: /downloads/puppet/apidocs/classes/Puppet/Parser/AST.html
+[node elements]: /projects/puppet/documentation/structures#nodes
+[yaml]: http://www.yaml.org/
+[Puppet::Parser::Parser#parse]: /downloads/puppet/apidocs/classes/Puppet/Parser/Parser.html
+[ast_evaluate]: /downloads/puppet/apidocs/classes/Puppet/Parser/AST.html
+[Puppet::Parser::Scope#to_trans]: /downloads/puppet/apidocs/classes/Puppet/Parser/Scope.html
+[TransObject]: /downloads/puppet/apidocs/classes/Puppet/TransObject.html
+[TransBucket]: /downloads/puppet/apidocs/classes/Puppet/TransBucket.html
+[Puppet::Server::Master#getconfig]: /downloads/puppet/apidocs/classes/Puppet/Server/Master.html
+[Puppet::Client::MasterClient#getconfig]: /downloads/puppet/apidocs/classes/Puppet/Client/MasterClient.html
+[Transportable]: /downloads/puppet/apidocs/classes/Puppet/TransBucket.html
+[Puppet::StateChange]: /downloads/puppet/apidocs/classes/Puppet/StateChange.html
+[Puppet::Transaction]: /downloads/puppet/apidocs/classes/Puppet/Transaction.html
+[Puppet::Client::MasterClient#apply]: /downloads/puppet/apidocs/classes/Puppet/Client/MasterClient.html
+[component_evaluate]: /downloads/puppet/apidocs/classes/Puppet/Type/Component.html
+[Puppet::Type::Component]: /downloads/puppet/apidocs/classes/Puppet/Type/Component.html
+[Puppet::Transaction#evaluate]: /downloads/puppet/apidocs/classes/Puppet/Transaction.html
+[interpreter]: /downloads/puppet/apidocs/classes/Puppet/Parser/Interpreter.html
+[Puppet::Type]: /downloads/puppet/apidocs/classes/Puppet/Type.html
+[Puppet::Type#finalize]: /downloads/puppet/apidocs/classes/Puppet/Type.html
diff --git a/documentation/index.page b/documentation/index.page
new file mode 100644
index 000000000..ab0edb299
--- /dev/null
+++ b/documentation/index.page
@@ -0,0 +1,118 @@
+---
+inMenu: true
+directoryName: Puppet
+---
+
+How to Use This Guide
+=====================
+This guide is largely a pointer to smaller, more focused guides, although it
+includes unique information when no appropriate smaller guide exists.
+
+Introduction to Puppet
+=======================
+
+Puppet is a declarative *language* for expressing system configuration, a
+*client and server* for distributing it, and a *library* for realizing the
+configuration.
+
+The Puppet [Introduction](intro.html) covers the basic architecture and design goals,
+including whether and why you should be using Puppet on your network.
+
+
+Installation
+===============
+There is an [Installation Guide](installation.html) meant for installation of
+Puppet across a network.
+
+There is also a guide for [using Puppet from source](fromsvn.html), and one for
+[testing Puppet](testing.html), to get an idea of what you can do without making a full
+deployment.
+
+Command Line Executables
+==========================
+
+This section will eventually have links to full man-pages for each executable,
+but for now the man pages can be found by running the respective executable
+with the '--help' flag (this requires the Rdoc::usage module, which is
+often missing).
+
+However, most arguments for the executables are in the form of configuration
+parameters used internally in the library.  All of the executables are
+written to accept any of these configuration parameters, and they
+are all defined in the
+[Puppet Executable Reference](puppet-executable-reference.html).
+
+puppet
+    Stand alone Puppet Site Manifest Script evaluator. Parses, evaluates,
+    and implements a Site Manifest locally.
+
+puppetmasterd
+    Puppet Site Manifest Server Daemon. Runs on each host
+    serving/providing configurations to Puppet client hosts.
+
+puppetd
+    Puppet Client Host Configuration Daemon. Runs on each host whose
+    configuration is managed by Puppet. Requests a Host Specific Manifest
+    from a Puppet Manifest Server and implements it locally.
+
+puppetca
+    SSL Certificate Authority Server used for receiving cerification
+    requests from puppet clients. Puppet Client Hosts are required to have
+    their SSL certs signed by their Puppet Manifest Server's Authority
+    before they can be authenticated and authorized to recieve
+    configurations.
+
+puppetdoc
+    Command line tool for printing Puppet Default and Local Type Library
+    reference documentation.  This is really only used internally.
+
+Type and Language Reference
+==============================
+The Puppet reference is split into two pieces:
+
+* [Language Tutorial](languagetutorial.html)
+
+  A simple description of how the Puppet language functions, with multiple
+  examples.
+
+* [Type Reference](typedocs.html)
+
+  A reference of all available Puppet Types.  The types defined in this
+  reference represent the total ability of Puppet to manage your system -- if
+  an object is not in this reference, then Puppet cannot currently manage it.
+
+* [Language Reference](structures.html)
+
+  A reference to all available language structures within Puppet.  This
+  reference presents the limits of and options for expressibility within
+  Puppet.
+
+API Documentation
+=================
+Until I have time to write tutorials on how to extend Puppet, you might find
+some benefit in perusing the [API docs](/downloads/puppet/apidocs).  They're woefully incomplete as of
+the middle of 2006, but I'll be updating them over time.
+
+Configuration
+================
+Most Puppet configuration is currently done directly through the executables
+through the use of command-line flags, although this should largely migrate to
+configuration files before 1.0.  As such, the man pages for the respective
+executables is the appropriate place to look for documentation on
+configuration (e.g., ``puppetmasterd`` for serving and ``puppetd`` for the
+client).
+
+There are some guides already, though:
+
+* [File Serving Configuration](fsconfigref.html)
+
+* [Puppet Certificates and Security](security.html)
+
+Additional Documentation
+========================
+While the above links represent the standard, recommended documentation, there
+is additional information available for those who are interested:
+
+* [Puppet Internals](howitworks.html)
+
+* [How Cfengine compares to Puppet](notcfengine.html)
diff --git a/documentation/installation.page b/documentation/installation.page
index 9102f90d7..b4c7e13dd 100644
--- a/documentation/installation.page
+++ b/documentation/installation.page
@@ -6,13 +6,13 @@ inMenu: true
 You will need to install Puppet on all machines that will use it, including
 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_.
+There are [packages][] available for some platforms, but for the rest
+you will have to install using the [tarball][] or [GEMs][].
 
 ## 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
@@ -76,7 +76,7 @@ this is the package dependency list for Puppet on Debian:
 
 ### Facter
 
-First install facter.  Like Puppet, there are packages_ available for
+First install facter.  Like Puppet, there are [packages][] available for
 some platforms, but you might have to use the tarball:
 
     # get the latest tarball
@@ -87,7 +87,7 @@ some platforms, but you might have to use the tarball:
     cd facter-*
     sudo ruby install.rb # or become root and run install.rb
 
-There are also gems available in the download_ directory.
+There are also gems available in the [download][] directory.
 
 ## Install Puppet
 
@@ -108,7 +108,7 @@ 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`_.
+For more information on RubyGems, see the [Gems User Guide][].
 
 ## Alternative alternative:  Native Packages
 
@@ -116,14 +116,11 @@ 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
 Red Hat Enterprise 4 and Fedora Core 4.  You can get them from his
-`yum repository`_.
+[yum repository][].
 
-There are also `Debian packages`_, although they are not quite as well
+There are also [Debian packages][], although they are not quite as well
 maintained as the RPMs.
 
-.. _yum repository: http://people.redhat.com/~dlutter/yum/
-.. _debian packages: /downloads/packages/Debian
-
 # Building the Server
 
 ## Create Your Site Manifest
@@ -141,12 +138,12 @@ You could have multiple, separate site manifests if you wanted, but at this
 point each of them would need their own servers.
 
 For more information on how to create the site manifest, see the
-`Language Reference`_ and the `Library Reference`_.
+[Language Reference][] and the [Library Reference][].
 
 Puppet will look for your site manifest in ``/etc/puppet/manifests/site.pp``,
 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.
+some kind of [version control][] on your manifests.
 
 ### Example Manifests
 
@@ -222,7 +219,7 @@ The daemon should start just fine with no arguments:
 It will automatically create all necessary certificates, directories, and
 files.  If you want the daemon to also function as a file server, so your
 clients can copy files from it, you will need to create a
-`fileserver configuration file`_.
+[fileserver configuration file][].
 
 If you are still only testing, and do not have node definitions in your
 site manifest (such as with the above example manifest) , tell
@@ -278,7 +275,7 @@ 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
+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.
@@ -294,15 +291,18 @@ Puppet:
   timeout of 60 seconds.
 * Patches are not only welcome, they're encouraged.
 
-.. _developed: /projects/facter
-.. _download: /downloads
-.. _version control: http://svnbook.red-bean.com/
-.. _fileserver configuration file: fsconfigref
-.. _Gems User Guide: http://docs.rubygems.org/read/book/1
-.. _Language Reference: structures
-.. _Library Reference: typedocs
-
-.. _packages: /downloads/packages
-.. _tarball: /downloads/puppet
-.. _gems: /downloads/gems
-.. _rpms: /downloads/rpm
+[developed]: /projects/facter
+[download]: /downloads
+[version control]: http://svnbook.red-bean.com/
+[fileserver configuration file]: fsconfigref
+[Gems User Guide]: http://docs.rubygems.org/read/book/1
+[Language Reference]: structures
+[Library Reference]: typedocs
+
+[packages]: /downloads/packages
+[tarball]: /downloads/puppet
+[gems]: /downloads/gems
+[rpms]: /downloads/rpm
+
+[yum repository]: http://people.redhat.com/~dlutter/yum/
+[debian packages]: /downloads/packages/Debian
diff --git a/documentation/testing.page b/documentation/testing.page
index c19c8697c..7ebe49e54 100644
--- a/documentation/testing.page
+++ b/documentation/testing.page
@@ -4,7 +4,7 @@ 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
+you can run it directly from the checked-out [source][], against a configuration
 in a temporary directory.
 
 The default Puppet configuration directory (where it looks for its manifests,
@@ -55,7 +55,7 @@ and run it.  In noop mode, this should work for any user, but if you run it as
 a normal user you might get some errors if you are not in noop mode (e.g.,
 normal users cannot use 'chown').
 
-Note that your ``site.pp`` file should have a node_ definition for the host
+Note that your ``site.pp`` file should have a [node][] definition for the host
 connecting; otherwise you will get an error complaining of no configuration for
 that host.  It is possible to skip this requirement -- see the ``--help``
 output of ``puppetmasterd`` for details.
@@ -83,5 +83,5 @@ element, all the way up to the base of the configuration, and it is also
 tagged with the host name.  So if 'classA' includes 'classB' which creates
 'fileC', then 'fileC' will be tagged with both classes.
 
-.. _node: structures#nodes
-.. _source: fromsvn
+[node]: structures#nodes
+[source]: fromsvn