Document new PIPE_ONCE macro

docsite/rst/playbooks2.rst

@@ -583,6 +583,18 @@ 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.
+
+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
 ````````````````````````````````````````````````