Rename 'yamlscripts' to 'yamlsyntax', add some extra crosslinking to make sure folks find the

interesting docs pages, some misc editing here and there.

rst/YAMLScripts.rst

@@ -1,83 +0,0 @@
-YAML Format
-===========
-
-This page provides a basic overview of correct YAML syntax, which is how Ansible
-playbooks (our configuration management language) are expressed.  
-You may also wish to read playbook examples and will quickly pick this up from those.
-
-YAML Basics
------------
-
-For `ansible`, every YAML file must be a list at it's root-most
-element. Each item in the list is a dictionary. These dictionaries
-represent all the options you can use to write an `ansible` file. In
-addition, all YAML files (regardless of their association with
-`ansible` or not) should start with ``---``.
-
-In YAML a list can be represented in two ways. In one way all members
-of a list are lines beginning at the same indentation level starting
-with a ``-`` character::
-
-    ---
-    # A list of tasty fruits
-    - Apple
-    - Orange
-    - Strawberry
-    - Mango
-
-In the second way a list is represented as comma separated elements
-surrounded by square brackets. Newlines are permitted between
-elements::
-
-    ---
-    # A list of tasty fruits
-    [apple, orange, banana, mango]
-
-A dictionary is represented in a simple ``key:`` and ``value`` form::
-
-    ---
-    # An employee record
-    name: John Eckersberg
-    job: Developer
-    skill: Elite
-
-Like lists, dictionaries can be represented in an abbreviated form::
-
-    ---
-    # An employee record
-    {name: John Eckersberg, job: Developer, skill: Elite}
-
-.. _truthiness:
-
-You can specify a boolean value (true/false) in several forms::
-
-    ---
-    knows_oop: True
-    likes_emacs: TRUE
-    uses_cvs: false
-
-Finally, you can combine these data structures::
-
-    ---
-    # An employee record
-    name: John Eckersberg
-    job: Developer
-    skill: Elite
-    employed: True
-    foods:
-        - Apple
-        - Orange
-        - Strawberry
-        - Mango
-    languages:
-        ruby: Elite
-	python: Elite
-	dotnet: Lame
-
-That's all you really need to know about YAML to get started writing
-`Ansible` playbooks.
-
-.. seealso::
-
-   `YAMLLint <http://yamllint.com/>`_
-       YAML Lint gets the lint out of your YAML

rst/YAMLSyntax.rst

@@ -0,0 +1,94 @@
+YAML Syntax
+===========
+
+This page provides a basic overview of correct YAML syntax, which is how Ansible
+playbooks (our configuration management language) are expressed.  
+
+We use YAML because it is easier to read and write for humans than other common 
+data formats like XML or JSON.  Further, there are libraries available for reading
+and writing YAML in most programming languages.  
+
+You may also wish to read playbook examples at the same time to see how this
+is used in practice.
+
+.. seealso::
+
+   :doc:`playbooks`
+       See YAML examples in practice in playbooks
+
+
+YAML Basics
+-----------
+
+For `ansible`, every YAML file starts with a list of things
+to do.   Each item in the list is a list of key/value pairs, commonly
+called a "hash" or a "dictionary".  So, we need to know how
+to write lists and dictionaries in YAML.
+
+There's another small quirk to YAML.  All YAML files (regardless of their association with
+`ansible` or not) should start with ``---``.  This is just a YAML
+format thing that means "this is the start of a document".
+
+All members of a list are lines beginning at the same indentation level starting
+with a ``-`` (dash) character::
+
+    ---
+    # A list of tasty fruits
+    - Apple
+    - Orange
+    - Strawberry
+    - Mango
+
+A dictionary is represented in a simple ``key:`` and ``value`` form::
+
+    ---
+    # An employee record
+    name: John Eckersberg
+    job: Developer
+    skill: Elite
+
+Dictionaries can also be represented in an abbreviated form if you really want to::
+
+    ---
+    # An employee record
+    {name: John Eckersberg, job: Developer, skill: Elite}
+
+.. _truthiness:
+
+Ansible doesn't really use these too much, but you can also specify a 
+boolean value (true/false) in several forms::
+
+    ---
+    knows_oop: True
+    likes_emacs: TRUE
+    uses_cvs: false
+
+Let's combine what we learned so far in an arbitary YAML example.  This really
+has nothing to do with Ansible, but will give you a feel for the format::
+
+    ---
+    # An employee record
+    name: John Eckersberg
+    job: Developer
+    skill: Elite
+    employed: True
+    foods:
+        - Apple
+        - Orange
+        - Strawberry
+        - Mango
+    languages:
+        ruby: Elite
+	python: Elite
+	dotnet: Lame
+
+That's all you really need to know about YAML to get started writing
+`Ansible` playbooks.
+
+.. seealso::
+
+   :doc:`playbooks`
+       Learn what playbooks can do and how to write/run them.
+   `YAMLLint <http://yamllint.com/>`_
+       YAML Lint (online) helps you debug YAML syntax if you are having problems
+

