cmark

My personal build of CMark ✏️
Commit: c8453ff31f696febac0fcf08c5b2d554b5df7b20
Parent: 704753ef8a4946eb63e4980b70f7d958fe14302b
Author: John MacFarlane <jgm@berkeley.edu>
Date: Sat, 24 Jan 2015 21:28:29 -0800
Removed non-C related parts of README.md.
Diffstat

1 file changed, 31 insertions, 185 deletions
Status	File Name	N° Changes	Insertions	Deletions
Modified	README.md	216	31	185
diff --git 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
-