Updating documentation

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

8 files changed, 214 insertions, 47 deletions

diff --git a/documentation/Rakefile b/documentation/Rakefile
index a2d36fa56..cb01fdc21 100644
--- a/documentation/Rakefile
+++ b/documentation/Rakefile
@@ -32,7 +32,12 @@ task :html => htmlfiles
 
 task :default => :html
 
-task :docs do
-    sh %{puppetdoc --arguments > documentation/reference/configref.page}
-    sh %{puppetdoc --types > documentation/reference/typedocs.page}
+docs = %w{configref types reports functions}
+
+docs.each do |doc|
+    task doc do
+        sh %{puppetdoc --mode %s > documentation/reference/%s.page} % [doc, doc]
+    end
 end
+
+task :docs => docs
diff --git a/documentation/documentation/about/glossary.page b/documentation/documentation/about/glossary.page
new file mode 100644
index 000000000..cd7a94b3a
--- /dev/null
+++ b/documentation/documentation/about/glossary.page
@@ -0,0 +1,56 @@
+---
+inMenu: true
+title: A Glossary of Terms
+orderInfo: 3
+subtreeLevel: 6
+---
+
+As developers have found time and time again, terminology is critical to
+successful projects.  The Puppet community has begun to coalesce around
+certain terms found to be useful in working with Puppet:
+
+* **client**:  An operating system instance managed by Puppet.  This can be
+  an OS running on its own hardware or a virtual image.
+
+* **defined type**:  A type written in Puppet's language.  Also sometimes
+  called ``definitions`` or ``components``.
+
+* **manifest**:  A configuration file written in the Puppet language.
+
+* **native type**:  A type written purely in Ruby.
+
+* **provider**:  A simple implementation of a type; examples of package
+  providers are ``dpkg`` and ``rpm``, and examples of user providers are
+  ``useradd`` and ``netinfo``.  Most often, providers are just Ruby wrappers
+  around shell commands, and they are usually very short and thus easy to
+  create.
+
+* **resource**:  An element to be managed on a client, such as a user, group,
+  or package.  Resources do not always directly map to simple details on the
+  client -- they might sometimes involve spreading information across multiple
+  files, or even involve modifying devices.
+
+* **resource object**:  A Puppet object in memory meant to manage a resource
+  on disk.  Resource specifications get converted to these, and then they
+  are used to perform any necessary work.
+
+* **resource specification**:  The details of how to manage a resource as
+  specified in Puppet code.  When speaking about resources, it is sometimes
+  important to differentiate between the literal resource on disk and the
+  specification for how to manage that resource; most often, these are just
+  referred to as resources.
+
+* **type**:  Also called ``resource type``.  A class of resources that can be
+  managed.  Types determine the modeling of the resources they are meant to
+  manage -- e.g., what attributes are valid, and what the valid values are for
+  those attributes.
+
+Here is a simple glossary of term
+
+About Puppet
+=====================
+* [Introduction](introduction.html)
+* [Puppet vs. Cfengine](notcfengine.html)
+
+
+*$Id$*
diff --git a/documentation/documentation/about/index.page b/documentation/documentation/about/index.page
index 4250ecc12..6956fc505 100644
--- a/documentation/documentation/about/index.page
+++ b/documentation/documentation/about/index.page
@@ -10,6 +10,7 @@ About Puppet
 =====================
 * [Introduction](introduction.html)
 * [Puppet vs. Cfengine](notcfengine.html)
+* [Glossary](glossary.html)
 
 
 
diff --git a/documentation/documentation/about/notcfengine.page b/documentation/documentation/about/notcfengine.page
index 711660f95..af482f35d 100644
--- a/documentation/documentation/about/notcfengine.page
+++ b/documentation/documentation/about/notcfengine.page
@@ -19,6 +19,29 @@ cfengine's current state.  Left out of this document are any process decisions
 that also led to Puppet's creation (e.g., the difficulty in getting
 significant changes accepted to cfengine).
 
