Updating various doc items with 0.6 features, releasing soon, and removing…

Updating various doc items with 0.6 features, releasing soon, and removing references to things new in 0.4, which
has been out long enough to no longer be new.

YAMLSyntax.html

@@ -289,7 +289,7 @@ languages:
 </p>
 <p>
         &copy; Copyright 2012 Michael DeHaan.<br/>
-      Last updated on Jul 30, 2012.<br/>
+      Last updated on Jul 31, 2012.<br/>
     </p>
   </div>
 </footer>

api.html

@@ -465,7 +465,7 @@ e.g.
 </p>
 <p>
         &copy; Copyright 2012 Michael DeHaan.<br/>
-      Last updated on Jul 30, 2012.<br/>
+      Last updated on Jul 31, 2012.<br/>
     </p>
   </div>
 </footer>

bestpractices.html

@@ -311,7 +311,7 @@ This way you have an audit trail describing when and why you changed the rules a
 </p>
 <p>
         &copy; Copyright 2012 Michael DeHaan.<br/>
-      Last updated on Jul 30, 2012.<br/>
+      Last updated on Jul 31, 2012.<br/>
     </p>
   </div>
 </footer>

examples.html

@@ -396,7 +396,7 @@ a simplified syntax for this.</p>
 </p>
 <p>
         &copy; Copyright 2012 Michael DeHaan.<br/>
-      Last updated on Jul 30, 2012.<br/>
+      Last updated on Jul 31, 2012.<br/>
     </p>
   </div>
 </footer>

faq.html

@@ -403,7 +403,7 @@ tasks – whether for a QA sytem, build system, or anything you can think of
 </p>
 <p>
         &copy; Copyright 2012 Michael DeHaan.<br/>
-      Last updated on Jul 30, 2012.<br/>
+      Last updated on Jul 31, 2012.<br/>
     </p>
   </div>
 </footer>

genindex.html

@@ -204,7 +204,7 @@ s.parentNode.insertBefore(ga, s);
 </p>
 <p>
         &copy; Copyright 2012 Michael DeHaan.<br/>
-      Last updated on Jul 30, 2012.<br/>
+      Last updated on Jul 31, 2012.<br/>
     </p>
   </div>
 </footer>

gettingstarted.html

@@ -391,7 +391,7 @@ explore, but you already have a fully working infrastructure!</p>
 </p>
 <p>
         &copy; Copyright 2012 Michael DeHaan.<br/>
-      Last updated on Jul 30, 2012.<br/>
+      Last updated on Jul 31, 2012.<br/>
     </p>
   </div>
 </footer>

index.html

@@ -410,7 +410,7 @@ Puppet Labs, and is now with <a class="reference external" href="http://rpath.co
 </p>
 <p>
         &copy; Copyright 2012 Michael DeHaan.<br/>
-      Last updated on Jul 30, 2012.<br/>
+      Last updated on Jul 31, 2012.<br/>
     </p>
   </div>
 </footer>

moduledev.html

@@ -340,8 +340,7 @@ a lot shorter than this:</p>
 <h2>Module Provided &#8216;Facts&#8217;<a class="headerlink" href="#module-provided-facts" title="Permalink to this headline">¶</a></h2>
 <p>The &#8216;setup&#8217; module that ships with Ansible provides many variables about a system that can be used in playbooks
 and templates.  However, it&#8217;s possible to also add your own facts without modifying the system module.  To do
