7 files changed, 65 insertions, 16 deletions
diff --git a/manifests/defines/append_if_no_such_line.pp b/manifests/defines/append_if_no_such_line.pp
new file mode 100644
index 0000000..6ccf9f9
--- /dev/null
+++ b/manifests/defines/append_if_no_such_line.pp
@@ -0,0 +1,14 @@
+#
+# This define is only for "CFEngine compatability". It is only a light
+# wrapper around the "line" define, which is equally dangerous, but at
+# least named according to a proper resource model.
+#
+define append_if_no_such_line($file, $line) {
+	line {
+		$name:
+			ensure => present,
+			file => $file,
+			line => $line;
+	}
+}
+
diff --git a/manifests/defines/config_file.pp b/manifests/defines/config_file.pp
index 2272558..2be2460 100644
--- a/manifests/defines/config_file.pp
+++ b/manifests/defines/config_file.pp
@@ -2,6 +2,8 @@
 # Copyright (C) 2007 David Schmitt <david@schmitt.edv-bus.at>
 # See LICENSE for the full license granted to you.
 
+# A simple wrapper to give all configuration files common defaults.
+#
 # Usage:
 # config_file { filename:
 #     content => "....\n",
diff --git a/manifests/defines/line.pp b/manifests/defines/line.pp
index 7ca3191..ccfa357 100644
--- a/manifests/defines/line.pp
+++ b/manifests/defines/line.pp
@@ -2,27 +2,38 @@
 # Copyright (C) 2007 David Schmitt <david@schmitt.edv-bus.at>
 # See LICENSE for the full license granted to you.
 
-# Usage:
-# line { description:
-#   file => "filename",
-#   line => "content",
-#   ensure => {absent,*present*}
-# }
+# Ensures that a specific line is present or absent in a file. This can
+# be very brittle, since even small changes can throw this off.
 #
-# Example:
-# The following ensures that the line "allow ^$munin_host$" exists
-# in /etc/munin/munin-node.conf, and if there are any changes notify the service for
-# a restart
+# If the line is not present yet, it will be appended to the file.
+# 
+# The name of the define is not used. Just keep it (globally) unique and
+# descriptive.
 #
-# line { allow_munin_host:
-#       file => "/etc/munin/munin-node.conf",
-#       line => "allow ^$munin_host$",
-#       ensure => present,
-#       notify => Service[munin-node],
-#       require => Package[munin-node],
+# Use this only for very trivial stuff. Usually replacing the whole file
+# is a more stable solution with less maintenance headaches afterwards.
+#
+# Usage:
+# line {
+#   description:
+#     file => "filename",
+#     line => "content",
+#     ensure => {absent,*present*}
 # }
 #
+# Example:
+# The following ensures that the line "allow ^$munin_host$" exists in
+# /etc/munin/munin-node.conf, and if there are any changes notify the
+# service for a restart
 #
+#  line {
+#  	allow_munin_host:
+#  		file => "/etc/munin/munin-node.conf",
+#  		line => "allow ^$munin_host$",
+#  		ensure => present,
+#  		notify => Service[munin-node],
+#  		require => Package[munin-node];
+#  }
 define line($file, $line, $ensure = 'present') {
   case $ensure {
     default : { err ( "unknown ensure value '${ensure}'" ) }
diff --git a/manifests/defines/module_dir.pp b/manifests/defines/module_dir.pp
index 613cc49..227fe71 100644
--- a/manifests/defines/module_dir.pp
+++ b/manifests/defines/module_dir.pp
@@ -4,6 +4,15 @@
 # Copyright (C) 2007 David Schmitt <david@schmitt.edv-bus.at>
 # See LICENSE for the full license granted to you.
 
+# A module_dir is a storage place for all the stuff a module might want to
+# store. According to the FHS, this should go to /var/lib. Since this is a part
+# of puppet, the full path is /var/lib/puppet/modules/${name}. Every module
+# should # prefix its module_dirs with its name.
+# 
+# By default, the module_dir is loaded from "puppet:///${name}/module_dir". If
+# that doesn't exist an empty directory is taken as source. The directory is
+# purged so that modules do not have to worry about removing cruft.
+# 
 # Usage:
 # include common::moduledir
 # module_dir { ["common", "common/dir1", "common/dir2" ]: }
diff --git a/manifests/defines/module_file.pp b/manifests/defines/module_file.pp
index 43b3c48..70e5cbf 100644
--- a/manifests/defines/module_file.pp
+++ b/manifests/defines/module_file.pp
@@ -4,6 +4,8 @@
 # Copyright (C) 2007 David Schmitt <david@schmitt.edv-bus.at>
 # See LICENSE for the full license granted to you.
 
+# Put a file into module-local storage.
+#
 # Usage:
 # modules_file { "module/file":
 #     source => "puppet:///...",
diff --git a/manifests/defines/replace.pp b/manifests/defines/replace.pp
index 7dabe59..dd8db4d 100644
--- a/manifests/defines/replace.pp
+++ b/manifests/defines/replace.pp
@@ -2,6 +2,16 @@
 # Copyright (C) 2007 David Schmitt <david@schmitt.edv-bus.at>
 # See LICENSE for the full license granted to you.
 
+# A hack to replace all occurrences of a regular expression in a file with a
+# specified string. Sometimes it can be less effort to replace only a single
+# value in a huge config file instead of creating a template out of it. Still,
+# creating a template is often better than this hack.
+#
+# This define uses perl regular expressions.
+#
+# Use this only for very trivial stuff. Usually replacing the whole file is a
+# more stable solution with less maintenance headaches afterwards. 
+# 
 # Usage:
 #
 # replace { description:
diff --git a/manifests/init.pp b/manifests/init.pp
index 3770897..3a9faf5 100644
--- a/manifests/init.pp
+++ b/manifests/init.pp
@@ -3,3 +3,4 @@
 # See LICENSE for the full license granted to you.
 
 import "defines/*.pp"
+