+# Extensibility
+
+One of the biggest differences between Cfengine and Puppet is how easy it is
+to extend Puppet.  There are many places in Puppet where you can create your
+own classes and Puppet will load them automatically, making them available for
+use immediately with no modification to the core.  For instance, you can
+create [new native resource types](../programmers/creating-a-puppet-type.html)
+(that is, types written entirely in Ruby), drop them where Ruby can find them,
+and just start using them -- Puppet will automatically load those types for
+you.  In addition to the types themselves, you can create
+[new providers](../programmers/providers.html), to support new package
+managers, for instance.  There are a few other areas that will automatically
+load your extensions, such as the report handlers.
+
+In contrast, Cfengine has a very limited interface for expansion -- you can
+call out to modules using a shell interface.  This limits the interface itself
+to being very simple, but it also means you don't get good logging, noop
+control, or much else.
+
+You could theoretically add new native types in C to Cfengine, but that would
+require modification of the entire tree, from the lexer through the parser and
+all the way through to the backend.
+
 # Abstraction
 
 Cfengine is a great way to scale common administrative practices -- you can
diff --git a/documentation/documentation/language/structures.page b/documentation/documentation/language/structures.page
index 8c7cb030b..b015b9fe1 100644
--- a/documentation/documentation/language/structures.page
+++ b/documentation/documentation/language/structures.page
@@ -4,46 +4,11 @@ title: Control Structures
 orderInfo: 30
 ---
 
-This is a brief overview of the language structures 
-available for making site configurations in Puppet.
-For futher documentation, visit the [Puppet homepage](/projects/puppet/).
+This is a brief overview of the language structures available for making site
+configurations in Puppet.  For futher documentation, visit the
+[Puppet homepage](/projects/puppet/).
 
-<h1><a name="types">Types</a></h1>
-
-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:
-
-    file { "/etc/passwd": owner => root, mode => 644 } 
-    package { apache: install => true }
-
-Puppet also provides facilities for defining new types as collections of
-existing types (see Components below), but there is no syntactic difference
-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](typedocs.html) for the documentation for the
-Puppet Library's primitive types.
-
-<h1><a name="assignment">Assignment</a></h1>
-
-
-    $variable = value
-
-Variables available in the current scope are referenced
-by preceding them with the ``$`` character. 
-
-Once assigned, variables cannot be reassigned. However,
-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
+# Importing Manifests
 
     import "filename"
 
diff --git a/documentation/documentation/language/tutorial.page b/documentation/documentation/language/tutorial.page
index 5179e7b86..ca3529e1f 100644
--- a/documentation/documentation/language/tutorial.page
+++ b/documentation/documentation/language/tutorial.page
@@ -102,12 +102,13 @@ This is only one assignment, so no errors.
 
 # Fact Variables (facts)
 
-In addition to variables that are manually assigned (as above), `puppet` also uses
-the [facter](/projects/facter/index.html) utility to glean information about the system.
-The facts gleaned by `facter` are made available as variables for use in `puppet`.
+In addition to variables that are manually assigned (as above), `puppet` also
+uses the [facter](/projects/facter/index.html) utility to glean information
+about the system.  The facts gleaned by `facter` are made available as
+variables for use in `puppet`.
 
-You can get a full listing of variables that should be set by `puppet` from `facter` facts by
-running the `facter` command with no arguments, for instance:
+You can get a full listing of variables that should be set by `puppet` from
+`facter` facts by running the `facter` command with no arguments, for instance:
 
     $ facter
     rubysitedir => /usr/lib/ruby/site_ruby/1.8
