big README revamp

README.md

@@ -2,72 +2,94 @@ JSON to YAML
 ===
 
 The purpose of this utility is to pretty-print JSON in the human-readable YAML object notation
-(ignore the misnomer, it's not a markup language at all)
+(ignore the misnomer, YAML is not a Markup Language at all).
 
-You see, JSON is a proper subset of YAML, The difference is that YAML can use whitespace instead of syntax, which is more human-readable.
-Also, YAML supports comments.
+Installation
+===
 
-So, for all the times you want to turn JSON int YAML (YML):
+```bash
+npm install -g json2yaml
+```
 
-    {
-      "foo": "bar",
-      "baz": [
-        "qux",
-        "quxx"
-      ],
-      "corge": null,
-      "grault": 1,
-      "garply": true,
-      "waldo": "false",
-      "fred": "undefined"
-    }
-
-becomes
-
-    ---
-      foo: "bar"
-      baz:
-        - "qux"
-        - "quxx"
-      corge: null
-      grault: 1
-      garply: true
-      waldo: "false"
-      fred: "undefined"
+*Note*: To use `npm` and `json2yaml` you must have installed [NodeJS](http://nodejs.org#download).
 
 Usage
 ---
 
 Specify a file:
 
-    json2yaml ./example.json
+```bash
+json2yaml ./example.json > ./example.yml
 
-    yaml2json ./example.kml | json2yaml
+yaml2json ./example.yml | json2yaml > ./example.yml
+```
 
 Or pipe from stdin:
 
-    curl -s http://foobar3000.com/echo/echo.json | json2yaml
+```bash
+curl -s http://foobar3000.com/echo/echo.json | json2yaml
 
-    wget -qO- http://foobar3000.com/echo/echo.json | json2yaml
+wget -qO- http://foobar3000.com/echo/echo.json | json2yaml
+```
 
 Or require:
 
-   (function () {
-      "use strict";
+```javascript
+(function () {
+  "use strict";
 
-      var YAML = require('json2yaml')
-        , ymlText
-        ;
+  var YAML = require('json2yaml')
+    , ymlText
+    ;
 
-      ymlText = YAML.stringify({
-          "foo": "bar"
-        , "baz": "corge"
-      });
+    ymlText = YAML.stringify({
+      "foo": "bar"
+    , "baz": "corge"
+    });
 
-      console.log(ymlText);
-    }()); 
+    console.log(ymlText);
+}());
+```
 
-Installation
+Example
+===
+
+So, for all the times you want to turn JSON int YAML (YML):
+
+```javascript
+{ "foo": "bar"
+, "baz": [
+    "qux"
+  , "quxx"
+  ]
+, "corge": null
+, "grault": 1
+, "garply": true
+, "waldo": "false"
+, "fred": "undefined"
+}
+```
+
+becomes
+
+```yaml
 ---
+  foo: "bar"
+  baz:
+    - "qux"
+    - "quxx"
+  corge: null
+  grault: 1
+  garply: true
+  waldo: "false"
+  fred: "undefined"
+```
 
-    npm install -g json2yaml
+*Note*: In fact, both of those Object Notations qualify as YAML
+because JSON technically *is* a proper subset of YAML.
+That is to say that all proper YAML parsers parse proper JSON.
+
+YAML can use either *whitespace and dashes* or *brackets and commas*.
+
+For human readability, the whitespace-based YAML is preferrable.
+For compression and computer readability, the syntax-based YAML is preferrable.