Some readme cleanup

README.md

@@ -28,7 +28,6 @@ Design Principles
     * No server or client daemons, uses existing SSHd
     * No additional software required on client boxes
     * Everything is self updating on the clients  
-    * Encourages use of ssh-agent
     * Plugins can be written in ANY language
     * API usage is an equal citizen to CLI usage
     * Can be controlled/installed/used as non-root
@@ -49,12 +48,10 @@ Optional -- If you want to push templates, the nodes need:
 Inventory file
 ==============
 
-The inventory file is a required list of hostnames that can be 
+To use ansible you must have a list of hosts somewhere.
-potentially managed by ansible.  Eventually this file may be editable 
-via the CLI, but for now, is edited with your favorite text editor.
 
 The default inventory file (-H) is /etc/ansible/hosts and is a list
-of all hostnames to target with ansible, one per line.  These
+of all hostnames to manage with ansible, one per line.  These
 can be hostnames or IPs
 
 Example:
@@ -70,63 +67,14 @@ specific hosts.  This is covered below.
 You can organize groups of systems by having multiple inventory
 files (i.e. keeping webservers different from dbservers, etc)
 
-Command line usage example
+Massive Parallelism, Pattern Matching, and a Usage Example
-==========================
+==========================================================
 
-Run a module by name with arguments
+Reboot all web servers in Atlanta, 10 at a time:
  
    * ssh-agent bash
    * ssh-add ~/.ssh/id_rsa.pub
-   * ansible -p "*.example.com" -n modName -a "arg1 arg2"
+   * ansible -p "atlanta-web*" -f 10 -n command -a "/sbin/reboot"
-
-API Example
-===========
-
-The API is simple and returns basic datastructures.  Ansible will keep
-track of which hosts were successfully contacted seperately from hosts
-that had communication problems.  The format of the return, if successful,
-is entirely up to the module.
-
-
-    import ansible.runner
-    runner = ansible.runner.Runner(
-        pattern='*',
-        module_name='inventory',
-        module_args='...' 
-    )
-    data = runner.run()
-
-data is a dictionary:
-    { 
-        'contacted' : {
-            'xyz.example.com' : [ 'any kind of datastructure is returnable' ],
-            'foo.example.com' : [ '...' ]
-        },
-        'dark' : {
-            'bar.example.com' : [ 'failure message' ]
-        }
-    }
-
-Additional options to Runner include the number of forks, hostname
-exclusion pattern, library path, arguments, and so on.  
-
-Read the source, it's not complicated.
-
-Patterns
-========
-
-To target only hosts starting with "rtp", for example:
-
-   * ansible -p "rtp*" -n command -a "yum update apache"
-
-Parallelism
-===========
-
-Specify the number of forks to use, to run things in greater parallelism.
-
-    * ansible -f 10 "*.example.com" -n command -a "yum update apache"
-
-10 forks.  The default is 3.  5 is right out.
 
 File Transfer
 =============
@@ -135,38 +83,45 @@ Ansible can SCP lots of files to lots of places in parallel.
 
    * ansible -p "web-*.acme.net" -f 10 -n copy -a "/etc/hosts /tmp/hosts"
 
-Ansible Library (Bundled Modules)
+Templating
-=================================
+==========
 
-See the example library for modules, they can be written in any language
+JSON files can be placed for template metadata using Jinja2.  Variables
-and simply return JSON to stdout.  The path to your ansible library is
+placed by 'setup' can be reused between ansible runs.
-specified with the "-L" flag should you wish to use a different location
-than "/usr/share/ansible".  This means anyone can use Ansible, even without
-root permissions.
 
-There is potential for a sizeable community to build 
+   * ansible -p "*" -n setup -a "ntp_server=192.168.1.1"
-up around the library scripts, and you can easily write your own.
+   * ansible -p "*" -n template /srv/motd.j2 /etc/motd 
+   * ansible -p "*" -n template /srv/foo.j2 /etc/foo
 
-Current modules include:
+Git Deployments
+===============
 
-   * command - runs commands, giving output, return codes, and run time info
+Deploy your webapp straight from git
-   * ping - just returns if the system is up or not
-   * facter - retrieves facts about the host OS
-   * ohai - similar to facter, but returns structured data
-   * copy - add files to remote systems
-   * setup - pushes key/value data onto the system for use in templating
-   * template - takes a local template file and saves a templated version remotely
-   * git - deploy simple apps directly from source control
 
-More coming soon!  Contributions welcome!
+  * ansible -p "web*" -n git -a "repo=git://foo dest=/srv/myapp version=HEAD"
+
+Take Inventory
+==============
+
+Run popular open-source data discovery tools across a wide number of hosts.
+This is best used from API scripts.
+
+  * ansible -p "dbserver*" -n facter
+  * ansible -p "dbserver"" -n ohai
+
+Other Modules
+=============
+
+See the library directory for lots of extras.  There's also a manpage,
+ansible-modules(5).
 
 Playbooks
 =========
 
 Playbooks are particularly awesome.  Playbooks can batch ansible commands
-together, and run some commands only when ansible modifies certain higher
+together, and can even fire off triggers when certain commands report changes.
-level resources -- such as restarting apache when a configuration file is 
+They are the basis for a really simple configuration management system, unlike
-replaced.  They generate detailed reports of what happend on each node.
+any that already exist.  Powerful, concise, but dead simple.
 
 See examples/playbook.yml for what the syntax looks like.
 
@@ -174,10 +129,7 @@ To run a playbook:
 
 ansible -r playbook.yml
 
-An ansible-playbook CLI command is pending.  Until then, remember that when
+Read ansible-playbook(5) for more details.
-using playbooks, the pattern and host list options come from the playbook
-and are ignored.  Other options still apply.
-
 
 Future plans
 ============
@@ -192,6 +144,7 @@ License
 Mailing List
 ============
 
+   * Join the mailing list to talk about Ansible!
    * [ansible-project](http://groups.google.com/group/ansible-project)
 
 Author