Update YAMLSyntax.rst

Updated to include a bit more depth in explaining the YAML, along with a link the Wikipedia page on YAML syntax.

1 files changed, 37 insertions, 2 deletions

diff --git a/docsite/rst/YAMLSyntax.rst b/docsite/rst/YAMLSyntax.rst
index 8189a6caf6..4b2ec0535d 100644
--- a/docsite/rst/YAMLSyntax.rst
+++ b/docsite/rst/YAMLSyntax.rst
@@ -42,6 +42,24 @@ A dictionary is represented in a simple ``key: value`` form (the colon must be f
         job: Developer
         skill: Elite
 
+More complicated data structures are possible, such as lists of dictionaries, or dictionaries whose values are lists.  Or a mix of both::
+
+    # Employee records
+    -  martin:
+        name: Martin D'vloper
+        job: Developer
+        skills:
+          - python
+          - perl
+          - pascal
+    -  tabitha:
+        name: Tabitha Bitumen
+        job: Developer
+        skills:
+          - lisp
+          - fortran
+          - erlang
+
 Dictionaries and lists can also be represented in an abbreviated form if you really want to::
 
     ---
@@ -59,6 +77,17 @@ Ansible doesn't really use these too much, but you can also specify a boolean va
     likes_emacs: TRUE
     uses_cvs: false
 
+Values can span multiple lines using *|* or *>* to include newlines or ignore them::
+
+    ignore_newlines: >
+                this is really a
+                single line of text
+                despite appearances
+                
+    include_newlines: |
+                exactly as you see
+                will appear these three
+                lines of poetry
 
 Let's combine what we learned so far in an arbitrary YAML example.
 This really has nothing to do with Ansible, but will give you a feel for the format::
@@ -75,9 +104,13 @@ This really has nothing to do with Ansible, but will give you a feel for the for
         - Strawberry
         - Mango
     languages:
-        ruby: Elite
+        perl: Elite
         python: Elite
-        dotnet: Lame
+        pascal: Lame
+    education: |
+        4 GCSEs
+        3 A-Levels
+        BSc in the Internet of Things
 
 That's all you really need to know about YAML to start writing `Ansible` playbooks.
 
@@ -116,6 +149,8 @@ In these cases just use quotes::
        YAML Lint (online) helps you debug YAML syntax if you are having problems
    `Github examples directory <https://github.com/ansible/ansible-examples>`_
        Complete playbook files from the github project source
+   `Wikipedia YAML syntax reference <https://en.wikipedia.org/wiki/YAML>`_
+       A good guide to YAML syntax
    `Mailing List <http://groups.google.com/group/ansible-project>`_
        Questions? Help? Ideas?  Stop by the list on Google Groups
    `irc.freenode.net <http://irc.freenode.net>`_