docs/proposal.html in maruku-0.4.1 vs docs/proposal.html in maruku-0.4.2
- old
+ new
@@ -4,52 +4,90 @@
<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>
<h1 id='proposal_for_adding_a_metadata_syntax_to_markdown'>Proposal for adding a meta-data syntax to Markdown</h1>
<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>
-<p>Last updated <strong>January 2nd, 2007</strong>: integrated topics discussed in mailing list.</p>
+<p><strong><em>Note: this is an evolving proposal</em></strong></p>
+<p>Last updated <strong>January 10th, 2007</strong>:</p>
+
+<ul>
+<li>
+<p>Changed the syntax for compatibility with a future extension mechanism.</p>
+
+<p>The first character in the curly braces must be a colon, optionally followed by a space:</p>
+<pre><code>{: ref .class #id}
+</code></pre>
+<p>The old syntax was <code>{ref .class #id}</code>.</p>
+
+<p>For ALDs, the new syntax is:</p>
+<pre><code>{:ref_id: key=val .class #id }
+</code></pre>
+<p>instead of:</p>
+<pre><code>{ref_id}: key=val .class #id
+</code></pre>
+<p>Converters that don’t use this syntax may just ignore everything which is in curly braces and starts with ”:”.</p>
+</li>
+
+<li>
+<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>
+<pre><code>Paragraph 1
+
+{:par2}
+Paragraph 2
+</code></pre>
+<p>is equivalent to:</p>
+<pre><code>Paragraph 1
+
+Paragraph 2
+{:par2}</code></pre></li>
+
+<li>
+<p>Simplified rules for escaping.</p>
+</li>
+</ul>
+
<p><em>Table of contents:</em></p>
-<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>
+<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>
<h2 id='overview'><span class='maruku_section_number'>1. </span>Overview</h2>
<p>This proposal describes two additions to the Markdown syntax:</p>
<ol>
<li>
<p>inline attribute lists (IAL)</p>
-<pre><code>## Header ## {key=val .class #id ref_id}</code></pre></li>
+<pre><code>## Header ## {: key=val .class #id ref_id}</code></pre></li>
<li>
<p>attribute lists definitions (ALD)</p>
-<pre><code>{ref_id}: key=val .class #id</code></pre></li>
+<pre><code>{:ref_id: key=val .class #id}</code></pre></li>
</ol>
<p>Every span-level or block-level element can be followed by an IAL:</p>
-<pre><code>### Header ### {#header1 class=c1}
+<pre><code>### Header ### {: #header1 class=c1}
-Paragraph *with emphasis*{class=c1}
+Paragraph *with emphasis*{: class=c1}
second line of paragraph
-{class=c1}
+{: class=c1}
</code></pre>
<p>In this example, the three IALs refer to the header, the emphasis span, and the entire paragraph, respectively.</p>
<p>IALs can reference ALDs. The result of the following example is the same as the previous one:</p>
-<pre><code>### Header ### {#header1 c1}
+<pre><code>### Header ### {: #header1 c1}
-Paragraph *with emphasis*{c1}
+Paragraph *with emphasis*{:c1}
second line of paragraph
-{c1}
+{:c1}
-{c1}: class=c1
+{:c1: class=c1}
</code></pre>
<h2 id='attribute_lists'><span class='maruku_section_number'>2. </span>Attribute lists</h2>
<p>This is an example attribute list, which shows everything you can put inside:</p>
-<pre><code>key1=val key2="long val" #myid .class1 .class2 ref1 ref2
+<pre><code>{: key1=val key2="long val" #myid .class1 .class2 ref1 ref2}
</code></pre>
<p>More in particular, an attribute list is a whitespace-separated list of elements of 4 different kinds:</p>
<ol>
<li>key/value pairs (quoted if necessary)</li>
@@ -72,81 +110,81 @@
<li>
<p><code>.myclass</code> means “add <code>myclass</code> to the current <code>class</code> attribute”.</p>
<p>So these are equivalent:</p>
-<pre><code>{.class1 .class2}
-{class="class1 class2"}</code></pre></li>
+<pre><code>{: .class1 .class2}
+{: class="class1 class2"}</code></pre></li>
</ul>
<p>The following attribute lists are equivalent:</p>
-<pre><code>{#myid .class1 .class2}
-{id=myid class=class1 .class2}
-{id=myid class="class1 class2"}
-{id=myid class="will be overridden" class=class1 .class2}
+<pre><code>{: #myid .class1 .class2}
+{: id=myid class=class1 .class2}
+{: id=myid class="class1 class2"}
+{: id=myid class="will be overridden" class=class1 .class2}
</code></pre>
<h2 id='where_to_put_inline_attribute_lists'><span class='maruku_section_number'>3. </span>Where to put inline attribute lists</h2>
<h3 id='for_blocklevel_elements'><span class='maruku_section_number'>3.1. </span>For block-level elements</h3>
<p>For paragraphs and other block-level elements, IAL go <strong>after</strong> the element:</p>
<pre><code>This is a paragraph.
Line 2 of the paragraph.
-{#myid .myclass}
+{: #myid .myclass}
A quote with a citation url:
> Who said that?
-{cite=google.com}
+{: cite=google.com}
</code></pre>
-<p>Note: empty lines between the block and the IAL are not tollerated. So this is not legal:</p>
+<p>Note: empty lines between the block and the IAL are not tolerated. So this is not legal:</p>
<pre><code>This is a paragraph.
Line 2 of the paragraph.
-{#myid .myclass}
+{: #myid .myclass}
</code></pre>
<p>Attribute lists may be indented up to 3 spaces:</p>
<pre><code>Paragraph1
-¬{ok}
+¬{:ok}
Paragraph2
-¬¬{ok}
+¬¬{:ok}
Paragraph2
-¬¬¬{ok}</code></pre>
+¬¬¬{:ok}</code></pre>
<h3 id='for_headers'><span class='maruku_section_number'>3.2. </span>For headers</h3>
<p>For headers, you can put attribute lists on the same line:</p>
-<pre><code>### Header ### {#myid}
+<pre><code>### Header ### {: #myid}
-Header {#myid .myclass}
+Header {: #myid .myclass}
------
</code></pre>
<p>or, as like other block-level elements, on the line below:</p>
<pre><code>### Header ###
-{#myid}
+{: #myid}
Header
------
-{#myid .myclass}
+{: #myid .myclass}
</code></pre>
<h3 id='for_spanlevel_elements'><span class='maruku_section_number'>3.3. </span>For span-level elements</h3>
<p>For span-level elements, meta-data goes immediately <strong>after</strong> in the flow.</p>
<p>For example, in this:</p>
-<pre><code>This is a *chunky paragraph*{#id1}
-{#id2}</code></pre>
+<pre><code>This is a *chunky paragraph*{: #id1}
+{: #id2}</code></pre>
<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>
<p>This works also for links, like this:</p>
-<pre><code>This is [a link][ref]{#myid rel=abc rev=abc}
+<pre><code>This is [a link][ref]{:#myid rel=abc rev=abc}
</code></pre>
<p>For images, this:</p>
<pre><code>This is 
</code></pre>
<p>is equivalent to:</p>
-<pre><code>This is {title="fresh carrots"}
+<pre><code>This is {:title="fresh carrots"}
</code></pre>
<h2 id='using_tags'><span class='maruku_section_number'>4. </span>Using attributes lists definition</h2>
<p>In an attribute list, you can have:</p>
@@ -157,51 +195,41 @@
<li>class attributes (<code>.myclass</code>)</li>
</ol>
<p>Everything else is interpreted as a reference to an ALD.</p>
-<pre><code># Header # {ref}
+<pre><code># Header # {:ref}
Blah blah blah.
-{ref}: #myhead .myclass lang=fr
+{:ref: #myhead .myclass lang=fr}
</code></pre>
<p>Of course, more than one IAL can reference the same ALD:</p>
-<pre><code># Header 1 # {1}
+<pre><code># Header 1 # {:1}
...
-# Header 2 # {1}
+# Header 2 # {:1}
-{1}: .myclass lang=fr
+{:1: .myclass lang=fr}
</code></pre>
-<h2 id='grammar'><span class='maruku_section_number'>5. </span>The rules</h2>
+<h2 id='the_rules'><span class='maruku_section_number'>5. </span>The rules</h2>
<h3 id='the_issue_of_escaping'><span class='maruku_section_number'>5.1. </span>The issue of escaping</h3>
<ol>
<li>
-<p>No escaping in code blocks.</p>
-
-<ul>
-<li><code>`\`</code> represents the one-character string <code>\</code>.</li>
-</ul>
+<p>No escaping in code spans/blocks.</p>
</li>
<li>
-<p>Everywhere else, <strong>all</strong> characters <strong>can</strong> be escaped:</p>
+<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>
-<ul>
-<li><code>\|</code> is the literal <code>|</code>, <code>\n</code> is the literal <code>n</code>.</li>
-
-<li><code>\ </code> represents a non-breaking space.</li>
-
-<li><code>\</code> followed by a newline represents a linebreak.</li>
-</ul>
+<p>A punctuation character is anything not a letter, a number, or whitespace (<code>[^a-zA-Z0-9\s\n]</code>).</p>
</li>
<li>
-<p>Quotes <strong>must</strong> be escaped inside quoted values:</p>
+<p>As a rule, quotes <strong>must</strong> be escaped inside quoted values:</p>
<ul>
<li>
<p>Inside <code>"quoted values"</code>, you <strong>must</strong> escape <code>"</code>.</p>
</li>
@@ -210,95 +238,49 @@
<p>Inside <code>'quoted values'</code>, you <strong>must</strong> escape <code>'</code>.</p>
</li>
<li>
<p>Other examples:</p>
+</li>
+</ul>
<p><code>"bah 'bah' bah"</code> = <code>"bah \'bah\' bah"</code> = <code>'bah \'bah\' bah'</code></p>
<p><code>'bah "bah" bah'</code> = <code>'bah \"bah\" bah'</code> = <code>"bah \"bah\" bah"</code></p>
</li>
-</ul>
-</li>
<li>
-<p>There is an exception for backward compatibility:</p>
-<pre><code>[text](url "title"with"quotes")</code></pre></li>
+<p>There is an exception for backward compatibility, in links/images titles:</p>
+<pre><code>[text](url "title"with"quotes")
+</code></pre>
+<p>The exception is not valid for attribute lists and in other contexts, where you have to use the canonical syntax.</p>
+</li>
</ol>
<h3 id='syntax_for_attribute_lists'><span class='maruku_section_number'>5.2. </span>Syntax for attribute lists</h3>
<p>Consider the following attribute list:</p>
-<pre><code>{key=value ref key2="quoted value" }</code></pre>
+<pre><code>{: key=value ref key2="quoted value" }</code></pre>
<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>
-<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>
+<p>Inside a quoted value you <strong>must</strong> escape the other kind of quote.</p>
-<h2 id='things_to_discuss'><span class='maruku_section_number'>6. </span>Things to discuss</h2>
+<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>
-<ul>
-<li>
-<p>A syntax for creating <code>SPAN</code> elements in the paragraphs and setting their attributes.</p>
+<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>
+<pre><code>r = /\{:(\\\}|[^\}])*\}/
-<p>This is my proposal:</p>
-<pre><code>a long paragraph with [special words]{#myspan} that I want to
-highlight
-</code></pre>
-<p>should originate the following HTML:</p>
-<pre><code><p>a long paragraph with <span id="myspan">special words</span>
- that I want to highlight</p>
-</code></pre>
-<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>
-</li>
+s.gsub(r, '') # ignore metadata</code></pre>
+<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>
-<li>
-<blockquote>
-<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>
-</blockquote>
+<p>For this example,</p>
+<pre><code>this is
+{: skipped="\}" val=\} bar}
-<p>Any opinion?</p>
-</li>
+for me
+{: also this}
+</code></pre>
+<p>the result is:</p>
+<pre><code>this is
+
-<li>
-<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>
-<pre><code>## Header ##
-
-Paragraph..
-
-## Second Header ## {.mah}
-
-Paragraph..
-
-{header2}: .myclass
-{paragraph}: .withmargins</code></pre></li>
-</ul>
-
-<p>In this example:</p>
-
-<ul>
-<li>the first header has attributes <code>class=myclass</code></li>
-
-<li>the second header has attributes <code>class="myclass mah"</code></li>
-
-<li>the two paragraphs have attributes <code>class=withmargins</code></li>
-</ul>
-
-<h2 id='design_rationale'><span class='maruku_section_number'>7. </span>Design rationale</h2>
-
-<ul>
-<li>
-<p>Question: should we allow whitespace at the sides of <code>=</code> in key/value pairs?</p>
-
-<blockquote>
-<p>No, because it is difficult to parse.</p>
-</blockquote>
-</li>
-
-<li>
-<p>Question: should <code>:</code> be a synonym for <code>=</code> in attributes list?</p>
-
-<blockquote>
-<p>No, because ’:’ is used for XML namespaces (<code>xml:lang=en</code>)</p>
-</blockquote>
-</li>
-</ul>
-<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>
+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>