maruku 0.4.1 → 0.4.2
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 +41 -25
- data/docs/char.html +1924 -0
- data/docs/entity_test.html +2 -2
- data/docs/exd.html +92 -0
- data/docs/index.html +77 -23
- data/docs/markdown_syntax.html +6 -6
- data/docs/maruku.html +75 -21
- data/docs/maruku.md +60 -26
- data/docs/proposal.html +105 -123
- data/docs/proposal.md +121 -109
- data/lib/maruku/attributes.rb +33 -1
- data/lib/maruku/defaults.rb +8 -0
- data/lib/maruku/input/charsource.rb +8 -2
- data/lib/maruku/input/parse_block.rb +44 -18
- data/lib/maruku/input/parse_doc.rb +28 -26
- data/lib/maruku/input/parse_span_better.rb +57 -41
- data/lib/maruku/input/type_detection.rb +3 -2
- data/lib/maruku/output/to_html.rb +6 -6
- data/lib/maruku/output/to_latex.rb +21 -5
- data/lib/maruku/structures.rb +0 -4
- data/lib/maruku/tests/new_parser.rb +6 -1
- data/lib/maruku/version.rb +1 -1
- data/tests/unittest/attributes/att2.md +36 -0
- data/tests/unittest/attributes/att3.md +55 -0
- data/tests/unittest/attributes/attributes.md +23 -18
- data/tests/unittest/attributes/circular.md +9 -9
- data/tests/unittest/email.md +2 -2
- data/tests/unittest/links.md +2 -2
- data/tests/unittest/misc_sw.md +1 -1
- data/tests/unittest/syntax_hl.md +3 -5
- data/tests/unittest/xml_instruction.md +1 -2
- metadata +6 -2
data/docs/maruku.md
CHANGED
@@ -4,13 +4,22 @@ HTML use syntax: true
|
|
4
4
|
LaTeX use listings: true
|
5
5
|
LaTeX CJK: true
|
6
6
|
|
7
|
-
|
7
|
+
{#logo}
|
8
8
|
|
9
9
|
Mar**u**k**u**: a Markdown-superset interpreter
|
10
10
|
===============================================
|
11
11
|
|
12
12
|
[Maruku][] is a Markdown interpreter written in [Ruby][].
|
13
13
|
|
14
|
+
> [Last release](#release_notes) is version 0.4.2 -- 2007-01-12.
|
15
|
+
>
|
16
|
+
> Use this command to update:
|
17
|
+
>
|
18
|
+
> $ gem update maruku
|
19
|
+
{#news}
|
20
|
+
|
21
|
+
* * *
|
22
|
+
|
14
23
|
Maruku allows you to write in an easy-to-read-and-write syntax, like this:
|
15
24
|
|
16
25
|
> [This document in Markdown][this_md]
|
@@ -59,14 +68,14 @@ is Japanese, and also the sillable "ru" appears in Maruku.
|
|
59
68
|
Table of contents: (**auto-generated by Maruku!**)
|
60
69
|
|
61
70
|
* This list will contain the toc (it doesn't matter what you write here)
|
62
|
-
{toc}
|
71
|
+
{:toc}
|
63
72
|
|
64
73
|
* * *
|
65
74
|
|
66
|
-
{ruby
|
67
|
-
{shell
|
68
|
-
{markdown
|
69
|
-
|
75
|
+
{:ruby: lang=ruby code_background_color='#efffef'}
|
76
|
+
{:shell: lang=sh code_background_color='#efefff'}
|
77
|
+
{:markdown: code_background_color='#ffefef'}
|
78
|
+
{:html: lang=html}
|
70
79
|
|
71
80
|
|
72
81
|
Release notes {#release_notes}
|
@@ -83,6 +92,31 @@ please write to the [Markdown-discuss mailing list][markdown-discuss].
|
|
83
92
|
|
84
93
|
Have fun!
|
85
94
|
|
95
|
+
|
96
|
+
#### Changes in 0.4.2 #### {#last}
|
97
|
+
|
98
|
+
* Adapted syntax to the [new meta-data proposal][proposal].
|
99
|
+
|
100
|
+
* Changes in LaTeX export:
|
101
|
+
|
102
|
+
* Links to external URLs are blue by default.
|
103
|
+
|
104
|
+
* New attributes: `latex_preamble` to add a custom preamble,
|
105
|
+
and `latex_cjk` to add packages for UTF-8 Japanese characters.
|
106
|
+
(**support for this is still shaky**). Example:
|
107
|
+
|
108
|
+
Title: my document
|
109
|
+
LaTeX CJK: true
|
110
|
+
LaTeX preamble: preamble.tex
|
111
|
+
|
112
|
+
Content
|
113
|
+
|
114
|
+
* Bug fixes
|
115
|
+
|
116
|
+
+ Images were not given `id` or `class` attributes.
|
117
|
+
|
118
|
+
+ Fixed bug in LaTeX export with handling of `<`,`>` enclosed URLs: `<google.com>`.
|
119
|
+
|
86
120
|
#### Changes in 0.4.1 aka "Typographer" ####
|
87
121
|
|
88
122
|
* Implemented SmartyPants support:
|
@@ -204,7 +238,7 @@ Install with:
|
|
204
238
|
|
205
239
|
$ gem install maruku
|
206
240
|
|
207
|
-
{shell}
|
241
|
+
{:shell}
|
208
242
|
|
209
243
|
Released files can also be seen at <http://rubyforge.org/frs/?group_id=2795>.
|
210
244
|
|
@@ -212,7 +246,7 @@ Anonymous access to the repository is possible with:
|
|
212
246
|
|
213
247
|
$ svn checkout svn://rubyforge.org/var/svn/maruku
|
214
248
|
|
215
|
-
{shell}
|
249
|
+
{:shell}
|
216
250
|
|
217
251
|
If you want commit access to the repository, just create an account on Rubyforge and [drop me a mail][drop].
|
218
252
|
|
@@ -236,19 +270,19 @@ This is the basic usage:
|
|
236
270
|
doc = Maruku.new(markdown_string)
|
237
271
|
puts doc.to_html
|
238
272
|
|
239
|
-
{ruby}
|
273
|
+
{:ruby}
|
240
274
|
|
241
275
|
The method `to_html` outputs only an HTML fragment, while the method `to_html_document` outputs a complete XHTML 1.0 document:
|
242
276
|
|
243
277
|
puts doc.to_html_document
|
244
278
|
|
245
|
-
{ruby}
|
279
|
+
{:ruby}
|
246
280
|
|
247
281
|
You can have the REXML document tree with:
|
248
282
|
|
249
283
|
tree = doc.to_html_document_tree
|
250
284
|
|
251
|
-
{ruby}
|
285
|
+
{:ruby}
|
252
286
|
|
253
287
|
### From the command line ###
|
254
288
|
|
@@ -257,13 +291,13 @@ There are two command-line programs installed: `maruku` and `marutex`.
|
|
257
291
|
* `maruku` converts Markdown to HTML:
|
258
292
|
|
259
293
|
$ maruku file.md # creates file.html
|
260
|
-
{shell}
|
294
|
+
{:shell}
|
261
295
|
|
262
296
|
* `marutex` converts Markdown to LaTeX, then calls `pdflatex` to
|
263
297
|
transform to PDF:
|
264
298
|
|
265
299
|
$ marutex file.md # creates file.tex and file.pdf
|
266
|
-
{shell}
|
300
|
+
{:shell}
|
267
301
|
|
268
302
|
|
269
303
|
Examples of PHP Markdown Extra syntax {#extra}
|
@@ -274,7 +308,7 @@ Examples of PHP Markdown Extra syntax {#extra}
|
|
274
308
|
Col1 | Very very long head | Very very long head|
|
275
309
|
-----|:-------------------:|-------------------:|
|
276
310
|
cell | center-align | right-align |
|
277
|
-
{markdown}
|
311
|
+
{:markdown}
|
278
312
|
|
279
313
|
Col1 | Very very long head | Very very long head|
|
280
314
|
-----|:-------------------:|-------------------:|
|
@@ -286,7 +320,7 @@ Examples of PHP Markdown Extra syntax {#extra}
|
|
286
320
|
* footnotes [^foot]
|
287
321
|
|
288
322
|
[^foot]: I really was missing those.
|
289
|
-
{markdown}
|
323
|
+
{:markdown}
|
290
324
|
|
291
325
|
[^foot]: I really was missing those.
|
292
326
|
|
@@ -295,7 +329,7 @@ Examples of PHP Markdown Extra syntax {#extra}
|
|
295
329
|
<div markdown="1" style="border: solid 1px black">
|
296
330
|
This is a div with Markdown **strong text**
|
297
331
|
</div>
|
298
|
-
|
332
|
+
{:html}
|
299
333
|
|
300
334
|
<div markdown="1" style="border: solid 1px black">
|
301
335
|
This is a div with Markdown **strong text**
|
@@ -305,7 +339,7 @@ Examples of PHP Markdown Extra syntax {#extra}
|
|
305
339
|
* header ids
|
306
340
|
|
307
341
|
## Download ## {#download}
|
308
|
-
{markdown}
|
342
|
+
{:markdown}
|
309
343
|
|
310
344
|
For example, [a link to the download](#download) header.
|
311
345
|
|
@@ -314,7 +348,7 @@ Examples of PHP Markdown Extra syntax {#extra}
|
|
314
348
|
|
315
349
|
Definition list
|
316
350
|
: something very hard to parse
|
317
|
-
{markdown}
|
351
|
+
{:markdown}
|
318
352
|
|
319
353
|
Definition list
|
320
354
|
: something very hard to parse
|
@@ -373,13 +407,13 @@ of email headers:
|
|
373
407
|
|
374
408
|
Content of the document
|
375
409
|
|
376
|
-
{markdown}
|
410
|
+
{:markdown}
|
377
411
|
|
378
412
|
When creating the document through
|
379
413
|
|
380
414
|
Maruku.new(s).to_html_document
|
381
415
|
|
382
|
-
{ruby}
|
416
|
+
{:ruby}
|
383
417
|
|
384
418
|
the title and stylesheet are added as expected.
|
385
419
|
|
@@ -451,8 +485,8 @@ An example of this is the following:
|
|
451
485
|
Two spaces
|
452
486
|
Tab, space, tab
|
453
487
|
Tab, tab, tab and all is green!
|
454
|
-
{code_show_spaces code_background_color=#ffeedd}
|
455
|
-
{markdown}
|
488
|
+
{:code_show_spaces code_background_color=#ffeedd}
|
489
|
+
{:markdown}
|
456
490
|
|
457
491
|
That will produce:
|
458
492
|
|
@@ -460,18 +494,18 @@ That will produce:
|
|
460
494
|
Two spaces
|
461
495
|
Tab, space, tab
|
462
496
|
Tab, tab, tab and all is green!
|
463
|
-
{code_show_spaces code_background_color=#ffeedd}
|
497
|
+
{:code_show_spaces code_background_color=#ffeedd}
|
464
498
|
|
465
499
|
|
466
500
|
Or highlighting (support depends on languages):
|
467
501
|
|
468
502
|
<div style="text-align:center">Div</div>
|
469
|
-
{lang=html}
|
503
|
+
{:lang=html}
|
470
504
|
|
471
505
|
produces:
|
472
506
|
|
473
507
|
<div style="text-align:center">Div</div>
|
474
|
-
{lang=html}
|
508
|
+
{:lang=html}
|
475
509
|
|
476
510
|
|
477
511
|
|
@@ -486,7 +520,7 @@ If you create a list, and then set the `toc` attribute, when rendering
|
|
486
520
|
Maruku will create an auto-generated table of contents.
|
487
521
|
|
488
522
|
* This will become a table of contents (this text will be scraped).
|
489
|
-
{toc}
|
523
|
+
{:toc}
|
490
524
|
|
491
525
|
You can see an example of this at the beginning of this document.
|
492
526
|
|
data/docs/proposal.html
CHANGED
@@ -6,11 +6,49 @@
|
|
6
6
|
|
7
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>
|
8
8
|
|
9
|
-
<p>
|
9
|
+
<p><strong><em>Note: this is an evolving proposal</em></strong></p>
|
10
|
+
|
11
|
+
<p>Last updated <strong>January 10th, 2007</strong>:</p>
|
12
|
+
|
13
|
+
<ul>
|
14
|
+
<li>
|
15
|
+
<p>Changed the syntax for compatibility with a future extension mechanism.</p>
|
16
|
+
|
17
|
+
<p>The first character in the curly braces must be a colon, optionally followed by a space:</p>
|
18
|
+
<pre><code>{: ref .class #id}
|
19
|
+
</code></pre>
|
20
|
+
<p>The old syntax was <code>{ref .class #id}</code>.</p>
|
21
|
+
|
22
|
+
<p>For ALDs, the new syntax is:</p>
|
23
|
+
<pre><code>{:ref_id: key=val .class #id }
|
24
|
+
</code></pre>
|
25
|
+
<p>instead of:</p>
|
26
|
+
<pre><code>{ref_id}: key=val .class #id
|
27
|
+
</code></pre>
|
28
|
+
<p>Converters that don’t use this syntax may just ignore everything which is in curly braces and starts with ”:”.</p>
|
29
|
+
</li>
|
30
|
+
|
31
|
+
<li>
|
32
|
+
<p>IAL can be put both <em>before</em> and <em>after</em> the element. There is no ambiguity as a blank line is needed between elements:</p>
|
33
|
+
<pre><code>Paragraph 1
|
34
|
+
|
35
|
+
{:par2}
|
36
|
+
Paragraph 2
|
37
|
+
</code></pre>
|
38
|
+
<p>is equivalent to:</p>
|
39
|
+
<pre><code>Paragraph 1
|
40
|
+
|
41
|
+
Paragraph 2
|
42
|
+
{:par2}</code></pre></li>
|
43
|
+
|
44
|
+
<li>
|
45
|
+
<p>Simplified rules for escaping.</p>
|
46
|
+
</li>
|
47
|
+
</ul>
|
10
48
|
|
11
49
|
<p><em>Table of contents:</em></p>
|
12
50
|
|
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='#
|
51
|
+
<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='#the_rules'>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></ul></div></blockquote>
|
14
52
|
|
15
53
|
<h2 id='overview'><span class='maruku_section_number'>1. </span>Overview</h2>
|
16
54
|
|
@@ -19,35 +57,35 @@
|
|
19
57
|
<ol>
|
20
58
|
<li>
|
21
59
|
<p>inline attribute lists (IAL)</p>
|
22
|
-
<pre><code>## Header ## {key=val .class #id ref_id}</code></pre></li>
|
60
|
+
<pre><code>## Header ## {: key=val .class #id ref_id}</code></pre></li>
|
23
61
|
|
24
62
|
<li>
|
25
63
|
<p>attribute lists definitions (ALD)</p>
|
26
|
-
<pre><code>{ref_id
|
64
|
+
<pre><code>{:ref_id: key=val .class #id}</code></pre></li>
|
27
65
|
</ol>
|
28
66
|
|
29
67
|
<p>Every span-level or block-level element can be followed by an IAL:</p>
|
30
|
-
<pre><code>### Header ### {#header1 class=c1}
|
68
|
+
<pre><code>### Header ### {: #header1 class=c1}
|
31
69
|
|
32
|
-
Paragraph *with emphasis*{class=c1}
|
70
|
+
Paragraph *with emphasis*{: class=c1}
|
33
71
|
second line of paragraph
|
34
|
-
{class=c1}
|
72
|
+
{: class=c1}
|
35
73
|
</code></pre>
|
36
74
|
<p>In this example, the three IALs refer to the header, the emphasis span, and the entire paragraph, respectively.</p>
|
37
75
|
|
38
76
|
<p>IALs can reference ALDs. The result of the following example is the same as the previous one:</p>
|
39
|
-
<pre><code>### Header ### {#header1 c1}
|
77
|
+
<pre><code>### Header ### {: #header1 c1}
|
40
78
|
|
41
|
-
Paragraph *with emphasis*{c1}
|
79
|
+
Paragraph *with emphasis*{:c1}
|
42
80
|
second line of paragraph
|
43
|
-
{c1}
|
81
|
+
{:c1}
|
44
82
|
|
45
|
-
{c1
|
83
|
+
{:c1: class=c1}
|
46
84
|
</code></pre>
|
47
85
|
<h2 id='attribute_lists'><span class='maruku_section_number'>2. </span>Attribute lists</h2>
|
48
86
|
|
49
87
|
<p>This is an example attribute list, which shows everything you can put inside:</p>
|
50
|
-
<pre><code>key1=val key2="long val" #myid .class1 .class2 ref1 ref2
|
88
|
+
<pre><code>{: key1=val key2="long val" #myid .class1 .class2 ref1 ref2}
|
51
89
|
</code></pre>
|
52
90
|
<p>More in particular, an attribute list is a whitespace-separated list of elements of 4 different kinds:</p>
|
53
91
|
|
@@ -74,15 +112,15 @@ second line of paragraph
|
|
74
112
|
<p><code>.myclass</code> means “add <code>myclass</code> to the current <code>class</code> attribute”.</p>
|
75
113
|
|
76
114
|
<p>So these are equivalent:</p>
|
77
|
-
<pre><code>{.class1 .class2}
|
78
|
-
{class="class1 class2"}</code></pre></li>
|
115
|
+
<pre><code>{: .class1 .class2}
|
116
|
+
{: class="class1 class2"}</code></pre></li>
|
79
117
|
</ul>
|
80
118
|
|
81
119
|
<p>The following attribute lists are equivalent:</p>
|
82
|
-
<pre><code>{#myid .class1 .class2}
|
83
|
-
{id=myid class=class1 .class2}
|
84
|
-
{id=myid class="class1 class2"}
|
85
|
-
{id=myid class="will be overridden" class=class1 .class2}
|
120
|
+
<pre><code>{: #myid .class1 .class2}
|
121
|
+
{: id=myid class=class1 .class2}
|
122
|
+
{: id=myid class="class1 class2"}
|
123
|
+
{: id=myid class="will be overridden" class=class1 .class2}
|
86
124
|
</code></pre>
|
87
125
|
<h2 id='where_to_put_inline_attribute_lists'><span class='maruku_section_number'>3. </span>Where to put inline attribute lists</h2>
|
88
126
|
|
@@ -91,60 +129,60 @@ second line of paragraph
|
|
91
129
|
<p>For paragraphs and other block-level elements, IAL go <strong>after</strong> the element:</p>
|
92
130
|
<pre><code>This is a paragraph.
|
93
131
|
Line 2 of the paragraph.
|
94
|
-
{#myid .myclass}
|
132
|
+
{: #myid .myclass}
|
95
133
|
|
96
134
|
A quote with a citation url:
|
97
135
|
> Who said that?
|
98
|
-
{cite=google.com}
|
136
|
+
{: cite=google.com}
|
99
137
|
</code></pre>
|
100
|
-
<p>Note: empty lines between the block and the IAL are not
|
138
|
+
<p>Note: empty lines between the block and the IAL are not tolerated. So this is not legal:</p>
|
101
139
|
<pre><code>This is a paragraph.
|
102
140
|
Line 2 of the paragraph.
|
103
141
|
|
104
|
-
{#myid .myclass}
|
142
|
+
{: #myid .myclass}
|
105
143
|
</code></pre>
|
106
144
|
<p>Attribute lists may be indented up to 3 spaces:</p>
|
107
145
|
<pre><code>Paragraph1
|
108
|
-
¬{ok}
|
146
|
+
¬{:ok}
|
109
147
|
|
110
148
|
Paragraph2
|
111
|
-
¬¬{ok}
|
149
|
+
¬¬{:ok}
|
112
150
|
|
113
151
|
Paragraph2
|
114
|
-
¬¬¬{ok}</code></pre>
|
152
|
+
¬¬¬{:ok}</code></pre>
|
115
153
|
<h3 id='for_headers'><span class='maruku_section_number'>3.2. </span>For headers</h3>
|
116
154
|
|
117
155
|
<p>For headers, you can put attribute lists on the same line:</p>
|
118
|
-
<pre><code>### Header ### {#myid}
|
156
|
+
<pre><code>### Header ### {: #myid}
|
119
157
|
|
120
|
-
Header {#myid .myclass}
|
158
|
+
Header {: #myid .myclass}
|
121
159
|
------
|
122
160
|
</code></pre>
|
123
161
|
<p>or, as like other block-level elements, on the line below:</p>
|
124
162
|
<pre><code>### Header ###
|
125
|
-
{#myid}
|
163
|
+
{: #myid}
|
126
164
|
|
127
165
|
Header
|
128
166
|
------
|
129
|
-
{#myid .myclass}
|
167
|
+
{: #myid .myclass}
|
130
168
|
</code></pre>
|
131
169
|
<h3 id='for_spanlevel_elements'><span class='maruku_section_number'>3.3. </span>For span-level elements</h3>
|
132
170
|
|
133
171
|
<p>For span-level elements, meta-data goes immediately <strong>after</strong> in the flow.</p>
|
134
172
|
|
135
173
|
<p>For example, in this:</p>
|
136
|
-
<pre><code>This is a *chunky paragraph*{#id1}
|
137
|
-
{#id2}</code></pre>
|
174
|
+
<pre><code>This is a *chunky paragraph*{: #id1}
|
175
|
+
{: #id2}</code></pre>
|
138
176
|
<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>
|
139
177
|
|
140
178
|
<p>This works also for links, like this:</p>
|
141
|
-
<pre><code>This is [a link][ref]{
|
179
|
+
<pre><code>This is [a link][ref]{:#myid rel=abc rev=abc}
|
142
180
|
</code></pre>
|
143
181
|
<p>For images, this:</p>
|
144
182
|
<pre><code>This is 
|
145
183
|
</code></pre>
|
146
184
|
<p>is equivalent to:</p>
|
147
|
-
<pre><code>This is {title="fresh carrots"}
|
185
|
+
<pre><code>This is {:title="fresh carrots"}
|
148
186
|
</code></pre>
|
149
187
|
<h2 id='using_tags'><span class='maruku_section_number'>4. </span>Using attributes lists definition</h2>
|
150
188
|
|
@@ -159,47 +197,37 @@ Header
|
|
159
197
|
</ol>
|
160
198
|
|
161
199
|
<p>Everything else is interpreted as a reference to an ALD.</p>
|
162
|
-
<pre><code># Header # {ref}
|
200
|
+
<pre><code># Header # {:ref}
|
163
201
|
|
164
202
|
Blah blah blah.
|
165
203
|
|
166
|
-
{ref
|
204
|
+
{:ref: #myhead .myclass lang=fr}
|
167
205
|
</code></pre>
|
168
206
|
<p>Of course, more than one IAL can reference the same ALD:</p>
|
169
|
-
<pre><code># Header 1 # {1}
|
207
|
+
<pre><code># Header 1 # {:1}
|
170
208
|
...
|
171
|
-
# Header 2 # {1}
|
209
|
+
# Header 2 # {:1}
|
172
210
|
|
173
|
-
{1
|
211
|
+
{:1: .myclass lang=fr}
|
174
212
|
|
175
213
|
</code></pre>
|
176
|
-
<h2 id='
|
214
|
+
<h2 id='the_rules'><span class='maruku_section_number'>5. </span>The rules</h2>
|
177
215
|
|
178
216
|
<h3 id='the_issue_of_escaping'><span class='maruku_section_number'>5.1. </span>The issue of escaping</h3>
|
179
217
|
|
180
218
|
<ol>
|
181
219
|
<li>
|
182
|
-
<p>No escaping in code blocks.</p>
|
183
|
-
|
184
|
-
<ul>
|
185
|
-
<li><code>`\`</code> represents the one-character string <code>\</code>.</li>
|
186
|
-
</ul>
|
220
|
+
<p>No escaping in code spans/blocks.</p>
|
187
221
|
</li>
|
188
222
|
|
189
223
|
<li>
|
190
|
-
<p>Everywhere else, <strong>all</strong> characters <strong>can</strong> be escaped
|
191
|
-
|
192
|
-
<ul>
|
193
|
-
<li><code>\|</code> is the literal <code>|</code>, <code>\n</code> is the literal <code>n</code>.</li>
|
194
|
-
|
195
|
-
<li><code>\ </code> represents a non-breaking space.</li>
|
224
|
+
<p>Everywhere else, <strong>all</strong> PUNCTUATION characters <strong>can</strong> be escaped, and <strong>must</strong> be escaped when they could trigger links, tables, etc</p>
|
196
225
|
|
197
|
-
<
|
198
|
-
</ul>
|
226
|
+
<p>A punctuation character is anything not a letter, a number, or whitespace (<code>[^a-zA-Z0-9\s\n]</code>).</p>
|
199
227
|
</li>
|
200
228
|
|
201
229
|
<li>
|
202
|
-
<p>
|
230
|
+
<p>As a rule, quotes <strong>must</strong> be escaped inside quoted values:</p>
|
203
231
|
|
204
232
|
<ul>
|
205
233
|
<li>
|
@@ -212,93 +240,47 @@ Blah blah blah.
|
|
212
240
|
|
213
241
|
<li>
|
214
242
|
<p>Other examples:</p>
|
243
|
+
</li>
|
244
|
+
</ul>
|
215
245
|
|
216
246
|
<p><code>"bah 'bah' bah"</code> = <code>"bah \'bah\' bah"</code> = <code>'bah \'bah\' bah'</code></p>
|
217
247
|
|
218
248
|
<p><code>'bah "bah" bah'</code> = <code>'bah \"bah\" bah'</code> = <code>"bah \"bah\" bah"</code></p>
|
219
249
|
</li>
|
220
|
-
</ul>
|
221
|
-
</li>
|
222
250
|
|
223
251
|
<li>
|
224
|
-
<p>There is an exception for backward compatibility:</p>
|
225
|
-
<pre><code>[text](url "title"with"quotes")
|
252
|
+
<p>There is an exception for backward compatibility, in links/images titles:</p>
|
253
|
+
<pre><code>[text](url "title"with"quotes")
|
254
|
+
</code></pre>
|
255
|
+
<p>The exception is not valid for attribute lists and in other contexts, where you have to use the canonical syntax.</p>
|
256
|
+
</li>
|
226
257
|
</ol>
|
227
258
|
|
228
259
|
<h3 id='syntax_for_attribute_lists'><span class='maruku_section_number'>5.2. </span>Syntax for attribute lists</h3>
|
229
260
|
|
230
261
|
<p>Consider the following attribute list:</p>
|
231
|
-
<pre><code>{key=value ref key2="quoted value" }</code></pre>
|
262
|
+
<pre><code>{: key=value ref key2="quoted value" }</code></pre>
|
232
263
|
<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>
|
233
264
|
|
234
|
-
<p>Inside a quoted value
|
235
|
-
|
236
|
-
<h2 id='things_to_discuss'><span class='maruku_section_number'>6. </span>Things to discuss</h2>
|
237
|
-
|
238
|
-
<ul>
|
239
|
-
<li>
|
240
|
-
<p>A syntax for creating <code>SPAN</code> elements in the paragraphs and setting their attributes.</p>
|
241
|
-
|
242
|
-
<p>This is my proposal:</p>
|
243
|
-
<pre><code>a long paragraph with [special words]{#myspan} that I want to
|
244
|
-
highlight
|
245
|
-
</code></pre>
|
246
|
-
<p>should originate the following HTML:</p>
|
247
|
-
<pre><code><p>a long paragraph with <span id="myspan">special words</span>
|
248
|
-
that I want to highlight</p>
|
249
|
-
</code></pre>
|
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>
|
251
|
-
</li>
|
252
|
-
|
253
|
-
<li>
|
254
|
-
<blockquote>
|
255
|
-
<p>Another question: does it makes sense to define <code><span></code> within Markdown when you can’t have <code><b></code> and <code><i></code>, or the more meaningful <code><cite></code>, <code><q></code>, <code><dfn></code>, and <code><var></code>? We have to draw the line somewhere, where should it be? Another good question for the list.</p>
|
256
|
-
</blockquote>
|
257
|
-
|
258
|
-
<p>Any opinion?</p>
|
259
|
-
</li>
|
260
|
-
|
261
|
-
<li>
|
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>
|
263
|
-
<pre><code>## Header ##
|
264
|
-
|
265
|
-
Paragraph..
|
265
|
+
<p>Inside a quoted value you <strong>must</strong> escape the other kind of quote.</p>
|
266
266
|
|
267
|
-
|
267
|
+
<p>Also, you <strong>must</strong> escape a closing curly brace <code>}</code> inside quoted values. This rule is for making life easier for interpreter that just want to skip the meta-data.</p>
|
268
268
|
|
269
|
-
|
269
|
+
<p>If you don’t implement this syntax, you can get rid of the IAL by using this regular expression (this is written in Ruby):</p>
|
270
|
+
<pre><code>r = /\{:(\\\}|[^\}])*\}/
|
270
271
|
|
271
|
-
|
272
|
-
{
|
273
|
-
</ul>
|
274
|
-
|
275
|
-
<p>In this example:</p>
|
276
|
-
|
277
|
-
<ul>
|
278
|
-
<li>the first header has attributes <code>class=myclass</code></li>
|
279
|
-
|
280
|
-
<li>the second header has attributes <code>class="myclass mah"</code></li>
|
281
|
-
|
282
|
-
<li>the two paragraphs have attributes <code>class=withmargins</code></li>
|
283
|
-
</ul>
|
284
|
-
|
285
|
-
<h2 id='design_rationale'><span class='maruku_section_number'>7. </span>Design rationale</h2>
|
272
|
+
s.gsub(r, '') # ignore metadata</code></pre>
|
273
|
+
<p>Basically: match everything contained in a couple of <code>{:</code> and <code>}</code>, taking care of escaping of <code>}</code>. This <code>\\\}|[^\}]</code> means: eat either any character which is not a <code>}</code> or an escape sequence <code>\}</code>.</p>
|
286
274
|
|
287
|
-
<
|
288
|
-
<
|
289
|
-
|
290
|
-
|
291
|
-
<blockquote>
|
292
|
-
<p>No, because it is difficult to parse.</p>
|
293
|
-
</blockquote>
|
294
|
-
</li>
|
275
|
+
<p>For this example,</p>
|
276
|
+
<pre><code>this is
|
277
|
+
{: skipped="\}" val=\} bar}
|
295
278
|
|
296
|
-
|
297
|
-
|
279
|
+
for me
|
280
|
+
{: also this}
|
281
|
+
</code></pre>
|
282
|
+
<p>the result is:</p>
|
283
|
+
<pre><code>this is
|
284
|
+
|
298
285
|
|
299
|
-
<
|
300
|
-
<p>No, because ’:’ is used for XML namespaces (<code>xml:lang=en</code>)</p>
|
301
|
-
</blockquote>
|
302
|
-
</li>
|
303
|
-
</ul>
|
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 for Ruby'>Maruku</a> at 23:18 on Monday, January 08th, 2007.</span></div></body></html>
|
286
|
+
for me </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 13:45 on Thursday, January 11st, 2007.</span></div></body></html>
|