Added more documentation in the README

README.md

@@ -2,38 +2,106 @@ node-xml2js
 ===========
 
 Description
------------
-
-Simple XML to JavaScript object converter. Uses [sax-js](http://github.com/isaacs/sax-js/).
+===========
 
-See the tests for examples until docs are written.
+Simple XML to JavaScript object converter. Uses
+[sax-js](http://github.com/isaacs/sax-js/).
 
 Note: If you're looking for a full DOM parser, you probably want
 [JSDom](http://github.com/tmpvar/jsdom).
 
 Installation
-------------
+============
 
 Simplest way to install `xml2js` is to use [npm](http://npmjs.org), just `npm
 install xml2js` which will download xml2js and all dependencies.
 
-Simple usage
------------
+Usage
+=====
+
+This will have to do, unless you're looking for some fancy extensive
+documentation. If you're looking for every single option and usage, see the
+unit tests.
+
+Simple as pie usage
+-------------------
+
+The simplest way to use it, is to use the optional callback interface added in
+0.1.11. That's right, if you have been using xml-simple or a home-grown
+wrapper, this is for you:
 
-    var fs = require('fs'),
-        xml2js = require('xml2js');
+```javascript
+var fs = require('fs'),
+    xml2js = require('xml2js');
 
-    var parser = new xml2js.Parser();
-    parser.addListener('end', function(result) {
+var parser = new xml2js.Parser();
+fs.readFile(__dirname + '/foo.xml', function(err, data) {
+    parser.parseString(data, function (err, result) {
         console.dir(result);
-        console.log('Done.');
-    });
-    fs.readFile(__dirname + '/foo.xml', function(err, data) {
-        parser.parseString(data);
+	console.log('Done');
     });
+});
+```
+
+Look ma, no event listeners! Alternatively you can still use the traditional
+`addListener` variant:
+
+```javascript
+var fs = require('fs'),
+    xml2js = require('xml2js');
+
+var parser = new xml2js.Parser();
+parser.addListener('end', function(result) {
+    console.dir(result);
+    console.log('Done.');
+});
+fs.readFile(__dirname + '/foo.xml', function(err, data) {
+    parser.parseString(data);
+});
+```
+
+You can also use xml2js from
+[CoffeeScript](http://jashkenas.github.com/coffee-script/), further reducing
+the clutter:
+
+```coffeescript
+fs = require 'fs',
+xml2js = require 'xml2js'
+
+parser = new xml2js.Parser()
+fs.readFile __dirname + '/foo.xml', (err, data) ->
+  parser.parseString data, (err, result) ->
+    console.dir result
+    console.log 'Done.'
+```
+
+So you wanna some JSON?
+-----------------------
+
+Just wrap the `result` object in a call to `JSON.stringify` like this
+`JSON.strintify(result)`. You get a string containing the JSON representation
+of the parsed object that you can feed to JSON-hungry consumers.
+
+Displaying results
+------------------
+
+You might wonder why, using `console.dir` or `console.log` the output at some
+level is only `[Object]`. Don't worry, this is not because xml2js got lazy.
+That's because Node uses `util.inspect` to convert the object into strings and
+that function stops after `depth=2` which is a bit low for most XML.
+
+To display the whole deal, you can use `console.log(util.inspect(result, false,
+null))`, which displays the whole result.
+
+So much for that, but what if you use
+[eyes](https://github.com/cloudhead/eyes.js) for nice colored output and it
+truncates the output with `…`? Don't fear, there's also a solution for that,
+you just need to increase the `maxLength` limit by creating a custom inspector
+`var inspect = require('eyes').inspector({maxLength: false})` and then you can
+easily `inspect(result)`.
 
 Options
--------
+=======
 
 Apart from the default settings, there is a number of options that can be
 specified for the parser. Options are specified by ``new Parser({optionName:
@@ -47,16 +115,16 @@ value})``. Possible options are:
     node in the resulting object.
   * `emptyTag` (default: `undefined`): what will the value of empty nodes be.
     Default is `{}`.
-  * `explicitArray` (default: `false`): Always put child nodes in an array if true;
-    otherwise an array is created only if there is more than one.
+  * `explicitArray` (default: `false`): Always put child nodes in an array if
+    true; otherwise an array is created only if there is more than one.
 
 These default settings are for backward-compatibility (and might change in the
 future). For the most 'clean' parsing, you should disable `normalize` and
 `trimming` and enable `explicitRoot`.
 
 Running tests, development
---------------------------
+==========================
 
 The development requirements are handled by npm, you just need to install
-them. We also have a number of unittests, they can be run using `zap`
+them. We also have a number of unit tests, they can be run using `zap`
 directly from the project root.