summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--README.md72
1 files changed, 40 insertions, 32 deletions
diff --git a/README.md b/README.md
index 597d5b0..20f6411 100644
--- a/README.md
+++ b/README.md
@@ -19,8 +19,7 @@ It is easy to use `libcmark` in python, lua, ruby, and other dynamic
languages: see the `wrappers/` subdirectory for some simple examples.
The JavaScript implementation is a single JavaScript file, with
-no dependencies, that can be linked to in an HTML page. Here
-is a simple usage example:
+no dependencies, that can be linked into an HTML page.
``` javascript
var reader = new commonmark.DocParser();
@@ -29,9 +28,6 @@ var parsed = reader.parse("Hello *world*");
var result = writer.render(parsed);
```
-A node package is also available (`npm install commonmark`). It includes
-a command-line tool called `commonmark`.
-
**A note on security:**
Neither implementation attempts to sanitize link attributes or
raw HTML. If you use these libraries in applications that accept
@@ -74,21 +70,26 @@ Or, to create Xcode project files on OSX:
make install
The GNU Makefile also provides a few other targets for developers.
+To run a benchmark:
+
+ make bench
+
To run a "fuzz test" against ten long randomly generated inputs:
make fuzztest
-To run a test for memory leaks using valgrind:
+To run a test for memory leaks using `valgrind`:
make leakcheck
+To reformat source code using `astyle`:
+
+ make astyle
+
To make a release tarball and zip archive:
make archive
-To test the archives:
-
- make testarchive
Compiling for Windows
---------------------
@@ -111,20 +112,29 @@ The JavaScript library can be installed through `npm`:
npm install commonmark
-To build the JavaScript library as a single standalone file:
+This includes a command-line converter called `commonmark`.
- browserify --standalone commonmark js/lib/index.js -o js/commonmark.js
-
-Or fetch a pre-built copy from
+If you want to use it in a client application, you can fetch
+a pre-built copy of `commonmark.js` from
<http://spec.commonmark.org/js/commonmark.js>.
+Or, to build it (this requires `browserify`):
+
+ make js/commonmark.js
+
To run tests for the JavaScript library:
make testjs
-or
+To run benchmarks against some other JavaScript converters:
+
+ npm install showdown marked markdown-it
+ make benchjs
+
+To start an interactive dingus that you can use to try out
+the library:
- node js/test.js
+ make dingus
The spec
--------
@@ -132,12 +142,12 @@ The spec
[The spec] contains over 500 embedded examples which serve as conformance
tests. To run the tests using an executable `$PROG`:
- python test/spec_tests.py --program $PROG
+ python3 test/spec_tests.py --program $PROG
If you want to extract the raw test data from the spec without
actually running the tests, you can do:
- python test/spec_tests.py --dump-tests
+ python3 test/spec_tests.py --dump-tests
and you'll get all the tests in JSON format.
@@ -153,8 +163,9 @@ 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.
+PDF version, do `make spec.pdf`. (Creating a PDF requires [pandoc]
+and a LaTeX installation. Creating the HTML version requires only
+`libcmark` and `python3`.)
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
@@ -190,15 +201,13 @@ Differences from original Markdown
There are only a few places where this spec says things that contradict
the canonical syntax description:
-- It [allows all punctuation symbols to be
- backslash-escaped](http://spec.commonmark.org/0.13/#backslash-escapes),
+- It allows all punctuation symbols to be backslash-escaped,
not just the symbols with special meanings in Markdown. We found
that it was just too hard to remember which symbols could be
escaped.
-- It introduces an [alternative syntax for hard line
- breaks](http://spec.commonmark.org/0.13/#hard-line-breaks), a
- backslash at the end of the line, supplementing the
+- It introduces an alternative syntax for hard line
+ breaks, a backslash at the end of the line, supplementing the
two-spaces-at-the-end-of-line rule. This is motivated by persistent
complaints about the “invisible” nature of the two-space rule.
@@ -206,13 +215,11 @@ the canonical syntax description:
backwards-compatible way). For example, `Markdown.pl` allows single
quotes around a title in inline links, but not in reference links.
This kind of difference is really hard for users to remember, so the
- spec [allows single quotes in both
- contexts](http://spec.commonmark.org/0.13/#links).
+ spec allows single quotes in both contexts.
- The rule for HTML blocks differs, though in most real cases it
- shouldn't make a difference. (See
- [here](http://spec.commonmark.org/0.13/#html-blocks) for
- details.) The spec's proposal makes it easy to include Markdown
+ shouldn't make a difference. (See the section on HTML Blocks
+ for 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.
@@ -231,7 +238,7 @@ the canonical syntax description:
- Rules for content in lists differ in a few respects, though (as with
HTML blocks), most lists in existing documents should render as
intended. There is some discussion of the choice points and
- differences [here](http://spec.commonmark.org/0.13/#motivation).
+ differences in the subsection of List Items entitled Motivation.
We think that the spec's proposal does better than any existing
implementation in rendering lists the way a human writer or reader
would intuitively understand them. (We could give numerous examples
@@ -253,7 +260,7 @@ the canonical syntax description:
- The start number of an ordered list is significant.
-- [Fenced code blocks](http://spec.commonmark.org/0.13/#fenced-code-blocks) are supported, delimited by either
+- Fenced code blocks are supported, delimited by either
backticks (```` ``` ```` or tildes (` ~~~ `).
Contributing
@@ -289,7 +296,8 @@ optimized the C implementation for performance, increasing its speed
tenfold. Kārlis Gaņģis helped work out a better parsing algorithm
for links and emphasis, eliminating several worst-case performance
issues. Nick Wellnhofer contributed many improvements, including
-most of the C library's API and its test harness.
+most of the C library's API and its test harness. Vitaly Puzrin
+has offered much good advice about the JavaScript implementation.
[cmake]: http://www.cmake.org/download/
[pandoc]: http://johnmacfarlane.net/pandoc/