Add README to apt module

additionally use modules_dir and remove legacy file removal

1 files changed, 72 insertions, 18 deletions

diff --git a/README b/README
index 8034a4f..f841834 100644
--- a/README
+++ b/README
@@ -1,19 +1,73 @@
-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."
-
-Provided Resources:
-	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] }
+Overview
+========
 
+This module manages apt on Debian.
+
+It keeps dpkg's and apt's databases as well as the keyrings for securing
+package download current.
+
+backports.org is added and an archive key is provided[1].
+
+dselect is switched to expert mode to suppress superfluous help screens.
+
+sources.list and apt_preferences are managed. Testing and unstable are pinned to
+very low values by default to prevent accidental upgrades.
+
+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."
+
+
+$lsbdistcodename: Contains the Codename ("etch", "lenny", ...) of the client's
+	release. While the values comes from lsb-release by default, this value
+	can be set manually too, to enable forced upgrades e.g.
+
+
+Classes
+=======
+
+This modules contains only the apt class, which sets up all described
+functionality.
+
+
+Resources
+=========
+
+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] }
+
+
+TODO
+====
+
+Enable debian-archive-keyring handling for sarge, lenny and sid.
+
+Enable selection of country-specific mirrors.
+
+Currently this module updates the caches on every run. Running dselect update is
+a expensive operation and should be done only on schedule by using apticron.
+Sometimes -- especially when initially starting management or deploying new
+packages -- a immediate update is really needed to be able to install the right
+packages without errors. Thus a method should be devised to be able to specify
+with high fidelity when a update should be run and when it is not needed.
+
+
+
+[1] Of course, you should check the validity of _this_ key yourself.