rst/faq.rst

@@ -181,3 +181,10 @@ It also excels for writing distributed
 scripts and ad-hoc applications that need to gather data or perform arbitrary
 tasks -- whether for a QA sytem, build system, or anything you can think of.
 
+.. seealso::
+
+   :doc:`examples`
+       Examples of basic commands
+   :doc:`playbooks`
+       Learning ansible's configuration management language
+

rst/gettingstarted.rst

@@ -99,13 +99,16 @@ Now run a live command on all of your nodes::
     ansible all /bin/echo hello
 
 Congratulations.  You've just contacted your nodes with Ansible.  It's
-now time to read some of the more real-world examples, and explore
+now time to read some of the more real-world :doc:`examples`, and explore
 what you can do with different modules, as well as the Ansible
-playbooks language.  Ansible is not just about running commands, but
+:doc:`playbooks` language.  Ansible is not just about running commands, but
 you already have a working infrastructure!
 
 
 .. seealso::
 
-   :ref:`Inventory <inventoryformat>`
-       Complete documentation on the inventory file format
+   :doc:`examples`
+       Examples of basic commands
+   :doc:`playbooks`
+       Learning ansible's configuration management language
+

rst/index.rst

@@ -88,7 +88,7 @@ Contents
    patterns
    examples
    modules
-   YAMLScripts
+   YAMLSyntax
    playbooks
    api
    faq

rst/patterns.rst

@@ -34,6 +34,8 @@ looks like this::
     two.example.com
     three.example.com
 
+The things in brackets are group names, you don't have to have them,
+but they are useful.
 
 Selecting Targets
 +++++++++++++++++
@@ -43,19 +45,20 @@ These patterns target all hosts in the inventory file::
     all
     *    
 
-It is also possible to address specific hosts::
+Basically 'all' is an alias for '*'.  It is also possible to address a specific host or hosts::
 
     one.example.com
     one.example.com:two.example.com
+    192.168.1.50
+    192.168.1.*
  
-
 The following patterns address one or more groups, which are denoted
-with the bracket headers in the inventory file::
+with the aforementioned bracket headers in the inventory file::
 
     webservers
     webservers:dbservers
 
-Individual hosts, but not groups, can also be referenced using
+Individual host names (or IPs), but not groups, can also be referenced using
 wildcards::
 
     *.example.com
@@ -66,4 +69,8 @@ It's also ok to mix wildcard patterns and groups at the same time::
     one*.com:dbservers
 
 .. note::
-    It is not possible to target a host not in the inventory file.
+    It is not possible to target a host not in the inventory file.   This is a safety feature.
+
+Easy enough.  Now see :doc:`examples` and then :doc:`playbooks` for how to do things to selected hosts.
+
+

rst/playbooks.rst

@@ -3,7 +3,7 @@ Playbooks
 
 .. seealso::
 
-   :doc:`YAMLScripts`
+   :doc:`YAMLSyntax`
        Learn about YAML syntax
    :doc:`modules`
        Learn about available modules and writing your own