patcito-maruku 0.6.0

data/docs/website/src/proposal.md

@@ -0,0 +1,271 @@
+CSS: style.css
+LaTeX_use_listings: true
+html_use_syntax: true
+use_numbered_headers: true
+
+Meta-data syntax implemented by Maruku
+======================================
+
+This document describes a syntax for attaching meta-data to
+block-level elements (headers, paragraphs, code blocks,…), 
+and to span-level elements (links, images,…).
+
+
+*Table of contents:*
+
+> * Table of contents
+> {:toc}
+
+Overview
+--------
+
+This proposal describes two additions to the Markdown syntax:
+
+1. inline attribute lists (IAL)
+
+   	## Header ##       {: key=val .class #id ref_id}
+
+2. attribute lists definitions (ALD)
+
+   	{:ref_id: key=val .class #id}
+
+Every span-level or block-level element can be followed by an IAL:
+
+	### Header ###     {: #header1 class=c1}
+	
+	Paragraph *with emphasis*{: class=c1}
+	second line of paragraph
+	{: 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}
+
+	Paragraph *with emphasis*{:c1}
+	second line of paragraph
+	{:c1}
+	
+	{:c1: class=c1}
+
+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}
+
+More in particular, an attribute list is a   whitespace-separated list 
+of elements of 4 different kinds:
+
+1. key/value pairs (quoted if necessary)
+2. [references to ALD](#using_tags) (`ref1`,`ref2`)
+3. [id specifiers](#class_id) (`#myid`)
+4. [class specifiers](#class_id) (`.myclass`) 
+
+### `id` and `class` are special ### {#class_id}
+
+For ID and classes there are special shortcuts:
+
+* `#myid` is a shortcut for `id=myid`
+* `.myclass` means "add `myclass` to the current `class` attribute".
+
+  So these are equivalent:
+
+  	{: .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}
+
+Where to put inline attribute lists
+----------------------------------
+
+### For block-level elements ###
+
+For paragraphs and other block-level elements, IAL go
+**after** the element:
+
+	This is a paragraph.
+	Line 2 of the paragraph.
+	{: #myid .myclass}
+	
+	A quote with a citation url:
+	> Who said that?
+	{: cite=google.com}
+
+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}
+
+Attribute lists may be indented up to 3 spaces:
+
+	Paragraph1
+	 {:ok}
+	
+	Paragraph2
+	  {:ok}
+	
+	Paragraph2
+	   {:ok}
+{:code_show_spaces}
+
+### For headers ###
+
+For headers, you can put attribute lists on the same line:
+
+	### Header ###     {: #myid}
+
+	Header     {: #myid .myclass}
+	------
+
+or, as like other block-level elements, on the line below:
+
+	### Header ###     
+	{: #myid}
+
+	Header     
+	------
+	{: #myid .myclass}
+
+### For span-level elements ###
+
+For span-level elements, meta-data goes immediately **after** in the 
+flow.
+
+For example, in this:
+
+	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}
+
+For images, this:
+
+	This is ![Alt text](url "fresh carrots")
+
+is equivalent to:
+	
+	This is ![Alt text](url){:title="fresh carrots"}
+
+Using attributes lists definition    {#using_tags}
+---------------------------------
+
+In an attribute list, you can have: 
+
+1. `key=value` pairs,
+2. id attributes (`#myid`)
+3. class attributes (`.myclass`) 
+
+Everything else is interpreted as a reference to 
+an ALD.
+
+	# Header #      {:ref}
+
+	Blah blah blah.
+	
+	{:ref: #myhead .myclass lang=fr}
+
+Of course, more than one IAL can reference the same ALD:
+
+	# Header 1 #      {:1}
+	...
+	# Header 2 #      {:1}
+
+	{:1: .myclass lang=fr}
+
+
+The rules           {:#grammar}
+---------
+
+### The issue of escaping ###
+
+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]`).
+
+3.	As a rule, quotes **must** be escaped inside quoted values:
+
+	* Inside `"quoted values"`, you **must** escape `"`.
+	* Inside `'quoted values'`, you **must** escape `'`.
+
+	* Other examples:
+
+	`"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:
+
+       [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" }
+	
+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 **must** escape the other kind of quote.
+
+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.
+
+### Just skip, if you want ####
+
+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}
+
+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 `\}`.
+
+For this example,
+
+	this is 
+	{: skipped="\}" val=\} bar} 
+	
+	for me 
+	{: also this} 
+
+the result is:
+
+	this is 
+	 
+	
+	for me 
+ 
+

data/lib/maruku.rb

@@ -0,0 +1,132 @@
+#   Copyright (C) 2006  Andrea Censi  <andrea (at) rubyforge.org>
+#
+# This file is part of Maruku.
+#
+#   Maruku is free software; you can redistribute it and/or modify
+#   it under the terms of the GNU General Public License as published by
+#   the Free Software Foundation; either version 2 of the License, or
+#   (at your option) any later version.
+#
+#   Maruku is distributed in the hope that it will be useful,
+#   but WITHOUT ANY WARRANTY; without even the implied warranty of
+#   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+#   GNU General Public License for more details.
+#
+#   You should have received a copy of the GNU General Public License
+#   along with Maruku; if not, write to the Free Software
+#   Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
+
+dir = File.dirname(__FILE__)
+$LOAD_PATH.unshift dir unless $LOAD_PATH.include?(dir)
+
+require 'rexml/document'
+
+module MaRuKu
+  module In
+    module Markdown
+      module SpanLevelParser; end
+      module BlockLevelParser; end
+    end
+  end
+
+  module Out
+    module Markdown; end
+    module HTML; end
+    module Latex; end
+  end
+
+  module Strings; end
+
+  module Helpers; end
+
+  module Errors; end
+
+  class MDElement
+    include REXML
+    include MaRuKu
+    include Out::Markdown
+    include Out::HTML
+    include Out::Latex
+    include Strings
+    include Helpers
+    include Errors
+  end
+
+
+  class MDDocument < MDElement
+    include In::Markdown
+    include In::Markdown::SpanLevelParser
+    include In::Markdown::BlockLevelParser
+  end
+end
+
+class Maruku < MaRuKu::MDDocument; end
+
+
+# Structures definition
+require 'maruku/structures'
+require 'maruku/structures_inspect'
+
+require 'maruku/defaults'
+# Less typing
+require 'maruku/helpers'
+
+# Code for parsing whole Markdown documents
+require 'maruku/input/parse_doc'
+
+# Ugly things kept in a closet
+require 'maruku/string_utils'
+require 'maruku/input/linesource'
+require 'maruku/input/type_detection'
+
+# A class for reading and sanitizing inline HTML
+require 'maruku/input/html_helper'
+
+# Code for parsing Markdown block-level elements
+require 'maruku/input/parse_block'
+
+# Code for parsing Markdown span-level elements
+require 'maruku/input/charsource'
+require 'maruku/input/parse_span_better'
+require 'maruku/input/rubypants'
+
+require 'maruku/input/extensions'
+
+require 'maruku/attributes'
+
+require 'maruku/structures_iterators'
+
+require 'maruku/errors'
+
+# Code for creating a table of contents
+require 'maruku/toc'
+
+# Support for div Markdown extension
+require 'maruku/ext/div'
+# Support for fenced codeblocks extension
+require 'maruku/ext/fenced_code'
+
+# Version and URL
+require 'maruku/version'
+
+
+# Exporting to html
+require 'maruku/output/to_html'
+
+# Exporting to latex
+require 'maruku/output/to_latex'
+require 'maruku/output/to_latex_strings'
+require 'maruku/output/to_latex_entities'
+
+# Pretty print
+require 'maruku/output/to_markdown'
+
+# S5 slides
+require 'maruku/output/s5/to_s5'
+require 'maruku/output/s5/fancy'
+
+# Exporting to text: strips all formatting (not complete)
+require 'maruku/output/to_s'
+
+# class Maruku is the global interface
+require 'maruku/maruku'

data/lib/maruku/attributes.rb

@@ -0,0 +1,138 @@
+#   Copyright (C) 2006  Andrea Censi  <andrea (at) rubyforge.org>
+#
+# This file is part of Maruku.
+#
+#   Maruku is free software; you can redistribute it and/or modify
+#   it under the terms of the GNU General Public License as published by
+#   the Free Software Foundation; either version 2 of the License, or
+#   (at your option) any later version.
+#
+#   Maruku is distributed in the hope that it will be useful,
+#   but WITHOUT ANY WARRANTY; without even the implied warranty of
+#   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+#   GNU General Public License for more details.
+#
+#   You should have received a copy of the GNU General Public License
+#   along with Maruku; if not, write to the Free Software
+#   Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
+
+
+module MaRuKu
+  # This represents a list of attributes specified in the Markdown document
+  # that apply to a Markdown-generated tag.
+  # What was `{#id .class key="val" ref}` in the Markdown
+  # is parsed into `[[:id, 'id'], [:class, 'id'], ['key', 'val'], [:ref, 'ref']]`.
+  class AttributeList < Array
+    def to_s
+      map do |k, v|
+        case k
+        when :id;    "#" + quote_if_needed(v)
+        when :class; "." + quote_if_needed(v)
+        when :ref;    quote_if_needed(v)
+        else quote_if_needed(k) + "=" + quote_if_needed(v)
+        end
+      end.join(' ')
+    end
+    alias to_md to_s
+
+    private
+
+    def quote_if_needed(str)
+      return str unless str =~ /[\s'"]/
+      str.inspect
+    end
+  end
+
+  module In::Markdown::SpanLevelParser
+    def md_al(s = []); AttributeList.new(s); end
+
+    # @return [AttributeList, nil]
+    def read_attribute_list(src, con, break_on_chars)
+      separators = break_on_chars + [?=, ?\s, ?\t]
+      escaped = Maruku::EscapedCharInQuotes
+
+      al = AttributeList.new
+      loop do
+        src.consume_whitespace
+        break if break_on_chars.include? src.cur_char
+
+        case src.cur_char
+        when nil
+          maruku_error "Attribute list terminated by EOF:\n #{al.inspect}", src, con
+          tell_user "Returning partial attribute list:\n #{al.inspect}"
+          break
+        when ?=     # error
+          src.ignore_char
+          maruku_error "In attribute lists, cannot start identifier with `=`."
+          tell_user "Ignoring and continuing."
+        when ?#     # id definition
+          src.ignore_char
+          if id = read_quoted_or_unquoted(src, con, escaped, separators)
+            al << [:id, id]
+          else
+            maruku_error 'Could not read `id` attribute.', src, con
+            tell_user 'Ignoring bad `id` attribute.'
+          end
+        when ?.     # class definition
+          src.ignore_char
+          if klass = read_quoted_or_unquoted(src, con, escaped, separators)
+            al << [:class, klass]
+          else
+            maruku_error 'Could not read `class` attribute.', src, con
+            tell_user 'Ignoring bad `class` attribute.'
+          end
+        else
+          unless key = read_quoted_or_unquoted(src, con, escaped, separators)
+            maruku_error 'Could not read key or reference.'
+            next
+          end
+
+          if src.cur_char != ?=
+            al << [:ref, key]
+            next
+          end
+
+          src.ignore_char # skip the =
+          if val = read_quoted_or_unquoted(src, con, escaped, separators)
+            al << [key, val]
+          else
+            maruku_error "Could not read value for key #{key.inspect}.", src, con
+            tell_user "Ignoring key #{key.inspect}"
+          end
+        end
+      end
+      al
+    end
+
+    def merge_ial(elements, src, con)
+      # Apply each IAL to the element before
+      (elements + [nil]).each_cons(3) do |before, e, after|
+        next unless ial?(e)
+
+        if before.kind_of? MDElement
+          before.al = e.ial
+        elsif after.kind_of? MDElement
+          after.al = e.ial
+        else
+          maruku_error <<ERR, src, con
+It's unclear which element the attribute list {:#{e.ial.to_md}}
+is referring to. The element before is a #{before.class},
+the element after is a #{after.class}.
+  before: #{before.inspect}
+  after: #{after.inspect}
+ERR
+        end
+      end
+
+      unless Globals[:debug_keep_ials]
+        elements.delete_if {|x| ial?(x) && x != elements.first}
+      end
+    end
+
+    private
+
+    def ial?(e)
+      e.is_a?(MDElement) && e.node_type == :ial
+    end
+  end
+end