Fleshed out README.

1 files changed, 70 insertions, 17 deletions

diff --git a/README.md b/README.md
index 1f7c7a5..f5099e4 100644
--- a/README.md
+++ b/README.md
@@ -1,27 +1,37 @@
 Standard markdown
 =================
 
-Standard markdown is a specification of markdown syntax, together
-with implementations (`stmd`) in C and javascript.
+Standard markdown is a specification of markdown syntax, together with
+implementations (`stmd`) in C and javascript.
+
+The implementations
+-------------------
 
 The C implementation provides both a library and a standalone program
-that converts markdown to HTML.  It is written in standard C99 and has
-no library dependencies.  (However, if you check it out from the
+`stmd` that converts markdown to HTML.  It is written in standard C99
+and has no library dependencies.  (However, if you check it out from the
 repository, you'll need `re2c` to generate `scanners.c` from
 `scanners.re`.  This is only a build dependency for developers, since
 `scanners.c` can be provided in a released source tarball.)
 
-The javascript implementation is a single javascript file
-that can be linked to an HTML page.  A standalone version (using
-`node.js`) is also provided (`js/markdown`), and there is a
-"dingus" for playing with it interactively.  (`make dingus` will start
+    Usage:   stmd [FILE*]
+    Options: --help, -h    Print usage information
+             --ast         Print AST instead of HTML
+             --version     Print version
+
+The javascript implementation is a single javascript file, with
+no dependencies, that can be linked to in an HTML page.  A standalone
+version (using `node.js`) is also provided (`js/markdown`), and there is
+a "dingus" for playing with it interactively.  (`make dingus` will start
 this.)
 
-The spec contains over 400 embedded examples which serve as
-conformance tests.  To run the tests for `stmd`, do `make test`.
-To run them for another markdown program, say `myprog`,
-do `make test PROG=myprog`.  To run the tests for `stmd.js`,
-do `make testjs`.
+The spec contains over 400 embedded examples which serve as conformance
+tests.  To run the tests for `stmd`, do `make test`.  To run them for
+another markdown program, say `myprog`, do `make test PROG=myprog`.  To
+run the tests for `stmd.js`, do `make testjs`.
+
+The spec
+--------
 
 The source of the spec is `spec.txt`.  This is basically a markdown
 file, with code examples written in a shorthand form:
@@ -32,8 +42,51 @@ file, with code examples written in a shorthand form:
     expected HTML output
     .
 
-To build an HTML version of the spec, do `make spec.html`.
-To build a PDF version, do `make spec.pdf`.  Both these commands
-require that pandoc is installed, and creating a PDF requires
-a latex installation.
+To build an HTML version of the spec, do `make spec.html`.  To build a
+PDF version, do `make spec.pdf`.  Both these commands require that
+pandoc is installed, and creating a PDF requires a latex installation.
+
+The spec is written from the point of view of the human writer, not
+the computer reader.  It is not an algorithm---an English translation of
+a computer program---but a declarative description of what counts as a block
+quote, a code block, and each of the other structural elements that can
+make up a markdown document.
+
+Because John Gruber's [canonical syntax
+description](http://daringfireball.net/projects/markdown/syntax) leaves
+many aspects of the syntax undetermined, writing a precise spec requires
+making a large number of decisions, many of them somewhat arbitrary.
+In making them, I have appealed to existing conventions and
+considerations of simplicity, readability, expressive power, and
+consistency.  I have tried to ensure that "normal" documents in the many
+incompatible existing implementations of markdown will render, as far as
+possible, as their authors intended.  And I have tried to make the rules
+for different elements work together harmoniously.  In places where
+different decisions could have been made (for example, the rules
+governing list indentation), I have explained the rationale for
+my choices.  In a few cases, I have departed slightly from the canonical
+syntax description, in ways that I think further the goals of markdown
+as stated in that description.
+
+For the most part, I have limited myself to the basic elements
+described in Gruber's canonical syntax description, eschewing extensions
+like footnotes and definition lists.  It is important to get the core
+right before considering such things. However, I have included a visible
+syntax for line breaks and fenced code blocks.
+
+In all of this, I have been guided by eight years experience writing
+markdown implementations in several languages, including the first
+markdown parser not based on regular expression substitutions
+([pandoc](http://github.com/jgm/pandoc) and the first markdown parsers
+based on PEG grammars
+([peg-markdown](http://github.com/jgm/peg-markdown),
+[lunamark](http://github.com/jgm/lunamark). Maintaining these projects
+and responding to years of user feedback have given me a good sense of
+the complexities involved in parsing markdown, and of the various design
+decisions that can be made.  I have also explored differences between
+markdown implementations extensively using [babelmark
+2](http://johnmacfarlane.net/babelmark2/).  In the early phases of
+working out the spec, I benefited greatly from collaboration with David
+Greenspan, and from feedback from several industrial users of markdown,
+including Jeff Atwood, Vincent Marti, and Neil Williams.