summaryrefslogtreecommitdiff
path: root/README.md
diff options
context:
space:
mode:
Diffstat (limited to 'README.md')
-rw-r--r--README.md216
1 files changed, 31 insertions, 185 deletions
diff --git a/README.md b/README.md
index 8af9a48..44ec5cf 100644
--- a/README.md
+++ b/README.md
@@ -7,32 +7,17 @@ implementations in C and JavaScript.
[Try it now!](http://spec.commonmark.org/dingus.html)
-The implementations
--------------------
+For more information, see <http://commonmark.org>.
-The C implementation provides both a shared library (`libcmark`) and a
-standalone program `cmark` that converts CommonMark to HTML. It is
-written in standard C99 and has no library dependencies. The parser is
-very fast (see [benchmarks](benchmarks.md)). For documentation, see
-the man pages in the `man` directory.
+This repository contains the C reference implementation.
+It provides a library with functions for parsing CommonMark
+documents to an abstract syntax tree (AST), manipulating the AST,
+and rendering the document to HTML or to an XML representation of the
+AST. It also provides a command-line program, `cmark`, for
+parsing and rendering CommonMark documents.
-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 provides both an NPM package and a
-single JavaScript file, with no dependencies, that can be linked into
-an HTML page. For further information, see its repository:
-<https://github.com/jgm/commonmark.js>.
-
-**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).
-
-Installing (C)
---------------
+Installing
+----------
Building the C program (`cmark`) and shared library (`libcmark`)
requires [cmake]. If you modify `scanners.re`, then you will also
@@ -87,9 +72,8 @@ To make a release tarball and zip archive:
make archive
-
-Compiling for Windows
----------------------
+Installing (Windows)
+--------------------
To compile with MSVC and NMAKE:
@@ -102,139 +86,18 @@ You can cross-compile a Windows binary and dll on linux if you have the
The binaries will be in `build-mingw/windows/bin`.
-Installing (JavaScript)
------------------------
-
-The JavaScript implementation has been split into its own
-repository: <https://github.com/jgm/commonmark.js>.
-Please look there for instructions for installation and use.
-
-The spec
---------
-
-[The spec] contains over 500 embedded examples which serve as conformance
-tests. To run the tests using an executable `$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:
-
- python3 test/spec_tests.py --dump-tests
-
-and you'll get all the tests in JSON format.
-
-[The spec]: http://spec.commonmark.org/0.13/
-
-The source of [the spec] is `spec.txt`. This is basically a Markdown
-file, with code examples written in a shorthand form:
-
- .
- Markdown source
- .
- expected HTML output
- .
-
-To build an HTML version of the spec, do `make spec.html`. To build a
-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
-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, we have appealed to existing conventions and
-considerations of simplicity, readability, expressive power, and
-consistency. We 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 we 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), we have explained the rationale for
-my choices. In a few cases, we have departed slightly from the canonical
-syntax description, in ways that we think further the goals of Markdown
-as stated in that description.
-
-For the most part, we have limited ourselves 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, we 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:
-
-- 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, 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.
-
-- Link syntax has been made a bit more predictable (in a
- 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.
-
-- The rule for HTML blocks differs, though in most real cases it
- 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.
-
-- It does not collapse adjacent bird-track blocks into a single
- blockquote:
-
- > this is two
-
- > blockquotes
-
- > this is a single
- >
- > blockquote with two paragraphs
-
-- 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 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
- of perfectly natural looking lists that nearly every existing
- implementation flubs up.)
-
-- The spec stipulates that two blank lines break out of all list
- contexts. This is an attempt to deal with issues that often come up
- when someone wants to have two adjacent lists, or a list followed by
- an indented code block.
-
-- Changing bullet characters, or changing from bullets to numbers or
- vice versa, starts a new list. We think that is almost always going
- to be the writer's intent.
-
-- The number that begins an ordered list item may be followed by
- either `.` or `)`. Changing the delimiter style starts a new
- list.
-
-- The start number of an ordered list is significant.
-
-- Fenced code blocks are supported, delimited by either
- backticks (```` ``` ```` or tildes (` ~~~ `).
+Usage
+-----
+
+Instructions for the use of the command line program and library can
+be found in the man pages in the `man` subdirectory.
+
+**A note on security:**
+This library does not attempt to sanitize link attributes or
+raw HTML. If you use it 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).
Contributing
------------
@@ -248,31 +111,14 @@ only for simple, clear, actionable issues.
Authors
-------
-The spec was written by John MacFarlane, drawing on
-
-- his experience writing and maintaining 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))
-- a detailed examination of the differences between existing Markdown
- implementations using [BabelMark 2](http://johnmacfarlane.net/babelmark2/),
- and
-- extensive discussions with David Greenspan, Jeff Atwood, Vicent
- Marti, Neil Williams, and Benjamin Dumke-von der Ehe.
-
-John MacFarlane was also responsible for the original versions of the
-C and JavaScript implementations. The block parsing algorithm was
-worked out together with David Greenspan. Vicent Marti
-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. Vitaly Puzrin
-has offered much good advice about the JavaScript implementation.
+John MacFarlane wrote the original library and program.
+The block parsing algorithm was worked out together with David
+Greenspan. Vicent Marti 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.
[cmake]: http://www.cmake.org/download/
-[pandoc]: http://johnmacfarlane.net/pandoc/
[re2c]: http://re2c.org
-