diff options
Diffstat (limited to 'narrative.md')
| -rw-r--r-- | narrative.md | 28 |
1 files changed, 14 insertions, 14 deletions
diff --git a/narrative.md b/narrative.md index 315c47b..2448ad8 100644 --- a/narrative.md +++ b/narrative.md @@ -2,14 +2,14 @@ title: CommonMark ... -CommonMark is a [specification of markdown +CommonMark is a [specification of Markdown syntax](http://jgm.github.io/stmd/spec.html), together with BSD3-licensed implementations (`stmd`) in C and javascript. The source for the spec and the two implementations can be found in [this repository](http://github.com/jgm/stmd). The C implementation provides both a library and a standalone program -`stmd` that converts markdown to HTML. It is written in standard C99 and +`stmd` that converts Markdown to HTML. It is written in standard C99 and has no library dependencies. The javascript implementation is a single javascript file, with no @@ -17,13 +17,13 @@ dependencies. [Try it now!](http://jgm.github.io/stmd/js/) [The spec](http://jgm.github.io/stmd/spec.html) contains over 400 embedded examples which serve as conformance tests. (The source contains -a perl script that will run the tests against any markdown program.) +a perl script that will run the tests against any Markdown program.) 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. For the most part, the spec limits itself +make up a Markdown document. For the most part, the spec limits itself to the basic elements described in John Gruber’s [canonical syntax description](http://daringfireball.net/projects/markdown/syntax), eschewing extensions like footnotes and definition lists. It is @@ -35,13 +35,13 @@ 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 +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 +in ways that I think further the goals of Markdown as stated in that description. There are only a few places where this spec says things that contradict @@ -49,7 +49,7 @@ the canonical syntax description: - It [allows all punctuation symbols to be backslash-escaped](http://jgm.github.io/stmd/spec.html#backslash-escapes), - not just the symbols with special meanings in markdown. I found + not just the symbols with special meanings in Markdown. I found that it was just too hard to remember which symbols could be escaped. @@ -69,7 +69,7 @@ the canonical syntax description: - The rule for HTML blocks differs, though in most real cases it shouldn't make a difference. (See [here](http://jgm.github.io/stmd/spec.html#html-blocks) for - details.) The spec's proposal makes it easy to include markdown + details.) The spec's proposal makes it easy to include Markdown inside HTML block-level tags, if you want to, but also allows you to exclude this. It is also makes parsing much easier, avoiding expensive backtracking. @@ -114,18 +114,18 @@ the canonical syntax description: backticks (` ``` `) or tildes (` ~~~ `). 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 +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 +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 +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 extensive discussions with a group of industrial -users of markdown, including Jeff Atwood, Vincent Marti, and Neil +users of Markdown, including Jeff Atwood, Vincent Marti, and Neil Williams. |