patcito-maruku 0.6.0

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/docs/website/src/bluecloth.md

@@ -0,0 +1,25 @@
+
+The other Ruby implementation of Markdown is [Bluecloth]. 
+
+Maruku is much different in philosophy from Bluecloth: the biggest 
+difference is that *parsing* is separated from *rendering*.
+In Maruku, an in-memory representation of the Markdown
+document is created. Instead, Bluecloth mantains the document in
+memory as a String at all times, and does a series of `gsub` 
+to transform to HTML.
+
+Maruku is usually faster than Bluecloth. Bluecloth is faster 
+for very small documents. Bluecloth sometimes chokes on very big
+documents (it is reported that the blame should be on Ruby's regexp 
+implementation).
+
+This is the canonical benchmark (the Markdown specification), 
+executed with Ruby 1.8.5 on a Powerbook 1.5GhZ:
+
+	BlueCloth (to_html): parsing 0.01 sec + rendering 1.87 sec = 1.88 sec   (1.00x)
+	   Maruku (to_html): parsing 0.66 sec + rendering 0.43 sec = 1.09 sec   (1.73x)
+	  Maruku (to_latex): parsing 0.67 sec + rendering 0.23 sec = 0.90 sec   (2.10x)
+
+Please note that Maruku has a lot more features and therefore is 
+looking for much more patterns in the file.
+

data/docs/website/src/download.md

@@ -0,0 +1,31 @@
+### Using rubygems ###
+
+Install with:
+
+	$ gem install maruku
+{:shell}
+
+### Distribution Packages ###
+
+Gentoo: <http://packages.gentoo.org/packages/?category=dev-ruby;name=maruku>
+
+Debian: <http://packages.debian.org/experimental/interpreters/libmaruku-ruby>
+
+### Repository ###
+
+The development site is <http://rubyforge.org/projects/maruku/>.
+
+Released files can also be seen at <http://rubyforge.org/frs/?group_id=2795>.
+
+Anonymous access to the repository is possible with:
+
+	$ svn checkout svn://rubyforge.org/var/svn/maruku/trunk
+{:shell}
+
+Also, each version has a tag:
+
+	$ svn checkout svn://rubyforge.org/var/svn/maruku/tags/0.5.6
+{:shell}
+
+If you want commit access to the repository, just create an account on Rubyforge and drop me a mail.
+

data/docs/website/src/maruku.md

