0
@@ -2,32 +2,46 @@ What is this?
0
 =============
0
 
0
 This is an implementation of John Gruber's "markdown"
0
-(http://daringfireball.net/projects/markdown/) in C.
0
-It uses a PEG grammar to define the syntax. This should allow easy
0
-modification and extension.
0
+(http://daringfireball.net/projects/markdown/) in C. It uses a [parsing
0
+expression grammar (PEG)] to define the syntax. This should allow easy
0
+modification and extension. It currently supports output in HTML, LaTeX,
0
+or groff_mm formats, and adding new formats is relatively easy.
0
+
0
+[parsing expression grammar (PEG)]:
0
+   http://en.wikipedia.org/wiki/Parsing_expression_grammar 
0
 
0
 It is pretty fast. A 179K text file that takes 5.7 seconds for
0
-Markdown.pl (v. 1.0.1) to parse takes only 0.14 seconds for this
0
-markdown.  It does, however, use a fair amount of memory.
0
+Markdown.pl (v. 1.0.1) to parse takes less than 0.2 seconds for this
0
+markdown. It does, however, use a lot of memory (up to 4M of heap space
0
+while parsing the 179K file, and up to 80K for a 4K file). (Note that
0
+the memory leaks in earlier versions of this program have now been
0
+plugged.)
0
+
0
+Both a library and a standalone program are provided.
0
+
0
+peg-markdown is written and maintained by John MacFarlane (jgm on
0
+github), with significant contributions by Ryan Tomayko (rtomayko).
0
+It is released under the GPL; see LICENSE for details.
0
 
0
 Installing
0
 ==========
0
 
0
-This program is written in portable ANSI C. It requires glib2:
0
-<http://library.gnome.org/devel/glib/>. Most *nix systems will have this
0
-installed already.
0
+This program is written in portable ANSI C. It requires [glib2]
0
+(http://www.gtk.org/download.html). Most *nix systems will have this
0
+installed already. The build system requires GNU make.
0
 
0
-The other required dependency, Ian Piumarta's peg/leg PEG parser
0
-generator <http://piumarta.com/software/peg/>, is included in the source
0
-directory. It will be built automatically.
0
+The other required dependency, [Ian Piumarta's peg/leg PEG parser
0
+generator] (http://piumarta.com/software/peg/), is included in the source
0
+directory. It will be built automatically. (However, it is not as portable
0
+as peg-markdown itself, and seems to require gcc.)
0
 
0
 To make the 'markdown' executable:
0
 
0
     make
0
 
0
-Then, for usage instructions:
0
+(Or, on some systems, `gmake`.) Then, for usage instructions:
0
 
0
-    ./markdown -h
0
+    ./markdown --help
0
 
0
 To run John Gruber's Markdown 1.0.3 test suite:
0
 
0
@@ -44,7 +58,7 @@ Markdown.pl encloses "item one" in the following list in `<p>` tags:
0
 
0
     3.  item three
0
 
0
-peg-markdown does not enclose "item one" in <p> tags unless it has a
0
+peg-markdown does not enclose "item one" in `<p>` tags unless it has a
0
 following blank line. This is consistent with the official markdown
0
 syntax description, and lets the author of the document choose whether
0
 `<p>` tags are desired.
0
@@ -53,15 +67,49 @@ Extensions
0
 ==========
0
 
0
 peg-markdown supports extensions to standard markdown syntax.
0
-These can be turned on using the command line flag `-x`.  `-x`
0
-by itself turns on all extensions; to turn on extensions selectively,
0
-specify their names after `-x`, for example: `-xsmart`.
0
+These can be turned on using the command line flag `-x` or
0
+`--extensions`.  `-x` by itself turns on all extensions.  Extensions
0
+can also be turned on selectively, using individual command-line
0
+options. To see the available extensions:
0
 
0
-The `smart` extension provides "smart quotes", dashes, and ellipses.
0
+    ./markdown --help-extensions
0
+ 
0
+The `--smart` extension provides "smart quotes", dashes, and ellipses.
0
 
0
-The `notes` extension provides a footnote syntax like that of
0
+The `--notes` extension provides a footnote syntax like that of
0
 Pandoc or PHP Markdown Extra.
0
 
0
+Using the library
0
+=================
0
+
0
+The library exports two functions:
0
+
0
+    GString * markdown_to_g_string(char *text, int extensions, int output_format);
0
+    char * markdown_to_string(char *text, int extensions, int output_format);
0
+
0
+The only difference between these is that `markdown_to_g_string` returns a
0
+`GString` (glib's automatically resizable string), while `markdown_to_string`
0
+returns a regular character pointer.  The memory allocated for these must be
0
+freed by the calling program, using `g_string_free()` or `free()`.
0
+
0
+`text` is the markdown-formatted text to be converted.  Note that tabs will
0
+be converted to spaces, using a four-space tab stop.  Character encodings are
0
+ignored.
0
+
0
+`extensions` is a bit-field specifying which syntax extensions should be used.
0
+If `extensions` is 0, no extensions will be used.  If it is `0xFFFFFF`,
0
+all extensions will be used.  To set extensions selectively, use the
0
+bitwise `&` operator and the following constants:
0
+
0
+ - `EXT_SMART` turns on smart quotes, dashes, and ellipses.
0
+ - `EXT_NOTES` turns on footnote syntax.  [Pandoc's footnote syntax] is used here.
0
+
0
+  [Pandoc's footnote syntax]: http://johnmacfarlane.net/pandoc/README.html#footnotes
0
+
0
+`output_format` is either `HTML_FORMAT`, `LATEX_FORMAT`, or `GROFF_MM_FORMAT`.
0
+
0
+To use the library, include `markdown_lib.h`.  See `markdown.c` for an example.
0
+
0
 Hacking
0
 =======
0
 
0
@@ -71,27 +119,32 @@ than HTML or LaTeX, and to parse syntax extensions.  A quick guide:
0
   * `markdown_parser.leg` contains the grammar itself.
0
 
0
   * `markdown_output.c` contains functions for printing the `Element`
0
-    structure in various output formats.  (This includes calling
0
-    `markdown()` again when needed to parse list items and blockquotes,
0
-    which are stored initially as raw strings.)
0
+    structure in various output formats.
0
 
0
-  * To add an output format, add the format to `formats`, modify
0
-    `print_element`, and add functions `print_XXXX_string`,
0
-    `print_XXXX_element`, and `print_XXXX_element_list`. Also add an
0
-    option in the main program that selects the new format. Don't forget
0
-    to add it to the help message.
0
+  * To add an output format, add the format to `markdown_formats` in
0
+    `markdown_lib.h`.  Then modify `print_element` in `markdown_output.c`,
0
+    and add functions `print_XXXX_string`, `print_XXXX_element`, and
0
+    `print_XXXX_element_list`. Also add an option in the main program
0
+    that selects the new format. Don't forget to add it to the list of
0
+    formats in the usage message.
0
 
0
   * To add syntax extensions, define them in the PEG grammar
0
     (`markdown_parser.leg`), using existing extensions as a guide. New
0
     inline elements will need to be added to `Inline =`; new block
0
-    elements will need to be added to `Block =`. If you need to add new
0
-    types of elements, modify the `keys` enum. By using `&{ }` rules
0
-    one can selectively disable extensions depending on command-line
0
-    options. For example, `&{ extension(EXT_SMART) }` succeeds only if
0
-    the `EXT_SMART` bit of the global `syntax_extensions` is set. Add
0
-    your option to `markdown_extensions`, and modify the option parsing
0
-    in `markdown.c` so that your option gets set appropriately.
0
-
0
-  * Note:  Avoid using `[^abc]` character classes in the grammar, because they
0
-    cause problems with non-ascii input.  Instead, use:  `( !'a' !'b' !'c' . )`
0
+    elements will need to be added to `Block =`. (Note: the order
0
+    of the alternatives does matter in PEG grammars.)
0
+
0
+  * If you need to add new types of elements, modify the `keys`
0
+    enum in `markdown_peg.h`.
0
+
0
+  * By using `&{ }` rules one can selectively disable extensions
0
+    depending on command-line options. For example,
0
+    `&{ extension(EXT_SMART) }` succeeds only if the `EXT_SMART` bit
0
+    of the global `syntax_extensions` is set. Add your option to
0
+    `markdown_extensions` in `markdown_lib.h`, and add an option in
0
+    `markdown.c` to turn on your extension.
0
+
0
+  * Note: Avoid using `[^abc]` character classes in the grammar, because
0
+    they cause problems with non-ascii input. Instead, use: `( !'a' !'b'
0
+    !'c' . )`
0