diff --git a/documentation/documentation/reference/functions.page b/documentation/documentation/reference/functions.page
new file mode 100644
index 000000000..f494df4d8
--- /dev/null
+++ b/documentation/documentation/reference/functions.page
@@ -0,0 +1,48 @@
+inMenu: true
+title: Function Reference
+orderInfo: 40
+
+There are two types of functions in Puppet: Statements and rvalues.
+Statements stand on their own and do not return arguments; they are used for
+performing stand-alone work like importing.  Rvalues return values and can
+only be used in a statement requiring a value, such as an assignment or a case
+statement.
+
+Here are the functions available in Puppet:
+
+* **alert** *statement*:  Log a message on the server at level alert.
+
+* **crit** *statement*:  Log a message on the server at level crit.
+
+* **debug** *statement*:  Log a message on the server at level debug.
+
+* **defined** *rvalue*:  Determine whether a given type is defined, either as a native type or a defined type.
+
+* **emerg** *statement*:  Log a message on the server at level emerg.
+
+* **err** *statement*:  Log a message on the server at level err.
+
+* **fail** *statement*:  Fail with a parse error.
+
+* **include** *statement*:  Evaluate one or more classes.
+
+* **info** *statement*:  Log a message on the server at level info.
+
+* **notice** *statement*:  Log a message on the server at level notice.
+
+* **realize** *statement*:  Make a virtual object real.  This is useful when you want to know the name of the virtual object and don't want to bother with a full collection.  It is slightly faster than a collection, and, of course, is a bit shorter.  You must pass the object using a reference; e.g.: ``realize User[luke]``.
+
+* **tag** *statement*:  Add the specified tags to the containing class or definition.  All contained objects will then acquire that tag, also. 
+
+* **tagged** *rvalue*:  A boolean function that tells you whether the current container is tagged with the specified tags. The tags are ANDed, so thta all of the specified tags must be included for the function to return true.
+
+* **template** *rvalue*:  Evaluate a template and return its value.  See [the templating docs](../advanced/templating.html) for more information.
+
+* **warning** *statement*:  Log a message on the server at level warning.
+
+
+
+----------------
+
+
+*This page autogenerated on Thu Nov 09 14:09:57 CST 2006*
diff --git a/documentation/documentation/reference/reports.page b/documentation/documentation/reference/reports.page
new file mode 100644
index 000000000..61776efce
--- /dev/null
+++ b/documentation/documentation/reference/reports.page
@@ -0,0 +1,68 @@
+Puppet clients can report back to the server after each
+transaction.  This transaction report is sent as a YAML dump and includes every
+log message that was generated during the transaction along with as many metrics
+as Puppet knows how to collect.
+
+Currently, clients default to not sending in reports; you can enable reporting
+by setting the ``report`` parameter to true.
+
+Puppet provides multiple report handlers that will process client reports:
+
+## rrdgraph
+
+Graph all available data about hosts using the RRD library.  You
+must have the RRD binary library installed to use this report, which
+you can get from [Tobias Oetiker's site](http://people.ee.ethz.ch/~oetiker/webtools/rrdtool/pub/contrib/).
+
+This report will create, manage, and graph RRD database files for each
+of the metrics generated during transactions, and it will create a
+few simple html files to display the reporting host's graphs.  At this
+point, it will not create a common index file to display links to
+all hosts.
+
+All RRD files and graphs get created in the ``rrddir`` directory.  If
+you want to serve these publicly, you should be able to just alias that
+directory in a web server.
+
+## store
+
+Store the yaml report on disk.  Each host sends its report as a YAML dump
+and this just stores the file on disk, in the ``reportdir`` directory.
+
+These files collect quickly -- one every half hour -- so it is a good idea
+to perform some maintenance on them if you use this report (it's the only
+default report).
+
+## tagmail
+
+This report sends specific log messages to specific email addresses
+based on the tags in the log messages.  See the
+[tag documentation](../advanced/tags.html) for more information on tags.
+
+To use this report, you must create a ``tagmail.conf`` (in the location
+specified by ``tagmap``).  This is a simple file that maps tags to
+email addresses:  Any log messages in the report that match the specified
+tags will be sent to the specified email addresses.
+
+Tags must be comma-separated, and they can be negated so that messages
+only match when they do not have that tag.  The tags are separated from
+the email addresses by a colon, and the email addresses should also
+be comma-separated.
+
+Lastly, there is an ``all`` tag that will always match all log messages.
+
+Here is an example tagmail.conf:
+
+    all: me@domain.com
+    webserver, !mailserver: httpadmins@domain.com
+
+This will send all messages to ``me@domain.com``, and all messages from
+webservers that are not also from mailservers to ``httpadmins@domain.com``.
+
+
+
+
+----------------
+
+
+*This page autogenerated on Thu Nov 09 14:29:10 CST 2006*