remi-maruku 0.5.9

data/docs/other_stuff.md

@@ -0,0 +1,51 @@
+*	*Jan. 22*  With very minimal changes, Maruku now works in JRuby. 
+	It is very slow, though.
+
+	Some benchmarks:
+
+	*	G4 1.5GhZ, Ruby 1.8.5:
+	
+			Maruku (to_html): parsing 0.65 sec + rendering 0.40 sec = 1.04 sec
+			Maruku (to_latex): parsing 0.70 sec + rendering 0.21 sec = 0.91 sec
+
+	*	G4 1.5GhZ, JRuby 1.9.2:
+
+			Maruku (to_html): parsing 4.77 sec + rendering 2.24 sec = 7.01 sec
+			Maruku (to_latex): parsing 4.04 sec + rendering 1.12 sec = 5.16 sec
+
+*	*Jan. 21*  Integration of Blahtex. PNG export of formula and alignment works
+	ok in Mozilla, Safari, Camino, Opera. IE7 is acting strangely.
+
+*	Support for LaTeX-style formula input, and export to MathML. 
+
+	[Jacques Distler] is integrating Maruku into Instiki (a Ruby On Rails-based wiki software), as to have a Ruby wiki with proper math support. You know, these physicists like all those funny symbols.
+
+	*	To have the MathML export, it is needed to install one of:
+	
+		* 	[RiTeX]   (`gem install ritex`) 
+		* 	[itex2MML] supports much more complex formulas than Ritex.
+		* 	PNG for old browser is not here yet. The plan is to use
+			BlahTeX.
+
+
+*	Command line options for the `maruku` command:
+
+		Usage: maruku [options] [file1.md [file2.md ...
+		    -v, --[no-]verbose               Run verbosely
+		    -u, --[no-]unsafe                Use unsafe features
+		    -b                               Break on error
+		    -m, --math-engine ENGINE         Uses ENGINE to render MathML
+		        --pdf                        Write PDF
+		        --html                       Write HTML
+		        --tex                        Write LaTeX
+		        --inspect                    Shows the parsing result
+		        --version                    Show version
+		    -h, --help                       Show this message
+
+*	Other things:
+	
+	*	Created the embryo of an extension system. Please don't use it
+		yet, as probably the API is bound to change.
+
+	*	There are a couple of hidden, unsafe, features that are not enabled by default.
+

data/docs/proposal.md

@@ -0,0 +1,309 @@
+CSS: style.css
+LaTeX_use_listings: true
+html_use_syntax: true
+use_numbered_headers: true
+
+Proposal for adding a meta-data syntax to Markdown
+=============================================
+
+This document describes a syntax for attaching meta-data to
+block-level elements (headers, paragraphs, code blocks,…), 
+and to span-level elements (links, images,…).
+
+***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}
+
+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.
+
+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,141 @@
+#--
+#   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
+#++
+$:.unshift File.dirname(__FILE__)
+
+require 'rexml/document'
+
+# :include:MaRuKu.txt
+module MaRuKu
+
+	module In
+		module Markdown
+			module SpanLevelParser; end
+			module BlockLevelParser; end
+		end
+		# more to come?
+	end
+
+	module Out
+		# Functions for exporting to MarkDown.
+		module Markdown; end
+		# Functions for exporting to HTML.
+		module HTML; end
+		# Functions for exporting to Latex
+		module Latex; end
+	end
+		
+	# These are strings utilities.
+	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
+
+# This is the public interface
+class Maruku < MaRuKu::MDDocument; end
+
+
+
+require 'rexml/document'
+
+# 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_management'
+
+# Code for creating a table of contents
+require 'maruku/toc'
+
+# 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'
+
+# require the new DIV syntax, by default
+require 'maruku/ext/div'