Update README with the canonicalize() stuff.

Author: tabatkins

README.md

@@ -67,6 +67,72 @@ because they're named exactly the same as the corresponding section of the Synta
 * `parseAListOfComponentValues()`
 * `parseACommaSeparatedListOfComponentValues()`
 
+Canonicalizing Against A Grammar
+--------------------------------
+
+By default, the parser can only do so much;
+it knows how to interpret the top-level rules in a stylesheet,
+but not how to interpret the contents of anything below that.
+This means that anything nested within a top-level block is left as a bare token stream,
+requiring you to call the correct parsing function on it.
+
+The `canonicalize()` function takes a parsing result and a grammar
+and transforms the result accordingly,
+rendering the result into an easier-to-digest form.
+
+A grammar is an object with one of the following four forms:
+
+1. ```
+	{"stylesheet":true}
+	```
+
+2. ```
+	{
+		"qualified": <grammar>,
+		"@foo": <grammar>,
+		"unknown": <function>
+	}
+	```
+
+3. ```
+	{
+		"declarations": true,
+		"@foo": <grammar>
+		"unknown": <function>
+	}
+	```
+
+4. `null`
+
+A `stylesheet` block contains nothing else;
+it just means that this rule uses the top-level grammar for its contents.
+This is true, for example, of the `@media` rule.
+
+A `qualified` block means that the rule's contents are qualified rules (style rules) and at-rules.
+The "qualified" key must have another grammar as its value (often `{declarations:true}`).
+Any at-rules that are valid in this context must be listed,
+also with a grammar for their contents.
+Optionally, the "unknown" key can be provided with a function value;
+this will be called with any unknown at-rules (ones not listed in the grammar)/
+If it returns a truthy value, it's inserted into the structure with everything else;
+if falsey, the rule is put into the "errors" entry of the resulting block for later processing or ignoring.
+
+A `declarations` block means that the rule's contents are declarations and at-rules.
+Currently, the "declarations" key only accepts the value `true`;
+eventually it'll allow you to specify what declarations are valid.
+Similar to `qualified` blocks,
+you must list what at-rules are allowed,
+and can provide an "unknown" function.
+
+A `null` just means that the block has no contents.
+This is used for at-rules that are statements,
+ended with a semicolon rather than a block,
+like `@import`.
+
+A `CSSGrammar` object is provided with a default grammar for CSS.
+If you call `canonicalize()` without a grammar,
+this is used automatically.
+
 Node Integration
 ----------------