@@ -0,0 +1,261 @@
+CSS: style.css
+Use numbered headers: true
+HTML use syntax: true
+LaTeX use listings: true
+LaTeX CJK: false
+LaTeX preamble: preamble.tex
+
+Maruku features
+===============
+
+Maruku allows you to write in an easy-to-read-and-write syntax, like this:
+
+> [This document in Markdown][this_md] 
+
+Then it can be translated to HTML:
+
+> [This document in HTML][this_html]
+	
+or LaTeX, which is then converted to PDF:
+
+> [This document in PDF][this_pdf]
+
+Maruku implements:
+
+* the original [Markdown syntax][markdown_html] 
+  ([HTML][markdown_html] or [PDF][markdown_pdf]), translated by Maruku.
+
+* all the improvements in [PHP Markdown Extra]. 
+
+* a new [meta-data syntax][meta_data_proposal]
+
+
+
+[romaji]: http://en.wikipedia.org/wiki/Romaji
+[katakana]: http://en.wikipedia.org/wiki/Katakana
+
+[tests]: http://maruku.rubyforge.org/tests/
+[maruku]: http://maruku.rubyforge.org/
+[markdown_html]: http://maruku.rubyforge.org/markdown_syntax.html
+[markdown_pdf]: http://maruku.rubyforge.org/markdown_syntax.pdf
+[this_md]: http://maruku.rubyforge.org/maruku.md
+[this_html]: http://maruku.rubyforge.org/maruku.html
+[this_pdf]: http://maruku.rubyforge.org/maruku.pdf
+[Andrea Censi]: http://www.dis.uniroma1.it/~acensi/
+
+[contact]: http://www.dis.uniroma1.it/~acensi/contact.html
+[gem]: http://rubygems.rubyforge.org/
+[tracker]: http://rubyforge.org/tracker/?group_id=2795
+
+
+[ruby]: http://www.ruby-lang.org
+[bluecloth]: http://www.deveiate.org/projects/BlueCloth
+[Markdown syntax]: http://daringfireball.net/projects/markdown/syntax
+[PHP Markdown Extra]: http://www.michelf.com/projects/php-markdown/extra/
+[math syntax]: http://maruku.rubyforge.org/math.xhtml
+[blahtex]: http://www.blahtex.org
+[ritex]: http://ritex.rubyforge.org
+[itex2mml]: http://golem.ph.utexas.edu/~distler/code/itexToMML/
+[syntax]: http://syntax.rubyforge.org/
+
+[listings]: http://www.ctan.org/tex-archive/macros/latex/contrib/listings/
+[meta_data_proposal]: http://maruku.rubyforge.org/proposal.html
+[markdown-discuss]: http://six.pairlist.net/mailman/listinfo/markdown-discuss
+
+* * *
+
+Table of contents: (**auto-generated by Maruku!**)
+
+* This list will contain the toc (it doesn't matter what you write here)
+{:toc}
+
+* * *
+
+{:ruby:     lang=ruby code_background_color='#efffef'}
+{:shell:    lang=sh code_background_color='#efefff'}
+{:markdown: code_background_color='#ffefef'}
+{:html:     lang=xml}
+
+
+
+
+
+Maruku summary of features                {#features}
+--------------------------
+
+*	Supported syntax
+	
+	*	[Basic Markdown][markdown_syntax]
+	*	[Markdown Extra](#extra)
+	*	[Meta-data syntax](#meta)
+	
+*	Output
+		
+	*	XHTML
+	
+		*	Syntax highlighting via the [`syntax`][syntax] library.
+	
+	*	LaTeX
+
+		*	[Translation of HTML entities to LaTeX](#entities)
+		*	Syntax highlighting via the [`listings`][listings] package.
+
+*	Misc
+
+	*	[Documentation for supported attributes][supported_attributes]
+	
+	*	[Automatic generation of the TOC](#toc-generation)
+
+
+[supported_attributes]: exd.html
+
+**Experimental features (not released yet)**
+
+*	[LaTeX Math syntax][math_syntax] (not enabled by default)
+*	An extension system for adding new syntax is available, 
+	but the API is bound to change in the future, 
+	so please don't use it.
+*	LaTeX to MathML using either one of [`ritex`][ritex], [`itex2mml`][itex2mml], 
+	[`blahtex`][blahtex].
+*	LaTeX to PNG using [`blahtex`][blahtex].
+
+### New meta-data syntax {#meta}
+
+Maruku implements a syntax that allows to attach "meta" information
+to objects.
+
+See [this proposal][meta_data_proposal] for how to attach
+metadata to the elements.
+
+See the [documentation for supported attributes][supported_attributes].
+
+Meta-data for the document itself is specified through the use
+of email headers:
+
+	Title: A simple document containing meta-headers
+	CSS: style.css
+	
+	Content of the document
+{:markdown}
+
+When creating the document through 
+
+	Maruku.new(s).to_html_document
+{:ruby}
+
+the title and stylesheet are added as expected.
+
+Meta-data keys are assumed to be case-insensitive.
+
+
+### Automatic generation of the table of contents ###    {#toc-generation}
+
+If you create a list, and then set the `toc` attribute, when rendering
+Maruku will create an auto-generated table of contents.
+
+	* This will become a table of contents (this text will be scraped).
+	{:toc}
+
+You can see an example of this at the beginning of this document.
+
+### Use HTML entities ### {#entities}
+
+If you want to use HTML entities, go on! We will take care
+of the translation to LaTeX:
+
+Entity      | Result
+------------|----------
+`©`    |  ©
+`£`   |  £
+`λ`  |  λ
+`—`   |  —
+
+See the [list of supported entities][ent_html] ([pdf][ent_pdf]).
+
+[ent_html]: http://maruku.rubyforge.org/entity_test.html
+[ent_pdf]: http://maruku.rubyforge.org/entity_test.pdf
+
+
+### This header contains *emphasis* **strong text** and `code` ####
+
+Note that this header contains formatting and it still works, also in the table of contents.
+
+And [This is a *link* with **all** ***sort*** of `weird stuff`](#features) in the text.
+
+
+Examples of PHP Markdown Extra syntax {#extra}
+-------------------------------------
+
+*	tables
+
+		Col1 | Very very long head | Very very long head|
+		-----|:-------------------:|-------------------:|
+		cell | center-align        | right-align        |
+	{:markdown}
+
+	Col1 | Very very long head | Very very long head|
+	-----|:-------------------:|-------------------:|
+	cell | center-align        | right-align        |
+
+
+*	footnotes [^foot]
+
+		* footnotes [^foot]
+	
+		[^foot]: I really was missing those.
+	{:markdown}
+
+[^foot]: I really was missing those.
+
+*	Markdown inside HTML elements
+
+		<div markdown="1" style="border: solid 1px black">
+		   This is a div with Markdown **strong text**
+		</div>
+	{:html}
+
+	<div markdown="1" style="border: solid 1px black">
+	   This is a div with Markdown **strong text**
+	</div>
+
+
+*	header ids
+
+		## Download ##     {#download}
+	{:markdown}
+
+	For example, [a link to the download](#download) header.
+
+
+*	definition lists
+
+		Definition list
+		: something very hard to parse
+	{:markdown}
+
+	Definition list
+	: something very hard to parse
+
+*	abbreviations or ABB for short.
+
+*[ABB]: Simply an abbreviation
+
+
+<script src="http://www.google-analytics.com/urchin.js" type="text/javascript">
+</script>
+<script type="text/javascript">
+_uacct = "UA-155626-2";
+urchinTracker();
+</script>
+
+<!--
+Future developments                              {#future}
+
+I think that [Pandoc] and [MultiMarkdown] are very cool projects.
+However, they are written in Haskell and Perl, respectively. 
+I would love to have an equivalent in Ruby.
+
+[Pandoc]: http://sophos.berkeley.edu/macfarlane/pandoc/
+[MultiMarkdown]: http://fletcher.freeshell.org/wiki/MultiMarkdown
+
+-->