Merge pull request #2109 from lorin/pipe_once_docs

Document new PIPE_ONCE macro

docsite/rst/playbooks2.rst

@@ -567,7 +567,7 @@ Negative numbers are not supported.  This works as follows::
 Getting values from files
 `````````````````````````
 
-.. versionadded: 0.8
+.. versionadded:: 0.8
 
 Sometimes you'll want to include the content of a file directly into a playbook.  You can do so using a macro.
 This syntax will remain in future versions, though we will also will provide ways to do this via lookup plugins (see "More Loops") as well.  What follows
@@ -583,6 +583,20 @@ is an example using the authorized_key module, which requires the actual text of
 
 The "$PIPE" macro works just like file, except you would feed it a command string instead.  It executes locally, not remotely, as does $FILE.
 
+Because Ansible uses lazy evaluation, a "$PIPE" macro will be executed each time it is used. For
+example, it will be executed separately for each host, and if it is used in a variable definition,
+it will be executed each time the variable is evaluated.
+
+.. versionadded:: 1.1
+
+The "$PIPE_ONCE" macro is an alternative that uses a caching strategy: it is executed only once, and
+subsequent accesses use the cached value. One use case is for computing a timestamp that is intended
+to be the same across all tasks and hosts that use it::
+
+    vars:
+      timestamp: $PIPE_ONCE(date +%Y%m%d-%H%M%S)
+
+
 Selecting Files And Templates Based On Variables
 ````````````````````````````````````````````````