maruku 0.4.1 → 0.4.2

data/docs/proposal.md

@@ -10,13 +10,51 @@ This document describes a syntax for attaching meta-data to
 block-level elements (headers, paragraphs, code blocks,…), 
 and to span-level elements (links, images,…).
 
-Last updated **January 2nd, 2007**: integrated topics 
-discussed in mailing list.
+***Note: this is an evolving proposal***
+
+Last updated **January 10th, 2007**: 
+
+*	Changed the syntax for compatibility with a future extension mechanism.
+
+	The first character in the curly braces must be a colon, optionally
+	followed by a space:
+	
+		{: ref .class #id}
+	
+	The old syntax was `{ref .class #id}`.
+	
+	For ALDs, the new syntax is:
+	
+		{:ref_id: key=val .class #id }
+	
+	instead of:
+	
+		{ref_id}: key=val .class #id 
+
+	Converters that don't use this syntax may just ignore everything
+	which is in curly braces and starts with ":".
+
+*	IAL can be put both *before* and *after* the element.
+	There is no ambiguity as a blank line is needed between elements:
+	
+		Paragraph 1
+		
+		{:par2}
+		Paragraph 2
+
+	is equivalent to:
+	
+		Paragraph 1
+	
+		Paragraph 2
+		{:par2}
+
+*	Simplified rules for escaping.
 
 *Table of contents:*
 
 > * Table of contents
-> {toc}
+> {:toc}
 
 Overview
 --------
@@ -25,31 +63,31 @@ This proposal describes two additions to the Markdown syntax:
 
 1. inline attribute lists (IAL)
 
-   	## Header ##       {key=val .class #id ref_id}
+   	## Header ##       {: key=val .class #id ref_id}
 
 2. attribute lists definitions (ALD)
 
-   	{ref_id}: key=val .class #id
+   	{:ref_id: key=val .class #id}
 
 Every span-level or block-level element can be followed by an IAL:
 
-	### Header ###     {#header1 class=c1}
+	### Header ###     {: #header1 class=c1}
 	
-	Paragraph *with emphasis*{class=c1}
+	Paragraph *with emphasis*{: class=c1}
 	second line of paragraph
-	{class=c1}
+	{: class=c1}
 
 In this example, the three IALs refer to the header, the emphasis span, and the entire paragraph, respectively.
 
 IALs can reference ALDs. The result of the following example is the same as the previous one:
 
-	### Header ###  {#header1 c1}
+	### Header ###  {: #header1 c1}
 
-	Paragraph *with emphasis*{c1}
+	Paragraph *with emphasis*{:c1}
 	second line of paragraph
-	{c1}
+	{:c1}
 	
-	{c1}: class=c1
+	{:c1: class=c1}
 
 Attribute lists
 ---------------
@@ -57,7 +95,7 @@ Attribute lists
 This is an example attribute list, which shows
 everything you can put inside:
 
-	key1=val key2="long val" #myid .class1 .class2 ref1 ref2
+	{: key1=val key2="long val" #myid .class1 .class2 ref1 ref2}
 
 More in particular, an attribute list is a   whitespace-separated list 
 of elements of 4 different kinds:
@@ -76,16 +114,16 @@ For ID and classes there are special shortcuts:
 
   So these are equivalent:
 
-  	{.class1 .class2}
-  	{class="class1 class2"}
+  	{: .class1 .class2}
+  	{: class="class1 class2"}
 
 
 The following attribute lists are equivalent:
 
-	{#myid .class1 .class2} 
-	{id=myid class=class1 .class2}
-	{id=myid class="class1 class2"}
-	{id=myid class="will be overridden" class=class1 .class2}
+	{: #myid .class1 .class2} 
+	{: id=myid class=class1 .class2}
+	{: id=myid class="class1 class2"}
+	{: id=myid class="will be overridden" class=class1 .class2}
 
 Where to put inline attribute lists
 ----------------------------------
@@ -97,49 +135,49 @@ For paragraphs and other block-level elements, IAL go
 
 	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}
 
-Note: empty lines between the block and the IAL are not tollerated.
+Note: empty lines between the block and the IAL are not tolerated.
 So this is not legal:
 
 	This is a paragraph.
 	Line 2 of the paragraph.
 	
-	{#myid .myclass}
+	{: #myid .myclass}
 
 Attribute lists may be indented up to 3 spaces:
 
 	Paragraph1
-	 {ok}
+	 {:ok}
 	
 	Paragraph2
-	  {ok}
+	  {:ok}
 	
 	Paragraph2
-	   {ok}
-{code_show_spaces}
+	   {:ok}
+{:code_show_spaces}
 
 ### For headers ###
 
 For headers, you can put attribute lists on the same line:
 
-	### Header ###     {#myid}
+	### Header ###     {: #myid}
 
-	Header     {#myid .myclass}
+	Header     {: #myid .myclass}
 	------
 
 or, as like other block-level elements, on the line below:
 
 	### Header ###     
-	{#myid}
+	{: #myid}
 
 	Header     
 	------
-	{#myid .myclass}
+	{: #myid .myclass}
 
 ### For span-level elements ###
 
@@ -148,15 +186,15 @@ flow.
 
 For example, in this:
 
-	This is a *chunky paragraph*{#id1}
-	{#id2}
+	This is a *chunky paragraph*{: #id1}
+	{: #id2}
 	
 the ID of the `em` element is set to `id1`
 and the ID of the paragraph is set to `id2`.
 
 This works also for links, like this:
 
-	This is [a link][ref]{#myid rel=abc rev=abc}
+	This is [a link][ref]{:#myid rel=abc rev=abc}
 
 For images, this:
 
@@ -164,7 +202,7 @@ For images, this:
 
 is equivalent to:
 	
-	This is ![Alt text](url){title="fresh carrots"}
+	This is ![Alt text](url){:title="fresh carrots"}
 
 Using attributes lists definition    {#using_tags}
 ---------------------------------
@@ -178,120 +216,94 @@ In an attribute list, you can have:
 Everything else is interpreted as a reference to 
 an ALD.
 
-	# Header #      {ref}
+	# Header #      {:ref}
 
 	Blah blah blah.
 	
-	{ref}: #myhead .myclass lang=fr
+	{:ref: #myhead .myclass lang=fr}
 
 Of course, more than one IAL can reference the same ALD:
 
-	# Header 1 #      {1}
+	# Header 1 #      {:1}
 	...
-	# Header 2 #      {1}
+	# Header 2 #      {:1}
 
-	{1}: .myclass lang=fr
+	{:1: .myclass lang=fr}
 
 
-The rules           {#grammar}
+The rules           {:#grammar}
 ---------
 
 ### The issue of escaping ###
 
-1. No escaping in code blocks.
+1.	No escaping in code spans/blocks.
+
+2.	Everywhere else, **all** PUNCTUATION characters **can** be escaped,
+and **must** be escaped when they could trigger links, tables, etc.
+	
+	A punctuation character is anything not a letter, a number, or whitespace
+	(`[^a-zA-Z0-9\s\n]`).
 
-   * ``` `\` ``` represents the one-character string `\`.
+3.	As a rule, quotes **must** be escaped inside quoted values:
 
-2. Everywhere else, **all** characters **can** be escaped:
+	* Inside `"quoted values"`, you **must** escape `"`.
+	* Inside `'quoted values'`, you **must** escape `'`.
 
-   * `\|` is the literal `|`, `\n` is the literal `n`.
-   * `\ ` represents a non-breaking space.
-   *  `\` followed by a newline represents a linebreak.
+	* Other examples:
 
-3. Quotes **must** be escaped inside quoted values:
-   
-   * Inside `"quoted values"`, you **must** escape `"`.
-   * Inside `'quoted values'`, you **must** escape `'`.
+	`"bah 'bah' bah"` =  `"bah \'bah\' bah"` = `'bah \'bah\' bah'`
 
-   * Other examples:
+	`'bah "bah" bah'` =  `'bah \"bah\" bah'` = `"bah \"bah\" bah"`
 
-     `"bah 'bah' bah"` =  `"bah \'bah\' bah"` = `'bah \'bah\' bah'`
-     
-     `'bah "bah" bah'` =  `'bah \"bah\" bah'` = `"bah \"bah\" bah"`
 
+4.	There is an exception for backward compatibility, in links/images titles:
 
-4. There is an exception for backward compatibility: 
+       [text](url "title"with"quotes")
 
-   	[text](url "title"with"quotes")
+	The exception is not valid for attribute lists and in other
+	contexts, where you have to use the canonical syntax.
 
 
 ### Syntax for attribute lists ####
 
 Consider the following attribute list:
 
-	{key=value ref key2="quoted value" }
+	{: key=value ref key2="quoted value" }
 	
 In this string, `key`, `value`, and `ref` can be substituted by any
 string that does not contain whitespace, or the unescaped characters `}`,`=`,`'`,`"`.
 
-Inside a quoted value, you **may** use `}`,`=` unescaped but you **must**
-escape the other kind of quote.
-
-
-Things to discuss 
------------------
-
-* A syntax for creating `SPAN` elements in the paragraphs and setting their attributes.
-
-  This is my proposal:
-
-  	a long paragraph with [special words]{#myspan} that I want to
-  	highlight
-
-  should originate the following HTML:
-
-  	<p>a long paragraph with <span id="myspan">special words</span>
-  	   that I want to highlight</p>
-
-  ***Note: I changed the old `{special words}{#myspan}` with `[special words]{#myspan}` which is less ambiguous.***
+Inside a quoted value you **must** escape the other kind of quote.
 
-* > Another question: does it makes sense to define `<span>` within
-  > Markdown when you can't have `<b>` and `<i>`, or the more meaningful
-  > `<cite>`, `<q>`, `<dfn>`, and `<var>`? We have to draw the line somewhere,
-  > where should it be? Another good question for the list.
+Also, you **must** escape a closing curly brace `}` inside quoted values.
+This rule is for making life easier for interpreter that just want to skip
+the meta-data.
 
-  Any opinion?
-
-* **Default ALD for classes of elements.**  For example, an header of level 2 inherits automatically the attributes of `{header2}`, if it is defined.
-
-  	## Header ##
-  	
-  	Paragraph..
-  	
-  	## Second Header ## {.mah} 
-  	
-  	Paragraph..
-  	
-  	{header2}: .myclass
-  	{paragraph}: .withmargins
-
-In this example:
-
-* the first header has attributes `class=myclass`
-* the second header has attributes `class="myclass mah"`
-* the two paragraphs have attributes `class=withmargins`
+If you don't implement this syntax, you can get rid of the IAL by using this 
+regular expression (this is written in Ruby):
 
+	r = /\{:(\\\}|[^\}])*\}/       
+	
+	s.gsub(r, '') # ignore metadata
+{:ruby}
 
-Design rationale
-----------------
+Basically: match everything contained in a couple of `{:` and `}`, taking care
+of escaping of `}`. This `\\\}|[^\}]` means: eat either any character which
+is not a `}` or an escape sequence `\}`.
 
-* Question: should we allow whitespace at the sides of `=` in key/value pairs?
+For this example,
 
-  > No, because it is difficult to parse.
+	this is 
+	{: skipped="\}" val=\} bar} 
+	
+	for me 
+	{: also this} 
 
-* Question: should `:` be a synonym for `=` in attributes list?
+the result is:
 
-  > No, because ':' is used for XML namespaces (`xml:lang=en`)
+	this is 
+	 
+	
+	for me 
  
 
-

data/lib/maruku/attributes.rb

@@ -30,6 +30,7 @@ class String
 end
 
 module MaRuKu; 
+	MagicChar = ':'
 	
 	class AttributeList < Array
 		
@@ -80,6 +81,9 @@ module MaRuKu; module In; module Markdown; module SpanLevelParser
 			[ "a =b", :throw, "No whitespace before `=`." ], 
 			[ "a= b", :throw, "No whitespace after `=`." ], 
 
+			[ "a b c", [[:ref, 'a'],[:ref, 'b'],[:ref, 'c']], "More than one ref" ], 
+			[ "hello notfound", [[:ref, 'hello'],[:ref, 'notfound']]], 
+
 			[ "'a'",  [[:ref, 'a']], "Quoted value." ], 
 			[ '"a"'   ], 
 
@@ -117,7 +121,7 @@ module MaRuKu; module In; module Markdown; module SpanLevelParser
 			@comment  = (comment  ||= (last=@comment) )
 			(comment == last && (comment += (@count+=1).to_s)) || @count = 1
 			expected = [md_ial(expected)] if expected.kind_of? Array
-			["{#{s}}", expected, "Attributes: #{comment}"]
+			["{#{MagicChar}#{s}}", expected, "Attributes: #{comment}"]
 		}
 	end
 	
@@ -181,6 +185,34 @@ module MaRuKu; module In; module Markdown; module SpanLevelParser
 		end # while true
 		al
 	end
+	
+	
+	def merge_ial(elements, src, con)	
+		# We need a helper
+		def is_ial(e); e.kind_of? MDElement and e.node_type == :ial end
+
+		# Apply each IAL to the element before
+		elements.each_with_index do |e, i| 
+		if is_ial(e) && i>= 1 then
+			before = elements[i-1]
+			after = elements[i+1]
+			if before.kind_of? MDElement
+				before.al = e.ial
+			elsif after.kind_of? MDElement
+				after.al = e.ial
+			else
+				maruku_error "I don't know who you are referring to:"+
+					" {#{e.ial.to_md}}", src, con
+				# xxx dire se c'è empty vicino
+				maruku_recover "Ignoring IAL: {#{e.ial.to_md}}", src, con
+			end
+		end 
+		end
+		
+		if not Globals[:debug_keep_ials]
+			elements.delete_if {|x| is_ial(x)} 
+		end
+	end
 		
 end end end end 
 #module MaRuKu; module In; module Markdown; module SpanLevelParser

data/lib/maruku/defaults.rb

@@ -20,9 +20,17 @@
 
 
 module MaRuKu
+	
+Globals = {
+	:unsafe_features => false,
+	
+	:debug_keep_ials => false
+}
+	
 module Defaults
 	DEFAULT_CODE_COLOR = '#fef'
 	
+	# unused
 	DefaultAttributes = <<EOF
 
 {header}:      .mrk-header