maruku 0.3.0 → 0.4.0
Sign up to get free protection for your applications and to get access to all the features.
- 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 ![Alt text](url "fresh carrots")
|
217
145
|
</code></pre>
|
218
|
-
|
219
146
|
<p>is equivalent to:</p>
|
220
|
-
|
221
147
|
<pre><code>This is ![Alt text](url){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>
|