aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorJohn MacFarlane <jgm@berkeley.edu>2014-11-11 20:45:30 -0800
committerJohn MacFarlane <jgm@berkeley.edu>2014-11-11 20:45:30 -0800
commitc6ef7456798cf6a82d102c44b1f9d4524beab83a (patch)
tree7d40bd83e554a44a86f3386b598577c2b4347949
parent96a4c15fa45c8093055bbfcffc7572ac801ecc62 (diff)
Revised README.
-rw-r--r--README.md98
1 files changed, 58 insertions, 40 deletions
diff --git a/README.md b/README.md
index 54e2786..66c312d 100644
--- a/README.md
+++ b/README.md
@@ -10,17 +10,10 @@ The implementations
The C implementation provides both a library and a standalone program
`cmark` that converts CommonMark 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`](http://re2c.org) 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 parser is very fast, on par with
+and has no library dependencies. The parser is very fast, on par with
[sundown](https://github.com/vmg/sundown). Some benchmarks (on
an ancient Thinkpad running Intel Core 2 Duo at 2GHz, measured using
-`time` and parsing a
-~500K book, the English version of [*Pro
+`time` and parsing a ~500K book, the English version of [*Pro
Git*](https://github.com/progit/progit/tree/master/en) by
Scott Chacon and Ben Straub):
@@ -35,61 +28,82 @@ Scott Chacon and Ben Straub):
| **cmark** | 0.020s| 1.1|
| sundown | 0.018s| 1.0|
- Usage: cmark [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. To build,
-it, do `make js/commonmark.js` (this requires `browserify`, which you
-can get using `npm install -g browserify`). You can also fetch
-a pre-built copy from `http://spec.commonmark.org/js/commonmark.js`.
-A command-line version (using `node.js`) is also provided
-(`js/bin/commonmark`), and there is a "dingus" for playing with it
-interactively. (`make dingus` will start this.)
+no dependencies, that can be linked to in an HTML page. A node
+package is also available; it includes a command-line tool called
+`commonmark`.
[Try it now!](http://jgm.github.io/CommonMark/js/)
-**Note:** neither implementation attempts to sanitize link attributes or
-raw HTML. If you use these libraries in applications that accept
-untrusted user input, you must run the output through an HTML
-sanitizer to protect against
-[XSS attacks](http://en.wikipedia.org/wiki/Cross-site_scripting).
-
-[The spec] contains over 500 embedded examples which serve as conformance
-tests. To run the tests for `cmark`, do `make test`. To run them for
-another Markdown program, say `myprog`, do `make test PROG=myprog`. To
-run the tests for `commonmark.js`, do `make testjs`.
-
-[The spec]: http://jgm.github.io/CommonMark/spec.html
-
Installing
----------
-To install the C program (and shared library), [cmake] is required:
+Building the C program (`cmark`) and shared library (`libcmark`)
+requires [cmake] and [`re2c`](http://re2c.org), which is used to
+generate `scanners.c` from `scanners.re`. (Note that `re2c` is only a
+build dependency for developers, since `scanners.c` can be provided in a
+released source tarball.)
+
+On \*nix systems, you can simply `make` and `make install`. This
+calls `cmake` to create a `Makefile` in the `build` directory,
+then uses that `Makefile` to create the executable and library.
+
+Alternatively, you can use `cmake` manually. `cmake` knows how
+to create build environments for many build systems. For
+example, to create Xcode project files on OSX:
mkdir build
cd build
- cmake .. # optionally: -DCMAKE_INSTALL_PREFIX=path
- make # executable will be created as build/src/cmake
+ cmake -G Xcode .. # optionally: -DCMAKE_INSTALL_PREFIX=path
+ make # executable will be created as build/src/cmake
make install
To run tests:
+ make test
+
+or
+
perl runtests.pl spec.txt build/src/cmark
-To build the javascript library:
+The JavaScript library can be installed through `npm`:
+
+ npm install commonmark
+
+To build the JavaScript library as a single standalone file:
browserify --standalone commonmark js/lib/index.js -o js/commonmark.js
-To run tests:
+Or fetch a pre-built copy from
+<http://spec.commonmark.org/js/commonmark.js>`.
+
+To run tests for the JavaScript library:
node js/test.js
+`make dingus` will start an interactive dingus you can use to
+play with the JavaScript implementation:
+
+A note on security
+------------------
+
+Neither implementation attempts to sanitize link attributes or
+raw HTML. If you use these libraries in applications that accept
+untrusted user input, you must run the output through an HTML
+sanitizer to protect against
+[XSS attacks](http://en.wikipedia.org/wiki/Cross-site_scripting).
+
The spec
--------
+[The spec] contains over 500 embedded examples which serve as conformance
+tests. To run the tests for `cmark`, do `make test`. To run them for
+another Markdown program, say `myprog`, do `make test PROG=myprog`. To
+run the tests for `commonmark.js`, do `make testjs`.
+
+[The spec]: http://jgm.github.io/CommonMark/spec.html
+
The source of [the spec] is `spec.txt`. This is basically a Markdown
file, with code examples written in a shorthand form:
@@ -101,7 +115,7 @@ file, with code examples written in a shorthand form:
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.
+[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
@@ -131,6 +145,9 @@ 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.
+Differences from original Markdown
+----------------------------------
+
There are only a few places where this spec says things that contradict
the canonical syntax description:
@@ -210,7 +227,7 @@ based on PEG grammars
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
+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,
@@ -226,4 +243,5 @@ Use the [github issue tracker](http://github.com/jgm/stmd/issues)
only for simple, clear, actionable issues.
[cmake]: http://www.cmake.org/download/
+[pandoc]: http://johnmacfarlane.net/pandoc/