maruku 0.4.1 → 0.4.2
Sign up to get free protection for your applications and to get access to all the features.
- 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
|
+
![MaRuKu](logo.png){#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 ![Alt text](url "fresh carrots")
|
145
183
|
</code></pre>
|
146
184
|
<p>is equivalent to:</p>
|
147
|
-
<pre><code>This is ![Alt text](url){title="fresh carrots"}
|
185
|
+
<pre><code>This is ![Alt text](url){: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>
|