maruku 0.3.0 → 0.4.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/{maruku0.3 → marudown} +6 -14
- data/bin/maruku +1 -1
- data/bin/marutest +37 -9
- data/docs/TOFIX.html +22 -0
- data/docs/TOFIX.md +3 -0
- data/docs/changelog-0.2.13.html +30 -0
- data/docs/changelog-0.2.13.md +6 -0
- data/docs/changelog-0.3.html +19 -5
- data/docs/faq.html +51 -40
- data/docs/faq.md +3 -3
- data/docs/hidden_o_n_squared.md +10 -0
- data/docs/index.html +84 -396
- data/docs/markdown_syntax.html +139 -330
- data/docs/markdown_syntax.md +80 -93
- data/docs/maruku.html +84 -396
- data/docs/maruku.md +88 -158
- data/docs/proposal.html +13 -106
- data/docs/proposal.md +3 -3
- data/docs/todo.html +38 -28
- data/lib/maruku.rb +77 -11
- data/lib/maruku/attributes.rb +186 -0
- data/lib/maruku/defaults.rb +40 -0
- data/lib/maruku/errors_management.rb +55 -39
- data/lib/maruku/helpers.rb +156 -72
- data/lib/maruku/input/charsource.rb +319 -0
- data/lib/maruku/{html_helper.rb → input/html_helper.rb} +30 -9
- data/lib/maruku/input/linesource.rb +111 -0
- data/lib/maruku/input/parse_block.rb +562 -0
- data/lib/maruku/{parse_doc.rb → input/parse_doc.rb} +60 -28
- data/lib/maruku/{parse_span_better.rb → input/parse_span_better.rb} +226 -256
- data/lib/maruku/input/type_detection.rb +137 -0
- data/lib/maruku/maruku.rb +33 -0
- data/lib/maruku/{to_html.rb → output/to_html.rb} +151 -132
- data/lib/maruku/{to_latex.rb → output/to_latex.rb} +31 -35
- data/lib/maruku/{to_latex_entities.rb → output/to_latex_entities.rb} +25 -3
- data/lib/maruku/output/to_latex_strings.rb +64 -0
- data/lib/maruku/output/to_markdown.rb +164 -0
- data/lib/maruku/{to_s.rb → output/to_s.rb} +6 -0
- data/lib/maruku/string_utils.rb +12 -181
- data/lib/maruku/structures.rb +91 -67
- data/lib/maruku/structures_inspect.rb +78 -0
- data/lib/maruku/structures_iterators.rb +24 -2
- data/lib/maruku/tests/benchmark.rb +41 -9
- data/lib/maruku/tests/new_parser.rb +317 -286
- data/lib/maruku/tests/tests.rb +20 -0
- data/lib/maruku/toc.rb +64 -64
- data/lib/maruku/usage/example1.rb +33 -0
- data/lib/maruku/version.rb +8 -2
- data/tests/unittest/abbreviations.md +27 -16
- data/tests/unittest/attributes/attributes.md +89 -0
- data/tests/unittest/attributes/circular.md +51 -0
- data/tests/unittest/attributes/default.md +47 -0
- data/tests/unittest/blank.md +10 -6
- data/tests/unittest/blanks_in_code.md +26 -26
- data/tests/unittest/code.md +9 -9
- data/tests/unittest/code2.md +12 -13
- data/tests/unittest/code3.md +34 -34
- data/tests/unittest/easy.md +9 -7
- data/tests/unittest/email.md +9 -7
- data/tests/unittest/encoding/iso-8859-1.md +41 -4
- data/tests/unittest/encoding/utf-8.md +6 -5
- data/tests/unittest/entities.md +52 -80
- data/tests/unittest/escaping.md +47 -35
- data/tests/unittest/extra_dl.md +19 -29
- data/tests/unittest/extra_header_id.md +31 -24
- data/tests/unittest/extra_table1.md +14 -32
- data/tests/unittest/footnotes.md +58 -42
- data/tests/unittest/headers.md +11 -11
- data/tests/unittest/hrule.md +14 -24
- data/tests/unittest/images.md +41 -26
- data/tests/unittest/inline_html.md +104 -56
- data/tests/unittest/inline_html2.md +38 -0
- data/tests/unittest/links.md +74 -33
- data/tests/unittest/list1.md +18 -15
- data/tests/unittest/list2.md +31 -13
- data/tests/unittest/list3.md +29 -28
- data/tests/unittest/list4.md +103 -12
- data/tests/unittest/lists.md +86 -53
- data/tests/unittest/lists6.md +53 -0
- data/tests/unittest/lists7.md +31 -0
- data/tests/unittest/lists_after_paragraph.md +105 -71
- data/tests/unittest/lists_ol.md +149 -73
- data/tests/unittest/misc_sw.md +366 -326
- data/tests/unittest/notyet/escape.md +10 -10
- data/tests/unittest/notyet/header_after_par.md +20 -14
- data/tests/unittest/notyet/ticks.md +8 -35
- data/tests/unittest/notyet/triggering.md +72 -45
- data/tests/unittest/olist.md +78 -0
- data/tests/unittest/one.md +5 -3
- data/tests/unittest/paragraph.md +5 -3
- data/tests/unittest/paragraph_rules/dont_merge_ref.md +15 -9
- data/tests/unittest/paragraph_rules/tab_is_blank.md +9 -5
- data/tests/unittest/paragraphs.md +21 -26
- data/tests/unittest/recover/recover_links.md +6 -5
- data/tests/unittest/references/long_example.md +39 -30
- data/tests/unittest/references/spaces_and_numbers.md +2 -2
- data/tests/unittest/syntax_hl.md +33 -31
- data/tests/unittest/test.md +4 -6
- data/tests/unittest/wrapping.md +43 -26
- metadata +160 -139
- data/docs/markdown_extra2.html +0 -87
- data/docs/markdown_extra2.md +0 -83
- data/docs/markdown_syntax_2.html +0 -152
- data/lib/maruku/parse_block.rb +0 -564
- data/lib/maruku/parse_span.rb +0 -451
- data/lib/maruku/to_latex_strings.rb +0 -59
- data/lib/maruku/to_markdown.rb +0 -110
- data/lib/test.rb +0 -29
data/docs/maruku.md
CHANGED
@@ -3,6 +3,11 @@ LaTeX_use_listings: true
|
|
3
3
|
html_use_syntax: true
|
4
4
|
use_numbered_headers: true
|
5
5
|
|
6
|
+
{ruby}: lang=ruby code_background_color='#efffef'
|
7
|
+
{shell}: lang=shell code_background_color='#efefff'
|
8
|
+
{markdown}: lang=markdown code_background_color='#ffefef'
|
9
|
+
|
10
|
+
|
6
11
|
Mar**u**k**u**: a Markdown-superset interpreter
|
7
12
|
===============================================
|
8
13
|
|
@@ -27,7 +32,7 @@ Maruku implements:
|
|
27
32
|
|
28
33
|
* all the improvements in [PHP Markdown Extra][].
|
29
34
|
|
30
|
-
* a new [meta-data syntax]
|
35
|
+
* a new [meta-data syntax][meta]
|
31
36
|
|
32
37
|
|
33
38
|
__Authors__: Maruku has been developed so far by [Andrea Censi][].
|
@@ -54,14 +59,13 @@ is Japanese, and also the sillable "ru" appears in Maruku.
|
|
54
59
|
|
55
60
|
Table of contents: (**auto-generated by Maruku!**)
|
56
61
|
|
57
|
-
@toc
|
58
|
-
|
59
62
|
* This list will contain the toc (it doesn't matter what you write here)
|
63
|
+
{toc}
|
60
64
|
|
61
65
|
* * *
|
62
66
|
|
63
|
-
Release notes
|
64
|
-
|
67
|
+
Release notes {#release_notes}
|
68
|
+
--------------
|
65
69
|
|
66
70
|
Note: Maruku seems to be very robust, nevertheless it is still beta-level
|
67
71
|
software. So if you want to use it in production environments, please
|
@@ -74,7 +78,18 @@ please write to the [Markdown-discuss mailing list][markdown-discuss].
|
|
74
78
|
|
75
79
|
Have fun!
|
76
80
|
|
77
|
-
Changes in 0.
|
81
|
+
#### Changes in 0.4 ####
|
82
|
+
|
83
|
+
* First implementation of [the new meta-data syntax][meta].
|
84
|
+
* General refactorization of the code and much cleaner error reporting.
|
85
|
+
* Created [the RDOC documentation][rdoc].
|
86
|
+
* The `add_whitespace` method took too much time -- it was O(n^2).
|
87
|
+
* Added unit-tests for block-level elements.
|
88
|
+
|
89
|
+
[rdoc]: http://maruku.rubyforge.org/rdoc/
|
90
|
+
[meta]: http://maruku.rubyforge.org/proposal.html
|
91
|
+
|
92
|
+
#### Changes in 0.3 ####
|
78
93
|
|
79
94
|
* A real parser is used instead of a regexp-based system, also for span-level
|
80
95
|
elements.
|
@@ -151,12 +166,16 @@ Install with:
|
|
151
166
|
|
152
167
|
$ gem install maruku
|
153
168
|
|
169
|
+
{shell}
|
170
|
+
|
154
171
|
Released files can also be seen at <http://rubyforge.org/frs/?group_id=2795>.
|
155
172
|
|
156
173
|
Anonymous access to the repository is possible with:
|
157
174
|
|
158
175
|
$ svn checkout svn://rubyforge.org/var/svn/maruku
|
159
176
|
|
177
|
+
{shell}
|
178
|
+
|
160
179
|
If you want commit access to the repository, just create an account on Rubyforge and [drop me a mail][drop].
|
161
180
|
|
162
181
|
[drop]: http://www.dis.uniroma1.it/~acensi/contact.html
|
@@ -173,97 +192,96 @@ Usage
|
|
173
192
|
|
174
193
|
This is the basic usage:
|
175
194
|
|
176
|
-
@ lang: ruby
|
177
|
-
|
178
195
|
require 'rubygems'
|
179
196
|
require 'maruku'
|
180
197
|
|
181
198
|
doc = Maruku.new(markdown_string)
|
182
199
|
puts doc.to_html
|
183
200
|
|
184
|
-
|
201
|
+
{ruby}
|
185
202
|
|
186
|
-
|
203
|
+
The method `to_html` outputs only an HTML fragment, while the method `to_html_document` outputs a complete XHTML 1.0 document:
|
187
204
|
|
188
205
|
puts doc.to_html_document
|
206
|
+
|
207
|
+
{ruby}
|
189
208
|
|
190
209
|
You can have the REXML document tree with:
|
191
210
|
|
192
|
-
@ lang: ruby
|
193
|
-
|
194
211
|
tree = doc.to_html_document_tree
|
195
212
|
|
213
|
+
{ruby}
|
214
|
+
|
196
215
|
### From the command line ###
|
197
216
|
|
198
217
|
There are two command-line programs installed: `maruku` and `marutex`.
|
199
218
|
|
200
|
-
*
|
219
|
+
* `maruku` converts Markdown to HTML:
|
201
220
|
|
202
|
-
|
221
|
+
$ maruku file.md # creates file.html
|
222
|
+
{shell}
|
203
223
|
|
204
|
-
*
|
205
|
-
transform to PDF:
|
224
|
+
* `marutex` converts Markdown to LaTeX, then calls `pdflatex` to
|
225
|
+
transform to PDF:
|
206
226
|
|
207
|
-
|
227
|
+
$ marutex file.md # creates file.tex and file.pdf
|
228
|
+
{shell}
|
208
229
|
|
209
230
|
|
210
231
|
Examples of PHP Markdown Extra syntax {#extra}
|
211
232
|
-------------------------------------
|
212
233
|
|
213
|
-
*
|
214
|
-
|
215
|
-
Col1 | Very very long head | Very very long head|
|
216
|
-
-----|:-------------------:|-------------------:|
|
217
|
-
cell | center-align | right-align |
|
234
|
+
* tables
|
218
235
|
|
219
|
-
|
236
|
+
Col1 | Very very long head | Very very long head|
|
237
|
+
-----|:-------------------:|-------------------:|
|
238
|
+
cell | center-align | right-align |
|
239
|
+
{markdown}
|
220
240
|
|
221
|
-
|
222
|
-
|
223
|
-
|
241
|
+
Col1 | Very very long head | Very very long head|
|
242
|
+
-----|:-------------------:|-------------------:|
|
243
|
+
cell | center-align | right-align |
|
224
244
|
|
225
245
|
|
226
|
-
*
|
246
|
+
* footnotes [^foot]
|
227
247
|
|
228
|
-
|
229
|
-
|
230
|
-
|
248
|
+
* footnotes [^foot]
|
249
|
+
|
250
|
+
[^foot]: I really was missing those.
|
251
|
+
{markdown}
|
231
252
|
|
232
253
|
[^foot]: I really was missing those.
|
233
254
|
|
234
|
-
*
|
255
|
+
* Markdown inside HTML elements
|
235
256
|
|
236
|
-
|
257
|
+
<div markdown="1" style="border: solid 1px black">
|
258
|
+
This is a div with Markdown **strong text**
|
259
|
+
</div>
|
260
|
+
{html}
|
237
261
|
|
238
|
-
|
239
|
-
|
240
|
-
|
262
|
+
<div markdown="1" style="border: solid 1px black">
|
263
|
+
This is a div with Markdown **strong text**
|
264
|
+
</div>
|
241
265
|
|
242
|
-
<div markdown="1" style="border: solid 1px black">
|
243
|
-
This is a div with Markdown **strong text**
|
244
|
-
</div>
|
245
266
|
|
267
|
+
* header ids
|
246
268
|
|
247
|
-
|
269
|
+
## Download ## {#download}
|
270
|
+
{markdown}
|
248
271
|
|
249
|
-
|
272
|
+
For example, [a link to the download](#download) header.
|
250
273
|
|
251
|
-
For example, [a link to the download](#download) header.
|
252
274
|
|
253
|
-
|
275
|
+
* definition lists
|
254
276
|
|
255
|
-
|
256
|
-
|
277
|
+
Definition list
|
278
|
+
: something very hard to parse
|
279
|
+
{markdown}
|
257
280
|
|
258
|
-
|
281
|
+
Definition list
|
282
|
+
: something very hard to parse
|
259
283
|
|
260
|
-
|
261
|
-
: something very hard to parse
|
262
|
-
|
263
|
-
Definition list
|
264
|
-
: something very hard to parse
|
265
|
-
|
266
|
-
* abbreviations or ABB for short.
|
284
|
+
* abbreviations or ABB for short.
|
267
285
|
|
268
286
|
*[ABB]: Simply an abbreviation
|
269
287
|
|
@@ -281,8 +299,6 @@ document is created. Instead, Bluecloth mantains the document in
|
|
281
299
|
memory as a String at all times, and does a series of `gsub`
|
282
300
|
to transform to HTML.
|
283
301
|
|
284
|
-
[^1]: "a different philosophy" stands for "ugly" `:-)`
|
285
|
-
|
286
302
|
The in-memory representation makes it very easy to export
|
287
303
|
to various formats (at the moment HTML and LaTeX/PDF;
|
288
304
|
the next is pretty-printed Markdown).
|
@@ -305,6 +321,10 @@ New meta-data syntax {#meta}
|
|
305
321
|
Maruku implements a syntax that allows to attach "meta" information
|
306
322
|
to objects.
|
307
323
|
|
324
|
+
### Meta-data for block-level and span-level elements ###
|
325
|
+
|
326
|
+
See [this proposal][meta].
|
327
|
+
|
308
328
|
### Meta-data for the document ###
|
309
329
|
|
310
330
|
Meta-data for the document itself is specified through the use
|
@@ -315,98 +335,23 @@ of email headers:
|
|
315
335
|
|
316
336
|
Content of the document
|
317
337
|
|
318
|
-
|
338
|
+
{markdown}
|
319
339
|
|
320
|
-
|
340
|
+
When creating the document through
|
321
341
|
|
322
342
|
Maruku.new(s).to_html_document
|
323
343
|
|
344
|
+
{ruby}
|
345
|
+
|
324
346
|
the title and stylesheet are added as expected.
|
325
347
|
|
326
348
|
Meta-data keys are assumed to be case-insensitive.
|
327
349
|
|
328
|
-
### Meta-data for elements ###
|
329
|
-
|
330
|
-
Maruku introduces a new syntax for attaching metadata to paragraphs, tables, and
|
331
|
-
so on.
|
332
|
-
|
333
|
-
For example, consider the creation of two paragraphs:
|
334
|
-
|
335
|
-
Paragraph 1 is a warning.
|
336
|
-
|
337
|
-
Paragraph 2
|
338
|
-
|
339
|
-
Now you really want to attach a 'class' attribute to the paragraphs (for
|
340
|
-
example for CSS styling). Maruku allows you to use:
|
341
|
-
|
342
|
-
@ class: warning
|
343
|
-
Paragraph 1 is a warning
|
344
|
-
|
345
|
-
Paragraph 2
|
346
|
-
|
347
|
-
|
348
|
-
You can add more by separating with a `;`:
|
349
|
-
|
350
|
-
@ class: warning; id: warning1
|
351
|
-
Paragraph 1 is a warning
|
352
|
-
|
353
|
-
A meta-data declaration is composed of
|
354
|
-
|
355
|
-
1. newline
|
356
|
-
2. an at-symbol `@`
|
357
|
-
3. a series of name-value pairs. Each name-value is separated
|
358
|
-
by a colon `:`, pairs are separated by semi-colons `;`
|
359
|
-
|
360
|
-
Many declaration can be used, and they refer to _the following_ object:
|
361
|
-
|
362
|
-
@ class: warning
|
363
|
-
@ id: warning1
|
364
|
-
Paragraph 1 is a warning
|
365
|
-
|
366
|
-
These can also be separated by newlines:
|
367
|
-
|
368
|
-
@ class: warning
|
369
|
-
|
370
|
-
@ id: warning1
|
371
|
-
|
372
|
-
Paragraph 1 is a warning
|
373
|
-
|
374
|
-
|
375
|
-
### Shortcuts ###
|
376
|
-
|
377
|
-
This:
|
378
|
-
|
379
|
-
@ .xyz
|
380
|
-
Paragraph
|
381
|
-
|
382
|
-
is equivalent to:
|
383
|
-
|
384
|
-
@ class: xyz
|
385
|
-
Paragraph
|
386
|
-
|
387
|
-
This:
|
388
|
-
|
389
|
-
@ #xyz
|
390
|
-
Paragraph
|
391
|
-
|
392
|
-
is equivalent to:
|
393
|
-
|
394
|
-
@ id: xyz
|
395
|
-
Paragraph
|
396
|
-
|
397
|
-
Also, if the value is not present, it defaults to `true`:
|
398
|
-
|
399
|
-
@ test
|
400
|
-
|
401
|
-
This paragraph has the attribute `test` set to `true`.
|
402
350
|
|
403
351
|
* * *
|
404
352
|
|
405
353
|
|
406
|
-
|
407
|
-
@ #metalist
|
408
|
-
|
409
|
-
### List of meta-data ###
|
354
|
+
### List of meta-data ### {#metalist}
|
410
355
|
|
411
356
|
[listings]: http://www.ctan.org/tex-archive/macros/latex/contrib/listings/
|
412
357
|
|
@@ -464,52 +409,37 @@ Also, if the value is not present, it defaults to `true`:
|
|
464
409
|
|
465
410
|
An example of this is the following:
|
466
411
|
|
467
|
-
@ code_show_spaces
|
468
|
-
@ code_show_spaces; code_background_color: green
|
469
|
-
|
470
412
|
One space
|
471
413
|
Two spaces
|
472
414
|
Tab, space, tab
|
473
415
|
Tab, tab, tab and all is green!
|
474
|
-
|
416
|
+
{code_show_spaces code_background_color=#ffeedd}
|
417
|
+
{markdown}
|
418
|
+
|
475
419
|
That will produce:
|
476
420
|
|
477
|
-
@ code_show_spaces
|
478
|
-
@ code_background_color: green
|
479
|
-
|
480
421
|
One space
|
481
422
|
Two spaces
|
482
423
|
Tab, space, tab
|
483
424
|
Tab, tab, tab and all is green!
|
425
|
+
{code_show_spaces code_background_color=#ffeedd}
|
484
426
|
|
485
|
-
Example with css-style color:
|
486
|
-
|
487
|
-
@ code_background_color: #455678
|
488
|
-
|
489
|
-
A strange color
|
490
|
-
|
491
|
-
produces:
|
492
|
-
|
493
|
-
@ code_background_color: #455678
|
494
|
-
|
495
|
-
A strange color
|
496
427
|
|
497
|
-
Or highlighting (
|
428
|
+
Or highlighting (support depends on languages):
|
498
429
|
|
499
|
-
@ lang: xml
|
500
430
|
<div style="text-align:center">Div</div>
|
431
|
+
{lang=html}
|
501
432
|
|
502
433
|
produces:
|
503
434
|
|
504
|
-
@ lang: xml
|
505
435
|
<div style="text-align:center">Div</div>
|
436
|
+
{lang=html}
|
506
437
|
|
507
438
|
|
508
439
|
|
509
440
|
* * *
|
510
441
|
|
511
|
-
|
512
|
-
Other Features
|
442
|
+
Other Features {#features}
|
513
443
|
--------------
|
514
444
|
|
515
445
|
### Automatic generation of the table of contents ###
|
@@ -517,8 +447,8 @@ Other Features
|
|
517
447
|
If you create a list, and then set the `toc` attribute, when rendering
|
518
448
|
Maruku will create an auto-generated table of contents.
|
519
449
|
|
520
|
-
@ toc
|
521
450
|
* This will become a table of contents (this text will be scraped).
|
451
|
+
{toc}
|
522
452
|
|
523
453
|
You can see an example of this at the beginning of this document.
|
524
454
|
|
data/docs/proposal.html
CHANGED
@@ -1,13 +1,7 @@
|
|
1
1
|
<?xml version='1.0' encoding='utf-8'?>
|
2
2
|
<!DOCTYPE html PUBLIC '-//W3C//DTD XHTML 1.0 Strict//EN'
|
3
3
|
'http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd'>
|
4
|
-
<html lang='en' xml:lang='en' xmlns='http://www.w3.org/1999/xhtml'>
|
5
|
-
<head>
|
6
|
-
<title>Proposal for adding a meta-data syntax to Markdown</title>
|
7
|
-
|
8
|
-
<link href='style.css' rel='stylesheet' type='text/css' />
|
9
|
-
</head>
|
10
|
-
<body>
|
4
|
+
<html lang='en' xml:lang='en' xmlns='http://www.w3.org/1999/xhtml'><head><meta content='text/html; charset=utf-8' http-equiv='Content-type' /><title>Proposal for adding a meta-data syntax to Markdown</title><link href='style.css' rel='stylesheet' type='text/css' /></head><body>
|
11
5
|
<h1 id='proposal_for_adding_a_metadata_syntax_to_markdown'>Proposal for adding a meta-data syntax to Markdown</h1>
|
12
6
|
|
13
7
|
<p>This document describes a syntax for attaching meta-data to block-level elements (headers, paragraphs, code blocks,…), and to span-level elements (links, images,…).</p>
|
@@ -16,43 +10,7 @@
|
|
16
10
|
|
17
11
|
<p><em>Table of contents:</em></p>
|
18
12
|
|
19
|
-
<blockquote>
|
20
|
-
<div class='maruku_toc'>
|
21
|
-
<ul style='list-style: none;'>
|
22
|
-
<li><span class='maruku_section_number'>1. </span><a href='#overview'>Overview</a></li>
|
23
|
-
|
24
|
-
<li><span class='maruku_section_number'>2. </span><a href='#attribute_lists'>Attribute lists</a>
|
25
|
-
<ul style='list-style: none;'>
|
26
|
-
<li><span class='maruku_section_number'>2.1. </span><a href='#class_id'><code>id</code> and <code>class</code> are special</a></li>
|
27
|
-
</ul>
|
28
|
-
</li>
|
29
|
-
|
30
|
-
<li><span class='maruku_section_number'>3. </span><a href='#where_to_put_inline_attribute_lists'>Where to put inline attribute lists</a>
|
31
|
-
<ul style='list-style: none;'>
|
32
|
-
<li><span class='maruku_section_number'>3.1. </span><a href='#for_blocklevel_elements'>For block-level elements</a></li>
|
33
|
-
|
34
|
-
<li><span class='maruku_section_number'>3.2. </span><a href='#for_headers'>For headers</a></li>
|
35
|
-
|
36
|
-
<li><span class='maruku_section_number'>3.3. </span><a href='#for_spanlevel_elements'>For span-level elements</a></li>
|
37
|
-
</ul>
|
38
|
-
</li>
|
39
|
-
|
40
|
-
<li><span class='maruku_section_number'>4. </span><a href='#using_tags'>Using attributes lists definition</a></li>
|
41
|
-
|
42
|
-
<li><span class='maruku_section_number'>5. </span><a href='#grammar'>The rules</a>
|
43
|
-
<ul style='list-style: none;'>
|
44
|
-
<li><span class='maruku_section_number'>5.1. </span><a href='#the_issue_of_escaping'>The issue of escaping</a></li>
|
45
|
-
|
46
|
-
<li><span class='maruku_section_number'>5.2. </span><a href='#syntax_for_attribute_lists'>Syntax for attribute lists</a></li>
|
47
|
-
</ul>
|
48
|
-
</li>
|
49
|
-
|
50
|
-
<li><span class='maruku_section_number'>6. </span><a href='#things_to_discuss'>Things to discuss</a></li>
|
51
|
-
|
52
|
-
<li><span class='maruku_section_number'>7. </span><a href='#design_rationale'>Design rationale</a></li>
|
53
|
-
</ul>
|
54
|
-
</div>
|
55
|
-
</blockquote>
|
13
|
+
<blockquote><div class='maruku_toc'><ul style='list-style: none;'><li><span class='maruku_section_number'>1. </span><a href='#overview'>Overview</a></li><li><span class='maruku_section_number'>2. </span><a href='#attribute_lists'>Attribute lists</a><ul style='list-style: none;'><li><span class='maruku_section_number'>2.1. </span><a href='#class_id'><code>id</code> and <code>class</code> are special</a></li></ul></li><li><span class='maruku_section_number'>3. </span><a href='#where_to_put_inline_attribute_lists'>Where to put inline attribute lists</a><ul style='list-style: none;'><li><span class='maruku_section_number'>3.1. </span><a href='#for_blocklevel_elements'>For block-level elements</a></li><li><span class='maruku_section_number'>3.2. </span><a href='#for_headers'>For headers</a></li><li><span class='maruku_section_number'>3.3. </span><a href='#for_spanlevel_elements'>For span-level elements</a></li></ul></li><li><span class='maruku_section_number'>4. </span><a href='#using_tags'>Using attributes lists definition</a></li><li><span class='maruku_section_number'>5. </span><a href='#grammar'>The rules</a><ul style='list-style: none;'><li><span class='maruku_section_number'>5.1. </span><a href='#the_issue_of_escaping'>The issue of escaping</a></li><li><span class='maruku_section_number'>5.2. </span><a href='#syntax_for_attribute_lists'>Syntax for attribute lists</a></li></ul></li><li><span class='maruku_section_number'>6. </span><a href='#things_to_discuss'>Things to discuss</a></li><li><span class='maruku_section_number'>7. </span><a href='#design_rationale'>Design rationale</a></li></ul></div></blockquote>
|
56
14
|
|
57
15
|
<h2 id='overview'><span class='maruku_section_number'>1. </span>Overview</h2>
|
58
16
|
|
@@ -61,30 +19,23 @@
|
|
61
19
|
<ol>
|
62
20
|
<li>
|
63
21
|
<p>inline attribute lists (IAL)</p>
|
64
|
-
|
65
|
-
<pre><code>## Header ## {key=val .class #id ref_id}</code></pre>
|
66
|
-
</li>
|
22
|
+
<pre><code>## Header ## {key=val .class #id ref_id}</code></pre></li>
|
67
23
|
|
68
24
|
<li>
|
69
25
|
<p>attribute lists definitions (ALD)</p>
|
70
|
-
|
71
|
-
<pre><code>{ref_id}: key=val .class #id</code></pre>
|
72
|
-
</li>
|
26
|
+
<pre><code>{ref_id}: key=val .class #id</code></pre></li>
|
73
27
|
</ol>
|
74
28
|
|
75
29
|
<p>Every span-level or block-level element can be followed by an IAL:</p>
|
76
|
-
|
77
30
|
<pre><code>### Header ### {#header1 class=c1}
|
78
31
|
|
79
32
|
Paragraph *with emphasis*{class=c1}
|
80
33
|
second line of paragraph
|
81
34
|
{class=c1}
|
82
35
|
</code></pre>
|
83
|
-
|
84
36
|
<p>In this example, the three IALs refer to the header, the emphasis span, and the entire paragraph, respectively.</p>
|
85
37
|
|
86
38
|
<p>IALs can reference ALDs. The result of the following example is the same as the previous one:</p>
|
87
|
-
|
88
39
|
<pre><code>### Header ### {#header1 c1}
|
89
40
|
|
90
41
|
Paragraph *with emphasis*{c1}
|
@@ -93,14 +44,11 @@ second line of paragraph
|
|
93
44
|
|
94
45
|
{c1}: class=c1
|
95
46
|
</code></pre>
|
96
|
-
|
97
47
|
<h2 id='attribute_lists'><span class='maruku_section_number'>2. </span>Attribute lists</h2>
|
98
48
|
|
99
49
|
<p>This is an example attribute list, which shows everything you can put inside:</p>
|
100
|
-
|
101
50
|
<pre><code>key1=val key2="long val" #myid .class1 .class2 ref1 ref2
|
102
51
|
</code></pre>
|
103
|
-
|
104
52
|
<p>More in particular, an attribute list is a whitespace-separated list of elements of 4 different kinds:</p>
|
105
53
|
|
106
54
|
<ol>
|
@@ -110,7 +58,7 @@ second line of paragraph
|
|
110
58
|
|
111
59
|
<li><a href='#class_id'>id specifiers</a> (<code>#myid</code>)</li>
|
112
60
|
|
113
|
-
<li><a href='#class_id'>class specifiers</a> (<code>.myclass</code>)
|
61
|
+
<li><a href='#class_id'>class specifiers</a> (<code>.myclass</code>)</li>
|
114
62
|
</ol>
|
115
63
|
|
116
64
|
<h3 id='class_id'><span class='maruku_section_number'>2.1. </span><code>id</code> and <code>class</code> are special</h3>
|
@@ -126,26 +74,21 @@ second line of paragraph
|
|
126
74
|
<p><code>.myclass</code> means "add <code>myclass</code> to the current <code>class</code> attribute".</p>
|
127
75
|
|
128
76
|
<p>So these are equivalent:</p>
|
129
|
-
|
130
77
|
<pre><code>{.class1 .class2}
|
131
|
-
{class="class1 class2"}</code></pre>
|
132
|
-
</li>
|
78
|
+
{class="class1 class2"}</code></pre></li>
|
133
79
|
</ul>
|
134
80
|
|
135
81
|
<p>The following attribute lists are equivalent:</p>
|
136
|
-
|
137
82
|
<pre><code>{#myid .class1 .class2}
|
138
83
|
{id=myid class=class1 .class2}
|
139
84
|
{id=myid class="class1 class2"}
|
140
85
|
{id=myid class="will be overridden" class=class1 .class2}
|
141
86
|
</code></pre>
|
142
|
-
|
143
87
|
<h2 id='where_to_put_inline_attribute_lists'><span class='maruku_section_number'>3. </span>Where to put inline attribute lists</h2>
|
144
88
|
|
145
89
|
<h3 id='for_blocklevel_elements'><span class='maruku_section_number'>3.1. </span>For block-level elements</h3>
|
146
90
|
|
147
91
|
<p>For paragraphs and other block-level elements, IAL go <strong>after</strong> the element:</p>
|
148
|
-
|
149
92
|
<pre><code>This is a paragraph.
|
150
93
|
Line 2 of the paragraph.
|
151
94
|
{#myid .myclass}
|
@@ -154,17 +97,13 @@ A quote with a citation url:
|
|
154
97
|
> Who said that?
|
155
98
|
{cite=google.com}
|
156
99
|
</code></pre>
|
157
|
-
|
158
100
|
<p>Note: empty lines between the block and the IAL are not tollerated. So this is not legal:</p>
|
159
|
-
|
160
101
|
<pre><code>This is a paragraph.
|
161
102
|
Line 2 of the paragraph.
|
162
103
|
|
163
104
|
{#myid .myclass}
|
164
105
|
</code></pre>
|
165
|
-
|
166
106
|
<p>Attribute lists may be indented up to 3 spaces:</p>
|
167
|
-
|
168
107
|
<pre><code>Paragraph1
|
169
108
|
¬{ok}
|
170
109
|
|
@@ -172,21 +111,16 @@ Paragraph2
|
|
172
111
|
¬¬{ok}
|
173
112
|
|
174
113
|
Paragraph2
|
175
|
-
¬¬¬{ok}
|
176
|
-
</code></pre>
|
177
|
-
|
114
|
+
¬¬¬{ok}</code></pre>
|
178
115
|
<h3 id='for_headers'><span class='maruku_section_number'>3.2. </span>For headers</h3>
|
179
116
|
|
180
117
|
<p>For headers, you can put attribute lists on the same line:</p>
|
181
|
-
|
182
118
|
<pre><code>### Header ### {#myid}
|
183
119
|
|
184
120
|
Header {#myid .myclass}
|
185
121
|
------
|
186
122
|
</code></pre>
|
187
|
-
|
188
123
|
<p>or, as like other block-level elements, on the line below:</p>
|
189
|
-
|
190
124
|
<pre><code>### Header ###
|
191
125
|
{#myid}
|
192
126
|
|
@@ -194,56 +128,44 @@ Header
|
|
194
128
|
------
|
195
129
|
{#myid .myclass}
|
196
130
|
</code></pre>
|
197
|
-
|
198
131
|
<h3 id='for_spanlevel_elements'><span class='maruku_section_number'>3.3. </span>For span-level elements</h3>
|
199
132
|
|
200
133
|
<p>For span-level elements, meta-data goes immediately <strong>after</strong> in the flow.</p>
|
201
134
|
|
202
135
|
<p>For example, in this:</p>
|
203
|
-
|
204
136
|
<pre><code>This is a *chunky paragraph*{#id1}
|
205
137
|
{#id2}</code></pre>
|
206
|
-
|
207
138
|
<p>the ID of the <code>em</code> element is set to <code>id1</code> and the ID of the paragraph is set to <code>id2</code>.</p>
|
208
139
|
|
209
140
|
<p>This works also for links, like this:</p>
|
210
|
-
|
211
141
|
<pre><code>This is [a link][ref]{#myid rel=abc rev=abc}
|
212
142
|
</code></pre>
|
213
|
-
|
214
143
|
<p>For images, this:</p>
|
215
|
-
|
216
144
|
<pre><code>This is 
|
217
145
|
</code></pre>
|
218
|
-
|
219
146
|
<p>is equivalent to:</p>
|
220
|
-
|
221
147
|
<pre><code>This is {title="fresh carrots"}
|
222
148
|
</code></pre>
|
223
|
-
|
224
149
|
<h2 id='using_tags'><span class='maruku_section_number'>4. </span>Using attributes lists definition</h2>
|
225
150
|
|
226
|
-
<p>In an attribute list, you can have
|
151
|
+
<p>In an attribute list, you can have:</p>
|
227
152
|
|
228
153
|
<ol>
|
229
154
|
<li><code>key=value</code> pairs,</li>
|
230
155
|
|
231
156
|
<li>id attributes (<code>#myid</code>)</li>
|
232
157
|
|
233
|
-
<li>class attributes (<code>.myclass</code>)
|
158
|
+
<li>class attributes (<code>.myclass</code>)</li>
|
234
159
|
</ol>
|
235
160
|
|
236
161
|
<p>Everything else is interpreted as a reference to an ALD.</p>
|
237
|
-
|
238
162
|
<pre><code># Header # {ref}
|
239
163
|
|
240
164
|
Blah blah blah.
|
241
165
|
|
242
166
|
{ref}: #myhead .myclass lang=fr
|
243
167
|
</code></pre>
|
244
|
-
|
245
168
|
<p>Of course, more than one IAL can reference the same ALD:</p>
|
246
|
-
|
247
169
|
<pre><code># Header 1 # {1}
|
248
170
|
...
|
249
171
|
# Header 2 # {1}
|
@@ -251,7 +173,6 @@ Blah blah blah.
|
|
251
173
|
{1}: .myclass lang=fr
|
252
174
|
|
253
175
|
</code></pre>
|
254
|
-
|
255
176
|
<h2 id='grammar'><span class='maruku_section_number'>5. </span>The rules</h2>
|
256
177
|
|
257
178
|
<h3 id='the_issue_of_escaping'><span class='maruku_section_number'>5.1. </span>The issue of escaping</h3>
|
@@ -300,18 +221,14 @@ Blah blah blah.
|
|
300
221
|
</li>
|
301
222
|
|
302
223
|
<li>
|
303
|
-
<p>There is an exception for backward compatibility
|
304
|
-
|
305
|
-
<pre><code>[text](url "title"with"quotes")</code></pre>
|
306
|
-
</li>
|
224
|
+
<p>There is an exception for backward compatibility:</p>
|
225
|
+
<pre><code>[text](url "title"with"quotes")</code></pre></li>
|
307
226
|
</ol>
|
308
227
|
|
309
228
|
<h3 id='syntax_for_attribute_lists'><span class='maruku_section_number'>5.2. </span>Syntax for attribute lists</h3>
|
310
229
|
|
311
230
|
<p>Consider the following attribute list:</p>
|
312
|
-
|
313
231
|
<pre><code>{key=value ref key2="quoted value" }</code></pre>
|
314
|
-
|
315
232
|
<p>In this string, <code>key</code>, <code>value</code>, and <code>ref</code> can be substituted by any string that does not contain whitespace, or the unescaped characters <code>}</code>,<code>=</code>,<code>'</code>,<code>"</code>.</p>
|
316
233
|
|
317
234
|
<p>Inside a quoted value, you <strong>may</strong> use <code>}</code>,<code>=</code> unescaped but you <strong>must</strong> escape the other kind of quote.</p>
|
@@ -323,17 +240,13 @@ Blah blah blah.
|
|
323
240
|
<p>A syntax for creating <code>SPAN</code> elements in the paragraphs and setting their attributes.</p>
|
324
241
|
|
325
242
|
<p>This is my proposal:</p>
|
326
|
-
|
327
243
|
<pre><code>a long paragraph with [special words]{#myspan} that I want to
|
328
244
|
highlight
|
329
245
|
</code></pre>
|
330
|
-
|
331
246
|
<p>should originate the following HTML:</p>
|
332
|
-
|
333
247
|
<pre><code><p>a long paragraph with <span id="myspan">special words</span>
|
334
248
|
that I want to highlight</p>
|
335
249
|
</code></pre>
|
336
|
-
|
337
250
|
<p><strong><em>Note: I changed the old <code>{special words}{#myspan}</code> with <code>[special words]{#myspan}</code> which is less ambiguous.</em></strong></p>
|
338
251
|
</li>
|
339
252
|
|
@@ -347,7 +260,6 @@ highlight
|
|
347
260
|
|
348
261
|
<li>
|
349
262
|
<p><strong>Default ALD for classes of elements.</strong> For example, an header of level 2 inherits automatically the attributes of <code>{header2}</code>, if it is defined.</p>
|
350
|
-
|
351
263
|
<pre><code>## Header ##
|
352
264
|
|
353
265
|
Paragraph..
|
@@ -357,8 +269,7 @@ Paragraph..
|
|
357
269
|
Paragraph..
|
358
270
|
|
359
271
|
{header2}: .myclass
|
360
|
-
{paragraph}: .withmargins</code></pre>
|
361
|
-
</li>
|
272
|
+
{paragraph}: .withmargins</code></pre></li>
|
362
273
|
</ul>
|
363
274
|
|
364
275
|
<p>In this example:</p>
|
@@ -390,8 +301,4 @@ Paragraph..
|
|
390
301
|
</blockquote>
|
391
302
|
</li>
|
392
303
|
</ul>
|
393
|
-
|
394
|
-
<div class='maruku_signature'>
|
395
|
-
<hr />
|
396
|
-
<span style='font-size: small; font-style: italic'>Created by <a href='http://maruku.rubyforge.org' title='Maruku: a Markdown interpreter'>Maruku</a> at 00:21 on Wednesday, January 03rd, 2007.</span></div>
|
397
|
-
</body></html>
|
304
|
+
<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'>Maruku</a> at 20:29 on Saturday, January 06th, 2007.</span></div></body></html>
|