patcito-maruku 0.6.0
Sign up to get free protection for your applications and to get access to all the features.
- data/AUTHORS +23 -0
- data/LICENSE +340 -0
- data/README.md +73 -0
- data/bin/maruku +196 -0
- data/bin/marutex +4 -0
- data/data/entities.xml +261 -0
- data/docs/changelog.md +334 -0
- data/docs/div_syntax.md +36 -0
- data/docs/entity_test.md +23 -0
- data/docs/markdown_syntax.md +899 -0
- data/docs/maruku.md +346 -0
- data/docs/math.md +194 -0
- data/docs/other_stuff.md +51 -0
- data/docs/proposal.md +309 -0
- data/docs/website/src/bluecloth.md +25 -0
- data/docs/website/src/download.md +31 -0
- data/docs/website/src/maruku.md +261 -0
- data/docs/website/src/proposal.md +271 -0
- data/lib/maruku.rb +132 -0
- data/lib/maruku/attributes.rb +138 -0
- data/lib/maruku/defaults.rb +69 -0
- data/lib/maruku/errors.rb +89 -0
- data/lib/maruku/ext/div.rb +121 -0
- data/lib/maruku/ext/fenced_code.rb +78 -0
- data/lib/maruku/ext/math.rb +37 -0
- data/lib/maruku/ext/math/elements.rb +21 -0
- data/lib/maruku/ext/math/latex_fix.rb +12 -0
- data/lib/maruku/ext/math/mathml_engines/blahtex.rb +93 -0
- data/lib/maruku/ext/math/mathml_engines/itex2mml.rb +39 -0
- data/lib/maruku/ext/math/mathml_engines/none.rb +21 -0
- data/lib/maruku/ext/math/mathml_engines/ritex.rb +24 -0
- data/lib/maruku/ext/math/parsing.rb +125 -0
- data/lib/maruku/ext/math/to_html.rb +237 -0
- data/lib/maruku/ext/math/to_latex.rb +36 -0
- data/lib/maruku/ext/yaml.rb +43 -0
- data/lib/maruku/helpers.rb +214 -0
- data/lib/maruku/input/charsource.rb +326 -0
- data/lib/maruku/input/extensions.rb +69 -0
- data/lib/maruku/input/html_helper.rb +189 -0
- data/lib/maruku/input/linesource.rb +111 -0
- data/lib/maruku/input/parse_block.rb +608 -0
- data/lib/maruku/input/parse_doc.rb +240 -0
- data/lib/maruku/input/parse_span_better.rb +746 -0
- data/lib/maruku/input/rubypants.rb +225 -0
- data/lib/maruku/input/type_detection.rb +147 -0
- data/lib/maruku/input_textile2/t2_parser.rb +163 -0
- data/lib/maruku/maruku.rb +31 -0
- data/lib/maruku/output/s5/fancy.rb +756 -0
- data/lib/maruku/output/s5/to_s5.rb +138 -0
- data/lib/maruku/output/to_html.rb +994 -0
- data/lib/maruku/output/to_latex.rb +580 -0
- data/lib/maruku/output/to_latex_entities.rb +101 -0
- data/lib/maruku/output/to_latex_strings.rb +64 -0
- data/lib/maruku/output/to_markdown.rb +164 -0
- data/lib/maruku/output/to_s.rb +54 -0
- data/lib/maruku/string_utils.rb +185 -0
- data/lib/maruku/structures.rb +143 -0
- data/lib/maruku/structures_inspect.rb +51 -0
- data/lib/maruku/structures_iterators.rb +48 -0
- data/lib/maruku/textile2.rb +1 -0
- data/lib/maruku/toc.rb +214 -0
- data/lib/maruku/usage/example1.rb +33 -0
- data/lib/maruku/version +0 -0
- data/lib/maruku/version.rb +54 -0
- data/spec/block_docs/abbreviations.md +52 -0
- data/spec/block_docs/alt.md +17 -0
- data/spec/block_docs/attributes/att2.md +20 -0
- data/spec/block_docs/attributes/att3.md +28 -0
- data/spec/block_docs/attributes/attributes.md +57 -0
- data/spec/block_docs/attributes/circular.md +26 -0
- data/spec/block_docs/attributes/default.md +22 -0
- data/spec/block_docs/blank.md +24 -0
- data/spec/block_docs/blanks_in_code.md +75 -0
- data/spec/block_docs/bug_def.md +16 -0
- data/spec/block_docs/bug_table.md +46 -0
- data/spec/block_docs/code.md +34 -0
- data/spec/block_docs/code2.md +28 -0
- data/spec/block_docs/code3.md +71 -0
- data/spec/block_docs/data_loss.md +25 -0
- data/spec/block_docs/divs/div1.md +167 -0
- data/spec/block_docs/divs/div2.md +21 -0
- data/spec/block_docs/divs/div3_nest.md +45 -0
- data/spec/block_docs/easy.md +15 -0
- data/spec/block_docs/email.md +20 -0
- data/spec/block_docs/encoding/iso-8859-1.md +23 -0
- data/spec/block_docs/encoding/utf-8.md +18 -0
- data/spec/block_docs/entities.md +94 -0
- data/spec/block_docs/escaping.md +67 -0
- data/spec/block_docs/extra_dl.md +52 -0
- data/spec/block_docs/extra_header_id.md +63 -0
- data/spec/block_docs/extra_table1.md +37 -0
- data/spec/block_docs/footnotes.md +97 -0
- data/spec/block_docs/headers.md +37 -0
- data/spec/block_docs/hex_entities.md +37 -0
- data/spec/block_docs/hrule.md +39 -0
- data/spec/block_docs/html2.md +22 -0
- data/spec/block_docs/html3.md +31 -0
- data/spec/block_docs/html4.md +25 -0
- data/spec/block_docs/html5.md +23 -0
- data/spec/block_docs/ie.md +49 -0
- data/spec/block_docs/images.md +90 -0
- data/spec/block_docs/images2.md +31 -0
- data/spec/block_docs/inline_html.md +152 -0
- data/spec/block_docs/inline_html2.md +21 -0
- data/spec/block_docs/links.md +152 -0
- data/spec/block_docs/links2.md +22 -0
- data/spec/block_docs/list1.md +46 -0
- data/spec/block_docs/list12.md +28 -0
- data/spec/block_docs/list2.md +56 -0
- data/spec/block_docs/list3.md +64 -0
- data/spec/block_docs/list4.md +89 -0
- data/spec/block_docs/lists.md +192 -0
- data/spec/block_docs/lists10.md +34 -0
- data/spec/block_docs/lists11.md +23 -0
- data/spec/block_docs/lists6.md +41 -0
- data/spec/block_docs/lists9.md +64 -0
- data/spec/block_docs/lists_after_paragraph.md +208 -0
- data/spec/block_docs/lists_ol.md +262 -0
- data/spec/block_docs/loss.md +16 -0
- data/spec/block_docs/math/equations.md +45 -0
- data/spec/block_docs/math/inline.md +46 -0
- data/spec/block_docs/math/math2.md +45 -0
- data/spec/block_docs/math/notmath.md +25 -0
- data/spec/block_docs/math/table.md +25 -0
- data/spec/block_docs/math/table2.md +42 -0
- data/spec/block_docs/misc_sw.md +525 -0
- data/spec/block_docs/notyet/escape.md +21 -0
- data/spec/block_docs/notyet/header_after_par.md +58 -0
- data/spec/block_docs/notyet/ticks.md +18 -0
- data/spec/block_docs/notyet/triggering.md +157 -0
- data/spec/block_docs/olist.md +45 -0
- data/spec/block_docs/one.md +15 -0
- data/spec/block_docs/paragraph.md +16 -0
- data/spec/block_docs/paragraph_rules/dont_merge_ref.md +42 -0
- data/spec/block_docs/paragraph_rules/tab_is_blank.md +24 -0
- data/spec/block_docs/paragraphs.md +46 -0
- data/spec/block_docs/pending/amps.md +15 -0
- data/spec/block_docs/pending/empty_cells.md +37 -0
- data/spec/block_docs/pending/link.md +72 -0
- data/spec/block_docs/pending/ref.md +21 -0
- data/spec/block_docs/recover/recover_links.md +15 -0
- data/spec/block_docs/red_tests/abbrev.md +679 -0
- data/spec/block_docs/red_tests/lists7.md +32 -0
- data/spec/block_docs/red_tests/lists7b.md +65 -0
- data/spec/block_docs/red_tests/lists8.md +42 -0
- data/spec/block_docs/red_tests/ref.md +23 -0
- data/spec/block_docs/red_tests/xml.md +35 -0
- data/spec/block_docs/references/long_example.md +71 -0
- data/spec/block_docs/references/spaces_and_numbers.md +15 -0
- data/spec/block_docs/smartypants.md +114 -0
- data/spec/block_docs/syntax_hl.md +52 -0
- data/spec/block_docs/table_attributes.md +34 -0
- data/spec/block_docs/test.md +19 -0
- data/spec/block_docs/underscore_in_words.md +15 -0
- data/spec/block_docs/wrapping.md +67 -0
- data/spec/block_docs/xml2.md +19 -0
- data/spec/block_docs/xml3.md +26 -0
- data/spec/block_docs/xml_instruction.md +52 -0
- data/spec/block_spec.rb +49 -0
- data/spec/span_spec.rb +254 -0
- data/spec/spec_helper.rb +6 -0
- metadata +247 -0
data/docs/maruku.md
ADDED
@@ -0,0 +1,346 @@
|
|
1
|
+
CSS: style.css
|
2
|
+
Use numbered headers: true
|
3
|
+
HTML use syntax: true
|
4
|
+
LaTeX use listings: true
|
5
|
+
LaTeX CJK: false
|
6
|
+
LaTeX preamble: preamble.tex
|
7
|
+
|
8
|
+
![MaRuKu](logo.png){#logo}
|
9
|
+
|
10
|
+
|
11
|
+
Mar**u**k**u**: a Markdown-superset interpreter
|
12
|
+
===============================================
|
13
|
+
|
14
|
+
[Maruku] is a Markdown interpreter written in [Ruby].
|
15
|
+
|
16
|
+
> [Last release](#release_notes) is version 0.5.6 -- 2007-05-22.
|
17
|
+
>
|
18
|
+
> Install using [rubygems]:
|
19
|
+
>
|
20
|
+
> $ gem install maruku
|
21
|
+
>
|
22
|
+
> Use this command to update to latest version:
|
23
|
+
>
|
24
|
+
> $ gem update maruku
|
25
|
+
>
|
26
|
+
{#news}
|
27
|
+
|
28
|
+
[rubygems]: http://rubygems.org
|
29
|
+
|
30
|
+
* * *
|
31
|
+
|
32
|
+
|
33
|
+
Maruku allows you to write in an easy-to-read-and-write syntax, like this:
|
34
|
+
|
35
|
+
> [This document in Markdown][this_md]
|
36
|
+
|
37
|
+
Then it can be translated to HTML:
|
38
|
+
|
39
|
+
> [This document in HTML][this_html]
|
40
|
+
|
41
|
+
or LaTeX, which is then converted to PDF:
|
42
|
+
|
43
|
+
> [This document in PDF][this_pdf]
|
44
|
+
|
45
|
+
Maruku implements:
|
46
|
+
|
47
|
+
* the original [Markdown syntax][markdown_html]
|
48
|
+
([HTML][markdown_html] or [PDF][markdown_pdf]), translated by Maruku).
|
49
|
+
|
50
|
+
* all the improvements in [PHP Markdown Extra].
|
51
|
+
|
52
|
+
* a new [meta-data syntax][meta_data_proposal]
|
53
|
+
|
54
|
+
|
55
|
+
__Authors__: Maruku has been developed so far by [Andrea Censi].
|
56
|
+
Contributors are most welcome!
|
57
|
+
|
58
|
+
__The name of the game__: Maruku is the [romaji] transliteration of
|
59
|
+
the [katakana] transliteration
|
60
|
+
of "Mark", the first word in Markdown. I chose this name because Ruby
|
61
|
+
is Japanese, and also the sillable "ru" appears in Maruku.
|
62
|
+
|
63
|
+
|
64
|
+
[romaji]: http://en.wikipedia.org/wiki/Romaji
|
65
|
+
[katakana]: http://en.wikipedia.org/wiki/Katakana
|
66
|
+
|
67
|
+
[tests]: http://maruku.rubyforge.org/tests/
|
68
|
+
[maruku]: http://maruku.rubyforge.org/
|
69
|
+
[markdown_html]: http://maruku.rubyforge.org/markdown_syntax.html
|
70
|
+
[markdown_pdf]: http://maruku.rubyforge.org/markdown_syntax.pdf
|
71
|
+
[this_md]: http://maruku.rubyforge.org/maruku.md
|
72
|
+
[this_html]: http://maruku.rubyforge.org/maruku.html
|
73
|
+
[this_pdf]: http://maruku.rubyforge.org/maruku.pdf
|
74
|
+
[Andrea Censi]: http://www.dis.uniroma1.it/~acensi/
|
75
|
+
|
76
|
+
[contact]: http://www.dis.uniroma1.it/~acensi/contact.html
|
77
|
+
[gem]: http://rubygems.rubyforge.org/
|
78
|
+
[tracker]: http://rubyforge.org/tracker/?group_id=2795
|
79
|
+
|
80
|
+
|
81
|
+
[ruby]: http://www.ruby-lang.org
|
82
|
+
[bluecloth]: http://www.deveiate.org/projects/BlueCloth
|
83
|
+
[Markdown syntax]: http://daringfireball.net/projects/markdown/syntax
|
84
|
+
[PHP Markdown Extra]: http://www.michelf.com/projects/php-markdown/extra/
|
85
|
+
[math syntax]: http://maruku.rubyforge.org/math.xhtml
|
86
|
+
[blahtex]: http://www.blahtex.org
|
87
|
+
[ritex]: http://ritex.rubyforge.org
|
88
|
+
[itex2mml]: http://golem.ph.utexas.edu/~distler/code/itexToMML/
|
89
|
+
[syntax]: http://syntax.rubyforge.org/
|
90
|
+
|
91
|
+
[listings]: http://www.ctan.org/tex-archive/macros/latex/contrib/listings/
|
92
|
+
[meta_data_proposal]: http://maruku.rubyforge.org/proposal.html
|
93
|
+
[markdown-discuss]: http://six.pairlist.net/mailman/listinfo/markdown-discuss
|
94
|
+
|
95
|
+
* * *
|
96
|
+
|
97
|
+
Table of contents: (**auto-generated by Maruku!**)
|
98
|
+
|
99
|
+
* This list will contain the toc (it doesn't matter what you write here)
|
100
|
+
{:toc}
|
101
|
+
|
102
|
+
* * *
|
103
|
+
|
104
|
+
{:ruby: lang=ruby code_background_color='#efffef'}
|
105
|
+
{:shell: lang=sh code_background_color='#efefff'}
|
106
|
+
{:markdown: code_background_color='#ffefef'}
|
107
|
+
{:html: lang=xml}
|
108
|
+
|
109
|
+
|
110
|
+
Release notes {#release_notes}
|
111
|
+
--------------
|
112
|
+
|
113
|
+
Note: Maruku seems to be very robust, nevertheless it is still beta-level
|
114
|
+
software. So if you want to use it in production environments, please
|
115
|
+
check back in a month or so, while we squash the remaining bugs.
|
116
|
+
|
117
|
+
In the meantime, feel free to toy around, and please signal problems,
|
118
|
+
request features, by [contacting me][contact] or using the [tracker][tracker].
|
119
|
+
For issues about the Markdown syntax itself and improvements to it,
|
120
|
+
please write to the [Markdown-discuss mailing list][markdown-discuss].
|
121
|
+
|
122
|
+
Have fun!
|
123
|
+
|
124
|
+
See the [changelog](http://maruku.rubyforge.org/changelog.html#stable).
|
125
|
+
|
126
|
+
|
127
|
+
Usage
|
128
|
+
--------
|
129
|
+
|
130
|
+
### Embedded Maruku ###
|
131
|
+
|
132
|
+
This is the basic usage:
|
133
|
+
|
134
|
+
require 'rubygems'
|
135
|
+
require 'maruku'
|
136
|
+
|
137
|
+
doc = Maruku.new(markdown_string)
|
138
|
+
puts doc.to_html
|
139
|
+
{:ruby}
|
140
|
+
|
141
|
+
The method `to_html` outputs only an HTML fragment, while the method `to_html_document` outputs a complete XHTML 1.0 document:
|
142
|
+
|
143
|
+
puts doc.to_html_document
|
144
|
+
{:ruby}
|
145
|
+
|
146
|
+
You can have the REXML document tree with:
|
147
|
+
|
148
|
+
tree = doc.to_html_document_tree
|
149
|
+
{:ruby}
|
150
|
+
|
151
|
+
### From the command line ###
|
152
|
+
|
153
|
+
There is one command-line program installed: `maruku`.
|
154
|
+
|
155
|
+
Without arguments, it converts Markdown to HTML:
|
156
|
+
|
157
|
+
$ maruku file.md # creates file.html
|
158
|
+
{:shell}
|
159
|
+
|
160
|
+
With the `--pdf` arguments, it converts Markdown to LaTeX, then calls `pdflatex` to
|
161
|
+
transform to PDF:
|
162
|
+
|
163
|
+
$ maruku --pdf file.md # creates file.tex and file.pdf
|
164
|
+
{:shell}
|
165
|
+
|
166
|
+
|
167
|
+
|
168
|
+
Maruku summary of features {#features}
|
169
|
+
--------------------------
|
170
|
+
|
171
|
+
* Supported syntax
|
172
|
+
|
173
|
+
* [Basic Markdown][markdown_syntax]
|
174
|
+
* [Markdown Extra](#extra)
|
175
|
+
* [Meta-data syntax](#meta)
|
176
|
+
|
177
|
+
* Output
|
178
|
+
|
179
|
+
* XHTML
|
180
|
+
|
181
|
+
* Syntax highlighting via the [`syntax`][syntax] library.
|
182
|
+
|
183
|
+
* LaTeX
|
184
|
+
|
185
|
+
* [Translation of HTML entities to LaTeX](#entities)
|
186
|
+
* Syntax highlighting via the [`listings`][listings] package.
|
187
|
+
|
188
|
+
* Misc
|
189
|
+
|
190
|
+
* [Documentation for supported attributes][supported_attributes]
|
191
|
+
|
192
|
+
* [Automatic generation of the TOC](#toc-generation)
|
193
|
+
|
194
|
+
|
195
|
+
[supported_attributes]: exd.html
|
196
|
+
|
197
|
+
**Experimental features (not released yet)**
|
198
|
+
|
199
|
+
* [LaTeX Math syntax][math_syntax] (not enabled by default)
|
200
|
+
* An extension system for adding new syntax is available,
|
201
|
+
but the API is bound to change in the future,
|
202
|
+
so please don't use it.
|
203
|
+
* LaTeX to MathML using either one of [`ritex`][ritex], [`itex2mml`][itex2mml],
|
204
|
+
[`blahtex`][blahtex].
|
205
|
+
* LaTeX to PNG using [`blahtex`][blahtex].
|
206
|
+
|
207
|
+
### New meta-data syntax {#meta}
|
208
|
+
|
209
|
+
Maruku implements a syntax that allows to attach "meta" information
|
210
|
+
to objects.
|
211
|
+
|
212
|
+
See [this proposal][meta_data_proposal] for how to attach
|
213
|
+
metadata to the elements.
|
214
|
+
|
215
|
+
See the [documentation for supported attributes][supported_attributes].
|
216
|
+
|
217
|
+
Meta-data for the document itself is specified through the use
|
218
|
+
of email headers:
|
219
|
+
|
220
|
+
Title: A simple document containing meta-headers
|
221
|
+
CSS: style.css
|
222
|
+
|
223
|
+
Content of the document
|
224
|
+
{:markdown}
|
225
|
+
|
226
|
+
When creating the document through
|
227
|
+
|
228
|
+
Maruku.new(s).to_html_document
|
229
|
+
{:ruby}
|
230
|
+
|
231
|
+
the title and stylesheet are added as expected.
|
232
|
+
|
233
|
+
Meta-data keys are assumed to be case-insensitive.
|
234
|
+
|
235
|
+
|
236
|
+
### Automatic generation of the table of contents ### {#toc-generation}
|
237
|
+
|
238
|
+
If you create a list, and then set the `toc` attribute, when rendering
|
239
|
+
Maruku will create an auto-generated table of contents.
|
240
|
+
|
241
|
+
* This will become a table of contents (this text will be scraped).
|
242
|
+
{:toc}
|
243
|
+
|
244
|
+
You can see an example of this at the beginning of this document.
|
245
|
+
|
246
|
+
### Use HTML entities ### {#entities}
|
247
|
+
|
248
|
+
If you want to use HTML entities, go on! We will take care
|
249
|
+
of the translation to LaTeX:
|
250
|
+
|
251
|
+
Entity | Result
|
252
|
+
------------|----------
|
253
|
+
`©` | ©
|
254
|
+
`£` | £
|
255
|
+
`λ` | λ
|
256
|
+
`—` | —
|
257
|
+
|
258
|
+
See the [list of supported entities][ent_html] ([pdf][ent_pdf]).
|
259
|
+
|
260
|
+
[ent_html]: http://maruku.rubyforge.org/entity_test.html
|
261
|
+
[ent_pdf]: http://maruku.rubyforge.org/entity_test.pdf
|
262
|
+
|
263
|
+
|
264
|
+
### This header contains *emphasis* **strong text** and `code` ####
|
265
|
+
|
266
|
+
Note that this header contains formatting and it still works, also in the table of contents.
|
267
|
+
|
268
|
+
And [This is a *link* with **all** ***sort*** of `weird stuff`](#features) in the text.
|
269
|
+
|
270
|
+
|
271
|
+
Examples of PHP Markdown Extra syntax {#extra}
|
272
|
+
-------------------------------------
|
273
|
+
|
274
|
+
* tables
|
275
|
+
|
276
|
+
Col1 | Very very long head | Very very long head|
|
277
|
+
-----|:-------------------:|-------------------:|
|
278
|
+
cell | center-align | right-align |
|
279
|
+
{:markdown}
|
280
|
+
|
281
|
+
Col1 | Very very long head | Very very long head|
|
282
|
+
-----|:-------------------:|-------------------:|
|
283
|
+
cell | center-align | right-align |
|
284
|
+
|
285
|
+
|
286
|
+
* footnotes [^foot]
|
287
|
+
|
288
|
+
* footnotes [^foot]
|
289
|
+
|
290
|
+
[^foot]: I really was missing those.
|
291
|
+
{:markdown}
|
292
|
+
|
293
|
+
[^foot]: I really was missing those.
|
294
|
+
|
295
|
+
* Markdown inside HTML elements
|
296
|
+
|
297
|
+
<div markdown="1" style="border: solid 1px black">
|
298
|
+
This is a div with Markdown **strong text**
|
299
|
+
</div>
|
300
|
+
{:html}
|
301
|
+
|
302
|
+
<div markdown="1" style="border: solid 1px black">
|
303
|
+
This is a div with Markdown **strong text**
|
304
|
+
</div>
|
305
|
+
|
306
|
+
|
307
|
+
* header ids
|
308
|
+
|
309
|
+
## Download ## {#download}
|
310
|
+
{:markdown}
|
311
|
+
|
312
|
+
For example, [a link to the download](#download) header.
|
313
|
+
|
314
|
+
|
315
|
+
* definition lists
|
316
|
+
|
317
|
+
Definition list
|
318
|
+
: something very hard to parse
|
319
|
+
{:markdown}
|
320
|
+
|
321
|
+
Definition list
|
322
|
+
: something very hard to parse
|
323
|
+
|
324
|
+
* abbreviations or ABB for short.
|
325
|
+
|
326
|
+
*[ABB]: Simply an abbreviation
|
327
|
+
|
328
|
+
|
329
|
+
<script src="http://www.google-analytics.com/urchin.js" type="text/javascript">
|
330
|
+
</script>
|
331
|
+
<script type="text/javascript">
|
332
|
+
_uacct = "UA-155626-2";
|
333
|
+
urchinTracker();
|
334
|
+
</script>
|
335
|
+
|
336
|
+
<!--
|
337
|
+
Future developments {#future}
|
338
|
+
|
339
|
+
I think that [Pandoc] and [MultiMarkdown] are very cool projects.
|
340
|
+
However, they are written in Haskell and Perl, respectively.
|
341
|
+
I would love to have an equivalent in Ruby.
|
342
|
+
|
343
|
+
[Pandoc]: http://sophos.berkeley.edu/macfarlane/pandoc/
|
344
|
+
[MultiMarkdown]: http://fletcher.freeshell.org/wiki/MultiMarkdown
|
345
|
+
|
346
|
+
-->
|
data/docs/math.md
ADDED
@@ -0,0 +1,194 @@
|
|
1
|
+
Title: Math support in Maruku
|
2
|
+
LaTeX preamble: math_preamble.tex
|
3
|
+
LaTeX use listings: true
|
4
|
+
CSS: math.css style.css
|
5
|
+
use numbered headers: true
|
6
|
+
|
7
|
+
Math support in Maruku
|
8
|
+
======================
|
9
|
+
|
10
|
+
This document describes Maruku's support of inline LaTeX-style math.
|
11
|
+
|
12
|
+
At the moment, **these features are experimental**, are probably
|
13
|
+
buggy and the syntax and implementation are bound to change in
|
14
|
+
the near future.
|
15
|
+
|
16
|
+
Also, there are many subtleties of which one must care for
|
17
|
+
correctly serving the XHTML+MathML document to browsers.
|
18
|
+
In fact, *this documentation is __not__ enough to get you started*,
|
19
|
+
unless you feel very adventurous.
|
20
|
+
|
21
|
+
* toc
|
22
|
+
{:toc}
|
23
|
+
|
24
|
+
Syntax
|
25
|
+
---------------------------------------
|
26
|
+
|
27
|
+
### Inline math
|
28
|
+
|
29
|
+
Inline math is contained inside couples of `$`.
|
30
|
+
|
31
|
+
Everything inside will be passed as-is to LaTeX: no Markdown
|
32
|
+
interpretation will take place.
|
33
|
+
|
34
|
+
Example: $x^{n}+y^{n} \neq z^{n}$ for $n \geq 3$
|
35
|
+
|
36
|
+
> Example: $x^{n}+y^{n} \neq z^{n}$ for $n \geq 3$
|
37
|
+
|
38
|
+
### Equations
|
39
|
+
|
40
|
+
Equations are specified using either the `$$ ... $$` or `\[ ... \]`
|
41
|
+
LaTeX notation. Equations can span multiple lines.
|
42
|
+
|
43
|
+
\[
|
44
|
+
\sum_{n=1}^\infty \frac{1}{n}
|
45
|
+
\text{ is divergent, but }
|
46
|
+
\lim_{n \to \infty} \sum_{i=1}^n \frac{1}{i} - \ln n \text{exists.}
|
47
|
+
\]
|
48
|
+
|
49
|
+
> \[
|
50
|
+
> \sum_{n=1}^\infty \frac{1}{n}
|
51
|
+
> \text{ is divergent, but }
|
52
|
+
> \lim_{n \to \infty} \sum_{i=1}^n \frac{1}{i} - \ln n \quad \text{exists.}
|
53
|
+
> \]
|
54
|
+
|
55
|
+
Some random AMSTeX symbols:
|
56
|
+
|
57
|
+
$$ \beth \Subset \bigtriangleup \bumpeq \ggg \pitchfork $$
|
58
|
+
|
59
|
+
$$ \beth \Subset \bigtriangleup \bumpeq \ggg \pitchfork $$
|
60
|
+
|
61
|
+
|
62
|
+
## Cross references ## {#cross}
|
63
|
+
|
64
|
+
Create a label for an equation in two ways:
|
65
|
+
|
66
|
+
* LaTeX style:
|
67
|
+
|
68
|
+
Consider \eqref{a}:
|
69
|
+
|
70
|
+
$$ \alpha = \beta \label{a} $$
|
71
|
+
|
72
|
+
* More readable style:
|
73
|
+
|
74
|
+
Consider (eq:a):
|
75
|
+
|
76
|
+
$$ \alpha = \beta $$ (a)
|
77
|
+
|
78
|
+
You can mix the two.
|
79
|
+
|
80
|
+
Labels will work as expected also in the PDF output, whatever
|
81
|
+
style you use: Maruku will insert the necessary `\label` commands.
|
82
|
+
|
83
|
+
The following are 4 equations, labeled A,B,C,D:
|
84
|
+
|
85
|
+
$$ \alpha $$ (A)
|
86
|
+
|
87
|
+
\[
|
88
|
+
\beta
|
89
|
+
\] (B)
|
90
|
+
|
91
|
+
$$ \gamma \label{C} $$
|
92
|
+
|
93
|
+
\[
|
94
|
+
\delta \label{D}
|
95
|
+
\]
|
96
|
+
|
97
|
+
You can now refer to (eq:A), (eq:B), \eqref{C}, \eqref{D}.
|
98
|
+
|
99
|
+
|
100
|
+
Enabling the extension
|
101
|
+
---------------------------------------
|
102
|
+
|
103
|
+
### On the command line
|
104
|
+
|
105
|
+
Use the `-m` option to choose the kind of output. Possible choices are:
|
106
|
+
|
107
|
+
`--math-engine itex2mml` : Outputs MathML using [itex2mml](#using_itex2mml).
|
108
|
+
`--math-engine ritex` : Outputs MathML using [ritex](#using_ritex).
|
109
|
+
`--math-engine blahtex` : Outputs MathML using [blahtex](#using_blahtex).
|
110
|
+
`--math-images blahtex` : Outputs PNGs using [blahtex](#using_blahtex).
|
111
|
+
|
112
|
+
### With embedded Maruku
|
113
|
+
|
114
|
+
You have to enable the math extension like this:
|
115
|
+
|
116
|
+
require 'maruku' # loads maruku
|
117
|
+
require 'maruku/ext/math' # loads the math extension
|
118
|
+
|
119
|
+
Use the following to choose the engine:
|
120
|
+
|
121
|
+
MaRuKu::Globals[:html_math_engine] = 'ritex'
|
122
|
+
MaRuKu::Globals[:html_png_engine] = 'blahtex'
|
123
|
+
|
124
|
+
Available MathML engines are 'none', 'itex2mml', 'blahtex'.
|
125
|
+
'blahtex' is the only PNG engine available.
|
126
|
+
|
127
|
+
External libraries needed
|
128
|
+
-------------------------
|
129
|
+
|
130
|
+
To output MathML or PNGs, it is needed to install one of the following libraries
|
131
|
+
|
132
|
+
### Using `ritex` ### {#using_ritex}
|
133
|
+
|
134
|
+
Install with
|
135
|
+
|
136
|
+
$ gem install ritex
|
137
|
+
|
138
|
+
ritex's abilities are very limited, but it is the easiest to install.
|
139
|
+
|
140
|
+
### Using `itex2mml` ### {#using_itex2mml}
|
141
|
+
|
142
|
+
itex2mml supports much more LaTeX commands/environments than ritex.
|
143
|
+
|
144
|
+
Install itex2mml using the instructions at:
|
145
|
+
|
146
|
+
> <http://golem.ph.utexas.edu/~distler/blog/itex2MML.html>
|
147
|
+
|
148
|
+
This is a summary of the available LaTeX commands:
|
149
|
+
|
150
|
+
> <http://golem.ph.utexas.edu/~distler/blog/itex2MMLcommands.html>
|
151
|
+
|
152
|
+
Moreover, [Jacques Distler] is integrating Maruku+itex2mml+[Instiki].
|
153
|
+
You can find more information here:
|
154
|
+
|
155
|
+
> <http://golem.ph.utexas.edu/~distler/blog/archives/001111.html>
|
156
|
+
|
157
|
+
[Jacques Distler]: http://golem.ph.utexas.edu/~distler
|
158
|
+
[instiki]: http://www.instiki.org
|
159
|
+
|
160
|
+
### Using `blahtex` ### {#using_blahtex}
|
161
|
+
|
162
|
+
Download from <http://www.blahtex.org>. Make sure you have
|
163
|
+
the command-line `blahtex` in your path.
|
164
|
+
|
165
|
+
|
166
|
+
Subtleties
|
167
|
+
----------
|
168
|
+
|
169
|
+
### Serving the right content/type ###
|
170
|
+
|
171
|
+
|
172
|
+
* Mozilla wants files to have the `.xhtml` extension.
|
173
|
+
|
174
|
+
...
|
175
|
+
|
176
|
+
### Where PNGS are put ###
|
177
|
+
|
178
|
+
* `Globals[:math_png_dir]`
|
179
|
+
|
180
|
+
* `Globals[:math_png_dir_url]`
|
181
|
+
|
182
|
+
|
183
|
+
### Styling equations ####
|
184
|
+
|
185
|
+
...
|
186
|
+
|
187
|
+
### Aligning PNGs ####
|
188
|
+
|
189
|
+
|
190
|
+
* using `ex`
|
191
|
+
|
192
|
+
* **IE7 bug**
|
193
|
+
|
194
|
+
...
|