Permalink
Browse files

Moved README -> README.markdown; added README as a symlink to README.…

…markdown.
  • Loading branch information...
1 parent 13051ec commit ff8eb5cbe18a717ae32a1e05fef3d1d333491458 @jgm jgm committed Jun 17, 2008
Showing with 151 additions and 150 deletions.
  1. +0 −150 README
  2. +1 −0 README
  3. +150 −0 README.markdown
View
150 README
@@ -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 `<p>` tags:
-
- 1. item one
- * subitem
- * subitem
-
- 2. item two
-
- 3. item three
-
-peg-markdown does not enclose "item one" in `<p>` 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
-`<p>` 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' . )`
-
View
1 README
View
150 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 `<p>` tags:
+
+ 1. item one
+ * subitem
+ * subitem
+
+ 2. item two
+
+ 3. item three
+
+peg-markdown does not enclose "item one" in `<p>` 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
+`<p>` 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' . )`
+

0 comments on commit ff8eb5c

Please sign in to comment.