reformat the README to be easier on the eyes

add more detailed information for $custom_sources_list with an example
add information about $custom_preferences with an example
add information about $custom_key_dir
add information about the apt::preseeded_package resource
add information about the apt::upgrade_package resource

README

@@ -19,24 +19,55 @@ This module needs lsb-release installed.
 Variables
 =========
 
-$apt_clean: Sets DSelect::Clean, defaults to 'auto' on normal hosts and
-	'pre-auto' in vservers, since the latter are usually more space-bound and
-	have better recovery mechanisms via the host
-	From apt.conf(5), 0.7.2: "Cache Clean mode; this value may be one of
-		always, prompt, auto, pre-auto and never. always and prompt will
-		remove all packages from the cache after upgrading, prompt (the
-		default) does so conditionally.  auto removes only those
-		packages which are no longer downloadable (replaced with a new
-		version for instance). pre-auto performs this action before
-		downloading new packages."
+$apt_clean
+----------
+Sets DSelect::Clean, defaults to 'auto' on normal hosts and 'pre-auto'
+in vservers, since the latter are usually more space-bound and have
+better recovery mechanisms via the host:
+
+From apt.conf(5), 0.7.2: 
+     "Cache Clean mode; this value may be one of always, prompt, auto,
+     pre-auto and never. always and prompt will remove all packages
+     from the cache after upgrading, prompt (the default) does so
+     conditionally.  auto removes only those packages which are no
+     longer downloadable (replaced with a new version for
+     instance). pre-auto performs this action before downloading new
+     packages."
 
 
-$lsbdistcodename: Contains the codename ("etch", "lenny", ...) of the client's
-	release. While these values come from lsb-release by default, this value
-	can be set manually too, e.g. to enable forced upgrades
+$lsbdistcodename
+---------------- 	
+Contains the codename ("etch", "lenny", ...) of the client's
+release. While these values come from lsb-release by default, this
+value can be set manually too, e.g. to enable forced upgrades
 
-$custom_sources_list: If non-empty, the contents of this variable are used as
-	new sources.list for the node.
+$custom_sources_list
+--------------------
+By default this module will use a basic apt/sources.list with a
+generic debian mirror. If you need to set more specific sources,
+e.g. for country proximity, proxies, etc. you can set this variable to
+the location of your sources.list template.  For example, setting the
+following variable before including this class will pull in the
+templates/apt/sources.list file: 
+$custom_sources_list ='template("apt/sources.list")'
+		       
+$custom_preferences	
+--------------------
+By default this module will use a basic apt/preferences file with
+unstable and testing pinned to very low values so that any package
+installation will not accidentally pull in packages from those suites
+unless you explicitly specify the version number. You can set this
+variable to pull in a customized apt/preferences template, for
+example, setting the following variable before including this class
+will pull in the templates/apt/preferences file: 
+$custom_preferences = 'template("apt/preferences")'
+
+$custom_key_dir
+---------------
+If you have different apt-key files that you want to get added to your
+apt keyring, you can set this variable to a path in your fileserver
+where individual key files can be placed. If this is set and keys
+exist there, this module will apt-key add each key
 
 Classes
 =======
@@ -48,13 +79,45 @@ functionality.
 Resources
 =========
 
-File[apt_config]: Use this resource to depend on or add to a completed apt
-	configuration
+File[apt_config]
+----------------
+Use this resource to depend on or add to a completed apt configuration
 
-Exec[apt_updated]: After this point, current packages can installed via apt,
-	usually used like this:
-	Package { require => Exec[apt_updated] }
+Exec[apt_updated]
+-----------------
+After this point, current packages can installed via apt, usually used
+like this: 
 
+Package { require => Exec[apt_updated] }
+
+apt::preseeded_package
+----------------------
+This simplifies installation of packages that you wish to preseed the
+answers to debconf. For example, if you wish to provide a preseed file
+for the locales package, you would place the locales.seed file in 
+templates/$debian_version/locales.seeds and then include the following
+in your manifest:
+
+apt::preseeded_package { locales: }
+
+apt::upgrade_package
+--------------------
+This simplifies upgrades for DSA security announcements or point-releases. This
+will ensure that the named package is upgrade to the version specified, only if the
+package is installed, otherwise nothing happens. If the specified version is 'latest' (the
+default), then the package is ensured to be upgraded to the latest package revision when
+it becomes available.  
+
+For example, the following upgrades the perl package to version 5.8.8-7etch1 (if it is
+installed), it also upgrades the syslog-ng and perl-modules packages to their latest (also,
+only if they are installed):
+
+upgrade_package { "perl":
+			version => '5.8.8-7etch1';
+		  "syslog-ng":
+			version => latest;
+		  "perl-modules":
+}
 
 TODO
 ====