Merge branch 'master' into backports_follow_debian_url

The README file was changed on the master branch and we'd like to change
it to add an upgrade notice.

1 files changed, 274 insertions, 210 deletions

diff --git a/README b/README.md
index e097a7e..5f6a109 100644
--- a/README
+++ b/README.md
@@ -1,6 +1,38 @@
-
-Overview
-========
+# apt module
+
+#### Table of Contents
+
+* [Overview](#overview)
+  * [Upgrade Notice](#upgrade-notice)
+* [Requirements](#requirements)
+* [Classes](#classes)
+  * [apt](#apt)
+  * [apt::apticron](#apt-apticron)
+  * [apt::cron::download](#apt-cron-download)
+  * [apt::cron::dist_upgrade](#apt-cron-dist_upgrade)
+  * [apt::dist_upgrade](#apt-dist_upgrade)
+  * [apt::dist_upgrade::initiator](#apt-dist_upgrade-initiator)
+  * [apt::dselect](#apt-dselect)
+  * [apt::listchanges](#apt-listchanges)
+  * [apt::proxy_client](#apt-proxy_client)
+  * [apt::reboot_required_notify](#apt-reboot_required_notify)
+  * [apt::unattended_upgrades](#apt-unattended_upgrades)
+* [Defines](#defines)
+  * [apt::apt_conf](#apt-apt_conf)
+  * [apt::preferences_snippet](#apt-preferences_snippet)
+  * [apt::preseeded_package](#apt-preseeded_package)
+  * [apt::sources_list](#apt-sources_list)
+  * [apt::key](#apt-key)
+  * [apt::key::plain](#apt-key-plain)
+  * [apt::upgrade_package](#apt-upgrade_package)
+* [Resources](#ressources)
+  * [File\['apt_config'\]](#fileapt_config)
+  * [Exec\['apt_updated'\]](#execapt_updated)
+* [Tests](#tests)
+* [Licensing](#licensing)
+
+
+# Overview<a name="overview"></a>
 
 This module manages apt on Debian.
 
@@ -9,31 +41,31 @@ package download current.
 
 backports.debian.org is added.
 
-/etc/apt/sources.list and /etc/apt/preferences are managed. More
+`/etc/apt/sources.list` and `/etc/apt/preferences` are managed. More
 recent Debian releases are pinned to very low values by default to
 prevent accidental upgrades.
 
 Ubuntu support is lagging behind but not absent either.
 
-! Upgrade Notice !
+## Upgrade Notice<a name="upgrade-notice"></a>
 
  * The `disable_update` parameter has been removed. The main apt class
    defaults to *not* run an `apt-get update` on every run anyway so this
    parameter seems useless.
    You can include the `apt::update` class if you want it to be run every time.
 
- * The `apt::upgrade_package` now doesn't automatically call an Exec['apt_updated']
+ * The `apt::upgrade_package` now doesn't automatically call an `Exec['apt_updated']`
    anymore, so you would need to include `apt::update` now by hand.
 
- * The apt::codename parameter has been removed. In its place, the
-   debian_codename fact may be overridden via an environment variable. This
-   will affect all other debian_* facts, and achieve the same result.
+ * The `apt::codename` parameter has been removed. In its place, the
+   `debian_codename` fact may be overridden via an environment variable. This
+   will affect all other `debian_*` facts, and achieve the same result.
 
-     FACTER_debian_codename=jessie puppet agent -t
+    FACTER_debian_codename=jessie puppet agent -t
 
- * If you were using custom 50unattended-upgrades.${::lsbdistcodename} in your
-   site_apt, these are no longer supported. You should migrate to passing
-   $blacklisted_packages to the apt::unattended_upgrades class.
+ * If you were using custom `50unattended-upgrades.${::lsbdistcodename}` in your
+   `site_apt`, these are no longer supported. You should migrate to passing
+   `$blacklisted_packages` to the `apt::unattended_upgrades` class.
 
  * the apt class has been moved to a paramterized class. if you were including
    this class before, after passing some variables, you will need to move to
@@ -47,20 +79,28 @@ Ubuntu support is lagging behind but not absent either.
    you will need to remove the variables, and the include and instead do
    the following:
 
-    class { 'apt': debian_url => 'http://localhost:9999/debian/', use_next_release => true }
+    class {
+      'apt':
+        debian_url       => 'http://localhost:9999/debian/',
+        use_next_release => true;
+    }
 
-   previously, you could manually set $lsbdistcodename which would enable forced
+   previously, you could manually set `$lsbdistcodename` which would enable forced
    upgrades, but because this is a top-level facter variable, and newer puppet
    versions do not let you assign variables to other namespaces, this is no
    longer possible. However, there is a way to obtain this functionality, and
    that is to pass the 'codename' parameter to the apt class, which will change
-   the sources.list and preferences files to be the codename you set, allowing
+   the `sources.list` and `preferences` files to be the codename you set, allowing
    you to trigger upgrades:
 
-   include apt::dist_upgrade
-   class { 'apt': codename => 'wheezy', notify => Exec['apt_dist-upgrade'] }
+    include apt::dist_upgrade
+    class {
+      'apt':
+        codename => 'wheezy',
+        notify   => Exec['apt_dist-upgrade'];
+    }
 
- * the apticron class has been moved to a parameterized class.  if you were
+ * the `apticron` class has been moved to a parameterized class.  if you were
    including this class before, you will need to move to instantiating the
    class instead. For example, if you had the following in your manifests:
 
@@ -72,9 +112,13 @@ Ubuntu support is lagging behind but not absent either.
    you will need to remove the variables, and the include and instead do the
    following:
 
-    class { 'apt::apticron': email => 'foo@example.com', notifynew => '1' }
+    class {
+    'apt::apticron':
+      email     => 'foo@example.com',
+      notifynew => '1';
+    }
 
- * the apt::listchanges class has been moved to a paramterized class. if you
+ * the `apt::listchanges` class has been moved to a paramterized class. if you
    were including this class before, after passing some variables, you will need
    to move to instantiating the class with those variables instead. For example,
    if you had the following in your manifests:
@@ -86,9 +130,12 @@ Ubuntu support is lagging behind but not absent either.
    you will need to remove the variables, and the include and instead do the
    following:
  
-    class { 'apt::listchanges': email => 'foo@example.com' }
+    class {
+      'apt::listchanges':
+        email => 'foo@example.com';
+    }
    
- * the apt::proxy_client class has been moved to a paramterized class. if you
+ * the `apt::proxy_client` class has been moved to a paramterized class. if you
    were including this class before, after passing some variables, you will need
    to move to instantiating the class with those variables instead. For example,
    if you had the following in your manifests:
@@ -100,19 +147,24 @@ Ubuntu support is lagging behind but not absent either.
    you will need to remove the variables, and the include and instead do the
    following:
 
-    class { 'apt::proxy_client': proxy => 'http://proxy.domain', port => '666' }
+    class {
+      'apt::proxy_client':
+        proxy => 'http://proxy.domain',
+        port  => '666';
+    }
+
 
-Requirements
-============
+# Requirements<a name="requirements"></a>
 
 This module needs:
 
-- the lsb-release package should be installed on the server prior to running
-  puppet. otherwise, all of the $::lsb* facts will be empty during runs.
-- the common module: https://gitlab.com/shared-puppet-modules-group/common
+ * the `lsb-release` package should be installed on the server prior to running
+  puppet. otherwise, all of the `$::lsb*` facts will be empty during runs.
+
+ * the [common module](https://gitlab.com/shared-puppet-modules-group/common)
 
 By default, on normal hosts, this module sets the configuration option
-DSelect::Clean to 'auto'. On virtual servers, the value is set by default to
+`DSelect::Clean` to 'auto'. On virtual servers, the value is set by default to
 'pre-auto', because virtual servers are usually more space-bound and have better
 recovery mechanisms via the host:
 
@@ -125,29 +177,31 @@ From apt.conf(5), 0.7.2:
      instance). pre-auto performs this action before downloading new
      packages."
 
-To change the default setting for DSelect::Clean, you can create a file named
-"03clean" or "03clean_vserver" in your site_apt module's files directory. You
+To change the default setting for `DSelect::Clean`, you can create a file named
+"03clean" or "03clean_vserver" in your `site_apt` module's files directory. You
 can also define this for a specific host by creating a file in a subdirectory of
-the site_apt modules' files directory that is named the same as the
+the `site_apt` modules' files directory that is named the same as the
 host. (example: site_apt/files/some.host.com/03clean, or
 site_apt/files/some.host.com/03clean_vserver)
 
-Classes
-=======
 
-apt
----
+# Classes<a name="classes"></a>
+
+## apt<a name="apt"></a>
 
 The apt class sets up most of the documented functionality. To use functionality
 that is not enabled by default, you must set one of the following parameters.
 
 Example usage:
 
- class { 'apt': use_next_release => true, debian_url => 'http://localhost:9999/debian/' }
+    class { 'apt':
+      use_next_release => true,
+      debian_url       => 'http://localhost:9999/debian/',
+    }
 
-Class parameters:
+**Class parameters:**
 
-* use_lts
+### use_lts
 
   If this variable is set to true the CODENAME-lts sources (such as
   squeeze-lts) are added.
@@ -155,7 +209,7 @@ Class parameters:
   By default this is false for backward compatibility with older
   versions of this module.
 
-* use_volatile
+### use_volatile
 
   If this variable is set to true the CODENAME-updates sources (such as
   squeeze-updates) are added.
@@ -163,7 +217,7 @@ Class parameters:
   By default this is false for backward compatibility with older
   versions of this module.
 
-* include_src
+### include_src
 
   If this variable is set to true a deb-src source is added for every
   added binary archive source.
@@ -171,7 +225,7 @@ Class parameters:
   By default this is false for backward compatibility with older
   versions of this module.
 
-* use_next_release
+### use_next_release
 
   If this variable is set to true the sources for the next Debian
   release are added. The default pinning configuration pins it to very
@@ -180,26 +234,26 @@ Class parameters:
   By default this is false for backward compatibility with older
   versions of this module.
 
-* debian_url, security_url, backports_url, volatile_url
+### debian_url, security_url, backports_url, volatile_url
 
   These variables allow to override the default APT mirrors respectively
   used for the standard Debian archives, the Debian security archive,
   the Debian official backports and the Debian Volatile archive.
 
-* ubuntu_url
+### ubuntu_url
 
   These variables allows to override the default APT mirror used for all
   standard Ubuntu archives (including updates, security, backports).
 
-* repos
+### repos
 
   If this variable is set the default repositories list ("main contrib non-free")
   is overriden.
 
-* custom_preferences
+### custom_preferences
 
   For historical reasons (Debian Lenny's version of APT did not support the use
-  of the preferences.d directory for putting fragments of 'preferences'), this
+  of the `preferences.d` directory for putting fragments of 'preferences'), this
   module will manage a default generic apt/preferences file with more
   recent releases pinned to very low values so that any package
   installation will not accidentally pull in packages from those suites
@@ -207,231 +261,240 @@ Class parameters:
   complemented with all of the preferences_snippet calls (see below).
 
   If the default preferences template doesn't suit your needs, you can create a
-  template located in your site_apt module, and set custom_preferences with the
+  template located in your `site_apt` module, and set custom_preferences with the
   content (eg. custom_preferences => template('site_apt/preferences') )
 
   Setting this variable to false before including this class will force the
-  apt/preferences file to be absent:
+  `apt/preferences` file to be absent:
 
-    class { 'apt': custom_preferences => false }
+    class { 'apt':
+      custom_preferences => false,
+    }
   
-* custom_sources_list
+### custom_sources_list
 
-  By default this module will use a basic apt/sources.list template with
+  By default this module will use a basic `apt/sources.list` template with
   a generic Debian mirror. If you need to set more specific sources,
   e.g. changing the sections included in the source, etc. you can set
   this variable to the content that you desire to use instead.
 
   For example, setting this variable will pull in the
-  templates/site_apt/sources.list file:
+  `templates/site_apt/sources.list` file:
 
-  class { 'apt': custom_sources_list => template('site_apt/sources.list') }
+    class { 'apt':
+      custom_sources_list => template('site_apt/sources.list'),
+    }
 
-* custom_key_dir
+### 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.
+  exist there, this module will `apt-key add` each key.
 
   The debian-archive-keyring package is installed and kept current up to the
   latest revision (this includes the backports archive keyring).
 
-apt::apticron
--------------
+
+## apt::apticron<a name="apt-apticron"></a>
 
 When you instantiate this class, apticron will be installed, with the following
 defaults, which you are free to change:
 
-  $ensure_version = 'installed',
-  $config = "apt/${::operatingsystem}/apticron_${::lsbdistcodename}.erb",
-  $email = 'root',
-  $diff_only = '1',
-  $listchanges_profile = 'apticron',
-  $system = false,
-  $ipaddressnum = false,
-  $ipaddresses = false,
-  $notifyholds = '0',
-  $notifynew = '0',
-  $customsubject = ''
+    $ensure_version = 'installed',
+    $config = "apt/${::operatingsystem}/apticron_${::lsbdistcodename}.erb",
+    $email = 'root',
+    $diff_only = '1',
+    $listchanges_profile = 'apticron',
+    $system = false,
+    $ipaddressnum = false,
+    $ipaddresses = false,
+    $notifyholds = '0',
+    $notifynew = '0',
+    $customsubject = ''
 
 Example usage:
 
- class { 'apt::apticron': email => 'foo@example.com', notifynew => '1' }
+    class { 'apt::apticron':
+      email     => 'foo@example.com',
+      notifynew => '1',
+    }
+
 
-apt::cron::download
--------------------
+## apt::cron::download<a name="apt-cron-download"></a>
 
-This class sets up cron-apt so that it downloads upgradable packages, does not
+This class sets up `cron-apt` so that it downloads upgradable packages, does not
 actually do any upgrade and emails when the output changes.
 
-cron-apt defaults to run at 4 AM. You may want to set the
-$apt_cron_hours variable before you include the class: its value will
+`cron-apt` defaults to run at 4 AM. You may want to set the
+`$apt_cron_hours` variable before you include the class: its value will
 be passed as the "hours" parameter of a cronjob. Example:
 
- # Run cron-apt every three hours
- $apt_cron_hours = '*/3'
+    # Run cron-apt every three hours
+    $apt_cron_hours = '*/3'
 
 Note that the default 4 AM cronjob won't be disabled.
 
-apt::cron::dist_upgrade
------------------------
+
+## apt::cron::dist_upgrade<a name="apt-cron-dist_upgrade"></a>
 
 This class sets up cron-apt so that it dist-upgrades the system and
 emails when upgrades are performed.
 
-See apt::cron::download above if you need to run cron-apt more often
+See [apt::cron::download](#apt-cron-download) above if you need to run `cron-apt` more often
 than once a day.
 
-apt::dist_upgrade
------------------
 
-This class provides the Exec['apt_dist-upgrade'] resource that
+## apt::dist_upgrade<a name="apt-dist_upgrade"></a>
+
+This class provides the `Exec['apt_dist-upgrade']` resource that
 dist-upgrade's the system.
 
 This exec is set as refreshonly so including this class does not
 trigger any action per-se: other resources may notify it, other
 classes may inherit from this one and add to its subscription list
-using the plusignment ('+>') operator. A real-world example can be
-seen in the apt::dist_upgrade::initiator source.
+using the plusignment (`+>`) operator. A real-world example can be
+seen in the `apt::dist_upgrade::initiator` source.
 
-apt::dist_upgrade::initiator
-----------------------------
+
+## apt::dist_upgrade::initiator<a name="apt-dist_upgrade-initiator"></a>
 
 This class automatically dist-upgrade's the system when an initiator
 file's content changes. The initiator file is copied from the first
 available source amongst the following ones, in decreasing priority
 order:
 
-- puppet:///modules/site_apt/${::fqdn}/upgrade_initiator
-- puppet:///modules/site_apt/upgrade_initiator
-- puppet:///modules/apt/upgrade_initiator
+ * `puppet:///modules/site_apt/${::fqdn}/upgrade_initiator`
+
+ * `puppet:///modules/site_apt/upgrade_initiator`
+
+ * `puppet:///modules/apt/upgrade_initiator`
 
 This is useful when one does not want to setup a fully automated
 upgrade process but still needs a way to manually trigger full
 upgrades of any number of systems at scheduled times.
 
-Beware: a dist-upgrade is triggered the first time Puppet runs after
+**Beware:** a `dist-upgrade` is triggered the first time Puppet runs after
 this class has been included. This is actually the single reason why
 this class is not enabled by default.
 
 When this class is included the APT indexes are updated on every
 Puppet run due to the author's lack of Puppet wizardry.
 
-apt::dselect
-------------
+
+## apt::dselect<a name="apt-dselect"></a>
 
 This class, when included, installs dselect and switches it to expert mode to
 suppress superfluous help screens.
 
-apt::listchanges
-----------------
 
-This class, when instantiated, installs apt-listchanges and configures it using
+## apt::listchanges<a name="apt-listchanges"></a>
+
+This class, when instantiated, installs `apt-listchanges` and configures it using
 the following parameterized variables, which can be changed:
 
- version = 'present'
- config = "apt/${::operatingsystem}/listchanges_${::lsbrelease}.erb"
- frontend = 'pager'
- email = 'root'
- confirm = 0
- saveseen = '/var/lib/apt/listchanges.db'
- which = 'both'
+    version = 'present'
+    config = "apt/${::operatingsystem}/listchanges_${::lsbrelease}.erb"
+    frontend = 'pager'
+    email = 'root'
+    confirm = 0
+    saveseen = '/var/lib/apt/listchanges.db'
+    which = 'both'
+
+Example usage:
 
- Example usage:
-  class { 'apt::listchanges': email => 'foo@example.com' }
+    class { 'apt::listchanges':
+      email => 'foo@example.com',
+    }
  
-apt::proxy_client
------------------
+
+## apt::proxy_client<a name="apt-proxy_client"></a>
 
 This class adds the right configuration to apt to make it fetch packages via a
-proxy. The class parameters apt_proxy and apt_proxy_port need to be set:
+proxy. The class parameters `apt_proxy` and `apt_proxy_port` need to be set:
 
-You can set the 'proxy' class parameter variable to the URL of the proxy that
+You can set the `proxy` class parameter variable to the URL of the proxy that
 will be used.  By default, the proxy will be queried on port 3142, but you can
-change the port number by setting the 'port' class parameter.
+change the port number by setting the `port` class parameter.
 
-Example:
+Example usage:
+
+    class { 'apt::proxy_client':
+      proxy => 'http://proxy.domain',
+      port  => '666',
+    }
 
- class { 'apt::proxy_client': proxy => 'http://proxy.domain', port => '666' }
 
-apt::reboot_required_notify
----------------------------
+## apt::reboot_required_notify<a name="apt-reboot_required_notify"></a>
 
 This class installs a daily cronjob that checks if a package upgrade
 requires the system to be rebooted; if so, cron sends a notification
 email to root.
 
-apt::unattended_upgrades
-------------------------
 
-If this class is included, it will install the package 'unattended-upgrades'
+## apt::unattended_upgrades<a name="apt-unattended_upgrades"></a>
+
+If this class is included, it will install the package `unattended-upgrades`
 and configure it to daily upgrade the system.
 
 The class has the following parameters that you can use to change the contents
 of the configuration file. The values shown here are the default values:
 
- * $config_content = undef
- * $config_template = 'apt/50unattended-upgrades.erb'
- * $mailonlyonerror = true
- * $mail_recipient = 'root'
- * $blacklisted_packages = []
+    $config_content = undef
+    $config_template = 'apt/50unattended-upgrades.erb'
+    $mailonlyonerror = true
+    $mail_recipient = 'root'
+    $blacklisted_packages = []
 
-Note that using $config_content actually specifies all of the configuration
+Note that using `$config_content` actually specifies all of the configuration
 contents and thus makes the other parameters useless.
 
-example:
+Example usage:
 
     class { 'apt::unattended_upgrades':
       config_template      => 'site_apt/50unattended-upgrades.jessie',
-      blacklisted_packages => [
-       'libc6', 'libc6-dev', 'libc6-i686', 'mysql-server', 'redmine', 'nodejs',
-       'bird'
-      ],
+      blacklisted_packages => [ 'libc6', 'libc6-dev', 'libc6-i686',
+                                'mysql-server', 'redmine', 'nodejs', 'bird' ],
     }
 
-Defines
-=======
 
-apt::apt_conf
--------------
+# Defines<a name="defines"></a>
+
+## apt::apt_conf<a name="apt-apt_conf"></a>
 
-Creates a file in the apt/apt.conf.d directory to easily add configuration
-components. One can use either the 'source' meta-parameter to specify a list of
-static files to include from the puppet fileserver or the 'content'
+Creates a file in the `apt/apt.conf.d` directory to easily add configuration
+components. One can use either the `source` meta-parameter to specify a list of
+static files to include from the puppet fileserver or the `content`
 meta-parameter to define content inline or with the help of a template.
 
-Example:
+Example usage:
+
+    apt::apt_conf { '80download-only':
+      source => 'puppet:///modules/site_apt/80download-only',
+    }
 
-  apt::apt_conf { '80download-only':
-    source => 'puppet:///modules/site_apt/80download-only',
-  }
 
-apt::preferences_snippet
-------------------------
+## apt::preferences_snippet<a name="apt-preferences_snippet"></a>
 
-A way to add pinning information to files in /etc/apt/preferences.d/
+A way to add pinning information to files in `/etc/apt/preferences.d/`
 
-Example:
+Examples:
 
-  apt::preferences_snippet {
-    'irssi-plugin-otr':
-      release => 'squeeze-backports',
-      priority => 999;
-  }
+    apt::preferences_snippet { 'irssi-plugin-otr':
+      release  => 'squeeze-backports',
+      priority => 999,
+    }
 
-  apt::preferences_snippet {
-    'unstable_fallback':
-      package => '*',
-      release => 'unstable',
-      priority => 1;
-  }
+    apt::preferences_snippet { 'unstable_fallback':
+      package  => '*',
+      release  => 'unstable',
+      priority => 1,
+    }
 
-  apt::preferences_snippet {
-    'ttdnsd':
-      pin => 'origin deb.torproject.org',
-      priority => 999;
-  }
+    apt::preferences_snippet { 'ttdnsd':
+      pin      => 'origin deb.torproject.org',
+      priority => 999,
+    }
 
 The names of the resources will be used as the names of the files in the
 preferences.d directory, so you should ensure that resource names follow the
@@ -444,52 +507,53 @@ From apt_preferences(5):
      only contain alphanumeric, hyphen (-), underscore (_) and period (.)
      characters - otherwise they will be silently ignored.
 
-apt::preseeded_package
-----------------------
+
+## apt::preseeded_package<a name="apt-preseeded_package"></a>
 
 This simplifies installation of packages for which 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
-'site_apt/templates/${::lsbdistcodename}/locales.seeds' and then include the
+locales package, you would place the `locales.seed` file in
+`site_apt/templates/${::lsbdistcodename}/locales.seeds` and then include the
 following in your manifest:
 
-  apt::preseeded_package { locales: }
+    apt::preseeded_package { locales: }
 
 You can also specify the content of the seed via the content parameter, 
 for example:
 
-  apt::preseeded_package { 'apticron':
-    content => 'apticron   apticron/notification   string  root@example.com',
-  }
+    apt::preseeded_package { 'apticron':
+      content => 'apticron apticron/notification string root@example.com',
+    }
+
 
-apt::sources_list
------------------
+## apt::sources_list<a name="apt-sources_list"></a>
 
-Creates a file in the apt/sources.list.d directory to easily add additional apt
-sources. One can use either the 'source' meta-parameter to specify a list of
-static files to include from the puppet fileserver or the 'content'
+Creates a file in the `apt/sources.list.d` directory to easily add additional apt
+sources. One can use either the `source` meta-parameter to specify a list of
+static files to include from the puppet fileserver or the `content`
 meta-parameter to define content inline or with the help of a template. Ending
-the resource name in '.list' is optional: it will be automatically added to the
+the resource name in `.list` is optional: it will be automatically added to the
 file name if not present in the resource name.
 
-Example:
+Example usage:
 
-  apt::sources_list { 'company_internals':
-    source => [ "puppet:///modules/site_apt/${::fqdn}/company_internals.list",
-                'puppet:///modules/site_apt/company_internals.list' ],
-  }
+    apt::sources_list { 'company_internals':
+      source => [ "puppet:///modules/site_apt/${::fqdn}/company_internals.list",
+                  'puppet:///modules/site_apt/company_internals.list' ];
+    }
 
-apt::key
---------
+
+## apt::key<a name="apt-key"></a>
 
 Deploys a secure apt OpenPGP key. This usually accompanies the
 sources.list snippets above for third party repositories. For example,
 you would do:
 
-  apt::key { 'neurodebian.gpg':
-    ensure => present,
-    source => 'puppet:///modules/site_apt/neurodebian.gpg',
-  }
+    apt::key {
+      'neurodebian.gpg':
+        ensure => present,
+        source => 'puppet:///modules/site_apt/neurodebian.gpg';
+    }
 
 This deploys the key in the `/etc/apt/trusted.gpg.d` directory, which
 is assumed by secure apt to be binary OpenPGP keys and *not*
@@ -498,16 +562,16 @@ use `apt::key::plain`.
 
 The `.gpg` extension is compulsory for `apt` to pickup the key properly.
 
-apt::key::plain
----------------
+
+## apt::key::plain<a name="apt-key-plain"></a>
 
 Deploys a secure apt OpenPGP key. This usually accompanies the
 sources.list snippets above for third party repositories. For example,
 you would do:
 
-  apt::key::plain { 'neurodebian.asc':
-    source => 'puppet:///modules/site_apt/neurodebian.asc',
-  }
+    apt::key::plain { 'neurodebian.asc':
+      source => 'puppet:///modules/site_apt/neurodebian.asc';
+    }
 
 This deploys the key in the `${apt_base_dir}/keys` directory (as
 opposed to `$custom_key_dir` which deploys it in `keys.d`). The reason
@@ -519,8 +583,8 @@ Note that this model does *not* currently allow keys to be removed!
 Use `apt::key` instead for a more practical, revokable approach, but
 that needs binary keys.
 
-apt::upgrade_package
---------------------
+
+## apt::upgrade_package<a name="apt-upgrade_package"></a>
 
 This simplifies upgrades for DSA security announcements or point-releases. This
 will ensure that the named package is upgraded to the version specified, only if
@@ -532,23 +596,22 @@ 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':
-}
+    upgrade_package {
+      'perl':
+        version => '5.8.8-7etch1';
+      'syslog-ng':
+        version => latest;
+      'perl-modules':
+    }
+
 
-Resources
-=========
+# Resources<a name="ressources"></a>
 
-File['apt_config']
-------------------
+## File['apt_config']<a name="file-apt-config"></a>
 
 Use this resource to depend on or add to a completed apt configuration
 
-Exec['apt_updated']
--------------------
+## Exec['apt_updated']<a name="exec-apt-updated"></a>
 
 After this point the APT indexes are up-to-date.
 This resource is set to `refreshonly => true` so it is not run on
@@ -559,17 +622,18 @@ This resource is usually used like this to ensure current packages are
 installed by Package resources:
 
     include apt::update
-    Package { require => Exec['apt_updated'] }
+    Package {
+      require => Exec['apt_updated']
+    }
 
 Note that nodes can be updated once a day by using
 
     APT::Periodic::Update-Package-Lists "1";
 
-in i.e. /etc/apt/apt.conf.d/80_apt_update_daily.
+in i.e. `/etc/apt/apt.conf.d/80_apt_update_daily`.
 
 
-Tests
-=====
+# Tests<a name="test"></a>
 
 To run pupept rspec tests:
 
@@ -581,8 +645,8 @@ Using different facter/puppet versions:
     FACTER_GEM_VERSION=1.6.10 PUPPET_GEM_VERSION=2.7.23 bundle install --path vendor/bundle
     bundle exec rake spec
 
-Licensing
-=========
+
+# Licensing<a name="licensing"></a>
 
 This puppet module is licensed under the GPL version 3 or later. Redistribution
 and modification is encouraged.