Clarify stderr behavior of modules

YAMLSyntax.html

@@ -247,7 +247,7 @@ languages:
     <p class="pull-right"><a href="#">Back to top</a></p>
     <p>
         &copy; Copyright 2012 Michael DeHaan.<br/>
-      Last updated on Apr 25, 2012.<br/>
+      Last updated on Apr 27, 2012.<br/>
       Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.8.<br/>
     </p>
   </div>

api.html

@@ -331,7 +331,7 @@ a conf.d file appropriately or something similar.  Who knows.</p>
     <p class="pull-right"><a href="#">Back to top</a></p>
     <p>
         &copy; Copyright 2012 Michael DeHaan.<br/>
-      Last updated on Apr 25, 2012.<br/>
+      Last updated on Apr 27, 2012.<br/>
       Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.8.<br/>
     </p>
   </div>

examples.html

@@ -346,7 +346,7 @@ a simplified syntax for this.</p>
     <p class="pull-right"><a href="#">Back to top</a></p>
     <p>
         &copy; Copyright 2012 Michael DeHaan.<br/>
-      Last updated on Apr 25, 2012.<br/>
+      Last updated on Apr 27, 2012.<br/>
       Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.8.<br/>
     </p>
   </div>

faq.html

@@ -353,7 +353,7 @@ tasks – whether for a QA sytem, build system, or anything you can think of
     <p class="pull-right"><a href="#">Back to top</a></p>
     <p>
         &copy; Copyright 2012 Michael DeHaan.<br/>
-      Last updated on Apr 25, 2012.<br/>
+      Last updated on Apr 27, 2012.<br/>
       Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.8.<br/>
     </p>
   </div>

genindex.html

@@ -162,7 +162,7 @@ s.parentNode.insertBefore(ga, s);
     <p class="pull-right"><a href="#">Back to top</a></p>
     <p>
         &copy; Copyright 2012 Michael DeHaan.<br/>
-      Last updated on Apr 25, 2012.<br/>
+      Last updated on Apr 27, 2012.<br/>
       Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.8.<br/>
     </p>
   </div>

gettingstarted.html

@@ -315,7 +315,7 @@ explore, but you already have a fully working infrastructure!</p>
     <p class="pull-right"><a href="#">Back to top</a></p>
     <p>
         &copy; Copyright 2012 Michael DeHaan.<br/>
-      Last updated on Apr 25, 2012.<br/>
+      Last updated on Apr 27, 2012.<br/>
       Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.8.<br/>
     </p>
   </div>

index.html

@@ -401,7 +401,7 @@ Puppet Labs, and rPath.  Reach Michael by email <a class="reference external" hr
     <p class="pull-right"><a href="#">Back to top</a></p>
     <p>
         &copy; Copyright 2012 Michael DeHaan.<br/>
-      Last updated on Apr 25, 2012.<br/>
+      Last updated on Apr 27, 2012.<br/>
       Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.8.<br/>
     </p>
   </div>

moduledev.html

@@ -176,9 +176,9 @@ a module that just outputs the current time.</p>
 <p>We are going to use Python here but any language is possible.  Only File I/O and outputing to standard
 out are required.  So, bash, C++, clojure, Python, Ruby, whatever you want
 is fine.</p>
-<p>It&#8217;s obvious that you would never really need to build a module to set the system time,
-the &#8216;command&#8217; module could already be used to do this.  However, it makes for a decent example.
-Reading the modules that come with ansible (linked above) is a great way to learn how to write
+<p>So, here&#8217;s an example.  You would never really need to build a module to set the system time,
+the &#8216;command&#8217; module could already be used to do this.  Though we&#8217;re going to make one.</p>
+<p>Reading the modules that come with ansible (linked above) is a great way to learn how to write
 modules.   Keep in mind, though, that some modules in ansible&#8217;s source tree are internalisms,
 so look at <cite>service</cite> or <cite>yum</cite>, and don&#8217;t stare too close into things like <cite>async_wrapper</cite> or
 you&#8217;ll turn to stone.  Nobody ever executes async_wrapper directly.</p>
@@ -331,6 +331,12 @@ json isn&#8217;t in the Python standard library until 2.5.:</p>
 </div>
 <p>Because the output is supposed to be valid JSON.  Except that&#8217;s not quite true,
 but we&#8217;ll get to that later.</p>
