From ff8eb5cbe18a717ae32a1e05fef3d1d333491458 Mon Sep 17 00:00:00 2001 From: John MacFarlane Date: Tue, 17 Jun 2008 09:35:17 -0700 Subject: [PATCH] Moved README -> README.markdown; added README as a symlink to README.markdown. --- README | 151 +----------------------------------------------- README.markdown | 150 +++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 151 insertions(+), 150 deletions(-) mode change 100644 => 120000 README create mode 100644 README.markdown diff --git a/README b/README deleted file mode 100644 index ca3a08be..00000000 --- a/README +++ /dev/null @@ -1,150 +0,0 @@ -What is this? -============= - -This is an implementation of John Gruber's "markdown" -(http://daringfireball.net/projects/markdown/) in C. It uses a [parsing -expression grammar (PEG)] to define the syntax. This should allow easy -modification and extension. It currently supports output in HTML, LaTeX, -or groff_mm formats, and adding new formats is relatively easy. - -[parsing expression grammar (PEG)]: - http://en.wikipedia.org/wiki/Parsing_expression_grammar - -It is pretty fast. A 179K text file that takes 5.7 seconds for -Markdown.pl (v. 1.0.1) to parse takes less than 0.2 seconds for this -markdown. It does, however, use a lot of memory (up to 4M of heap space -while parsing the 179K file, and up to 80K for a 4K file). (Note that -the memory leaks in earlier versions of this program have now been -plugged.) - -Both a library and a standalone program are provided. - -peg-markdown is written and maintained by John MacFarlane (jgm on -github), with significant contributions by Ryan Tomayko (rtomayko). -It is released under the GPL; see LICENSE for details. - -Installing -========== - -This program is written in portable ANSI C. It requires [glib2] -(http://www.gtk.org/download.html). Most *nix systems will have this -installed already. The build system requires GNU make. - -The other required dependency, [Ian Piumarta's peg/leg PEG parser -generator] (http://piumarta.com/software/peg/), is included in the source -directory. It will be built automatically. (However, it is not as portable -as peg-markdown itself, and seems to require gcc.) - -To make the 'markdown' executable: - - make - -(Or, on some systems, `gmake`.) Then, for usage instructions: - - ./markdown --help - -To run John Gruber's Markdown 1.0.3 test suite: - - make test - -The test suite will fail on one of the list tests. Here's why. -Markdown.pl encloses "item one" in the following list in `

` tags: - - 1. item one - * subitem - * subitem - - 2. item two - - 3. item three - -peg-markdown does not enclose "item one" in `

` tags unless it has a -following blank line. This is consistent with the official markdown -syntax description, and lets the author of the document choose whether -`

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

` tags: + + 1. item one + * subitem + * subitem + + 2. item two + + 3. item three + +peg-markdown does not enclose "item one" in `

` tags unless it has a +following blank line. This is consistent with the official markdown +syntax description, and lets the author of the document choose whether +`

` tags are desired. + +Extensions +========== + +peg-markdown supports extensions to standard markdown syntax. +These can be turned on using the command line flag `-x` or +`--extensions`. `-x` by itself turns on all extensions. Extensions +can also be turned on selectively, using individual command-line +options. To see the available extensions: + + ./markdown --help-extensions + +The `--smart` extension provides "smart quotes", dashes, and ellipses. + +The `--notes` extension provides a footnote syntax like that of +Pandoc or PHP Markdown Extra. + +Using the library +================= + +The library exports two functions: + + GString * markdown_to_g_string(char *text, int extensions, int output_format); + char * markdown_to_string(char *text, int extensions, int output_format); + +The only difference between these is that `markdown_to_g_string` returns a +`GString` (glib's automatically resizable string), while `markdown_to_string` +returns a regular character pointer. The memory allocated for these must be +freed by the calling program, using `g_string_free()` or `free()`. + +`text` is the markdown-formatted text to be converted. Note that tabs will +be converted to spaces, using a four-space tab stop. Character encodings are +ignored. + +`extensions` is a bit-field specifying which syntax extensions should be used. +If `extensions` is 0, no extensions will be used. If it is `0xFFFFFF`, +all extensions will be used. To set extensions selectively, use the +bitwise `&` operator and the following constants: + + - `EXT_SMART` turns on smart quotes, dashes, and ellipses. + - `EXT_NOTES` turns on footnote syntax. [Pandoc's footnote syntax] is used here. + + [Pandoc's footnote syntax]: http://johnmacfarlane.net/pandoc/README.html#footnotes + +`output_format` is either `HTML_FORMAT`, `LATEX_FORMAT`, or `GROFF_MM_FORMAT`. + +To use the library, include `markdown_lib.h`. See `markdown.c` for an example. + +Hacking +======= + +It should be pretty easy to modify the program to produce other formats +than HTML or LaTeX, and to parse syntax extensions. A quick guide: + + * `markdown_parser.leg` contains the grammar itself. + + * `markdown_output.c` contains functions for printing the `Element` + structure in various output formats. + + * To add an output format, add the format to `markdown_formats` in + `markdown_lib.h`. Then modify `print_element` in `markdown_output.c`, + and add functions `print_XXXX_string`, `print_XXXX_element`, and + `print_XXXX_element_list`. Also add an option in the main program + that selects the new format. Don't forget to add it to the list of + formats in the usage message. + + * To add syntax extensions, define them in the PEG grammar + (`markdown_parser.leg`), using existing extensions as a guide. New + inline elements will need to be added to `Inline =`; new block + elements will need to be added to `Block =`. (Note: the order + of the alternatives does matter in PEG grammars.) + + * If you need to add new types of elements, modify the `keys` + enum in `markdown_peg.h`. + + * By using `&{ }` rules one can selectively disable extensions + depending on command-line options. For example, + `&{ extension(EXT_SMART) }` succeeds only if the `EXT_SMART` bit + of the global `syntax_extensions` is set. Add your option to + `markdown_extensions` in `markdown_lib.h`, and add an option in + `markdown.c` to turn on your extension. + + * Note: Avoid using `[^abc]` character classes in the grammar, because + they cause problems with non-ascii input. Instead, use: `( !'a' !'b' + !'c' . )` +