-this, just have the module return a <cite>ansible_facts</cite> key, like so, along with other return data.  This requires
-Ansible 0.4 and later:</p>
+this, just have the module return a <cite>ansible_facts</cite> key, like so, along with other return data:</p>
 <div class="highlight-python"><pre>{
     "changed" : True,
     "rc" : 5,
@@ -469,7 +468,7 @@ Stop by the mailing list to inquire about requirements.</p>
 </p>
 <p>
         &copy; Copyright 2012 Michael DeHaan.<br/>
-      Last updated on Jul 30, 2012.<br/>
+      Last updated on Jul 31, 2012.<br/>
     </p>
   </div>
 </footer>

modules.html

@@ -818,8 +818,7 @@ host before using this module.</p>
 </div>
 <div class="section" id="raw">
 <span id="id13"></span><h2>raw<a class="headerlink" href="#raw" title="Permalink to this headline">¶</a></h2>
-<p>Executes a low-down and dirty SSH command, not going through the module subsystem.
-This module is new in Ansible 0.4.</p>
+<p>Executes a low-down and dirty SSH command, not going through the module subsystem.</p>
 <p>This is useful and should only be done in two cases.  The first case is installing
 python-simplejson on older (python 2.4 and before) hosts that need it as a dependency
 to run modules, since nearly all core modules require it.  Another is speaking to any
@@ -1275,7 +1274,7 @@ yum name=httpd state=installed</pre>
 </p>
 <p>
         &copy; Copyright 2012 Michael DeHaan.<br/>
-      Last updated on Jul 30, 2012.<br/>
+      Last updated on Jul 31, 2012.<br/>
     </p>
   </div>
 </footer>

patterns.html

@@ -271,7 +271,7 @@ proxy=proxy.atlanta.example.com</pre>
 </div>
 <div class="section" id="groups-of-groups-and-group-variables">
 <h2>Groups of Groups, and Group Variables<a class="headerlink" href="#groups-of-groups-and-group-variables" title="Permalink to this headline">¶</a></h2>
-<p>Using Ansible 0.4, it is possible to make groups of groups and assign
+<p>It is also possible to make groups of groups and assign
 variables to groups.  These variables can be used by /usr/bin/ansible-playbook, but not
 /usr/bin/ansible:</p>
 <div class="highlight-python"><pre>[atlanta]
@@ -380,7 +380,7 @@ a <a class="reference external" href="https://github.com/ansible/ansible/blob/de
 </p>
 <p>
         &copy; Copyright 2012 Michael DeHaan.<br/>
-      Last updated on Jul 30, 2012.<br/>
+      Last updated on Jul 31, 2012.<br/>
     </p>
   </div>
 </footer>

rst/moduledev.rst

@@ -174,8 +174,7 @@ Module Provided 'Facts'
 
 The 'setup' module that ships with Ansible provides many variables about a system that can be used in playbooks
 and templates.  However, it's possible to also add your own facts without modifying the system module.  To do
-this, just have the module return a `ansible_facts` key, like so, along with other return data.  This requires
-Ansible 0.4 and later::
+this, just have the module return a `ansible_facts` key, like so, along with other return data::
 
     {
         "changed" : True,

rst/modules.rst

@@ -433,7 +433,6 @@ raw
 ```
 
 Executes a low-down and dirty SSH command, not going through the module subsystem.
-This module is new in Ansible 0.4.
 
 This is useful and should only be done in two cases.  The first case is installing
 python-simplejson on older (python 2.4 and before) hosts that need it as a dependency

rst/patterns.rst

@@ -110,7 +110,7 @@ Variables can also be applied to an entire group at once::
 Groups of Groups, and Group Variables
 +++++++++++++++++++++++++++++++++++++
 
-Using Ansible 0.4, it is possible to make groups of groups and assign
+It is also possible to make groups of groups and assign
 variables to groups.  These variables can be used by /usr/bin/ansible-playbook, but not
 /usr/bin/ansible::
 

rst/playbooks.rst

 Playbooks
 =========
 
-Playbooks are a completely different way to use ansible and are
-particularly awesome.   They are the basis for a really simple 
+Playbooks are a completely different way to use ansible than in task execution mode, and are
+particularly awesome.   Simply put, playbooks are the basis for a really simple 
 configuration management and multi-machine deployment system, 
-unlike any that already exist, and
-one that is very well suited to deploying complex applications.
+unlike any that already exist, and one that is very well suited to deploying complex applications.
 
 Playbooks can declare configurations, but they can also orchestrate steps of
 any manual ordered process, even as different steps must bounce back and forth
@@ -21,12 +20,16 @@ Let's dive in and see how they work.  As you go, you may wish to open
 the `github examples directory <https://github.com/ansible/ansible/tree/master/examples/playbooks>`_ in
 another tab, so you can apply the theory to what things look like in practice.
 
-Playbook Example
-````````````````
+Playbook Language Example
+`````````````````````````
 
 Playbooks are expressed in YAML format and have a minimum of syntax.
 Each playbook is composed of one or more 'plays' in a list.  
 
+The goal of a play is map a group of hosts to some well defined roles, represented by
+things ansible called tasks.  At the basic level, a task is nothing more than a call
+to an ansible module, which you should have learned about in earlier chapters.
+
 By composing a playbook of multiple 'plays', it is possible to
 orchestrate multi-machine deployments, running certain steps on all
 machines in the webservers group, then certain steps on the database
@@ -116,25 +119,21 @@ These variables can be used later in the playbook like this::
 
     $varname or ${varname}
 
-The later is useful in the event you need to do something like ${other}_concatenated_value.
+The later is useful in the event you need to do something like ${other}_some_string.
 
-The full power of the Jinja2 templating language is also available (note: in 0.4, this is only true inside of templates), which looks like this::
+The full power of the `Jinja2 <http://jinja.pocoo.org/docs/>`_ templating language is also available, which looks like this::
 
     {{ varname }}
 
 The Jinja2 documentation provides information about how to construct loops and conditionals for those
 who which to use more advanced templating.  This is optional and the $varname format still works in template
-files.
-
-If there are discovered variables about the system (ansible provides some of these,
-plus we include ones taken from facter or ohai if installed) these variables bubble up back into the
-playbook, and can be used on each system just like explicitly set
-variables.  
+files. 
 
-Facter variables are prefixed with ``facter_`` and Ohai
-variables are prefixed with ``ohai_``.  Ansible variables (0.3 and later) 
-are not surprisingly prefixed with ``ansible_`` (See the :ref:`setup` module
-documentation for a list of Ansible variables).
+If there are discovered variables about the system, called 'facts', these variables bubble up back into the
+playbook, and can be used on each system just like explicitly set variables.  Ansible provides several
+of these, prefixed with 'ansible', and are documented under :ref:`setup` in the module documentation.  Additionally,
+facts can be gathered by ohai and facter if they are installed.  Facter variables are prefixed with ``facter_`` and Ohai
+variables are prefixed with ``ohai_``.  
 
 So for instance, if I wanted
 to write the hostname into the /etc/motd file, I could say::
@@ -153,23 +152,26 @@ Tasks list
 
 Each play contains a list of tasks.  Tasks are executed in order, one
 at a time, against all machines matched by the host pattern,
-before moving on to the next task.
+before moving on to the next task.  It is important to understand that, within a play,
+all hosts are going to get the same task directives.  It is the purpose of a play to map
+a selection of hosts to tasks.
 
-Hosts with failed tasks are taken out of the rotation for the entire
-playbook.  If things fail, simply correct the playbook file and rerun.
+When running the playbook, which runs top to bottom, hosts with failed tasks are 
+taken out of the rotation for the entire playbook.  If things fail, simply correct the playbook file and rerun.
 
 The goal of each task is to execute a module, with very specific arguments.
 Variables, as mentioned above, can be used in arguments to modules.
 
-Modules other than `command` and `shell` are 'idempotent', meaning if you run them
+Modules are 'idempotent', meaning if you run them
 again, they will make the changes they are told to make to bring the
 system to the desired state.  This makes it very safe to rerun
 the same playbook multiple times.  They won't change things
 unless they have to change things.  
 
-The `command` and `shell` modules will actually rerun the same command again, 
+The `command` and `shell` modules will typically rerun the same command again, 
 which is totally ok if the command is something like 
-'chmod' or 'setsebool', etc.
+'chmod' or 'setsebool', etc.  Though there is a 'creates' flag available which can
+be used to make these modules also idempotent.
 
 Every task should have a `name`, which is included in the output from
 running the playbook.   This is output for humans, so it is
@@ -192,6 +194,13 @@ them work just like you would expect. Simple::
      - name: disable selinux 
        action: command /sbin/setenforce 0
 
+The command and shell module care about return codes, so if you have a command
+who's successful exit code is not zero, you may wish to do this:
+
+   tasks:
+     - name: run this command and ignore the result
+       action: shell /usr/bin/somecommand & /bin/true
+
 Variables can be used in action lines.   Suppose you defined
 a variable called 'vhost' in the 'vars' section, you could do this::
 
@@ -201,11 +210,13 @@ a variable called 'vhost' in the 'vars' section, you could do this::
 
 Those same variables are usable in templates, which we'll get to later.
 
+Now in a very basic playbook all the tasks will be listed directly in that play, though it will usually
+make more sense to break up tasks using the 'include:' directive.  We'll show that a bit later.
 
 Running Operations On Change
 ````````````````````````````
 
-As we've mentioned, nearly all modules are written to be 'idempotent' and can relay  when
+As we've mentioned, modules are written to be 'idempotent' and can relay  when
 they have made a change on the remote system.   Playbooks recognize this and
 have a basic event system that can be used to respond to change.
 
@@ -246,13 +257,15 @@ won't need them for much else.
    Notify handlers are always run in the order written.
 
 
-Include Files And Reuse
-```````````````````````
+Include Files And Encouraging Reuse
+```````````````````````````````````
 
 Suppose you want to reuse lists of tasks between plays or playbooks.  You can use
-include files to do this.
+include files to do this.  Use of included task lists is a great way to define a role
+that system is going to fulfill.  Remember, the goal of a play in a playbook is to map
+a group of systems into multiple roles.  Let's see what this looks like...
 
-An include file simply contains a flat list of tasks, like so::
+A task include file simply contains a flat list of tasks, like so::
 
     ---
     # possibly saved as tasks/foo.yml
@@ -261,12 +274,12 @@ An include file simply contains a flat list of tasks, like so::
     - name: placeholder bar
       action: command /bin/bar
 
-Include directives look like this::
+Include directives look like this, and can be mixed in with regular tasks in a playbook::
 
    - tasks:
       - include: tasks/foo.yml
 
-You can also pass variables into includes directly.  We might call this a 'parameterized include'.
+You can also pass variables into includes.  We call this a 'parameterized include'.
 
 For instance, if deploying multiple wordpress instances, I could
 contain all of my wordpress tasks in a single wordpress.yml file, and use it like so::
@@ -276,17 +289,17 @@ contain all of my wordpress tasks in a single wordpress.yml file, and use it lik
      - include: wordpress.yml user=alice
      - include: wordpress.yml user=bob
 
-Variables passed in can be used in the included files.  You can reference them like this::
+Variables passed in can then be used in the included files.  You can reference them like this::
    
    $user
 
-In addition to the explicitly passed in parameters, all variables from
-the vars section are also available for use here as well.  
+(In addition to the explicitly passed in parameters, all variables from
+the vars section are also available for use here as well.)
 
 .. note::
-   Include statements are only usable from the top level
-   playbook file.  This means includes can not include other
-   includes.  This may be implemented in a later release.
+   Task include statements are only usable one-level deep.
+   This means task includes can not include other
+   task includes.  This may change in a later release.
 
 Includes can also be used in the 'handlers' section, for instance, if you
 want to define how to restart apache, you only have to do that once for all
@@ -305,10 +318,12 @@ of a play::
 
 You can mix in includes along with your regular non-included tasks and handlers.
 
-Note that you can not conditionally path the location to an include file, like you can
+NOTE:: you can not conditionally path the location to an include file, like you can
 with 'vars_files'.  If you find yourself needing to do this, consider how you can
-restructure your playbook to be more class/role oriented.  
-
+restructure your playbook to be more class/role oriented.  This is to say you cannot
+use a 'fact' to decide what include file to use.  All hosts contained within the play
+are going to get the same tasks.  ('only_if' provides some ability for hosts to conditionally
+skip tasks).
 
 Executing A Playbook
 ````````````````````

search.html

@@ -221,7 +221,7 @@ s.parentNode.insertBefore(ga, s);
 </p>
 <p>
         &copy; Copyright 2012 Michael DeHaan.<br/>
-      Last updated on Jul 30, 2012.<br/>
+      Last updated on Jul 31, 2012.<br/>
     </p>
   </div>
 </footer>

who_uses_ansible.html

@@ -257,7 +257,7 @@ s.parentNode.insertBefore(ga, s);
 </p>
 <p>
         &copy; Copyright 2012 Michael DeHaan.<br/>
-      Last updated on Jul 30, 2012.<br/>
+      Last updated on Jul 31, 2012.<br/>
     </p>
   </div>
 </footer>