maruku 0.2.13 → 0.3.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/maruku +23 -15
- data/bin/maruku0.3 +37 -0
- data/bin/marutest +277 -0
- data/docs/changelog-0.3.html +99 -0
- data/docs/changelog-0.3.md +84 -0
- data/docs/faq.html +46 -0
- data/docs/faq.md +32 -0
- data/docs/index.html +629 -64
- data/docs/markdown_extra2.html +67 -14
- data/docs/markdown_syntax.html +631 -94
- data/docs/markdown_syntax_2.html +152 -0
- data/docs/maruku.html +629 -64
- data/docs/maruku.md +108 -105
- data/docs/proposal.html +362 -55
- data/docs/proposal.md +133 -169
- data/docs/todo.html +30 -0
- data/lib/maruku.rb +13 -3
- data/lib/maruku/errors_management.rb +75 -0
- data/lib/maruku/helpers.rb +164 -0
- data/lib/maruku/html_helper.rb +33 -13
- data/lib/maruku/parse_block.rb +89 -92
- data/lib/maruku/parse_doc.rb +43 -18
- data/lib/maruku/parse_span.rb +17 -46
- data/lib/maruku/parse_span_better.rb +681 -0
- data/lib/maruku/string_utils.rb +17 -10
- data/lib/maruku/structures.rb +62 -35
- data/lib/maruku/structures_iterators.rb +39 -0
- data/lib/maruku/tests/benchmark.rb +12 -4
- data/lib/maruku/tests/new_parser.rb +318 -0
- data/lib/maruku/to_html.rb +113 -44
- data/lib/maruku/to_latex.rb +32 -14
- data/lib/maruku/to_markdown.rb +110 -0
- data/lib/maruku/toc.rb +35 -1
- data/lib/maruku/version.rb +10 -1
- data/lib/test.rb +29 -0
- data/tests/others/escaping.md +6 -4
- data/tests/others/links.md +1 -1
- data/tests/others/lists_after_paragraph.md +44 -0
- data/tests/unittest/abbreviations.md +71 -0
- data/tests/unittest/blank.md +43 -0
- data/tests/unittest/blanks_in_code.md +131 -0
- data/tests/unittest/code.md +64 -0
- data/tests/unittest/code2.md +59 -0
- data/tests/unittest/code3.md +121 -0
- data/tests/unittest/easy.md +36 -0
- data/tests/unittest/email.md +39 -0
- data/tests/unittest/encoding/iso-8859-1.md +9 -0
- data/tests/unittest/encoding/utf-8.md +38 -0
- data/tests/unittest/entities.md +174 -0
- data/tests/unittest/escaping.md +97 -0
- data/tests/unittest/extra_dl.md +81 -0
- data/tests/unittest/extra_header_id.md +96 -0
- data/tests/unittest/extra_table1.md +78 -0
- data/tests/unittest/footnotes.md +120 -0
- data/tests/unittest/headers.md +64 -0
- data/tests/unittest/hrule.md +77 -0
- data/tests/unittest/images.md +114 -0
- data/tests/unittest/inline_html.md +185 -0
- data/tests/unittest/links.md +162 -0
- data/tests/unittest/list1.md +80 -0
- data/tests/unittest/list2.md +75 -0
- data/tests/unittest/list3.md +111 -0
- data/tests/unittest/list4.md +43 -0
- data/tests/unittest/lists.md +262 -0
- data/tests/unittest/lists_after_paragraph.md +280 -0
- data/tests/unittest/lists_ol.md +323 -0
- data/tests/unittest/misc_sw.md +751 -0
- data/tests/unittest/notyet/escape.md +46 -0
- data/tests/unittest/notyet/header_after_par.md +85 -0
- data/tests/unittest/notyet/ticks.md +67 -0
- data/tests/unittest/notyet/triggering.md +210 -0
- data/tests/unittest/one.md +33 -0
- data/tests/unittest/paragraph.md +34 -0
- data/tests/unittest/paragraph_rules/dont_merge_ref.md +60 -0
- data/tests/unittest/paragraph_rules/tab_is_blank.md +43 -0
- data/tests/unittest/paragraphs.md +84 -0
- data/tests/unittest/recover/recover_links.md +32 -0
- data/tests/unittest/references/long_example.md +87 -0
- data/tests/unittest/references/spaces_and_numbers.md +27 -0
- data/tests/unittest/syntax_hl.md +99 -0
- data/tests/unittest/test.md +36 -0
- data/tests/unittest/wrapping.md +88 -0
- data/tests/utf8-files/simple.md +1 -0
- metadata +139 -86
- data/lib/maruku/maruku.rb +0 -50
- data/tests/a.md +0 -10
data/docs/maruku.md
CHANGED
|
@@ -3,47 +3,51 @@ LaTeX_use_listings: true
|
|
|
3
3
|
html_use_syntax: true
|
|
4
4
|
use_numbered_headers: true
|
|
5
5
|
|
|
6
|
-
Mar**u**k**u**: a Markdown interpreter
|
|
7
|
-
|
|
6
|
+
Mar**u**k**u**: a Markdown-superset interpreter
|
|
7
|
+
===============================================
|
|
8
8
|
|
|
9
9
|
[Maruku][] is a Markdown interpreter written in [Ruby][].
|
|
10
10
|
|
|
11
|
-
[maruku]: <http://maruku.rubyforge.org/>
|
|
12
|
-
|
|
13
11
|
Maruku allows you to write in an easy-to-read-and-write syntax, like this:
|
|
14
12
|
|
|
15
|
-
> [This document in Markdown]
|
|
13
|
+
> [This document in Markdown][this_md]
|
|
16
14
|
|
|
17
15
|
Then it can be translated to HTML:
|
|
18
16
|
|
|
19
|
-
> [This document in HTML]
|
|
17
|
+
> [This document in HTML][this_html]
|
|
20
18
|
|
|
21
19
|
or LaTeX, which is then converted to PDF:
|
|
22
20
|
|
|
23
|
-
> [This document in PDF]
|
|
21
|
+
> [This document in PDF][this_pdf]
|
|
24
22
|
|
|
25
23
|
Maruku implements:
|
|
26
24
|
|
|
27
|
-
* the original [Markdown syntax][]
|
|
28
|
-
|
|
29
|
-
[PDF](http://maruku.rubyforge.org/markdown_syntax.pdf), translated by Maruku).
|
|
25
|
+
* the original [Markdown syntax][markdown_html] ([HTML][markdown_html] or
|
|
26
|
+
[PDF][markdown_pdf]), translated by Maruku).
|
|
30
27
|
|
|
31
28
|
* all the improvements in [PHP Markdown Extra][].
|
|
32
29
|
|
|
33
30
|
* a new [meta-data syntax](#meta)
|
|
34
31
|
|
|
35
|
-
* some ideas from [MultiMarkdown][]
|
|
36
|
-
* attributes in image links
|
|
37
32
|
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
[tests]: http://maruku.rubyforge.org/tests/
|
|
33
|
+
__Authors__: Maruku has been developed so far by [Andrea Censi][].
|
|
34
|
+
Contributors are most welcome!
|
|
41
35
|
|
|
42
|
-
|
|
36
|
+
__The name of the game__: Maruku is the [romaji][] translitteration of
|
|
37
|
+
the [katakana][] translitteration
|
|
38
|
+
of "Mark", the first word in Markdown. I chose this name because Ruby
|
|
39
|
+
is Japanese, and also the sillable "ru" appears in Maruku.
|
|
43
40
|
|
|
44
|
-
|
|
45
|
-
|
|
41
|
+
[romaji]: http://en.wikipedia.org/wiki/Romaji
|
|
42
|
+
[katakana]: http://en.wikipedia.org/wiki/Katakana
|
|
46
43
|
|
|
44
|
+
[tests]: http://maruku.rubyforge.org/tests/
|
|
45
|
+
[maruku]: <http://maruku.rubyforge.org/>
|
|
46
|
+
[markdown_html]: http://maruku.rubyforge.org/markdown_syntax.html
|
|
47
|
+
[markdown_pdf]: http://maruku.rubyforge.org/markdown_syntax.pdf
|
|
48
|
+
[this_md]: http://maruku.rubyforge.org/maruku.md
|
|
49
|
+
[this_html]: http://maruku.rubyforge.org/maruku.html
|
|
50
|
+
[this_pdf]: http://maruku.rubyforge.org/maruku.pdf
|
|
47
51
|
[Andrea Censi]: http://www.dis.uniroma1.it/~acensi/
|
|
48
52
|
|
|
49
53
|
* * *
|
|
@@ -56,7 +60,87 @@ Table of contents: (**auto-generated by Maruku!**)
|
|
|
56
60
|
|
|
57
61
|
* * *
|
|
58
62
|
|
|
59
|
-
|
|
63
|
+
Release notes - version 0.3.0 (January 3rd, 2007) {#release_notes}
|
|
64
|
+
-------------------------------------------------
|
|
65
|
+
|
|
66
|
+
Note: Maruku seems to be very robust, nevertheless it is still beta-level
|
|
67
|
+
software. So if you want to use it in production environments, please
|
|
68
|
+
check back in a month or so, while we squash the remaining bugs.
|
|
69
|
+
|
|
70
|
+
In the meantime, feel free to toy around, and please signal problems,
|
|
71
|
+
request features, by [contacting me][contact] or using the [tracker][tracker].
|
|
72
|
+
For issues about the Markdown syntax itself and improvements to it,
|
|
73
|
+
please write to the [Markdown-discuss mailing list][markdown-discuss].
|
|
74
|
+
|
|
75
|
+
Have fun!
|
|
76
|
+
|
|
77
|
+
Changes in 0.3.0:
|
|
78
|
+
|
|
79
|
+
* A real parser is used instead of a regexp-based system, also for span-level
|
|
80
|
+
elements.
|
|
81
|
+
|
|
82
|
+
Now Maruku is almost 2x faster than Bluecloth, while having more features.
|
|
83
|
+
|
|
84
|
+
Here are some benchmarks:
|
|
85
|
+
|
|
86
|
+
BlueCloth (to_html): parsing 0.00 sec + rendering 1.54 sec = 1.55 sec
|
|
87
|
+
Maruku (to_html): parsing 0.47 sec + rendering 0.38 sec = 0.85 sec
|
|
88
|
+
Maruku (to_latex): parsing 0.49 sec + rendering 0.25 sec = 0.73 sec
|
|
89
|
+
|
|
90
|
+
This is the result of running `lib/maruku/tests/benchmark.rb` on the Markdown
|
|
91
|
+
specification.
|
|
92
|
+
|
|
93
|
+
* Prettier HTML output by adding whitespace.
|
|
94
|
+
|
|
95
|
+
* Added a full suite of unit-tests for the span-level parser.
|
|
96
|
+
|
|
97
|
+
* Error management: Having a real parser, Maruku warns you about syntax issues.
|
|
98
|
+
|
|
99
|
+
The default action is to warn and try to continue. If you do this:
|
|
100
|
+
|
|
101
|
+
Maruku.new(string, {:on_error => :raise})
|
|
102
|
+
|
|
103
|
+
then syntax errors will cause an exception to be raised (you can catch this
|
|
104
|
+
and retry).
|
|
105
|
+
|
|
106
|
+
* Fixed a series of bugs in handling inline HTML code.
|
|
107
|
+
|
|
108
|
+
Immediate TODO-list:
|
|
109
|
+
|
|
110
|
+
* UTF-8 input/output works OK for HTML, however I am having pain trying to export
|
|
111
|
+
to LaTeX. I want at least Japanese characters support, so if you know how to
|
|
112
|
+
do this you are very welcome to give me an hand.
|
|
113
|
+
|
|
114
|
+
For example: in the HTML version, you should see accented characters in this
|
|
115
|
+
parenthesis:
|
|
116
|
+
|
|
117
|
+
> (àèìòù)
|
|
118
|
+
|
|
119
|
+
and Japanese text in these other parentheses:
|
|
120
|
+
|
|
121
|
+
> (カタカナで 私の 名前は アンドレア チェンシ です).
|
|
122
|
+
>
|
|
123
|
+
> (日本のガルは 大好き、でも、日本語は難しですから、そうぞ 英語話すガルを おしえてください).
|
|
124
|
+
|
|
125
|
+
In the LaTeX version, these do not appear. I know how to do LaTeX with
|
|
126
|
+
ISO-8859-1 encoding (European characters), but I'm struggling with half-baked
|
|
127
|
+
solutions for UTF-8 encoded documents.
|
|
128
|
+
|
|
129
|
+
* Implement the [new meta-data proposal][proposal].
|
|
130
|
+
|
|
131
|
+
* Exporting to Markdown (pretty printing).
|
|
132
|
+
|
|
133
|
+
* Exporting to HTML splitting in multiple files.
|
|
134
|
+
|
|
135
|
+
* RubyPants.
|
|
136
|
+
|
|
137
|
+
* Support for images in PDF.
|
|
138
|
+
|
|
139
|
+
|
|
140
|
+
[proposal]: http://maruku.rubyforge.org/proposal.html
|
|
141
|
+
[contact]: http://www.dis.uniroma1.it/~acensi/contact.html
|
|
142
|
+
[markdown-discuss]: http://six.pairlist.net/mailman/listinfo/markdown-discuss
|
|
143
|
+
[tracker]: http://rubyforge.org/tracker/?group_id=2795
|
|
60
144
|
|
|
61
145
|
Download {#download}
|
|
62
146
|
--------
|
|
@@ -80,8 +164,9 @@ If you want commit access to the repository, just create an account on Rubyforge
|
|
|
80
164
|
|
|
81
165
|
### Bugs report ###
|
|
82
166
|
|
|
83
|
-
Use the [tracker]
|
|
84
|
-
|
|
167
|
+
Use the [tracker][tracker] or [drop me an email][drop].
|
|
168
|
+
|
|
169
|
+
[tracker]: http://rubyforge.org/tracker/?group_id=2795
|
|
85
170
|
|
|
86
171
|
Usage
|
|
87
172
|
--------
|
|
@@ -160,7 +245,9 @@ Examples of PHP Markdown Extra syntax {#extra}
|
|
|
160
245
|
|
|
161
246
|
|
|
162
247
|
* header ids
|
|
248
|
+
|
|
163
249
|
## Download ## {#download}
|
|
250
|
+
|
|
164
251
|
For example, [a link to the download](#download) header.
|
|
165
252
|
|
|
166
253
|
Note that you can use also the new [meta-data syntax](#meta) for the same purpose:
|
|
@@ -455,23 +542,6 @@ Entity | Result
|
|
|
455
542
|
`—` | —
|
|
456
543
|
|
|
457
544
|
|
|
458
|
-
TODO list
|
|
459
|
-
--------------------------
|
|
460
|
-
|
|
461
|
-
|
|
462
|
-
* Export to HTML
|
|
463
|
-
1. Add `-split` options to `maruku` that splits the document over multiple
|
|
464
|
-
pages.
|
|
465
|
-
|
|
466
|
-
This should require the possibility of specifying a template for navigational
|
|
467
|
-
elements. Investigate template engine.
|
|
468
|
-
|
|
469
|
-
2. Include RubyPants
|
|
470
|
-
|
|
471
|
-
* Export to PDF
|
|
472
|
-
* support for images
|
|
473
|
-
|
|
474
|
-
* Export to Markdown (pretty-printing)
|
|
475
545
|
|
|
476
546
|
|
|
477
547
|
Future developments {#future}
|
|
@@ -481,77 +551,10 @@ I think that [Pandoc][] and [MultiMarkdown][] are very cool projects.
|
|
|
481
551
|
However, they are written in Haskell and Perl, respectively.
|
|
482
552
|
I would love to have an equivalent in Ruby.
|
|
483
553
|
|
|
484
|
-
|
|
485
554
|
[Pandoc]: http://sophos.berkeley.edu/macfarlane/pandoc/
|
|
486
555
|
[MultiMarkdown]: http://fletcher.freeshell.org/wiki/MultiMarkdown
|
|
487
556
|
|
|
488
557
|
|
|
489
|
-
### A syntax for specifying meta-data for span-level elements ###
|
|
490
|
-
|
|
491
|
-
Maybe something like this:
|
|
492
|
-
|
|
493
|
-
This is a paragraph. Really, a normal paragraph. The second
|
|
494
|
-
line of this paragraph has the last element {with meta data}@ class: important_span
|
|
495
|
-
and the paragraph continues...
|
|
496
|
-
|
|
497
|
-
So the idea is:
|
|
498
|
-
|
|
499
|
-
* Only elements at the end of the line can have meta data.
|
|
500
|
-
* Syntax is:
|
|
501
|
-
1. Opening brace `{`.
|
|
502
|
-
2. Any string that does not contain the sequence `}@`.
|
|
503
|
-
3. Closing brace and at-symbol `}@`.
|
|
504
|
-
4. Attributes specification like the block-level metadata.
|
|
505
|
-
|
|
506
|
-
Or, we could allow metadata specified **after the text**.
|
|
507
|
-
In the following, three fragments are marked as "special",
|
|
508
|
-
and, after their containing block-level elements, their
|
|
509
|
-
attributes are set:
|
|
510
|
-
|
|
511
|
-
Lorem ipsum dolor sit @{amet}, consectetuer adipiscing
|
|
512
|
-
elit. Donec sit amet sapien vitae augue @{interdum hendrerit.}
|
|
513
|
-
Maecenas tempor ultrices nisl. @{Praesent laoreet tortor sit
|
|
514
|
-
amet est.} Praesent in nisl eu libero sodales bibendum.
|
|
515
|
-
|
|
516
|
-
@{1} id: amet
|
|
517
|
-
@{2} style: "font-style: bold"
|
|
518
|
-
@{3} class: warning
|
|
519
|
-
|
|
520
|
-
We can be much liberal in the syntax. For example, instead of
|
|
521
|
-
numeric references to the part in the text, we could write:
|
|
522
|
-
|
|
523
|
-
Lorem ipsum dolor sit @{amet}, consectetuer adipiscing
|
|
524
|
-
elit. Donec sit amet sapien vitae augue @{interdum hendrerit.}
|
|
525
|
-
Maecenas tempor ultrices nisl. @{Praesent laoreet tortor sit
|
|
526
|
-
amet est.} Praesent in nisl eu libero sodales bibendum.
|
|
527
|
-
|
|
528
|
-
@{amet} id: amet
|
|
529
|
-
@{interdum ...} style: "font-style: bold"
|
|
530
|
-
@{Praesent ...} class: warning
|
|
531
|
-
|
|
532
|
-
with `...` acting as a wildcard, to match a long phrase (`{ Praesent laoreet tortor sit amet est.}`) without specifying the full text.
|
|
533
|
-
|
|
534
|
-
I feel this is very readable and not intrusive. But then again,
|
|
535
|
-
subjective tastes vary. Let me know of any comments and suggestions.
|
|
536
|
-
I want to wait for feedback before implementing this.
|
|
537
|
-
|
|
538
|
-
### A syntax for commenting parts of the document ###
|
|
539
|
-
|
|
540
|
-
This is a paragraph
|
|
541
|
-
% This is a comment
|
|
542
|
-
|
|
543
|
-
Or `%` on a line by itself comments the following block:
|
|
544
|
-
|
|
545
|
-
% The following paragraph is ignored
|
|
546
|
-
|
|
547
|
-
%
|
|
548
|
-
Lorem ipsum dolor sit amet, consectetuer adipiscing
|
|
549
|
-
elit. Donec sit amet sapien vitae augue interdum hendrerit.
|
|
550
|
-
Maecenas tempor ultrices nisl. Praesent laoreet tortor sit
|
|
551
|
-
amet est. Praesent in nisl eu libero sodales bibendum.
|
|
552
|
-
|
|
553
|
-
This paragraph is not ignored.
|
|
554
|
-
|
|
555
558
|
### A syntax for adding math ###
|
|
556
559
|
|
|
557
560
|
Something inspired from LaTeX should be familiar to all:
|
data/docs/proposal.html
CHANGED
|
@@ -1,24 +1,171 @@
|
|
|
1
|
-
<?xml version='1.0' ?>
|
|
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
|
-
|
|
6
|
-
|
|
7
|
-
|
|
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>
|
|
11
|
+
<h1 id='proposal_for_adding_a_metadata_syntax_to_markdown'>Proposal for adding a meta-data syntax to Markdown</h1>
|
|
12
|
+
|
|
13
|
+
<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>
|
|
14
|
+
|
|
15
|
+
<p>Last updated <strong>January 2nd, 2007</strong>: integrated topics discussed in mailing list.</p>
|
|
16
|
+
|
|
17
|
+
<p><em>Table of contents:</em></p>
|
|
18
|
+
|
|
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>
|
|
56
|
+
|
|
57
|
+
<h2 id='overview'><span class='maruku_section_number'>1. </span>Overview</h2>
|
|
58
|
+
|
|
59
|
+
<p>This proposal describes two additions to the Markdown syntax:</p>
|
|
60
|
+
|
|
61
|
+
<ol>
|
|
62
|
+
<li>
|
|
63
|
+
<p>inline attribute lists (IAL)</p>
|
|
64
|
+
|
|
65
|
+
<pre><code>## Header ## {key=val .class #id ref_id}</code></pre>
|
|
66
|
+
</li>
|
|
67
|
+
|
|
68
|
+
<li>
|
|
69
|
+
<p>attribute lists definitions (ALD)</p>
|
|
70
|
+
|
|
71
|
+
<pre><code>{ref_id}: key=val .class #id</code></pre>
|
|
72
|
+
</li>
|
|
73
|
+
</ol>
|
|
74
|
+
|
|
75
|
+
<p>Every span-level or block-level element can be followed by an IAL:</p>
|
|
76
|
+
|
|
77
|
+
<pre><code>### Header ### {#header1 class=c1}
|
|
78
|
+
|
|
79
|
+
Paragraph *with emphasis*{class=c1}
|
|
80
|
+
second line of paragraph
|
|
81
|
+
{class=c1}
|
|
82
|
+
</code></pre>
|
|
83
|
+
|
|
84
|
+
<p>In this example, the three IALs refer to the header, the emphasis span, and the entire paragraph, respectively.</p>
|
|
85
|
+
|
|
86
|
+
<p>IALs can reference ALDs. The result of the following example is the same as the previous one:</p>
|
|
87
|
+
|
|
88
|
+
<pre><code>### Header ### {#header1 c1}
|
|
89
|
+
|
|
90
|
+
Paragraph *with emphasis*{c1}
|
|
91
|
+
second line of paragraph
|
|
92
|
+
{c1}
|
|
93
|
+
|
|
94
|
+
{c1}: class=c1
|
|
95
|
+
</code></pre>
|
|
96
|
+
|
|
97
|
+
<h2 id='attribute_lists'><span class='maruku_section_number'>2. </span>Attribute lists</h2>
|
|
98
|
+
|
|
99
|
+
<p>This is an example attribute list, which shows everything you can put inside:</p>
|
|
100
|
+
|
|
101
|
+
<pre><code>key1=val key2="long val" #myid .class1 .class2 ref1 ref2
|
|
102
|
+
</code></pre>
|
|
103
|
+
|
|
104
|
+
<p>More in particular, an attribute list is a whitespace-separated list of elements of 4 different kinds:</p>
|
|
105
|
+
|
|
106
|
+
<ol>
|
|
107
|
+
<li>key/value pairs (quoted if necessary)</li>
|
|
108
|
+
|
|
109
|
+
<li><a href='#using_tags'>references to ALD</a> (<code>ref1</code>,<code>ref2</code>)</li>
|
|
110
|
+
|
|
111
|
+
<li><a href='#class_id'>id specifiers</a> (<code>#myid</code>)</li>
|
|
112
|
+
|
|
113
|
+
<li><a href='#class_id'>class specifiers</a> (<code>.myclass</code>) </li>
|
|
114
|
+
</ol>
|
|
115
|
+
|
|
116
|
+
<h3 id='class_id'><span class='maruku_section_number'>2.1. </span><code>id</code> and <code>class</code> are special</h3>
|
|
117
|
+
|
|
118
|
+
<p>For ID and classes there are special shortcuts:</p>
|
|
119
|
+
|
|
120
|
+
<ul>
|
|
121
|
+
<li>
|
|
122
|
+
<p><code>#myid</code> is a shortcut for <code>id=myid</code></p>
|
|
123
|
+
</li>
|
|
124
|
+
|
|
125
|
+
<li>
|
|
126
|
+
<p><code>.myclass</code> means "add <code>myclass</code> to the current <code>class</code> attribute".</p>
|
|
127
|
+
|
|
128
|
+
<p>So these are equivalent:</p>
|
|
129
|
+
|
|
130
|
+
<pre><code>{.class1 .class2}
|
|
131
|
+
{class="class1 class2"}</code></pre>
|
|
132
|
+
</li>
|
|
133
|
+
</ul>
|
|
134
|
+
|
|
135
|
+
<p>The following attribute lists are equivalent:</p>
|
|
136
|
+
|
|
137
|
+
<pre><code>{#myid .class1 .class2}
|
|
138
|
+
{id=myid class=class1 .class2}
|
|
8
139
|
{id=myid class="class1 class2"}
|
|
140
|
+
{id=myid class="will be overridden" class=class1 .class2}
|
|
141
|
+
</code></pre>
|
|
142
|
+
|
|
143
|
+
<h2 id='where_to_put_inline_attribute_lists'><span class='maruku_section_number'>3. </span>Where to put inline attribute lists</h2>
|
|
144
|
+
|
|
145
|
+
<h3 id='for_blocklevel_elements'><span class='maruku_section_number'>3.1. </span>For block-level elements</h3>
|
|
146
|
+
|
|
147
|
+
<p>For paragraphs and other block-level elements, IAL go <strong>after</strong> the element:</p>
|
|
9
148
|
|
|
10
|
-
|
|
149
|
+
<pre><code>This is a paragraph.
|
|
11
150
|
Line 2 of the paragraph.
|
|
12
151
|
{#myid .myclass}
|
|
13
152
|
|
|
14
153
|
A quote with a citation url:
|
|
15
154
|
> Who said that?
|
|
16
155
|
{cite=google.com}
|
|
17
|
-
</pre
|
|
156
|
+
</code></pre>
|
|
157
|
+
|
|
158
|
+
<p>Note: empty lines between the block and the IAL are not tollerated. So this is not legal:</p>
|
|
159
|
+
|
|
160
|
+
<pre><code>This is a paragraph.
|
|
18
161
|
Line 2 of the paragraph.
|
|
19
162
|
|
|
20
163
|
{#myid .myclass}
|
|
21
|
-
</pre
|
|
164
|
+
</code></pre>
|
|
165
|
+
|
|
166
|
+
<p>Attribute lists may be indented up to 3 spaces:</p>
|
|
167
|
+
|
|
168
|
+
<pre><code>Paragraph1
|
|
22
169
|
¬{ok}
|
|
23
170
|
|
|
24
171
|
Paragraph2
|
|
@@ -26,65 +173,225 @@ Paragraph2
|
|
|
26
173
|
|
|
27
174
|
Paragraph2
|
|
28
175
|
¬¬¬{ok}
|
|
29
|
-
</pre
|
|
176
|
+
</code></pre>
|
|
177
|
+
|
|
178
|
+
<h3 id='for_headers'><span class='maruku_section_number'>3.2. </span>For headers</h3>
|
|
179
|
+
|
|
180
|
+
<p>For headers, you can put attribute lists on the same line:</p>
|
|
181
|
+
|
|
182
|
+
<pre><code>### Header ### {#myid}
|
|
30
183
|
|
|
31
184
|
Header {#myid .myclass}
|
|
32
185
|
------
|
|
33
|
-
</pre
|
|
186
|
+
</code></pre>
|
|
187
|
+
|
|
188
|
+
<p>or, as like other block-level elements, on the line below:</p>
|
|
189
|
+
|
|
190
|
+
<pre><code>### Header ###
|
|
34
191
|
{#myid}
|
|
35
192
|
|
|
36
193
|
Header
|
|
37
194
|
------
|
|
38
195
|
{#myid .myclass}
|
|
39
|
-
</pre
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
196
|
+
</code></pre>
|
|
197
|
+
|
|
198
|
+
<h3 id='for_spanlevel_elements'><span class='maruku_section_number'>3.3. </span>For span-level elements</h3>
|
|
199
|
+
|
|
200
|
+
<p>For span-level elements, meta-data goes immediately <strong>after</strong> in the flow.</p>
|
|
201
|
+
|
|
202
|
+
<p>For example, in this:</p>
|
|
203
|
+
|
|
204
|
+
<pre><code>This is a *chunky paragraph*{#id1}
|
|
205
|
+
{#id2}</code></pre>
|
|
206
|
+
|
|
207
|
+
<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
|
+
|
|
209
|
+
<p>This works also for links, like this:</p>
|
|
210
|
+
|
|
211
|
+
<pre><code>This is [a link][ref]{#myid rel=abc rev=abc}
|
|
212
|
+
</code></pre>
|
|
213
|
+
|
|
214
|
+
<p>For images, this:</p>
|
|
215
|
+
|
|
216
|
+
<pre><code>This is 
|
|
217
|
+
</code></pre>
|
|
218
|
+
|
|
219
|
+
<p>is equivalent to:</p>
|
|
220
|
+
|
|
221
|
+
<pre><code>This is {title="fresh carrots"}
|
|
222
|
+
</code></pre>
|
|
223
|
+
|
|
224
|
+
<h2 id='using_tags'><span class='maruku_section_number'>4. </span>Using attributes lists definition</h2>
|
|
225
|
+
|
|
226
|
+
<p>In an attribute list, you can have: </p>
|
|
227
|
+
|
|
228
|
+
<ol>
|
|
229
|
+
<li><code>key=value</code> pairs,</li>
|
|
230
|
+
|
|
231
|
+
<li>id attributes (<code>#myid</code>)</li>
|
|
232
|
+
|
|
233
|
+
<li>class attributes (<code>.myclass</code>) </li>
|
|
234
|
+
</ol>
|
|
235
|
+
|
|
236
|
+
<p>Everything else is interpreted as a reference to an ALD.</p>
|
|
237
|
+
|
|
238
|
+
<pre><code># Header # {ref}
|
|
44
239
|
|
|
45
240
|
Blah blah blah.
|
|
46
241
|
|
|
47
|
-
{
|
|
48
|
-
</pre
|
|
49
|
-
|
|
50
|
-
|
|
242
|
+
{ref}: #myhead .myclass lang=fr
|
|
243
|
+
</code></pre>
|
|
244
|
+
|
|
245
|
+
<p>Of course, more than one IAL can reference the same ALD:</p>
|
|
51
246
|
|
|
52
|
-
{
|
|
53
|
-
</pre><p>In this case, however, you should not assign the <tt style='background-color: #f0f0e0;'>id</tt> attribute. So this is <strong>not</strong> valid:</p><pre style='background-color: #f0f0e0;'># Header 1 # {tag}
|
|
247
|
+
<pre><code># Header 1 # {1}
|
|
54
248
|
...
|
|
55
|
-
# Header 2 # {
|
|
56
|
-
|
|
57
|
-
{
|
|
58
|
-
|
|
59
|
-
</pre
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
</
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
</
|
|
85
|
-
|
|
249
|
+
# Header 2 # {1}
|
|
250
|
+
|
|
251
|
+
{1}: .myclass lang=fr
|
|
252
|
+
|
|
253
|
+
</code></pre>
|
|
254
|
+
|
|
255
|
+
<h2 id='grammar'><span class='maruku_section_number'>5. </span>The rules</h2>
|
|
256
|
+
|
|
257
|
+
<h3 id='the_issue_of_escaping'><span class='maruku_section_number'>5.1. </span>The issue of escaping</h3>
|
|
258
|
+
|
|
259
|
+
<ol>
|
|
260
|
+
<li>
|
|
261
|
+
<p>No escaping in code blocks.</p>
|
|
262
|
+
|
|
263
|
+
<ul>
|
|
264
|
+
<li><code>`\`</code> represents the one-character string <code>\</code>.</li>
|
|
265
|
+
</ul>
|
|
266
|
+
</li>
|
|
267
|
+
|
|
268
|
+
<li>
|
|
269
|
+
<p>Everywhere else, <strong>all</strong> characters <strong>can</strong> be escaped:</p>
|
|
270
|
+
|
|
271
|
+
<ul>
|
|
272
|
+
<li><code>\|</code> is the literal <code>|</code>, <code>\n</code> is the literal <code>n</code>.</li>
|
|
273
|
+
|
|
274
|
+
<li><code>\ </code> represents a non-breaking space.</li>
|
|
275
|
+
|
|
276
|
+
<li><code>\</code> followed by a newline represents a linebreak.</li>
|
|
277
|
+
</ul>
|
|
278
|
+
</li>
|
|
279
|
+
|
|
280
|
+
<li>
|
|
281
|
+
<p>Quotes <strong>must</strong> be escaped inside quoted values:</p>
|
|
282
|
+
|
|
283
|
+
<ul>
|
|
284
|
+
<li>
|
|
285
|
+
<p>Inside <code>"quoted values"</code>, you <strong>must</strong> escape <code>"</code>.</p>
|
|
286
|
+
</li>
|
|
287
|
+
|
|
288
|
+
<li>
|
|
289
|
+
<p>Inside <code>'quoted values'</code>, you <strong>must</strong> escape <code>'</code>.</p>
|
|
290
|
+
</li>
|
|
291
|
+
|
|
292
|
+
<li>
|
|
293
|
+
<p>Other examples:</p>
|
|
294
|
+
|
|
295
|
+
<p><code>"bah 'bah' bah"</code> = <code>"bah \'bah\' bah"</code> = <code>'bah \'bah\' bah'</code></p>
|
|
296
|
+
|
|
297
|
+
<p><code>'bah "bah" bah'</code> = <code>'bah \"bah\" bah'</code> = <code>"bah \"bah\" bah"</code></p>
|
|
298
|
+
</li>
|
|
299
|
+
</ul>
|
|
300
|
+
</li>
|
|
301
|
+
|
|
302
|
+
<li>
|
|
303
|
+
<p>There is an exception for backward compatibility: </p>
|
|
304
|
+
|
|
305
|
+
<pre><code>[text](url "title"with"quotes")</code></pre>
|
|
306
|
+
</li>
|
|
307
|
+
</ol>
|
|
308
|
+
|
|
309
|
+
<h3 id='syntax_for_attribute_lists'><span class='maruku_section_number'>5.2. </span>Syntax for attribute lists</h3>
|
|
310
|
+
|
|
311
|
+
<p>Consider the following attribute list:</p>
|
|
312
|
+
|
|
313
|
+
<pre><code>{key=value ref key2="quoted value" }</code></pre>
|
|
314
|
+
|
|
315
|
+
<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
|
+
|
|
317
|
+
<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>
|
|
318
|
+
|
|
319
|
+
<h2 id='things_to_discuss'><span class='maruku_section_number'>6. </span>Things to discuss</h2>
|
|
320
|
+
|
|
321
|
+
<ul>
|
|
322
|
+
<li>
|
|
323
|
+
<p>A syntax for creating <code>SPAN</code> elements in the paragraphs and setting their attributes.</p>
|
|
324
|
+
|
|
325
|
+
<p>This is my proposal:</p>
|
|
326
|
+
|
|
327
|
+
<pre><code>a long paragraph with [special words]{#myspan} that I want to
|
|
86
328
|
highlight
|
|
87
|
-
</pre
|
|
329
|
+
</code></pre>
|
|
330
|
+
|
|
331
|
+
<p>should originate the following HTML:</p>
|
|
332
|
+
|
|
333
|
+
<pre><code><p>a long paragraph with <span id="myspan">special words</span>
|
|
88
334
|
that I want to highlight</p>
|
|
89
|
-
</
|
|
90
|
-
|
|
335
|
+
</code></pre>
|
|
336
|
+
|
|
337
|
+
<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
|
+
</li>
|
|
339
|
+
|
|
340
|
+
<li>
|
|
341
|
+
<blockquote>
|
|
342
|
+
<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>
|
|
343
|
+
</blockquote>
|
|
344
|
+
|
|
345
|
+
<p>Any opinion?</p>
|
|
346
|
+
</li>
|
|
347
|
+
|
|
348
|
+
<li>
|
|
349
|
+
<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
|
+
<pre><code>## Header ##
|
|
352
|
+
|
|
353
|
+
Paragraph..
|
|
354
|
+
|
|
355
|
+
## Second Header ## {.mah}
|
|
356
|
+
|
|
357
|
+
Paragraph..
|
|
358
|
+
|
|
359
|
+
{header2}: .myclass
|
|
360
|
+
{paragraph}: .withmargins</code></pre>
|
|
361
|
+
</li>
|
|
362
|
+
</ul>
|
|
363
|
+
|
|
364
|
+
<p>In this example:</p>
|
|
365
|
+
|
|
366
|
+
<ul>
|
|
367
|
+
<li>the first header has attributes <code>class=myclass</code></li>
|
|
368
|
+
|
|
369
|
+
<li>the second header has attributes <code>class="myclass mah"</code></li>
|
|
370
|
+
|
|
371
|
+
<li>the two paragraphs have attributes <code>class=withmargins</code></li>
|
|
372
|
+
</ul>
|
|
373
|
+
|
|
374
|
+
<h2 id='design_rationale'><span class='maruku_section_number'>7. </span>Design rationale</h2>
|
|
375
|
+
|
|
376
|
+
<ul>
|
|
377
|
+
<li>
|
|
378
|
+
<p>Question: should we allow whitespace at the sides of <code>=</code> in key/value pairs?</p>
|
|
379
|
+
|
|
380
|
+
<blockquote>
|
|
381
|
+
<p>No, because it is difficult to parse.</p>
|
|
382
|
+
</blockquote>
|
|
383
|
+
</li>
|
|
384
|
+
|
|
385
|
+
<li>
|
|
386
|
+
<p>Question: should <code>:</code> be a synonym for <code>=</code> in attributes list?</p>
|
|
387
|
+
|
|
388
|
+
<blockquote>
|
|
389
|
+
<p>No, because ':' is used for XML namespaces (<code>xml:lang=en</code>)</p>
|
|
390
|
+
</blockquote>
|
|
391
|
+
</li>
|
|
392
|
+
</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>
|