maruku 0.4.2.1 → 0.5.0

data/docs/maruku.md

@@ -2,16 +2,16 @@ CSS: style.css
 Use numbered headers: true
 HTML use syntax: true
 LaTeX use listings: true
-LaTeX CJK: true
+LaTeX CJK: false
 
 ![MaRuKu](logo.png){#logo}
 
 Mar**u**k**u**: a Markdown-superset interpreter 
 ===============================================
 
-[Maruku][] is a Markdown interpreter written in [Ruby][].
+[Maruku] is a Markdown interpreter written in [Ruby].
 
-> [Last release](#release_notes) is version 0.4.2 -- 2007-01-12.
+> [Last release](#release_notes) is version 0.5.0 -- 2007-01-23.
 >
 > Use this command to update:
 >
@@ -37,16 +37,16 @@ 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][]. 
+* all the improvements in [PHP Markdown Extra]. 
 
-* a new [meta-data syntax][meta]
+* a new [meta-data syntax][meta_data_proposal]
 
 
-__Authors__: Maruku has been developed so far by [Andrea Censi][].
+__Authors__: Maruku has been developed so far by [Andrea Censi].
 Contributors are most welcome!
 
-__The name of the game__: Maruku is the [romaji][] transliteration of 
-the [katakana][] transliteration
+__The name of the game__: Maruku is the [romaji] transliteration of 
+the [katakana] transliteration
 of "Mark", the first word in Markdown. I chose this name because Ruby 
 is Japanese, and also the sillable "ru" appears in Maruku.
 
@@ -63,6 +63,25 @@ is Japanese, and also the sillable "ru" appears in Maruku.
 [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!**)
@@ -92,142 +111,7 @@ please write to the [Markdown-discuss mailing list][markdown-discuss].
 
 Have fun!
 
-
-#### Changes in 0.4.2 ####     {#last}
-
-*	Adapted syntax to the [new meta-data proposal][proposal].
-
-*	Changes in LaTeX export: 
-
-	*	Links to external URLs are blue by default.
-
-	*	New attributes: `latex_preamble` to add a custom preamble,
-		and `latex_cjk` to add packages for UTF-8 Japanese characters.
-		(**support for this is still shaky**). Example:
-	
-			Title: my document
-			LaTeX CJK: true
-			LaTeX preamble: preamble.tex
-		
-			Content
-
-*	Bug fixes
-
-	+ Images were not given `id` or `class` attributes.
-
-	+ Fixed bug in LaTeX export with handling of `<`,`>` enclosed URLs: `<google.com>`.
-
-#### Changes in 0.4.1 aka "Typographer" ####
-
-*	Implemented SmartyPants support:
-
-		'Twas a "test" to 'remember' -- in the '90s 
-		--- while I was <<ok>>. She was 6\"12\'.
-	> 'Twas a "test" to 'remember' -- in the '90s --- while I was <<ok>>.
-	> She was 6\"12\'.
-
-	I adapted the code from RubyPants.
-	
-*	Server directives between `<? ?>` are properly preserved.
-*	Changes in LaTeX export:
-
-	*	Now Japanese text rendering sort of works, using the following packages:
-
-			\usepackage[C40]{fontenc}
-			\usepackage[cjkjis]{ucs}
-			\usepackage[utf8x]{inputenc}
-		
-		Nevertheless, I could only get bitmap fonts working -- probably it's a problem
-		with my setup.
-
-		A quick test: 日本、中国、ひらがな、カタカナ。
-
-	*	Fixed bugs in rendering of immediate links.
-	*	External packages are `require`d only if needed.
-	*	More symbols supported.
-		See the symbol list 
-		[in HTML](http://maruku.rubyforge.org/entity_test.html) and
-		[in PDF](http://maruku.rubyforge.org/entity_test.pdf).
-
-
-#### Changes in 0.4 ####
-
-* First implementation of [the new meta-data syntax][meta].
-* General refactorization of the code and much cleaner error reporting.
-* Created [the RDOC documentation][rdoc].
-* The `add_whitespace` method took too much time -- it was O(n^2).
-* Added unit-tests for block-level elements.
-
-[rdoc]: http://maruku.rubyforge.org/rdoc/
-[meta]: http://maruku.rubyforge.org/proposal.html
-
-#### Changes in 0.3 ####
-
-*	A real parser is used instead of a regexp-based system, also for span-level 
-	elements.
-
-	Now Maruku is almost 2x faster than Bluecloth, while having more features.
-
-	Here are some benchmarks:
-	
-		BlueCloth (to_html): parsing 0.00 sec + rendering 1.54 sec = 1.55 sec 
-		Maruku (to_html):    parsing 0.47 sec + rendering 0.38 sec = 0.85 sec 
-		Maruku (to_latex):   parsing 0.49 sec + rendering 0.25 sec = 0.73 sec
-		
-	This is the result of running `lib/maruku/tests/benchmark.rb` on the Markdown 
-	specification.
-
-*	Prettier HTML output by adding whitespace.
- 
-*	Added a full suite of unit-tests for the span-level parser.
-
-*	Error management: Having a real parser, Maruku warns you about syntax issues.
-	
-	The default action is to warn and try to continue. If you do this:
-
-		Maruku.new(string, {:on_error => :raise})
-
-	then syntax errors will cause an exception to be raised (you can catch this
-	and retry).
-
-*	Fixed a series of bugs in handling inline HTML code.
-
-Immediate TODO-list:
-
-*	UTF-8 input/output works OK for HTML, however I am having pain trying to export
-	to LaTeX. I want at least Japanese characters support, so if you know how to 
-	do this you are very welcome to give me an hand.
-	
-	For example: in the HTML version, you should see accented characters in this
-	parenthesis: 
-	
-	> (àèìòù)
-	
-	and Japanese text in these other parentheses: 
-	
-	> (カタカナで 私の 名前は アンドレア チェンシ です).
-	>
-	> (日本のガルは 大好き、でも、日本語は難しですから、そうぞ 英語話すガルを おしえてください).
-	
-	In the LaTeX version, these do not appear. I know how to do LaTeX with 
-	ISO-8859-1 encoding (European characters), but I'm struggling with half-baked 
-	solutions for UTF-8 encoded documents.
-
-*	Implement the [new meta-data proposal][proposal].
-
-*	Exporting to Markdown (pretty printing).
-
-*	Exporting to HTML splitting in multiple files.
-
-*	RubyPants.
-
-*	Support for images in PDF.
-
-
-[proposal]: http://maruku.rubyforge.org/proposal.html
-[contact]: http://www.dis.uniroma1.it/~acensi/contact.html
-[markdown-discuss]: http://six.pairlist.net/mailman/listinfo/markdown-discuss
-[tracker]: http://rubyforge.org/tracker/?group_id=2795
+See the [changelog](http://maruku.rubyforge.org/changelog.html#stable).
 
 Download       {#download}
 --------
@@ -244,24 +128,22 @@ 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
+	$ svn checkout svn://rubyforge.org/var/svn/maruku/trunk
 
   {:shell}
 
-If you want commit access to the repository, just create an account on Rubyforge and [drop me a mail][drop].
-
-[drop]: http://www.dis.uniroma1.it/~acensi/contact.html
-[gem]: http://rubygems.rubyforge.org/
+If you want commit access to the repository, just create an account on Rubyforge and [drop me a mail][contact].
 
 ### Bugs report ###
 
-Use the [tracker][tracker] or [drop me an email][drop].
+Use the [tracker][tracker] or [drop me an email][contact].
 
-[tracker]: http://rubyforge.org/tracker/?group_id=2795
 
 Usage
 --------
 
+### Embedded Maruku ###
+
 This is the basic usage:
 
 	require 'rubygems'
@@ -286,118 +168,97 @@ You can have the REXML document tree with:
 
 ### From the command line ###
 
-There are two command-line programs installed: `maruku` and `marutex`.
-
-*	`maruku` converts Markdown to HTML:
-
-		$ maruku file.md  # creates file.html
-	{:shell}
-
-* 	`marutex` converts Markdown to LaTeX, then calls `pdflatex` to 
-	transform to PDF:
-
-		$ marutex file.md  # creates file.tex and file.pdf
-	{:shell}
-
-
-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}
+There is one command-line program installed: `maruku`.
 
-[^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}
+Without arguments, it converts  Markdown to HTML:
 
-	<div markdown="1" style="border: solid 1px black">
-	   This is a div with Markdown **strong text**
-	</div>
+	$ maruku file.md  # creates file.html
+{:shell}
 
+With the `--pdf` arguments, it converts Markdown to LaTeX, then calls `pdflatex` to 
+transform to PDF:
 
-*	header ids
+	$ maruku --pdf file.md  # creates file.tex and file.pdf
+{:shell}
 
-		## Download ##     {#download}
-	{:markdown}
 
-	For example, [a link to the download](#download) header.
+Maruku and Bluecloth          {#maruku-and-bluecloth}
+--------------------
 
+The other Ruby implementation of Markdown is [Bluecloth]. 
 
-*	definition lists
+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.
 
-		Definition list
-		: something very hard to parse
-	{:markdown}
+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).
 
-	Definition list
-	: something very hard to parse
+This is the canonical benchmark (the Markdown specification), 
+executed with Ruby 1.8.5 on a Powerbook 1.5GhZ:
 
-*	abbreviations or ABB for short.
+	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)
 
-*[ABB]: Simply an abbreviation
+Please note that Maruku has a lot more features and therefore is 
+looking for much more patterns in the file.
 
 
 
-Maruku and Bluecloth          {#maruku-and-bluecloth}
---------------------
+Maruku summary of features
+--------------------------
 
-The other Ruby implementation of Markdown is [Bluecloth][]. 
+*	Supported syntax
+	
+	*	[Basic Markdown][markdown_syntax]
+	*	[Markdown Extra](#extra)
+	*	[Meta-data syntax](#meta)
+	
+*	Output
+		
+	*	XHTML
+	
+		*	Syntax highlighting via the [`syntax`][syntax] library.
+	
+	*	LaTeX
 
-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.
+		*	[Translation of HTML entities to LaTeX](#entities)
+		*	Syntax highlighting via the [`listings`][listings] package.
 
-The in-memory representation makes it very easy to export
-to various formats (at the moment HTML and LaTeX/PDF; 
-the next is pretty-printed Markdown).
+*	Misc
 
-Other improvements over Bluecloth:
+	*	[Documentation for supported attributes][supported_attributes]
+	
+	*	[Automatic generation of the TOC](#toc-generation)
 
-* the HTML output is provided also as a `REXML` document tree.
 
-* PHP Markdown Syntax support.
+[supported_attributes]: exd.html
 
-[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/
+**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}
---------------------
+### New meta-data syntax {#meta}
 
 Maruku implements a syntax that allows to attach "meta" information
 to objects.
 
-### Meta-data for block-level and span-level elements ###
-
-See [this proposal][meta].
+See [this proposal][meta_data_proposal] for how to attach
+metadata to the elements.
 
-### Meta-data for the document ###
+See the [documentation for supported attributes][supported_attributes].
 
 Meta-data for the document itself is specified through the use
 of email headers:
@@ -420,154 +281,108 @@ the title and stylesheet are added as expected.
 Meta-data keys are assumed to be case-insensitive.
 
 
-* * *
-
-
-### List of meta-data  ###    {#metalist}
-
-[listings]: http://www.ctan.org/tex-archive/macros/latex/contrib/listings/
+### Automatic generation of the table of contents ###    {#toc-generation}
 
-**`title`, `subject`**
-: (document) Sets the title of the document (HTML: used in the `TITLE` element).
+If you create a list, and then set the `toc` attribute, when rendering
+Maruku will create an auto-generated table of contents.
 
-**`use_numbered_headers`**
-: (document) If `true`, headers are numbered (just like this document). Default is `false`.
+	* This will become a table of contents (this text will be scraped).
+	{:toc}
 
-**`css`**
-: (document, HTML) Url of stylesheet.
+You can see an example of this at the beginning of this document.
 
-**`html_use_syntax`**
-: (document, HTML) If set, use the [Ruby `syntax` library][syntax] to add source highlighting.
+### Use HTML entities ### {#entities}
 
-**`latex_use_listings`**
-: (document, LaTeX) If set, use the fancy [`listings` package][listings] for better displaying code blocks.
-     
-     If not set,  use standard `verbatim` environment.
+If you want to use HTML entities, go on! We will take care
+of the translation to LaTeX:
 
-**`style`, `id`, `class`**
-: (any block object, HTML) Standard CSS attributes are copied.
+Entity      | Result
+------------|----------
+`&copy;`    |  &copy;
+`&pound;`   |  &pound;
+`&lambda;`  |  &lambda;
+`&mdash;`   |  &mdash;
 
-**`lang`**
-: (code blocks) Name of programming language (`ruby`) for syntax highlighting.
+See the [list of supported entities][ent_html] ([pdf][ent_pdf]).
 
-      Default for this is `code_lang` in document.
-      
-      Syntax highlighting is delegated to the [`syntax` library][syntax] for
-      HTML output and to the [`listings` package][listings] for LaTeX output.
+[ent_html]: http://maruku.rubyforge.org/entity_test.html
+[ent_pdf]: http://maruku.rubyforge.org/entity_test.pdf
 
 
-**`code_show_spaces`**
-: Shows tabs and newlines (default is read in the document object).
+### This header contains *emphasis* **strong text** and `code` ####
 
-**`code_background_color`**
-: Background color for code blocks. (default is read in the document object).
+Note that this header contains formatting and it still works, also in the table of contents.
 
-    The format is either a named color (`green`, `red`) or a CSS color
-    of the form `#ff00ff`. 
+And [This is a *link* with **all** ***sort*** of `weird stuff`](#features) in the text.
 
-    * for **HTML output**, the value is put straight in the `background-color` CSS 
-      property of the block.
 
-    * for **LaTeX output**, if it is a named color, it must be a color accepted
-      by the LaTeX `color` packages. If it is of the form `#ff00ff`, Maruku
-      defines a color using the `\color[rgb]{r,g,b}` macro. 
+Examples of PHP Markdown Extra syntax {#extra}
+-------------------------------------
 
-      For example, for `#0000ff`, the macro is called as: `\color[rgb]{0,0,1}`.
+*	tables
 
-[syntax]: http://syntax.rubyforge.org/
+		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        |
 
-### Examples ###
 
-An example of this is the following:
+*	footnotes [^foot]
 
-		 One space
-		  Two spaces
-			 	Tab, space, tab
-					Tab, tab, tab and all is green!
-	{:code_show_spaces code_background_color=#ffeedd}
-{:markdown}
+		* footnotes [^foot]
 	
-That will produce:
-
-	 One space
-	  Two spaces
-		 	Tab, space, tab
-				Tab, tab, tab and all is green!
-{:code_show_spaces code_background_color=#ffeedd}
-
-
-Or highlighting (support depends on languages):
-
-		<div style="text-align:center">Div</div>
-	{:lang=html}
-
-produces:
-
-	<div style="text-align:center">Div</div>
-{:lang=html}
-
+		[^foot]: I really was missing those.
+	{:markdown}
 
+[^foot]: I really was missing those.
 
-* * *
+*	Markdown inside HTML elements
 
-Other Features      {#features}
---------------
+		<div markdown="1" style="border: solid 1px black">
+		   This is a div with Markdown **strong text**
+		</div>
+	{:html}
 
-### Automatic generation of the table of contents ###
+	<div markdown="1" style="border: solid 1px black">
+	   This is a div with Markdown **strong text**
+	</div>
 
-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}
+*	header ids
 
-You can see an example of this at the beginning of this document.
+		## Download ##     {#download}
+	{:markdown}
 
-### This header contains *emphasis* **strong text** and `code` ####
+	For example, [a link to the download](#download) header.
 
-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.
+*	definition lists
 
-### Use HTML entities ###
+		Definition list
+		: something very hard to parse
+	{:markdown}
 
-If you want to use HTML entities, go on! We will take care
-of the translation to LaTeX:
+	Definition list
+	: something very hard to parse
 
-Entity      | Result
-------------|----------
-`&copy;`    |  &copy;
-`&pound;`   |  &pound;
-`a&nbsp;b`  |  a&nbsp;b
-`&lambda;`  |  &lambda;
-`&mdash;`   |  &mdash;
+*	abbreviations or ABB for short.
 
+*[ABB]: Simply an abbreviation
 
 
 
+<!--
 Future developments                              {#future}
--------------------
 
-I think that [Pandoc][] and [MultiMarkdown][] are very cool projects.
+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
 
-
-### A syntax for adding math ###
-
-Something inspired from LaTeX should be familiar to all:
-
-	This is inline math: $\alpha$
-
-
-	This is an equation with label:
-
-	$ \alpha = \beta + \gamma  $        (eq:1)
-
-	This is a reference to equation: please see (eq:1)
-
-
+-->