Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 221 lines (153 sloc) 8.085 kb
ff8eb5c @jgm Moved README -> README.markdown; added README as a symlink to README.mar...
authored
1 What is this?
2 =============
3
8c78ea7 @jgm Fixes to README.markdown for github's limited markdown parser.
authored
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
76a0755 @jgm Acknowledge Fletcher Penney for ODF code.
authored
7 HTML, LaTeX, ODF, or groff_mm formats, and adding new formats is
8 relatively easy.
ff8eb5c @jgm Moved README -> README.markdown; added README as a symlink to README.mar...
authored
9
8c78ea7 @jgm Fixes to README.markdown for github's limited markdown parser.
authored
10 [parsing expression grammar (PEG)]: http://en.wikipedia.org/wiki/Parsing_expression_grammar
11 [markdown]: http://daringfireball.net/projects/markdown/
ff8eb5c @jgm Moved README -> README.markdown; added README as a symlink to README.mar...
authored
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).
feaa802 @jgm Dual license GPL/MIT. Bump version to 0.4.5.
authored
24 It is released under both the GPL and the MIT license; see LICENSE for
25 details.
ff8eb5c @jgm Moved README -> README.markdown; added README as a symlink to README.mar...
authored
26
27 Installing
28 ==========
29
e7a83fe @jgm Added windows compilation instructions to README.
authored
30 On a linux or unix-based system
31 -------------------------------
32
8c78ea7 @jgm Fixes to README.markdown for github's limited markdown parser.
authored
33 This program is written in portable ANSI C. It requires
f6b9180 @jgm Updated glib download link. Closes #11.
authored
34 [glib2](http://www.gtk.org/download/index.php). Most *nix systems will have
8c78ea7 @jgm Fixes to README.markdown for github's limited markdown parser.
authored
35 this installed already. The build system requires GNU make.
ff8eb5c @jgm Moved README -> README.markdown; added README as a symlink to README.mar...
authored
36
37 The other required dependency, [Ian Piumarta's peg/leg PEG parser
8c78ea7 @jgm Fixes to README.markdown for github's limited markdown parser.
authored
38 generator](http://piumarta.com/software/peg/), is included in the source
ff8eb5c @jgm Moved README -> README.markdown; added README as a symlink to README.mar...
authored
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
e7a83fe @jgm Added windows compilation instructions to README.
authored
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
8452e4e @jgm FIxed README bug.
authored
92 2. Run the cross compiler with include flag for the Windows glib-2.0 headers:
e7a83fe @jgm Added windows compilation instructions to README.
authored
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
8f8fc22 @jgm Updated README instructions for mingw compile.
authored
119 make PKG_CONFIG=c:/path/to/glib/bin/pkg-config.exe
e7a83fe @jgm Added windows compilation instructions to README.
authored
120
ff8eb5c @jgm Moved README -> README.markdown; added README as a symlink to README.mar...
authored
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
575c375 @rekado add instructions for strike-through extension
rekado authored
137 The `--strike` extension provides a strike-through syntax like that of
138 Redcarpet. For strike-through support in LaTeX documents the `sout`
139 macro from the `ulem` package is used. Add
140 `\usepackage[normalem]{ulem}` to your document's preamble to load it.
141
142
ff8eb5c @jgm Moved README -> README.markdown; added README as a symlink to README.mar...
authored
143 Using the library
144 =================
145
146 The library exports two functions:
147
148 GString * markdown_to_g_string(char *text, int extensions, int output_format);
149 char * markdown_to_string(char *text, int extensions, int output_format);
150
151 The only difference between these is that `markdown_to_g_string` returns a
152 `GString` (glib's automatically resizable string), while `markdown_to_string`
153 returns a regular character pointer. The memory allocated for these must be
154 freed by the calling program, using `g_string_free()` or `free()`.
155
156 `text` is the markdown-formatted text to be converted. Note that tabs will
157 be converted to spaces, using a four-space tab stop. Character encodings are
158 ignored.
159
160 `extensions` is a bit-field specifying which syntax extensions should be used.
161 If `extensions` is 0, no extensions will be used. If it is `0xFFFFFF`,
162 all extensions will be used. To set extensions selectively, use the
163 bitwise `&` operator and the following constants:
164
165 - `EXT_SMART` turns on smart quotes, dashes, and ellipses.
8c78ea7 @jgm Fixes to README.markdown for github's limited markdown parser.
authored
166 - `EXT_NOTES` turns on footnote syntax. [Pandoc's footnote syntax][] is used here.
8d79bae @jgm Documented EXT_FILTER_HTML and EXT_FILTER_STYLES in README.
authored
167 - `EXT_FILTER_HTML` filters out raw HTML (except for styles).
168 - `EXT_FILTER_STYLES` filters out styles in HTML.
575c375 @rekado add instructions for strike-through extension
rekado authored
169 - `EXT_STRIKE` turns on strike-through syntax.
ff8eb5c @jgm Moved README -> README.markdown; added README as a symlink to README.mar...
authored
170
171 [Pandoc's footnote syntax]: http://johnmacfarlane.net/pandoc/README.html#footnotes
172
76a0755 @jgm Acknowledge Fletcher Penney for ODF code.
authored
173 `output_format` is either `HTML_FORMAT`, `LATEX_FORMAT`, `ODF_FORMAT`,
174 or `GROFF_MM_FORMAT`.
ff8eb5c @jgm Moved README -> README.markdown; added README as a symlink to README.mar...
authored
175
176 To use the library, include `markdown_lib.h`. See `markdown.c` for an example.
177
178 Hacking
179 =======
180
76a0755 @jgm Acknowledge Fletcher Penney for ODF code.
authored
181 It should be pretty easy to modify the program to produce other formats,
182 and to parse syntax extensions. A quick guide:
ff8eb5c @jgm Moved README -> README.markdown; added README as a symlink to README.mar...
authored
183
184 * `markdown_parser.leg` contains the grammar itself.
185
186 * `markdown_output.c` contains functions for printing the `Element`
187 structure in various output formats.
188
189 * To add an output format, add the format to `markdown_formats` in
190 `markdown_lib.h`. Then modify `print_element` in `markdown_output.c`,
191 and add functions `print_XXXX_string`, `print_XXXX_element`, and
192 `print_XXXX_element_list`. Also add an option in the main program
193 that selects the new format. Don't forget to add it to the list of
194 formats in the usage message.
195
196 * To add syntax extensions, define them in the PEG grammar
197 (`markdown_parser.leg`), using existing extensions as a guide. New
198 inline elements will need to be added to `Inline =`; new block
199 elements will need to be added to `Block =`. (Note: the order
200 of the alternatives does matter in PEG grammars.)
201
202 * If you need to add new types of elements, modify the `keys`
203 enum in `markdown_peg.h`.
204
205 * By using `&{ }` rules one can selectively disable extensions
206 depending on command-line options. For example,
207 `&{ extension(EXT_SMART) }` succeeds only if the `EXT_SMART` bit
208 of the global `syntax_extensions` is set. Add your option to
209 `markdown_extensions` in `markdown_lib.h`, and add an option in
210 `markdown.c` to turn on your extension.
211
212 * Note: Avoid using `[^abc]` character classes in the grammar, because
213 they cause problems with non-ascii input. Instead, use: `( !'a' !'b'
214 !'c' . )`
215
76a0755 @jgm Acknowledge Fletcher Penney for ODF code.
authored
216 Acknowledgements
217 ================
218
219 Support for ODF output was added by Fletcher T. Penney.
220
Something went wrong with that request. Please try again.