apt::pin: Allow for packages to be an array.

[puppet-modules/puppetlabs-apt.git] / README.md

diff --git a/README.md b/README.md
index 402d7ab021982244b61a07ab923405c536418cd3..3a7bc8ca0c2a061fc2d99266336cb041d9650f24 100644 (file)
--- a/README.md
+++ b/README.md
@@ -4,12 +4,15 @@ apt
 [![Build Status](https://travis-ci.org/puppetlabs/puppetlabs-apt.png?branch=master)](https://travis-ci.org/puppetlabs/puppetlabs-apt)
 
 ## Description
+
 Provides helpful definitions for dealing with Apt.
+
 =======
+
 Overview
 --------
 
-The APT module provides a simple interface for managing APT source, key, and definitions with Puppet. 
+The APT module provides a simple interface for managing APT source, key, and definitions with Puppet.
 
 Module Description
 ------------------
@@ -28,11 +31,11 @@ Setup
 * authentication keys
 * wget (optional)
 
-###Beginning with APT
+### Beginning with APT
 
 To begin using the APT module with default parameters, declare the class
 
-    class { 'apt': }
+    include apt
  
 Puppet code that uses anything from the APT module requires that the core apt class be declared. 
 
@@ -41,7 +44,7 @@ Usage
 
 Using the APT module consists predominantly in declaring classes that provide desired functionality and features. 
  
-###apt
+### apt
 
 `apt` provides a number of common resources and options that are shared by the various defined types in this module, so you MUST always include this class in your manifests.
 
@@ -54,20 +57,21 @@ The parameters for `apt` are not required in general and are predominantly for d
       proxy_port           => '8080',
       purge_sources_list   => false,
       purge_sources_list_d => false,
-      purge_preferences_d  => false
+      purge_preferences_d  => false,
+      update_timeout       => undef
     }
 
 Puppet will manage your system's `sources.list` file and `sources.list.d` directory but will do its best to respect existing content. 
 
 If you declare your apt class with `purge_sources_list` and `purge_sources_list_d` set to 'true', Puppet will unapologetically purge any existing content it finds that wasn't declared with Puppet. 
 
-###apt::builddep
+### apt::builddep
 
 Installs the build depends of a specified package.
 
     apt::builddep { 'glusterfs-server': }
 
-###apt::force
+### apt::force
 
 Forces a package to be installed from a specific release.  This class is particularly useful when using repositories, like Debian, that are unstable in Ubuntu.
 
@@ -77,7 +81,7 @@ Forces a package to be installed from a specific release.  This class is particu
          require => Apt::Source['debian_unstable'],
     }
 
-###apt::key
+### apt::key
 
 Adds a key to the list of keys used by APT to authenticate packages.
 
@@ -93,7 +97,7 @@ Adds a key to the list of keys used by APT to authenticate packages.
 
 Note that use of `key_source` requires wget to be installed and working.
 
-###apt::pin
+### apt::pin
 
 Adds an apt pin for a certain release.
 
@@ -111,13 +115,17 @@ Note you can also specifying more complex pins using distribution properties.
       label           => 'Debian'
     }
 
-###apt::ppa
+If you wish to pin a number of packages you may specify the packages as a space
+delimited string using the `packages` attribute or pass in an array of package
+names.
+
+### apt::ppa
 
 Adds a ppa repository using `add-apt-repository`.
 
     apt::ppa { 'ppa:drizzle-developers/ppa': }
 
-###apt::release
+### apt::release
 
 Sets the default apt release. This class is particularly useful when using repositories, like Debian, that are unstable in Ubuntu.
 
@@ -125,7 +133,7 @@ Sets the default apt release. This class is particularly useful when using repos
       release_id => 'precise',
     }
 
-###apt::source
+### apt::source
 
 Adds an apt source to `/etc/apt/sources.list.d/`.
 
@@ -149,11 +157,11 @@ If you would like to configure your system so the source is the Puppet Labs APT
       key_server => 'pgp.mit.edu',
     }
 
-###Testing
+### Testing
 
 The APT module is mostly a collection of defined resource types, which provide reusable logic that can be leveraged to manage APT. It does provide smoke tests for testing functionality on a target system, as well as spec tests for checking a compiled catalog against an expected set of resources.
 
-####Example Test
+#### Example Test
 
 This test will set up a Puppet Labs apt repository. Start by creating a new smoke test in the apt module's test folder. Call it puppetlabs-apt.pp. Inside, declare a single resource representing the Puppet Labs APT source and gpg key
 
@@ -182,7 +190,7 @@ The above example used a smoke test to easily lay out a resource declaration and
 Implementation
 --------------
 
-###apt::backports
+### apt::backports
 
 Adds the necessary components to get backports for Ubuntu and Debian. The release name defaults to `$lsbdistcodename`. Setting this manually can cause undefined behavior (read: universe exploding).