+<p>Further, modules must not output anything on stderr, even if the JSON returned
+out stdout is valid.  This is due to the internals of our SSH library, more or less.</p>
+<p>If a module returns stderr or otherwise fails to produce valid JSON, the actual output
+will still be shown in Ansible, however, but the command will not succeed.</p>
+<p>Always use the hacking/test-module script when developing modules and it will warn
+you about these kind of things.</p>
 </div>
 <div class="section" id="conventions">
 <h2>Conventions<a class="headerlink" href="#conventions" title="Permalink to this headline">¶</a></h2>
@@ -396,7 +402,7 @@ Stop by the mailing list to inquire about requirements.</p>
     <p class="pull-right"><a href="#">Back to top</a></p>
     <p>
         &copy; Copyright 2012 Michael DeHaan.<br/>
-      Last updated on Apr 25, 2012.<br/>
+      Last updated on Apr 27, 2012.<br/>
       Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.8.<br/>
     </p>
   </div>

modules.html

@@ -724,7 +724,7 @@ yum pkg=httpd state=installed</pre>
     <p class="pull-right"><a href="#">Back to top</a></p>
     <p>
         &copy; Copyright 2012 Michael DeHaan.<br/>
-      Last updated on Apr 25, 2012.<br/>
+      Last updated on Apr 27, 2012.<br/>
       Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.8.<br/>
     </p>
   </div>

patterns.html

@@ -268,6 +268,10 @@ style file with a YAML one.:</p>
     - asdf: 1234</pre>
 </div>
 <p>Tip: Be sure to start your YAML file with the YAML record designator &#8220;&#8212;&#8221;.</p>
+<p>NOTE: variables specified in playbooks will override variables specified
+in the host file.  Further, if a host is in multiple groups, currently, the
+variables set by the last loaded group will win over variables set in other
+groups.  This behavior may be refined in future releases.</p>
 <div class="admonition-see-also admonition seealso">
 <p class="first admonition-title">See also</p>
 <dl class="last docutils">
@@ -291,7 +295,7 @@ style file with a YAML one.:</p>
     <p class="pull-right"><a href="#">Back to top</a></p>
     <p>
         &copy; Copyright 2012 Michael DeHaan.<br/>
-      Last updated on Apr 25, 2012.<br/>
+      Last updated on Apr 27, 2012.<br/>
       Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.8.<br/>
     </p>
   </div>

playbooks.html

@@ -684,7 +684,7 @@ Let&#8217;s run a playbook using a parallelism level of 10:</p>
     <p class="pull-right"><a href="#">Back to top</a></p>
     <p>
         &copy; Copyright 2012 Michael DeHaan.<br/>
-      Last updated on Apr 25, 2012.<br/>
+      Last updated on Apr 27, 2012.<br/>
       Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.8.<br/>
     </p>
   </div>

rst/moduledev.rst

@@ -17,8 +17,9 @@ We are going to use Python here but any language is possible.  Only File I/O and
 out are required.  So, bash, C++, clojure, Python, Ruby, whatever you want
 is fine.  
 
-It's obvious that you would never really need to build a module to set the system time,
-the 'command' module could already be used to do this.  However, it makes for a decent example.
+So, here's an example.  You would never really need to build a module to set the system time,
+the 'command' module could already be used to do this.  Though we're going to make one.
+
 Reading the modules that come with ansible (linked above) is a great way to learn how to write
 modules.   Keep in mind, though, that some modules in ansible's source tree are internalisms,
 so look at `service` or `yum`, and don't stare too close into things like `async_wrapper` or
@@ -187,6 +188,15 @@ You should also never do this in a module::
 Because the output is supposed to be valid JSON.  Except that's not quite true,
 but we'll get to that later.
 
+Further, modules must not output anything on stderr, even if the JSON returned
+out stdout is valid.  This is due to the internals of our SSH library, more or less.
+
+If a module returns stderr or otherwise fails to produce valid JSON, the actual output
+will still be shown in Ansible, however, but the command will not succeed.
+
+Always use the hacking/test-module script when developing modules and it will warn
+you about these kind of things.
+
 Conventions
 ```````````
 

search.html

@@ -179,7 +179,7 @@ s.parentNode.insertBefore(ga, s);
     <p class="pull-right"><a href="#">Back to top</a></p>
     <p>
         &copy; Copyright 2012 Michael DeHaan.<br/>
-      Last updated on Apr 25, 2012.<br/>
+      Last updated on Apr 27, 2012.<br/>
       Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.8.<br/>
     </p>
   </div>