Debian Codegraph @

markdown/peg-markdown/README

raw
1 What is this?
2 =============
3
4 This is an implementation of John Gruber's [markdown][] in C. It uses a
5 [parsing expression grammar (PEG)][] to define the syntax. This should
6 allow easy modification and extension. It currently supports output in
7 HTML, LaTeX, ODF, or groff_mm formats, and adding new formats is
8 relatively easy.
9
10 [parsing expression grammar (PEG)]: http://en.wikipedia.org/wiki/Parsing_expression_grammar
11 [markdown]: http://daringfireball.net/projects/markdown/
12
13 It is pretty fast. A 179K text file that takes 5.7 seconds for
14 Markdown.pl (v. 1.0.1) to parse takes less than 0.2 seconds for this
15 markdown. It does, however, use a lot of memory (up to 4M of heap space
16 while parsing the 179K file, and up to 80K for a 4K file). (Note that
17 the memory leaks in earlier versions of this program have now been
18 plugged.)
19
20 Both a library and a standalone program are provided.
21
22 peg-markdown is written and maintained by John MacFarlane (jgm on
23 github), with significant contributions by Ryan Tomayko (rtomayko).
24 It is released under both the GPL and the MIT license; see LICENSE for
25 details.
26
27 Installing
28 ==========
29
30 On a linux or unix-based system
31 -------------------------------
32
33 This program is written in portable ANSI C. It requires
34 [glib2](http://www.gtk.org/download/index.php). Most *nix systems will have
35 this installed already. The build system requires GNU make.
36
37 The other required dependency, [Ian Piumarta's peg/leg PEG parser
38 generator](http://piumarta.com/software/peg/), is included in the source
39 directory. It will be built automatically. (However, it is not as portable
40 as peg-markdown itself, and seems to require gcc.)
41
42 To make the 'markdown' executable:
43
44 make
45
46 (Or, on some systems, `gmake`.) Then, for usage instructions:
47
48 ./markdown --help
49
50 To run John Gruber's Markdown 1.0.3 test suite:
51
52 make test
53
54 The test suite will fail on one of the list tests. Here's why.
55 Markdown.pl encloses "item one" in the following list in `<p>` tags:
56
57 1. item one
58 * subitem
59 * subitem
60
61 2. item two
62
63 3. item three
64
65 peg-markdown does not enclose "item one" in `<p>` tags unless it has a
66 following blank line. This is consistent with the official markdown
67 syntax description, and lets the author of the document choose whether
68 `<p>` tags are desired.
69
70 Cross-compiling for Windows with MinGW on a linux box
71 -----------------------------------------------------
72
73 Prerequisites:
74
75 * Linux system with MinGW cross compiler For Ubuntu:
76
77 sudo apt-get install mingw32
78
79 * [Windows glib-2.0 binary & development files](http://www.gtk.org/download-windows.html).
80 Unzip files into cross-compiler directory tree (e.g., `/usr/i586-mingw32msvc`).
81
82 Steps:
83
84 1. Create the markdown parser using Linux-compiled `leg` from peg-0.1.4:
85
86 ./peg-0.1.4/leg markdown_parser.leg >markdown_parser.c
87
88 (Note: The same thing could be accomplished by cross-compiling leg,
89 executing it on Windows, and copying the resulting C file to the Linux
90 cross-compiler host.)
91
92 2. Run the cross compiler with include flag for the Windows glib-2.0 headers:
93 for example,
94
95 /usr/bin/i586-mingw32msvc-cc -c \
96 -I/usr/i586-mingw32msvc/include/glib-2.0 \
97 -I/usr/i586-mingw32msvc/lib/glib-2.0/include -Wall -O3 -ansi markdown*.c
98
99 3. Link against Windows glib-2.0 headers: for example,
100
101 /usr/bin/i586-mingw32msvc-cc markdown*.o \
102 -Wl,-L/usr/i586-mingw32msvc/lib/glib,--dy,--warn-unresolved-symbols,-lglib-2.0 \
103 -o markdown.exe
104
105 The resulting executable depends on the glib dll file, so be sure to
106 load the glib binary on the Windows host.
107
108 Compiling with MinGW on Windows
109 -------------------------------
110
111 These directions assume that MinGW is installed in `c:\MinGW` and glib-2.0
112 is installed in the MinGW directory hierarchy (with the mingw bin directory
113 in the system path).
114
115 Unzip peg-markdown in a temp directory. From the directory with the
116 peg-markdown source, execute:
117
118 cd peg-0.1.4
119 make PKG_CONFIG=c:/path/to/glib/bin/pkg-config.exe
120
121 Extensions
122 ==========
123
124 peg-markdown supports extensions to standard markdown syntax.
125 These can be turned on using the command line flag `-x` or
126 `--extensions`. `-x` by itself turns on all extensions. Extensions
127 can also be turned on selectively, using individual command-line
128 options. To see the available extensions:
129
130 ./markdown --help-extensions
131
132 The `--smart` extension provides "smart quotes", dashes, and ellipses.
133
134 The `--notes` extension provides a footnote syntax like that of
135 Pandoc or PHP Markdown Extra.
136
137 Using the library
138 =================
139
140 The library exports two functions:
141
142 GString * markdown_to_g_string(char *text, int extensions, int output_format);
143 char * markdown_to_string(char *text, int extensions, int output_format);
144
145 The only difference between these is that `markdown_to_g_string` returns a
146 `GString` (glib's automatically resizable string), while `markdown_to_string`
147 returns a regular character pointer. The memory allocated for these must be
148 freed by the calling program, using `g_string_free()` or `free()`.
149
150 `text` is the markdown-formatted text to be converted. Note that tabs will
151 be converted to spaces, using a four-space tab stop. Character encodings are
152 ignored.
153
154 `extensions` is a bit-field specifying which syntax extensions should be used.
155 If `extensions` is 0, no extensions will be used. If it is `0xFFFFFF`,
156 all extensions will be used. To set extensions selectively, use the
157 bitwise `&` operator and the following constants:
158
159 - `EXT_SMART` turns on smart quotes, dashes, and ellipses.
160 - `EXT_NOTES` turns on footnote syntax. [Pandoc's footnote syntax][] is used here.
161 - `EXT_FILTER_HTML` filters out raw HTML (except for styles).
162 - `EXT_FILTER_STYLES` filters out styles in HTML.
163
164 [Pandoc's footnote syntax]: http://johnmacfarlane.net/pandoc/README.html#footnotes
165
166 `output_format` is either `HTML_FORMAT`, `LATEX_FORMAT`, `ODF_FORMAT`,
167 or `GROFF_MM_FORMAT`.
168
169 To use the library, include `markdown_lib.h`. See `markdown.c` for an example.
170
171 Hacking
172 =======
173
174 It should be pretty easy to modify the program to produce other formats,
175 and to parse syntax extensions. A quick guide:
176
177 * `markdown_parser.leg` contains the grammar itself.
178
179 * `markdown_output.c` contains functions for printing the `Element`
180 structure in various output formats.
181
182 * To add an output format, add the format to `markdown_formats` in
183 `markdown_lib.h`. Then modify `print_element` in `markdown_output.c`,
184 and add functions `print_XXXX_string`, `print_XXXX_element`, and
185 `print_XXXX_element_list`. Also add an option in the main program
186 that selects the new format. Don't forget to add it to the list of
187 formats in the usage message.
188
189 * To add syntax extensions, define them in the PEG grammar
190 (`markdown_parser.leg`), using existing extensions as a guide. New
191 inline elements will need to be added to `Inline =`; new block
192 elements will need to be added to `Block =`. (Note: the order
193 of the alternatives does matter in PEG grammars.)
194
195 * If you need to add new types of elements, modify the `keys`
196 enum in `markdown_peg.h`.
197
198 * By using `&{ }` rules one can selectively disable extensions
199 depending on command-line options. For example,
200 `&{ extension(EXT_SMART) }` succeeds only if the `EXT_SMART` bit
201 of the global `syntax_extensions` is set. Add your option to
202 `markdown_extensions` in `markdown_lib.h`, and add an option in
203 `markdown.c` to turn on your extension.
204
205 * Note: Avoid using `[^abc]` character classes in the grammar, because
206 they cause problems with non-ascii input. Instead, use: `( !'a' !'b'
207 !'c' . )`
208
209 Acknowledgements
210 ================
211
212 Support for ODF output was added by Fletcher T. Penney.
213