From 1e787bd91e663d6fa291290dc83482ee3133429a Mon Sep 17 00:00:00 2001
From: Adam Miller <admiller@redhat.com>
Date: Wed, 4 Feb 2015 09:49:51 -0600
Subject: [PATCH] Add intro to playbook docs using YAML dictionaries

---
 docsite/rst/playbooks_intro.rst | 37 +++++++++++++++++++++++++++++++++
 1 file changed, 37 insertions(+)

diff --git a/docsite/rst/playbooks_intro.rst b/docsite/rst/playbooks_intro.rst
index ecf8d46de1e..4adb5d53a68 100644
--- a/docsite/rst/playbooks_intro.rst
+++ b/docsite/rst/playbooks_intro.rst
@@ -73,6 +73,43 @@ For starters, here's a playbook that contains just one play::
         - name: restart apache
           service: name=httpd state=restarted
 
+We can also break task items out over multiple lines using the YAML dictionary
+types to supply module arguments. This can be helpful when working with tasks
+that have really long parameters or modules that take many parameters to keep
+them well structured. Below is another version of the above example but using
+YAML dictionaries to supply the modules with their key=value arguments.::
+
+    ---
+    - hosts: webservers
+      vars:
+        http_port: 80
+        max_clients: 200
+      remote_user: root
+      tasks:
+      - name: ensure apache is at the latest version
+        yum:
+          pkg: httpd
+          state: latest
+      - name: write the apache config file
+        template:
+          src: /srv/httpd.j2
+          dest: /etc/httpd.conf
+        notify:
+        - restart apache
+      - name: ensure apache is running
+        service:
+          name: httpd
+          state: started
+      handlers:
+        - name: restart apache
+          service:
+            name: httpd
+            state: restarted
+
+.. note::
+
+    The above example using YAML dictionaries for module arguments can also be accomplished using the YAML multiline string syntax with the `>` character but this can lead to string quoting errors.
+
 Below, we'll break down what the various features of the playbook language are.
 
 .. _playbook_basics: