Merge pull request #4 from yahoo/readme

Add more content to README

Author: ericf

LICENSE

@@ -28,7 +28,7 @@ SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
 --------------------------------------------------------------------------------
 
-Inspired by and derivied from:
+Inspired by and derived from:
 messageformat.js https://github.com/SlexAxton/messageformat.js
 Copyright 2014 Alex Sexton
 Apache License, Version 2.0

README.md

@@ -1,26 +1,63 @@
-intl-messageformat-parser
+Intl MessageFormat Parser
 =========================
 
-Parses ICU message strings to an AST that can be used to format the messages for
-a person's locale.
+Parses [ICU Message strings][ICU] into an AST via JavaScript.
 
-[![npm Version](https://img.shields.io/npm/v/intl-messageformat-parser.svg?style=flat)][npm]
-[![Dependency Status](https://img.shields.io/david/yahoo/intl-messageformat-parser.svg?style=flat)][david]
+[![npm Version][npm-badge]][npm]
+[![Build Status][travis-badge]][travis]
+[![Dependency Status][david-badge]][david]
+
+
+Overview
+--------
+
+This package implements a parser in JavaScript that parses the industry standard [ICU Message strings][ICU] — used for internationalization — into an AST. The produced AST can then be used by a compiler, like [`intl-messageformat`][intl-mf], to produce localized formatted strings for display to users.
+
+This parser is written in [PEG.js][], a parser generator for JavaScript. This parser's implementation was inspired by and derived from Alex Sexton's [messageformat.js][] project. The differences from Alex's implementation are:
+
+- This project is standalone.
+- It's authored as ES6 modules compiled to CommonJS and the Bundle format for the browser.
+- The produced AST is more descriptive and uses recursive structures.
+- The keywords used in the AST match the ICU Message "spec".
 
-[npm]: https://www.npmjs.org/package/intl-messageformat-parser
-[david]: https://david-dm.org/yahoo/intl-messageformat-parser
 
 Usage
 -----
 
-Given a message like this:
+### Loading in the Browser
+
+The `dist/` folder contains the version of this package for use in the browser, and it can be loaded and used like this:
+
+```html
+<script src="intl-messageformat-parser/dist/parser.min.js"></script>
+<script>
+    IntlMessageFormatParser.parse('...');
+</script>
+```
+
+### Loading in Node.js
+
+This package can also be `require()`-ed in Node.js:
 
 ```js
-var photosMsg = 'On {takenDate, date, short} {name} took {numPhotos, plural,' +
-    '=0 {no photos :(}' +
-    '=1 {one photo.}' +
-    'other {# photos!}}';
+var parser = require('intl-messageformat-parser');
+parser.parse('...');
+```
+
+### Example
+
+Given an ICU Message string like this:
+
+```
+On {takenDate, date, short} {name} took {numPhotos, plural,
+    =0 {no photos.}
+    =1 {one photo.}
+    other {# photos.}
+}
+```
 
+```js
+// Assume `msg` is the string above.
 parser.parse(msg);
 ```
 
@@ -70,7 +107,7 @@ This parser will produce this AST:
                             "elements": [
                                 {
                                     "type": "messageTextElement",
-                                    "value": "no photos :("
+                                    "value": "no photos."
                                 }
                             ]
                         }
@@ -96,7 +133,7 @@ This parser will produce this AST:
                             "elements": [
                                 {
                                     "type": "messageTextElement",
-                                    "value": "# photos!"
+                                    "value": "# photos."
                                 }
                             ]
                         }
@@ -108,10 +145,22 @@ This parser will produce this AST:
 }
 ```
 
+
 License
 -------
 
 This software is free to use under the Yahoo! Inc. BSD license.
 See the [LICENSE file][] for license text and copyright information.
 
-[LICENSE file]: /blob/master/LICENSE
+
+[npm]: https://www.npmjs.org/package/intl-messageformat-parser
+[npm-badge]: https://img.shields.io/npm/v/intl-messageformat-parser.svg?style=flat-square
+[david]: https://david-dm.org/yahoo/intl-messageformat-parser
+[david-badge]: https://img.shields.io/david/yahoo/intl-messageformat-parser.svg?style=flat-square
+[travis]: https://travis-ci.org/yahoo/intl-messageformat-parser
+[travis-badge]: https://img.shields.io/travis/yahoo/intl-messageformat-parser.svg?style=flat-square
+[ICU]: http://userguide.icu-project.org/formatparse/messages
+[intl-mf]: https://github.com/yahoo/intl-messageformat
+[PEG.js]: http://pegjs.majda.cz
+[messageformat.js]: https://github.com/SlexAxton/messageformat.js
+[LICENSE file]: https://github.com/yahoo/intl-messageformat-parser/blob/master/LICENSE

package.json

@@ -1,7 +1,7 @@
 {
   "name": "intl-messageformat-parser",
   "version": "1.0.0-rc-2",
-  "description": "Parses ICU message strings to an AST that can be used to format the messages for a person's locale.",
+  "description": "Parses ICU Message strings into an AST via JavaScript.",
   "main": "index.js",
   "jsnext:main": "src/parser.js",
   "scripts": {