maruku 0.4.2.1 → 0.5.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- data/bin/maruku +66 -20
- data/bin/marutest +12 -2
- data/docs/changelog.html +188 -23
- data/docs/changelog.md +128 -5
- data/docs/entity_test.html +245 -240
- data/docs/entity_test.md +2 -0
- data/docs/exd.html +181 -23
- data/docs/index.html +130 -349
- data/docs/markdown_syntax.html +55 -51
- data/docs/maruku.html +130 -349
- data/docs/maruku.md +154 -339
- data/docs/math.md +143 -0
- data/docs/proposal.html +16 -12
- data/lib/maruku.rb +6 -3
- data/lib/maruku/attributes.rb +7 -2
- data/lib/maruku/defaults.rb +27 -27
- data/lib/maruku/errors_management.rb +10 -9
- data/lib/maruku/ext/diagrams/diagrams.rb +8 -0
- data/lib/maruku/ext/diagrams/grid.rb +78 -0
- data/lib/maruku/ext/diagrams/inspect.rb +11 -0
- data/lib/maruku/ext/diagrams/layout.rb +105 -0
- data/lib/maruku/ext/diagrams/parser.rb +219 -0
- data/lib/maruku/ext/diagrams/structures.rb +168 -0
- data/lib/maruku/ext/diagrams/to_html.rb +37 -0
- data/lib/maruku/ext/diagrams/to_latex.rb +308 -0
- data/lib/maruku/ext/diagrams/unittest.rb +123 -0
- data/lib/maruku/ext/math.rb +11 -0
- data/lib/maruku/ext/math/elements.rb +26 -0
- data/lib/maruku/ext/math/mathml_engines/blahtex.rb +108 -0
- data/lib/maruku/ext/math/mathml_engines/itex2mml.rb +29 -0
- data/lib/maruku/ext/math/mathml_engines/none.rb +20 -0
- data/lib/maruku/ext/math/mathml_engines/ritex.rb +24 -0
- data/lib/maruku/ext/math/parsing.rb +82 -0
- data/lib/maruku/ext/math/to_html.rb +178 -0
- data/lib/maruku/ext/math/to_latex.rb +21 -0
- data/lib/maruku/helpers.rb +11 -0
- data/lib/maruku/input/charsource.rb +1 -1
- data/lib/maruku/input/extensions.rb +68 -0
- data/lib/maruku/input/html_helper.rb +91 -60
- data/lib/maruku/input/parse_block.rb +10 -9
- data/lib/maruku/input/parse_doc.rb +21 -13
- data/lib/maruku/input/parse_span_better.rb +19 -8
- data/lib/maruku/input/type_detection.rb +5 -3
- data/lib/maruku/output/to_html.rb +236 -67
- data/lib/maruku/output/to_latex.rb +69 -26
- data/lib/maruku/output/to_latex_entities.rb +14 -2
- data/lib/maruku/output/to_s.rb +8 -0
- data/lib/maruku/structures.rb +1 -1
- data/lib/maruku/tests/benchmark.rb +2 -2
- data/lib/maruku/tests/new_parser.rb +13 -5
- data/lib/maruku/version.rb +1 -1
- data/lib/sort_prof.rb +22 -0
- data/tests/diagrams/diagrams.md +54 -0
- data/tests/math/syntax.md +46 -0
- data/tests/math_usage/document.md +13 -0
- data/tests/unittest/attributes/attributes.md +50 -6
- data/tests/unittest/easy.md +1 -1
- data/tests/unittest/email.md +3 -3
- data/tests/unittest/entities.md +12 -7
- data/tests/unittest/escaping.md +4 -4
- data/tests/unittest/extra_table1.md +3 -1
- data/tests/unittest/footnotes.md +5 -5
- data/tests/unittest/headers.md +3 -3
- data/tests/unittest/images.md +7 -7
- data/tests/unittest/inline_html.md +51 -5
- data/tests/unittest/links.md +7 -7
- data/tests/unittest/list2.md +1 -1
- data/tests/unittest/lists.md +1 -1
- data/tests/unittest/lists_after_paragraph.md +1 -1
- data/tests/unittest/lists_ol.md +1 -1
- data/tests/unittest/math/equations.md +82 -0
- data/tests/unittest/math/inline.md +80 -0
- data/tests/unittest/math/table.md +51 -0
- data/tests/unittest/math/table2.md +67 -0
- data/tests/unittest/misc_sw.md +24 -24
- data/tests/unittest/notyet/ticks.md +1 -1
- data/tests/unittest/references/long_example.md +2 -2
- data/tests/unittest/smartypants.md +4 -4
- data/tests/unittest/xml.md +68 -0
- data/tests/unittest/xml2.md +36 -0
- data/tests/unittest/xml3.md +52 -0
- data/tests/unittest/xml_instruction.md +5 -5
- metadata +33 -4
- data/docs/a.html +0 -6
- data/docs/char.html +0 -1924
data/docs/entity_test.md
CHANGED
data/docs/exd.html
CHANGED
|
@@ -1,12 +1,14 @@
|
|
|
1
|
-
<?xml version=
|
|
2
|
-
<!DOCTYPE html PUBLIC
|
|
3
|
-
|
|
4
|
-
|
|
1
|
+
<?xml version="1.0" encoding="utf-8"?>
|
|
2
|
+
<!DOCTYPE html PUBLIC
|
|
3
|
+
"-//W3C//DTD XHTML 1.1 plus MathML 2.0 plus SVG 1.1//EN"
|
|
4
|
+
"http://www.w3.org/2002/04/xhtml-math-svg/xhtml-math-svg.dtd">
|
|
5
|
+
<html xmlns:svg='http://www.w3.org/2000/svg' xml:lang='en' xmlns='http://www.w3.org/1999/xhtml'>
|
|
6
|
+
<head><meta content='application/xhtml+xml;charset=utf-8' http-equiv='Content-type' /><title></title><link href='style.css' rel='stylesheet' type='text/css' />
|
|
7
|
+
</head>
|
|
8
|
+
<body>
|
|
5
9
|
<h1>Auto-extracted documentation</h1>
|
|
6
10
|
|
|
7
|
-
<p>This documentation is auto-generated by reading from the Ruby source for <code>maruku</code> by the program <code>docs/exd/exd.rb</code
|
|
8
|
-
|
|
9
|
-
<p>It is important to have documentation near the code!</p>
|
|
11
|
+
<p>This documentation is auto-generated by reading from the Ruby source for <code>maruku</code> by the program <code>docs/exd/exd.rb</code>. It is important to have documentation near the code!</p>
|
|
10
12
|
|
|
11
13
|
<p>Each block is delimited by <code>=begin</code> and <code>=end</code> blocks and is a Markdown document:</p>
|
|
12
14
|
<pre><code>...
|
|
@@ -19,33 +21,138 @@ Expanded documentation (Markdown format)
|
|
|
19
21
|
...</code></pre>
|
|
20
22
|
<h2>Attribute documentation</h2>
|
|
21
23
|
|
|
24
|
+
<h3 id='class'>Attribute <code>class</code></h3>
|
|
25
|
+
|
|
26
|
+
<p class='maruku-att-origin'>Read from file <code>output/to_html.rb</code>, line 303:</p>
|
|
27
|
+
|
|
28
|
+
<p>It is copied as a standard HTML attribute.</p>
|
|
29
|
+
|
|
30
|
+
<h3 id='code_background_color'>Attribute <code>code_background_color</code></h3>
|
|
31
|
+
|
|
32
|
+
<p class='maruku-att-default'>Default: <code>"#fef"</code></p>
|
|
33
|
+
|
|
34
|
+
<p class='maruku-att-origin'>Read from file <code>output/to_html.rb</code>, line 486:</p>
|
|
35
|
+
|
|
36
|
+
<p>The format is either a named color (<code>green</code>, <code>red</code>) or a CSS color of the form <code>#ff00ff</code>.</p>
|
|
37
|
+
|
|
38
|
+
<ul>
|
|
39
|
+
<li>
|
|
40
|
+
<p>for <strong>HTML output</strong>, the value is put straight in the <code>background-color</code> CSS property of the block.</p>
|
|
41
|
+
</li>
|
|
42
|
+
|
|
43
|
+
<li>
|
|
44
|
+
<p>for <strong>LaTeX output</strong>, if it is a named color, it must be a color accepted by the LaTeX <code>color</code> packages. If it is of the form <code>#ff00ff</code>, Maruku defines a color using the <code>\color[rgb]{r,g,b}</code> macro.</p>
|
|
45
|
+
|
|
46
|
+
<p>For example, for <code>#0000ff</code>, the macro is called as: <code>\color[rgb]{0,0,1}</code>.</p>
|
|
47
|
+
</li>
|
|
48
|
+
</ul>
|
|
49
|
+
|
|
50
|
+
<h3 id='code_show_spaces'>Attribute <code>code_show_spaces</code></h3>
|
|
51
|
+
|
|
52
|
+
<p class='maruku-att-default'>Default: <code>false</code></p>
|
|
53
|
+
|
|
54
|
+
<p class='maruku-att-origin'>Read from file <code>output/to_latex.rb</code>, line 193:</p>
|
|
55
|
+
|
|
56
|
+
<p>If <code>true</code>, shows spaces and tabs in code blocks.</p>
|
|
57
|
+
|
|
58
|
+
<p>Example:</p>
|
|
59
|
+
<pre><code> One space
|
|
60
|
+
Two spaces
|
|
61
|
+
Tab, space, tab
|
|
62
|
+
Tab, tab, tab and all is green!
|
|
63
|
+
{:code_show_spaces code_background_color=#ffeedd}</code></pre>
|
|
64
|
+
<p>That will produce:</p>
|
|
65
|
+
<pre style='background-color: #ffeedd;'><code>¬One¬space
|
|
66
|
+
¬¬Two¬spaces
|
|
67
|
+
»   ¬»   Tab,¬space,¬tab
|
|
68
|
+
»   »   »   Tab,¬tab,¬tab¬and¬all¬is¬green!</code></pre>
|
|
69
|
+
<h3 id='css'>Attribute <code>css</code></h3>
|
|
70
|
+
|
|
71
|
+
<p class='maruku-att-origin'>Read from file <code>output/to_html.rb</code>, line 134:</p>
|
|
72
|
+
|
|
73
|
+
<p><code>css</code> should be a space-separated list of urls.</p>
|
|
74
|
+
|
|
75
|
+
<p>Example:</p>
|
|
76
|
+
<pre><code>CSS: style.css math.css</code></pre>
|
|
22
77
|
<h3 id='encoding'>Attribute <code>encoding</code></h3>
|
|
23
78
|
|
|
24
|
-
<p>Read from file <code>input/parse_doc.rb</code>, line 35:</p>
|
|
79
|
+
<p class='maruku-att-origin'>Read from file <code>input/parse_doc.rb</code>, line 35:</p>
|
|
25
80
|
|
|
26
81
|
<p>If the <code>encoding</code> attribute is specified, then the content will be converted from the specified encoding to UTF-8.</p>
|
|
27
82
|
|
|
28
83
|
<p>Conversion happens using the <code>iconv</code> library.</p>
|
|
29
84
|
|
|
30
|
-
<h3 id='
|
|
85
|
+
<h3 id='html_math_engine'>Attribute <code>html_math_engine</code></h3>
|
|
31
86
|
|
|
32
|
-
<p>
|
|
87
|
+
<p class='maruku-att-default'>Default: <code>"none"</code></p>
|
|
33
88
|
|
|
34
|
-
<p>
|
|
89
|
+
<p class='maruku-att-origin'>Read from file <code>ext/math/to_html.rb</code>, line 2:</p>
|
|
90
|
+
|
|
91
|
+
<p>Select the rendering engine for math.</p>
|
|
92
|
+
|
|
93
|
+
<p>If you want to use your custom engine <code>foo</code>, then set:</p>
|
|
94
|
+
<pre><code>HTML math engine: foo</code></pre>
|
|
95
|
+
<p>and then implement two functions:</p>
|
|
96
|
+
<pre><code>def convert_to_mathml_foo(kind, tex)
|
|
97
|
+
...
|
|
98
|
+
end</code></pre>
|
|
99
|
+
<h3 id='html_png_engine'>Attribute <code>html_png_engine</code></h3>
|
|
100
|
+
|
|
101
|
+
<p class='maruku-att-default'>Default: <code>"none"</code></p>
|
|
102
|
+
|
|
103
|
+
<p class='maruku-att-origin'>Read from file <code>ext/math/to_html.rb</code>, line 24:</p>
|
|
104
|
+
|
|
105
|
+
<p>Same thing as <code>html_math_engine</code>, only for PNG output.</p>
|
|
106
|
+
<pre><code>def convert_to_png_foo(kind, tex)
|
|
107
|
+
# same thing
|
|
108
|
+
...
|
|
109
|
+
end</code></pre>
|
|
110
|
+
<h3 id='html_use_syntax'>Attribute <code>html_use_syntax</code></h3>
|
|
111
|
+
|
|
112
|
+
<p class='maruku-att-default'>Default: <code>false</code></p>
|
|
113
|
+
|
|
114
|
+
<p class='maruku-att-origin'>Read from file <code>output/to_html.rb</code>, line 400:</p>
|
|
115
|
+
|
|
116
|
+
<p>If true, the <code>syntax</code> package is used. It supports the <code>ruby</code> and <code>xml</code> languages. Remember to set the <code>lang</code> attribute of the code block.</p>
|
|
117
|
+
|
|
118
|
+
<p>Examples:</p>
|
|
119
|
+
<pre><code> require 'maruku'
|
|
120
|
+
{:lang=ruby html_use_syntax=true}
|
|
121
|
+
</code></pre>
|
|
122
|
+
<p>and</p>
|
|
123
|
+
<pre><code> <div style="text-align:center">Div</div>
|
|
124
|
+
{:lang=html html_use_syntax=true}
|
|
125
|
+
</code></pre>
|
|
126
|
+
<p>produces:</p>
|
|
127
|
+
<pre class='ruby'><span class='ident'>require</span> <span class='punct'>'</span><span class='string'>maruku</span><span class='punct'>'</span></pre>
|
|
128
|
+
<p>and</p>
|
|
129
|
+
<pre class='xml'><span class='punct'><</span><span class='tag'>div</span> <span class='attribute'>style</span><span class='punct'>="</span><span class='string'>text-align:center</span><span class='punct'>"></span>Div<span class='punct'></</span><span class='tag'>div</span><span class='punct'>></span></pre>
|
|
130
|
+
<h3 id='id'>Attribute <code>id</code></h3>
|
|
131
|
+
|
|
132
|
+
<p class='maruku-att-origin'>Read from file <code>output/to_html.rb</code>, line 291:</p>
|
|
133
|
+
|
|
134
|
+
<p>It is copied as a standard HTML attribute.</p>
|
|
135
|
+
|
|
136
|
+
<p>Moreover, it used as a label name for hyperlinks in both HTML and in PDF.</p>
|
|
35
137
|
|
|
36
138
|
<h3 id='latex_cjk'>Attribute <code>latex_cjk</code></h3>
|
|
37
139
|
|
|
38
|
-
<p>
|
|
140
|
+
<p class='maruku-att-default'>Default: <code>false</code></p>
|
|
141
|
+
|
|
142
|
+
<p class='maruku-att-origin'>Read from file <code>output/to_latex.rb</code>, line 69:</p>
|
|
39
143
|
|
|
40
|
-
<p>If the <code>latex_cjk</code> attribute is specified, then appropriate headers are added to the LaTeX preamble to support Japanese fonts. You have to have these fonts installed
|
|
144
|
+
<p>If the <code>latex_cjk</code> attribute is specified, then appropriate headers are added to the LaTeX preamble to support Japanese fonts. You have to have these fonts installed – and this can be a pain.</p>
|
|
41
145
|
|
|
42
146
|
<p>If <code>latex_cjk</code> is specified, this is added to the preamble:</p>
|
|
43
|
-
|
|
147
|
+
<pre><code>\usepackage[C40]{fontenc}
|
|
148
|
+
\usepackage[cjkjis]{ucs}
|
|
149
|
+
\usepackage[utf8x]{inputenc}</code></pre>
|
|
44
150
|
<p>while the default is to add this:</p>
|
|
45
|
-
|
|
151
|
+
<pre><code>\usepackage{ucs}
|
|
152
|
+
\usepackage[utf8x]{inputenc}</code></pre>
|
|
46
153
|
<h3 id='latex_preamble'>Attribute <code>latex_preamble</code></h3>
|
|
47
154
|
|
|
48
|
-
<p>Read from file <code>output/to_latex.rb</code>, line
|
|
155
|
+
<p class='maruku-att-origin'>Read from file <code>output/to_latex.rb</code>, line 94:</p>
|
|
49
156
|
|
|
50
157
|
<p>If the <code>latex_preamble</code> attribute is specified, then its value will be used as a custom preamble.</p>
|
|
51
158
|
|
|
@@ -59,7 +166,9 @@ Latex preamble: preamble.tex
|
|
|
59
166
|
...</code></pre>
|
|
60
167
|
<h3 id='latex_use_listings'>Attribute <code>latex_use_listings</code></h3>
|
|
61
168
|
|
|
62
|
-
<p>
|
|
169
|
+
<p class='maruku-att-default'>Default: <code>false</code></p>
|
|
170
|
+
|
|
171
|
+
<p class='maruku-att-origin'>Read from file <code>output/to_latex.rb</code>, line 218:</p>
|
|
63
172
|
|
|
64
173
|
<p>If the <code>latex_use_listings</code> attribute is specified, then code block are rendered using the <code>listings</code> package. Otherwise, a standard <code>verbatim</code> environment is used.</p>
|
|
65
174
|
|
|
@@ -82,11 +191,60 @@ Latex preamble: preamble.tex
|
|
|
82
191
|
</li>
|
|
83
192
|
</ul>
|
|
84
193
|
|
|
85
|
-
<
|
|
194
|
+
<h3 id='maruku_signature'>Attribute <code>maruku_signature</code></h3>
|
|
195
|
+
|
|
196
|
+
<p class='maruku-att-default'>Default: <code>true</code></p>
|
|
197
|
+
|
|
198
|
+
<p class='maruku-att-origin'>Read from file <code>output/to_latex.rb</code>, line 45:</p>
|
|
199
|
+
|
|
200
|
+
<p>If false, Maruku does not append a signature to the generated file.</p>
|
|
201
|
+
|
|
202
|
+
<h3 id='style'>Attribute <code>style</code></h3>
|
|
203
|
+
|
|
204
|
+
<p class='maruku-att-origin'>Read from file <code>output/to_html.rb</code>, line 311:</p>
|
|
205
|
+
|
|
206
|
+
<p>It is copied as a standard HTML attribute.</p>
|
|
207
|
+
|
|
208
|
+
<h3 id='subject'>Attribute <code>subject</code></h3>
|
|
209
|
+
|
|
210
|
+
<p class='maruku-att-origin'>Read from file <code>output/to_html.rb</code>, line 126:</p>
|
|
211
|
+
|
|
212
|
+
<p>Synonim for <code>title</code>.</p>
|
|
213
|
+
|
|
214
|
+
<h3 id='title'>Attribute <code>title</code></h3>
|
|
215
|
+
|
|
216
|
+
<p class='maruku-att-origin'>Read from file <code>output/to_html.rb</code>, line 103:</p>
|
|
217
|
+
|
|
218
|
+
<p>Sets the title of the document. If a title is not specified, the first header will be used.</p>
|
|
219
|
+
|
|
220
|
+
<p>These should be equivalent:</p>
|
|
221
|
+
<pre><code>Title: my document
|
|
222
|
+
|
|
223
|
+
Content
|
|
224
|
+
</code></pre>
|
|
225
|
+
<p>and</p>
|
|
226
|
+
<pre><code>my document
|
|
227
|
+
===========
|
|
228
|
+
|
|
229
|
+
Content
|
|
230
|
+
</code></pre>
|
|
231
|
+
<p>In both cases, the title is set to “my document”.</p>
|
|
232
|
+
|
|
233
|
+
<h3 id='unsafe_features'>Attribute <code>unsafe_features</code></h3>
|
|
234
|
+
|
|
235
|
+
<p class='maruku-att-default'>Default: <code>true</code></p>
|
|
236
|
+
|
|
237
|
+
<p class='maruku-att-origin'>Read from file <code>input/parse_doc.rb</code>, line 86:</p>
|
|
238
|
+
|
|
239
|
+
<p>Disabled by default because of security concerns.</p>
|
|
240
|
+
|
|
241
|
+
<h3 id='use_numbered_headers'>Attribute <code>use_numbered_headers</code></h3>
|
|
242
|
+
|
|
243
|
+
<p class='maruku-att-default'>Default: <code>false</code></p>
|
|
244
|
+
|
|
245
|
+
<p class='maruku-att-origin'>Read from file <code>output/to_html.rb</code>, line 348:</p>
|
|
86
246
|
|
|
87
|
-
<p>
|
|
247
|
+
<p>If <code>true</code>, section headers will be numbered.</p>
|
|
88
248
|
|
|
89
|
-
<p>
|
|
90
|
-
<
|
|
91
|
-
#abc
|
|
92
|
-
#aabbcc</code></pre><div class='maruku_signature'><hr /><span style='font-size: small; font-style: italic'>Created by <a href='http://maruku.rubyforge.org' title='Maruku: a Markdown interpreter for Ruby'>Maruku</a> at 10:34 on Tuesday, January 09th, 2007.</span></div></body></html>
|
|
249
|
+
<p>In LaTeX export, the numbering of headers is managed by Maruku, to have the same results in both HTML and LaTeX.</p>
|
|
250
|
+
<div class='maruku_signature'><hr /><span style='font-size: small; font-style: italic'>Created by <a href='http://maruku.rubyforge.org' title='Maruku: a Markdown-superset interpreter for Ruby'>Maruku</a> at 14:10 on Tuesday, January 23rd, 2007.</span></div></body></html>
|
data/docs/index.html
CHANGED
|
@@ -1,15 +1,19 @@
|
|
|
1
|
-
<?xml version=
|
|
2
|
-
<!DOCTYPE html PUBLIC
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
<
|
|
1
|
+
<?xml version="1.0" encoding="utf-8"?>
|
|
2
|
+
<!DOCTYPE html PUBLIC
|
|
3
|
+
"-//W3C//DTD XHTML 1.1 plus MathML 2.0 plus SVG 1.1//EN"
|
|
4
|
+
"http://www.w3.org/2002/04/xhtml-math-svg/xhtml-math-svg.dtd">
|
|
5
|
+
<html xmlns:svg='http://www.w3.org/2000/svg' xml:lang='en' xmlns='http://www.w3.org/1999/xhtml'>
|
|
6
|
+
<head><meta content='application/xhtml+xml;charset=utf-8' http-equiv='Content-type' /><title>Maruku: a Markdown-superset interpreter</title><link href='style.css' rel='stylesheet' type='text/css' />
|
|
7
|
+
</head>
|
|
8
|
+
<body>
|
|
9
|
+
<p><img src='logo.png' id='logo' alt='' /></p>
|
|
6
10
|
|
|
7
11
|
<h1 id='maruku_a_markdownsuperset_interpreter'>Mar<strong>u</strong>k<strong>u</strong>: a Markdown-superset interpreter</h1>
|
|
8
12
|
|
|
9
13
|
<p><a href='http://maruku.rubyforge.org/'>Maruku</a> is a Markdown interpreter written in <a href='http://www.ruby-lang.org'>Ruby</a>.</p>
|
|
10
14
|
|
|
11
15
|
<blockquote id='news'>
|
|
12
|
-
<p><a href='#release_notes'>Last release</a> is version 0.
|
|
16
|
+
<p><a href='#release_notes'>Last release</a> is version 0.5.0 – 2007-01-23.</p>
|
|
13
17
|
|
|
14
18
|
<p>Use this command to update:</p>
|
|
15
19
|
<pre><code>$ gem update maruku</code></pre></blockquote>
|
|
@@ -50,10 +54,10 @@
|
|
|
50
54
|
|
|
51
55
|
<p><strong>Authors</strong>: Maruku has been developed so far by <a href='http://www.dis.uniroma1.it/~acensi/'>Andrea Censi</a>. Contributors are most welcome!</p>
|
|
52
56
|
|
|
53
|
-
<p><strong>The name of the game</strong>: Maruku is the <a href='http://en.wikipedia.org/wiki/Romaji'>romaji</a>
|
|
57
|
+
<p><strong>The name of the game</strong>: Maruku is the <a href='http://en.wikipedia.org/wiki/Romaji'>romaji</a> transliteration of the <a href='http://en.wikipedia.org/wiki/Katakana'>katakana</a> transliteration of “Mark”, the first word in Markdown. I chose this name because Ruby is Japanese, and also the sillable “ru” appears in Maruku.</p>
|
|
54
58
|
<hr />
|
|
55
59
|
<p>Table of contents: (<strong>auto-generated by Maruku!</strong>)</p>
|
|
56
|
-
<div class='maruku_toc'><ul style='list-style: none;'><li><span class='maruku_section_number'>1. </span><a href='#release_notes'>Release notes</a></li><li><span class='maruku_section_number'>2. </span><a href='#download'>Download</a><ul style='list-style: none;'><li><span class='maruku_section_number'>2.1. </span><a href='#bugs_report'>Bugs report</a></li></ul></li><li><span class='maruku_section_number'>3. </span><a href='#usage'>Usage</a><ul style='list-style: none;'><li><span class='maruku_section_number'>3.1. </span><a href='#
|
|
60
|
+
<div class='maruku_toc'><ul style='list-style: none;'><li><span class='maruku_section_number'>1. </span><a href='#release_notes'>Release notes</a></li><li><span class='maruku_section_number'>2. </span><a href='#download'>Download</a><ul style='list-style: none;'><li><span class='maruku_section_number'>2.1. </span><a href='#bugs_report'>Bugs report</a></li></ul></li><li><span class='maruku_section_number'>3. </span><a href='#usage'>Usage</a><ul style='list-style: none;'><li><span class='maruku_section_number'>3.1. </span><a href='#embedded_maruku'>Embedded Maruku</a></li><li><span class='maruku_section_number'>3.2. </span><a href='#from_the_command_line'>From the command line</a></li></ul></li><li><span class='maruku_section_number'>4. </span><a href='#maruku-and-bluecloth'>Maruku and Bluecloth</a></li><li><span class='maruku_section_number'>5. </span><a href='#maruku_summary_of_features'>Maruku summary of features</a><ul style='list-style: none;'><li><span class='maruku_section_number'>5.1. </span><a href='#meta'>New meta-data syntax</a></li><li><span class='maruku_section_number'>5.2. </span><a href='#toc-generation'>Automatic generation of the table of contents</a></li><li><span class='maruku_section_number'>5.3. </span><a href='#entities'>Use HTML entities</a></li><li><span class='maruku_section_number'>5.4. </span><a href='#this_header_contains_emphasis_strong_text_and_'>This header contains <em>emphasis</em> <strong>strong text</strong> and <code>code</code></a></li></ul></li><li><span class='maruku_section_number'>6. </span><a href='#extra'>Examples of PHP Markdown Extra syntax</a></li></ul></div><hr />
|
|
57
61
|
<h2 id='release_notes'><span class='maruku_section_number'>1. </span>Release notes</h2>
|
|
58
62
|
|
|
59
63
|
<p>Note: Maruku seems to be very robust, nevertheless it is still beta-level software. So if you want to use it in production environments, please check back in a month or so, while we squash the remaining bugs.</p>
|
|
@@ -62,244 +66,186 @@
|
|
|
62
66
|
|
|
63
67
|
<p>Have fun!</p>
|
|
64
68
|
|
|
65
|
-
<
|
|
69
|
+
<p>See the <a href='http://maruku.rubyforge.org/changelog.html#stable'>changelog</a>.</p>
|
|
66
70
|
|
|
67
|
-
<
|
|
68
|
-
<li>
|
|
69
|
-
<p>Adapted syntax to the <a href='http://maruku.rubyforge.org/proposal.html'>new meta-data proposal</a>.</p>
|
|
70
|
-
</li>
|
|
71
|
+
<h2 id='download'><span class='maruku_section_number'>2. </span>Download</h2>
|
|
71
72
|
|
|
72
|
-
<
|
|
73
|
-
<p>Changes in LaTeX export:</p>
|
|
73
|
+
<p>The development site is <a href='http://rubyforge.org/projects/maruku/'>http://rubyforge.org/projects/maruku/</a>.</p>
|
|
74
74
|
|
|
75
|
-
<
|
|
76
|
-
<
|
|
77
|
-
|
|
78
|
-
</
|
|
75
|
+
<p>Install with:</p>
|
|
76
|
+
<pre><code>$ gem install maruku
|
|
77
|
+
</code></pre>
|
|
78
|
+
<p>Released files can also be seen at <a href='http://rubyforge.org/frs/?group_id=2795'>http://rubyforge.org/frs/?group_id=2795</a>.</p>
|
|
79
79
|
|
|
80
|
-
<
|
|
81
|
-
<
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
LaTeX preamble: preamble.tex
|
|
80
|
+
<p>Anonymous access to the repository is possible with:</p>
|
|
81
|
+
<pre><code>$ svn checkout svn://rubyforge.org/var/svn/maruku/trunk
|
|
82
|
+
</code></pre>
|
|
83
|
+
<p>If you want commit access to the repository, just create an account on Rubyforge and <a href='http://www.dis.uniroma1.it/~acensi/contact.html'>drop me a mail</a>.</p>
|
|
85
84
|
|
|
86
|
-
|
|
87
|
-
</ul>
|
|
88
|
-
</li>
|
|
85
|
+
<h3 id='bugs_report'><span class='maruku_section_number'>2.1. </span>Bugs report</h3>
|
|
89
86
|
|
|
90
|
-
<
|
|
91
|
-
<p>Bug fixes</p>
|
|
87
|
+
<p>Use the <a href='http://rubyforge.org/tracker/?group_id=2795'>tracker</a> or <a href='http://www.dis.uniroma1.it/~acensi/contact.html'>drop me an email</a>.</p>
|
|
92
88
|
|
|
93
|
-
<
|
|
94
|
-
<li>
|
|
95
|
-
<p>Images were not given <code>id</code> or <code>class</code> attributes.</p>
|
|
96
|
-
</li>
|
|
89
|
+
<h2 id='usage'><span class='maruku_section_number'>3. </span>Usage</h2>
|
|
97
90
|
|
|
98
|
-
<
|
|
99
|
-
<p>Fixed bug in LaTeX export with handling of <code><</code>,<code>></code> enclosed URLs: <code><google.com></code>.</p>
|
|
100
|
-
</li>
|
|
101
|
-
</ul>
|
|
102
|
-
</li>
|
|
103
|
-
</ul>
|
|
91
|
+
<h3 id='embedded_maruku'><span class='maruku_section_number'>3.1. </span>Embedded Maruku</h3>
|
|
104
92
|
|
|
105
|
-
<
|
|
93
|
+
<p>This is the basic usage:</p>
|
|
94
|
+
<pre><code>require 'rubygems'
|
|
95
|
+
require 'maruku'
|
|
106
96
|
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
<
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
<p
|
|
114
|
-
|
|
97
|
+
doc = Maruku.new(markdown_string)
|
|
98
|
+
puts doc.to_html
|
|
99
|
+
</code></pre>
|
|
100
|
+
<p>The method <code>to_html</code> outputs only an HTML fragment, while the method <code>to_html_document</code> outputs a complete XHTML 1.0 document:</p>
|
|
101
|
+
<pre><code>puts doc.to_html_document
|
|
102
|
+
</code></pre>
|
|
103
|
+
<p>You can have the REXML document tree with:</p>
|
|
104
|
+
<pre><code>tree = doc.to_html_document_tree
|
|
105
|
+
</code></pre>
|
|
106
|
+
<h3 id='from_the_command_line'><span class='maruku_section_number'>3.2. </span>From the command line</h3>
|
|
115
107
|
|
|
116
|
-
<p>
|
|
117
|
-
</li>
|
|
108
|
+
<p>There is one command-line program installed: <code>maruku</code>.</p>
|
|
118
109
|
|
|
119
|
-
<
|
|
120
|
-
<
|
|
121
|
-
</
|
|
110
|
+
<p>Without arguments, it converts Markdown to HTML:</p>
|
|
111
|
+
<pre><code>$ maruku file.md # creates file.html</code></pre>
|
|
112
|
+
<p>With the <code>--pdf</code> arguments, it converts Markdown to LaTeX, then calls <code>pdflatex</code> to transform to PDF:</p>
|
|
113
|
+
<pre><code>$ maruku --pdf file.md # creates file.tex and file.pdf</code></pre>
|
|
114
|
+
<h2 id='maruku-and-bluecloth'><span class='maruku_section_number'>4. </span>Maruku and Bluecloth</h2>
|
|
122
115
|
|
|
123
|
-
<
|
|
124
|
-
<p>Changes in LaTeX export:</p>
|
|
116
|
+
<p>The other Ruby implementation of Markdown is <a href='http://www.deveiate.org/projects/BlueCloth'>Bluecloth</a>.</p>
|
|
125
117
|
|
|
126
|
-
<
|
|
127
|
-
<li>
|
|
128
|
-
<p>Now Japanese text rendering sort of works, using the following packages:</p>
|
|
129
|
-
<pre><code>\usepackage[C40]{fontenc}
|
|
130
|
-
\usepackage[cjkjis]{ucs}
|
|
131
|
-
\usepackage[utf8x]{inputenc}
|
|
132
|
-
</code></pre>
|
|
133
|
-
<p>Nevertheless, I could only get bitmap fonts working – probably it’s a problem with my setup.</p>
|
|
118
|
+
<p>Maruku is much different in philosophy from Bluecloth: the biggest difference is that <em>parsing</em> is separated from <em>rendering</em>. In Maruku, an in-memory representation of the Markdown document is created. Instead, Bluecloth mantains the document in memory as a String at all times, and does a series of <code>gsub</code> to transform to HTML.</p>
|
|
134
119
|
|
|
135
|
-
<p>
|
|
136
|
-
</li>
|
|
120
|
+
<p>Maruku is usually faster than Bluecloth. Bluecloth is faster for very small documents. Bluecloth sometimes chokes on very big documents (it is reported that the blame should be on Ruby’s regexp implementation).</p>
|
|
137
121
|
|
|
138
|
-
<
|
|
139
|
-
<
|
|
140
|
-
|
|
122
|
+
<p>This is the canonical benchmark (the Markdown specification), executed with Ruby 1.8.5 on a Powerbook 1.5GhZ:</p>
|
|
123
|
+
<pre><code>BlueCloth (to_html): parsing 0.01 sec + rendering 1.87 sec = 1.88 sec (1.00x)
|
|
124
|
+
Maruku (to_html): parsing 0.66 sec + rendering 0.43 sec = 1.09 sec (1.73x)
|
|
125
|
+
Maruku (to_latex): parsing 0.67 sec + rendering 0.23 sec = 0.90 sec (2.10x)
|
|
126
|
+
</code></pre>
|
|
127
|
+
<p>Please note that Maruku has a lot more features and therefore is looking for much more patterns in the file.</p>
|
|
141
128
|
|
|
142
|
-
<
|
|
143
|
-
<p>External packages are <code>require</code>d only if needed.</p>
|
|
144
|
-
</li>
|
|
129
|
+
<h2 id='maruku_summary_of_features'><span class='maruku_section_number'>5. </span>Maruku summary of features</h2>
|
|
145
130
|
|
|
131
|
+
<ul>
|
|
146
132
|
<li>
|
|
147
|
-
<p>
|
|
148
|
-
</li>
|
|
149
|
-
</ul>
|
|
150
|
-
</li>
|
|
151
|
-
</ul>
|
|
152
|
-
|
|
153
|
-
<h4 id='changes_in_04'>Changes in 0.4</h4>
|
|
133
|
+
<p>Supported syntax</p>
|
|
154
134
|
|
|
155
135
|
<ul>
|
|
156
|
-
<li
|
|
157
|
-
|
|
158
|
-
<li>General refactorization of the code and much cleaner error reporting.</li>
|
|
136
|
+
<li><a href='http://daringfireball.net/projects/markdown/syntax'>Basic Markdown</a></li>
|
|
159
137
|
|
|
160
|
-
<li
|
|
138
|
+
<li><a href='#extra'>Markdown Extra</a></li>
|
|
161
139
|
|
|
162
|
-
<li>
|
|
163
|
-
|
|
164
|
-
<li>Added unit-tests for block-level elements.</li>
|
|
140
|
+
<li><a href='#meta'>Meta-data syntax</a></li>
|
|
165
141
|
</ul>
|
|
142
|
+
</li>
|
|
166
143
|
|
|
167
|
-
<
|
|
144
|
+
<li>
|
|
145
|
+
<p>Output</p>
|
|
168
146
|
|
|
169
147
|
<ul>
|
|
170
148
|
<li>
|
|
171
|
-
<p>
|
|
172
|
-
|
|
173
|
-
<p>Now Maruku is almost 2x faster than Bluecloth, while having more features.</p>
|
|
149
|
+
<p>XHTML</p>
|
|
174
150
|
|
|
175
|
-
<
|
|
176
|
-
<
|
|
177
|
-
|
|
178
|
-
Maruku (to_latex): parsing 0.49 sec + rendering 0.25 sec = 0.73 sec</code></pre>
|
|
179
|
-
<p>This is the result of running <code>lib/maruku/tests/benchmark.rb</code> on the Markdown specification.</p>
|
|
151
|
+
<ul>
|
|
152
|
+
<li>Syntax highlighting via the <a href='http://syntax.rubyforge.org/'><code>syntax</code></a> library.</li>
|
|
153
|
+
</ul>
|
|
180
154
|
</li>
|
|
181
155
|
|
|
182
156
|
<li>
|
|
183
|
-
<p>
|
|
184
|
-
</li>
|
|
157
|
+
<p>LaTeX</p>
|
|
185
158
|
|
|
186
|
-
<
|
|
187
|
-
<
|
|
159
|
+
<ul>
|
|
160
|
+
<li><a href='#entities'>Translation of HTML entities to LaTeX</a></li>
|
|
161
|
+
|
|
162
|
+
<li>Syntax highlighting via the <a href='http://www.ctan.org/tex-archive/macros/latex/contrib/listings/'><code>listings</code></a> package.</li>
|
|
163
|
+
</ul>
|
|
164
|
+
</li>
|
|
165
|
+
</ul>
|
|
188
166
|
</li>
|
|
189
167
|
|
|
190
168
|
<li>
|
|
191
|
-
<p>
|
|
169
|
+
<p>Misc</p>
|
|
192
170
|
|
|
193
|
-
<
|
|
194
|
-
<
|
|
195
|
-
</
|
|
196
|
-
<p>then syntax errors will cause an exception to be raised (you can catch this and retry).</p>
|
|
171
|
+
<ul>
|
|
172
|
+
<li>
|
|
173
|
+
<p><a href='exd.html'>Documentation for supported attributes</a></p>
|
|
197
174
|
</li>
|
|
198
175
|
|
|
199
176
|
<li>
|
|
200
|
-
<p>
|
|
177
|
+
<p><a href='#toc-generation'>Automatic generation of the TOC</a></p>
|
|
178
|
+
</li>
|
|
179
|
+
</ul>
|
|
201
180
|
</li>
|
|
202
181
|
</ul>
|
|
203
182
|
|
|
204
|
-
<p>
|
|
183
|
+
<p><strong>Experimental features (not released yet)</strong></p>
|
|
205
184
|
|
|
206
185
|
<ul>
|
|
207
|
-
<li>
|
|
208
|
-
<p>UTF-8 input/output works OK for HTML, however I am having pain trying to export to LaTeX. I want at least Japanese characters support, so if you know how to do this you are very welcome to give me an hand.</p>
|
|
209
|
-
|
|
210
|
-
<p>For example: in the HTML version, you should see accented characters in this parenthesis:</p>
|
|
211
|
-
|
|
212
|
-
<blockquote>
|
|
213
|
-
<p>(àèìòù)</p>
|
|
214
|
-
</blockquote>
|
|
215
|
-
|
|
216
|
-
<p>and Japanese text in these other parentheses:</p>
|
|
217
|
-
|
|
218
|
-
<blockquote>
|
|
219
|
-
<p>(カタカナで 私の 名前は アンドレア チェンシ です).</p>
|
|
186
|
+
<li><a href='http://maruku.rubyforge.org/math.xhtml'>LaTeX Math syntax</a> (not enabled by default)</li>
|
|
220
187
|
|
|
221
|
-
<
|
|
222
|
-
</blockquote>
|
|
188
|
+
<li>An extension system for adding new syntax is available, but the API is bound to change in the future, so please don’t use it.</li>
|
|
223
189
|
|
|
224
|
-
<
|
|
225
|
-
</li>
|
|
190
|
+
<li>LaTeX to MathML using either one of <a href='http://ritex.rubyforge.org'><code>ritex</code></a>, <a href='http://golem.ph.utexas.edu/~distler/code/itexToMML/'><code>itex2mml</code></a>, <a href='http://www.blahtex.org'><code>blahtex</code></a>.</li>
|
|
226
191
|
|
|
227
|
-
<li>
|
|
228
|
-
|
|
229
|
-
</li>
|
|
192
|
+
<li>LaTeX to PNG using <a href='http://www.blahtex.org'><code>blahtex</code></a>.</li>
|
|
193
|
+
</ul>
|
|
230
194
|
|
|
231
|
-
<
|
|
232
|
-
<p>Exporting to Markdown (pretty printing).</p>
|
|
233
|
-
</li>
|
|
195
|
+
<h3 id='meta'><span class='maruku_section_number'>5.1. </span>New meta-data syntax</h3>
|
|
234
196
|
|
|
235
|
-
<
|
|
236
|
-
<p>Exporting to HTML splitting in multiple files.</p>
|
|
237
|
-
</li>
|
|
238
|
-
|
|
239
|
-
<li>
|
|
240
|
-
<p>RubyPants.</p>
|
|
241
|
-
</li>
|
|
197
|
+
<p>Maruku implements a syntax that allows to attach “meta” information to objects.</p>
|
|
242
198
|
|
|
243
|
-
<
|
|
244
|
-
<p>Support for images in PDF.</p>
|
|
245
|
-
</li>
|
|
246
|
-
</ul>
|
|
199
|
+
<p>See <a href='http://maruku.rubyforge.org/proposal.html'>this proposal</a> for how to attach metadata to the elements.</p>
|
|
247
200
|
|
|
248
|
-
<
|
|
201
|
+
<p>See the <a href='exd.html'>documentation for supported attributes</a>.</p>
|
|
249
202
|
|
|
250
|
-
<p>
|
|
203
|
+
<p>Meta-data for the document itself is specified through the use of email headers:</p>
|
|
204
|
+
<pre><code>Title: A simple document containing meta-headers
|
|
205
|
+
CSS: style.css
|
|
251
206
|
|
|
252
|
-
|
|
253
|
-
<pre><code>$ gem install maruku
|
|
207
|
+
Content of the document
|
|
254
208
|
</code></pre>
|
|
255
|
-
<p>
|
|
256
|
-
|
|
257
|
-
<p>Anonymous access to the repository is possible with:</p>
|
|
258
|
-
<pre><code>$ svn checkout svn://rubyforge.org/var/svn/maruku
|
|
209
|
+
<p>When creating the document through</p>
|
|
210
|
+
<pre><code>Maruku.new(s).to_html_document
|
|
259
211
|
</code></pre>
|
|
260
|
-
<p>
|
|
212
|
+
<p>the title and stylesheet are added as expected.</p>
|
|
261
213
|
|
|
262
|
-
<
|
|
214
|
+
<p>Meta-data keys are assumed to be case-insensitive.</p>
|
|
263
215
|
|
|
264
|
-
<
|
|
216
|
+
<h3 id='toc-generation'><span class='maruku_section_number'>5.2. </span>Automatic generation of the table of contents</h3>
|
|
265
217
|
|
|
266
|
-
<
|
|
218
|
+
<p>If you create a list, and then set the <code>toc</code> attribute, when rendering Maruku will create an auto-generated table of contents.</p>
|
|
219
|
+
<pre><code>* This will become a table of contents (this text will be scraped).
|
|
220
|
+
{:toc}
|
|
221
|
+
</code></pre>
|
|
222
|
+
<p>You can see an example of this at the beginning of this document.</p>
|
|
267
223
|
|
|
268
|
-
<
|
|
269
|
-
<pre><code>require 'rubygems'
|
|
270
|
-
require 'maruku'
|
|
224
|
+
<h3 id='entities'><span class='maruku_section_number'>5.3. </span>Use HTML entities</h3>
|
|
271
225
|
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
</code></
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
</
|
|
278
|
-
<p>
|
|
279
|
-
<pre><code>tree = doc.to_html_document_tree
|
|
280
|
-
</code></pre>
|
|
281
|
-
<h3 id='from_the_command_line'><span class='maruku_section_number'>3.1. </span>From the command line</h3>
|
|
226
|
+
<p>If you want to use HTML entities, go on! We will take care of the translation to LaTeX:</p>
|
|
227
|
+
<table><thead><tr><th>Entity</th><th>Result</th></tr></thead><tbody><tr><td style='text-align: left;'><code>&copy;</code></td><td style='text-align: left;'>©</td>
|
|
228
|
+
</tr><tr><td style='text-align: left;'><code>&pound;</code></td><td style='text-align: left;'>£</td>
|
|
229
|
+
</tr><tr><td style='text-align: left;'><code>&lambda;</code></td><td style='text-align: left;'>λ</td>
|
|
230
|
+
</tr><tr><td style='text-align: left;'><code>&mdash;</code></td><td style='text-align: left;'>—</td>
|
|
231
|
+
</tr></tbody></table>
|
|
232
|
+
<p>See the <a href='http://maruku.rubyforge.org/entity_test.html'>list of supported entities</a> (<a href='http://maruku.rubyforge.org/entity_test.pdf'>pdf</a>).</p>
|
|
282
233
|
|
|
283
|
-
<
|
|
234
|
+
<h3 id='this_header_contains_emphasis_strong_text_and_'><span class='maruku_section_number'>5.4. </span>This header contains <em>emphasis</em> <strong>strong text</strong> and <code>code</code></h3>
|
|
284
235
|
|
|
285
|
-
<
|
|
286
|
-
<li>
|
|
287
|
-
<p><code>maruku</code> converts Markdown to HTML:</p>
|
|
288
|
-
<pre><code>$ maruku file.md # creates file.html</code></pre></li>
|
|
236
|
+
<p>Note that this header contains formatting and it still works, also in the table of contents.</p>
|
|
289
237
|
|
|
290
|
-
<
|
|
291
|
-
<p><code>marutex</code> converts Markdown to LaTeX, then calls <code>pdflatex</code> to transform to PDF:</p>
|
|
292
|
-
<pre><code>$ marutex file.md # creates file.tex and file.pdf</code></pre></li>
|
|
293
|
-
</ul>
|
|
238
|
+
<p>And <a href='#features'>This is a <em>link</em> with <strong>all</strong> <strong><em>sort</em></strong> of <code>weird stuff</code></a> in the text.</p>
|
|
294
239
|
|
|
295
|
-
<h2 id='extra'><span class='maruku_section_number'>
|
|
240
|
+
<h2 id='extra'><span class='maruku_section_number'>6. </span>Examples of PHP Markdown Extra syntax</h2>
|
|
296
241
|
|
|
297
242
|
<ul>
|
|
298
243
|
<li>
|
|
299
244
|
<p>tables</p>
|
|
300
245
|
<pre><code>Col1 | Very very long head | Very very long head|
|
|
301
246
|
-----|:-------------------:|-------------------:|
|
|
302
|
-
cell | center-align | right-align |</code></pre><table><thead><tr><th>Col1</th><th>Very very long head</th><th>Very very long head</th></tr></thead><tbody><tr><td style='text-align: left;'>cell</td><td style='text-align: center;'>center-align</td><td style='text-align: right;'>right-align</td
|
|
247
|
+
cell | center-align | right-align |</code></pre><table><thead><tr><th>Col1</th><th>Very very long head</th><th>Very very long head</th></tr></thead><tbody><tr><td style='text-align: left;'>cell</td><td style='text-align: center;'>center-align</td><td style='text-align: right;'>right-align</td>
|
|
248
|
+
</tr></tbody></table></li>
|
|
303
249
|
|
|
304
250
|
<li>
|
|
305
251
|
<p>footnotes <sup id='fnref:1'><a href='#fn:1' rel='footnote'>1</a></sup></p>
|
|
@@ -338,181 +284,16 @@ cell | center-align | right-align |</code></pre><table><thead><tr>
|
|
|
338
284
|
<p>abbreviations or <abbr title='Simply an abbreviation'>ABB</abbr> for short.</p>
|
|
339
285
|
</li>
|
|
340
286
|
</ul>
|
|
287
|
+
<!--
|
|
288
|
+
Future developments {#future}
|
|
341
289
|
|
|
342
|
-
|
|
343
|
-
|
|
344
|
-
|
|
345
|
-
|
|
346
|
-
<p>Maruku is much different in philosophy from Bluecloth: the biggest difference is that <em>parsing</em> is separated from <em>rendering</em>. In Maruku, an in-memory representation of the Markdown document is created. Instead, Bluecloth mantains the document in memory as a String at all times, and does a series of <code>gsub</code> to transform to HTML.</p>
|
|
347
|
-
|
|
348
|
-
<p>The in-memory representation makes it very easy to export to various formats (at the moment HTML and LaTeX/PDF; the next is pretty-printed Markdown).</p>
|
|
349
|
-
|
|
350
|
-
<p>Other improvements over Bluecloth:</p>
|
|
351
|
-
|
|
352
|
-
<ul>
|
|
353
|
-
<li>
|
|
354
|
-
<p>the HTML output is provided also as a <code>REXML</code> document tree.</p>
|
|
355
|
-
</li>
|
|
356
|
-
|
|
357
|
-
<li>
|
|
358
|
-
<p>PHP Markdown Syntax support.</p>
|
|
359
|
-
</li>
|
|
360
|
-
</ul>
|
|
361
|
-
|
|
362
|
-
<h2 id='meta'><span class='maruku_section_number'>6. </span>New meta-data syntax</h2>
|
|
363
|
-
|
|
364
|
-
<p>Maruku implements a syntax that allows to attach “meta” information to objects.</p>
|
|
365
|
-
|
|
366
|
-
<h3 id='metadata_for_blocklevel_and_spanlevel_elements'><span class='maruku_section_number'>6.1. </span>Meta-data for block-level and span-level elements</h3>
|
|
367
|
-
|
|
368
|
-
<p>See <a href='http://maruku.rubyforge.org/proposal.html'>this proposal</a>.</p>
|
|
369
|
-
|
|
370
|
-
<h3 id='metadata_for_the_document'><span class='maruku_section_number'>6.2. </span>Meta-data for the document</h3>
|
|
371
|
-
|
|
372
|
-
<p>Meta-data for the document itself is specified through the use of email headers:</p>
|
|
373
|
-
<pre><code>Title: A simple document containing meta-headers
|
|
374
|
-
CSS: style.css
|
|
375
|
-
|
|
376
|
-
Content of the document
|
|
377
|
-
</code></pre>
|
|
378
|
-
<p>When creating the document through</p>
|
|
379
|
-
<pre><code>Maruku.new(s).to_html_document
|
|
380
|
-
</code></pre>
|
|
381
|
-
<p>the title and stylesheet are added as expected.</p>
|
|
382
|
-
|
|
383
|
-
<p>Meta-data keys are assumed to be case-insensitive.</p>
|
|
384
|
-
<hr />
|
|
385
|
-
<h3 id='metalist'><span class='maruku_section_number'>6.3. </span>List of meta-data</h3>
|
|
386
|
-
|
|
387
|
-
<dl>
|
|
388
|
-
<dt><strong><code>title</code>, <code>subject</code></strong></dt>
|
|
389
|
-
|
|
390
|
-
<dd>
|
|
391
|
-
<p>(document) Sets the title of the document (HTML: used in the <code>TITLE</code> element).</p>
|
|
392
|
-
</dd>
|
|
393
|
-
|
|
394
|
-
<dt><strong><code>use_numbered_headers</code></strong></dt>
|
|
395
|
-
|
|
396
|
-
<dd>
|
|
397
|
-
<p>(document) If <code>true</code>, headers are numbered (just like this document). Default is <code>false</code>.</p>
|
|
398
|
-
</dd>
|
|
399
|
-
|
|
400
|
-
<dt><strong><code>css</code></strong></dt>
|
|
401
|
-
|
|
402
|
-
<dd>
|
|
403
|
-
<p>(document, HTML) Url of stylesheet.</p>
|
|
404
|
-
</dd>
|
|
405
|
-
|
|
406
|
-
<dt><strong><code>html_use_syntax</code></strong></dt>
|
|
407
|
-
|
|
408
|
-
<dd>
|
|
409
|
-
<p>(document, HTML) If set, use the <a href='http://syntax.rubyforge.org/'>Ruby <code>syntax</code> library</a> to add source highlighting.</p>
|
|
410
|
-
</dd>
|
|
411
|
-
|
|
412
|
-
<dt><strong><code>latex_use_listings</code></strong></dt>
|
|
413
|
-
|
|
414
|
-
<dd>
|
|
415
|
-
<p>(document, LaTeX) If set, use the fancy <a href='http://www.ctan.org/tex-archive/macros/latex/contrib/listings/'><code>listings</code> package</a> for better displaying code blocks.</p>
|
|
416
|
-
|
|
417
|
-
<p>If not set, use standard <code>verbatim</code> environment.</p>
|
|
418
|
-
</dd>
|
|
419
|
-
|
|
420
|
-
<dt><strong><code>style</code>, <code>id</code>, <code>class</code></strong></dt>
|
|
421
|
-
|
|
422
|
-
<dd>
|
|
423
|
-
<p>(any block object, HTML) Standard CSS attributes are copied.</p>
|
|
424
|
-
</dd>
|
|
425
|
-
|
|
426
|
-
<dt><strong><code>lang</code></strong></dt>
|
|
427
|
-
|
|
428
|
-
<dd>
|
|
429
|
-
<p>(code blocks) Name of programming language (<code>ruby</code>) for syntax highlighting.</p>
|
|
430
|
-
|
|
431
|
-
<p>Default for this is <code>code_lang</code> in document.</p>
|
|
432
|
-
|
|
433
|
-
<p>Syntax highlighting is delegated to the <a href='http://syntax.rubyforge.org/'><code>syntax</code> library</a> for HTML output and to the <a href='http://www.ctan.org/tex-archive/macros/latex/contrib/listings/'><code>listings</code> package</a> for LaTeX output.</p>
|
|
434
|
-
</dd>
|
|
435
|
-
|
|
436
|
-
<dt><strong><code>code_show_spaces</code></strong></dt>
|
|
437
|
-
|
|
438
|
-
<dd>
|
|
439
|
-
<p>Shows tabs and newlines (default is read in the document object).</p>
|
|
440
|
-
</dd>
|
|
441
|
-
|
|
442
|
-
<dt><strong><code>code_background_color</code></strong></dt>
|
|
443
|
-
|
|
444
|
-
<dd>
|
|
445
|
-
<p>Background color for code blocks. (default is read in the document object).</p>
|
|
446
|
-
|
|
447
|
-
<p>The format is either a named color (<code>green</code>, <code>red</code>) or a CSS color of the form <code>#ff00ff</code>.</p>
|
|
448
|
-
|
|
449
|
-
<ul>
|
|
450
|
-
<li>
|
|
451
|
-
<p>for <strong>HTML output</strong>, the value is put straight in the <code>background-color</code> CSS property of the block.</p>
|
|
452
|
-
</li>
|
|
453
|
-
|
|
454
|
-
<li>
|
|
455
|
-
<p>for <strong>LaTeX output</strong>, if it is a named color, it must be a color accepted by the LaTeX <code>color</code> packages. If it is of the form <code>#ff00ff</code>, Maruku defines a color using the <code>\color[rgb]{r,g,b}</code> macro.</p>
|
|
456
|
-
|
|
457
|
-
<p>For example, for <code>#0000ff</code>, the macro is called as: <code>\color[rgb]{0,0,1}</code>.</p>
|
|
458
|
-
</li>
|
|
459
|
-
</ul>
|
|
460
|
-
</dd>
|
|
461
|
-
</dl>
|
|
462
|
-
|
|
463
|
-
<h3 id='examples'><span class='maruku_section_number'>6.4. </span>Examples</h3>
|
|
464
|
-
|
|
465
|
-
<p>An example of this is the following:</p>
|
|
466
|
-
<pre><code> One space
|
|
467
|
-
Two spaces
|
|
468
|
-
Tab, space, tab
|
|
469
|
-
Tab, tab, tab and all is green!
|
|
470
|
-
{:code_show_spaces code_background_color=#ffeedd}</code></pre>
|
|
471
|
-
<p>That will produce:</p>
|
|
472
|
-
<pre style='background-color: #ffeedd;'><code>¬One¬space
|
|
473
|
-
¬¬Two¬spaces
|
|
474
|
-
» ¬» Tab,¬space,¬tab
|
|
475
|
-
» » » Tab,¬tab,¬tab¬and¬all¬is¬green!</code></pre>
|
|
476
|
-
<p>Or highlighting (support depends on languages):</p>
|
|
477
|
-
<pre><code> <div style="text-align:center">Div</div>
|
|
478
|
-
{:lang=html}
|
|
479
|
-
</code></pre>
|
|
480
|
-
<p>produces:</p>
|
|
481
|
-
<pre class='xml'><span class='punct'><</span><span class='tag'>div</span> <span class='attribute'>style</span><span class='punct'>="</span><span class='string'>text-align:center</span><span class='punct'>"></span>Div<span class='punct'></</span><span class='tag'>div</span><span class='punct'>></span></pre><hr />
|
|
482
|
-
<h2 id='features'><span class='maruku_section_number'>7. </span>Other Features</h2>
|
|
483
|
-
|
|
484
|
-
<h3 id='automatic_generation_of_the_table_of_contents'><span class='maruku_section_number'>7.1. </span>Automatic generation of the table of contents</h3>
|
|
485
|
-
|
|
486
|
-
<p>If you create a list, and then set the <code>toc</code> attribute, when rendering Maruku will create an auto-generated table of contents.</p>
|
|
487
|
-
<pre><code>* This will become a table of contents (this text will be scraped).
|
|
488
|
-
{:toc}
|
|
489
|
-
</code></pre>
|
|
490
|
-
<p>You can see an example of this at the beginning of this document.</p>
|
|
491
|
-
|
|
492
|
-
<h3 id='this_header_contains_emphasis_strong_text_and_'><span class='maruku_section_number'>7.2. </span>This header contains <em>emphasis</em> <strong>strong text</strong> and <code>code</code></h3>
|
|
493
|
-
|
|
494
|
-
<p>Note that this header contains formatting and it still works, also in the table of contents.</p>
|
|
495
|
-
|
|
496
|
-
<p>And <a href='#features'>This is a <em>link</em> with <strong>all</strong> <strong><em>sort</em></strong> of <code>weird stuff</code></a> in the text.</p>
|
|
497
|
-
|
|
498
|
-
<h3 id='use_html_entities'><span class='maruku_section_number'>7.3. </span>Use HTML entities</h3>
|
|
499
|
-
|
|
500
|
-
<p>If you want to use HTML entities, go on! We will take care of the translation to LaTeX:</p>
|
|
501
|
-
<table><thead><tr><th>Entity</th><th>Result</th></tr></thead><tbody><tr><td style='text-align: left;'><code>&copy;</code></td><td style='text-align: left;'>©</td></tr><tr><td style='text-align: left;'><code>&pound;</code></td><td style='text-align: left;'>£</td></tr><tr><td style='text-align: left;'><code>a&nbsp;b</code></td><td style='text-align: left;'>a b</td></tr><tr><td style='text-align: left;'><code>&lambda;</code></td><td style='text-align: left;'>λ</td></tr><tr><td style='text-align: left;'><code>&mdash;</code></td><td style='text-align: left;'>—</td></tr></tbody></table>
|
|
502
|
-
<h2 id='future'><span class='maruku_section_number'>8. </span>Future developments</h2>
|
|
503
|
-
|
|
504
|
-
<p>I think that <a href='http://sophos.berkeley.edu/macfarlane/pandoc/'>Pandoc</a> and <a href='http://fletcher.freeshell.org/wiki/MultiMarkdown'>MultiMarkdown</a> are very cool projects. However, they are written in Haskell and Perl, respectively. I would love to have an equivalent in Ruby.</p>
|
|
505
|
-
|
|
506
|
-
<h3 id='a_syntax_for_adding_math'><span class='maruku_section_number'>8.1. </span>A syntax for adding math</h3>
|
|
507
|
-
|
|
508
|
-
<p>Something inspired from LaTeX should be familiar to all:</p>
|
|
509
|
-
<pre><code>This is inline math: $\alpha$
|
|
510
|
-
|
|
511
|
-
|
|
512
|
-
This is an equation with label:
|
|
290
|
+
I think that [Pandoc] and [MultiMarkdown] are very cool projects.
|
|
291
|
+
However, they are written in Haskell and Perl, respectively.
|
|
292
|
+
I would love to have an equivalent in Ruby.
|
|
513
293
|
|
|
514
|
-
|
|
294
|
+
[Pandoc]: http://sophos.berkeley.edu/macfarlane/pandoc/
|
|
295
|
+
[MultiMarkdown]: http://fletcher.freeshell.org/wiki/MultiMarkdown
|
|
515
296
|
|
|
516
|
-
|
|
297
|
+
--><div class='footnotes'><hr /><ol><li id='fn:1'>
|
|
517
298
|
<p>I really was missing those.</p>
|
|
518
|
-
<a href='#fnref:1' rev='footnote'>↩</a></li></ol></div><div class='maruku_signature'><hr /><span style='font-size: small; font-style: italic'>Created by <a href='http://maruku.rubyforge.org' title='Maruku: a Markdown interpreter for Ruby'>Maruku</a> at
|
|
299
|
+
<a href='#fnref:1' rev='footnote'>↩</a></li></ol></div><div class='maruku_signature'><hr /><span style='font-size: small; font-style: italic'>Created by <a href='http://maruku.rubyforge.org' title='Maruku: a Markdown-superset interpreter for Ruby'>Maruku</a> at 14:11 on Tuesday, January 23rd, 2007.</span></div></body></html>
|