docco is wonderful, but it isn't exactly the most concise way of figuring out how to use acorn. Here's a real README.

Fixed a typo in the options comments.

README.md

@@ -1,5 +1,122 @@
 # Acorn
 
-A tiny, fast JavaScript parser in JavaScript.
+[acorn]: http://marijnhaverbeke.nl/acorn/
+[range]: https://bugzilla.mozilla.org/show_bug.cgi?id=745678
 
-See http://marijnhaverbeke.nl/acorn/
+A tiny, fast JavaScript parser, written completely in JavaScript.
+
+## Invoking
+
+Acorn can be invoked in several ways.
+
+- From a Node script.
+- From the command line.
+- From a browser script.
+
+### Node script
+
+To use acorn from a [Node](http://nodejs.org) script, install acorn as a package as usual using npm:
+
+```sh
+npm install acorn
+```
+
+Alternately, download the source and link to that:
+
+```sh
+git clone https://github.com/marijnh/acorn.git
+cd acorn
+npm link
+cd /path/to/project
+npm link acorn
+```
+
+Now you can `require` acorn in your node scripts. The main entrypoint to acorn is the `parse` function, which returns an object with the AST nodes:
+
+```javascript
+var fs = require('fs'),
+    acorn = require('acorn');
+
+try
+{
+    var code = fs.readFileSync(pathToFile, "utf8"),
+        ast = acorn.parse(code);
+}
+catch(e)
+{
+    console.error(e.message);
+    process.exit(1);
+}
+```
+
+### Command line
+
+To use acorn from the command line, use the `acorn` binary, which is installed when you use npm to install or link the acorn package. Alternately, you can execute `bin/acorn` directly. The syntax is as follows:
+
+```text
+acorn [options] file
+
+Parses <file> and outputs the AST in JSON format.
+
+Options:
+--ecma3|--ecma5     Sets the ECMAScript version to parse. Default is version 5.
+--strictSemicolons  Prevents the parser from doing automatic semicolon insertion.
+                    Statements that do not end in semicolons will generate an error.
+--locations         Attaches a "loc" object to each node with "start" and "end" subobjects,
+                    each of which contains the one-based line and zero-based column numbers
+                    in {line, column} form.
+--compact           No whitespace is used in the AST output.
+--silent            Do not output the AST, just return the exit status.
+--help              Print this usage information and quit.
+```
+
+### Browser script
+
+To use acorn in the browser, load `acorn.js` with a `<script>` tag:
+
+```
+<script src="acorn.js" type="text/javascript"></script>
+```
+
+Acorn is compatible with [AMD](https://github.com/amdjs/amdjs-api/wiki/AMD), so you may also use loaders like [require.js](http://www.requirejs.org) to load acorn in the browser.
+
+Once acorn is loaded, you may use acorn within your own scripts by calling `acorn.parse` as illustrated in the Node example above.
+
+## Options
+
+The optional second parameter to the `parse` function is an options object. Acorn supports a number of options that control its behavior and its output.
+
+- **ecmaVersion**: Indicates the ECMAScript version to parse. Must be either 3 or 5. This influences support for strict mode, the set of reserved words, and support for getters and setter. *Default*: 5
+
+- **strictSemicolons**: If `true`, prevents the parser from doing automatic semicolon insertion, and statements that do not end with a semicolon will generate an error. *Default*: `false`
+
+- **allowTrailingCommas**: If `false`, the parser will not allow trailing commas in array and object literals.
+
+- **forbidReserved**: If `true`, using a reserved word will generate an error. *Default*: `false`
+
+- **locations**: When `true`, each node has a "loc" object attached with "start" and "end" subobjects, each of which contains the one-based line and zero-based column numbers in `{line, column}` form. *Default*: `false`
+
+- **onComment**: If a function is passed for this option, whenever a comment is encountered the function will be called with the following parameters:
+    - **block**: `true` if the comment is a block comment, false if it is a line comment.
+    - **text**: The content of the comment.
+    - **start**: Character offset of the start of the comment.
+    - **end**: Character offset of the end of the comment.
+
+    When the `locations` options is on, the `{line, column}` locations of the comment’s start and end are passed as two additional parameters. *Default*: `null`
+
+- **ranges**: Nodes have their start and end characters offsets recorded in "start" and "end" properties (directly on the node, rather than the "loc" object, which holds line/column data. To also add a [semi-standardized][range] "range" property holding a `[start, end]` array with the same numbers, set the `ranges` option to `true`. *Default*: `false`
+
+- **program**: It is possible to parse multiple files into a single AST by passing the tree produced by parsing the first file as the `program` option in subsequent parses. This will add the toplevel forms of the parsed file to the "Program" (top) node of an existing parse tree. *Default*: `null`
+
+- **sourceFile**: When the `locations` option is `true`, you can pass this option to add a "sourceFile" attribute in every node’s "loc" object. Note that the contents of this option are not examined or processed in any way; you are free to use whatever format you choose. *Default*: `null`
+
+- **directSourceFile**: Like the `sourceFile` option, but adds a "sourceFile" attribute directly to every node, whether or not `locations` is `true`. *Default*: `null`
+
+## Errors
+
+When an error occurs, acorn throws a `SyntaxError` with the following attributes:
+
+- **message**: A descriptive message of the error. The error message will end with `(line:column)`, where `line` is the one-based line number on which the error occurred, and `column` is the zero-based column within that line.
+- **pos**: The zero-based character position at which the error occurred.
+- **loc**: An object in the form `{line:N, column:N}`, where `line` is the one-based line number on which the error occurred, and `column` is the zero-based column number within that line.
+- **raisedAt**: The zero-based character position the parser had reached at the point where the error occurred.

acorn.js

@@ -94,11 +94,11 @@
     // toplevel forms of the parsed file to the `Program` (top) node
     // of an existing parse tree.
     program: null,
-    // When `location` is on, you can pass this to record the source
+    // When `locations` is on, you can pass this to record the source
     // file in every node's `loc` object.
     sourceFile: null,
     // This value, if given, is stored in every node, whether
-    // `location` is on or off.
+    // `locations` is on or off.
     directSourceFile: null
   };