docs/maruku.html in maruku-0.2.13 vs docs/maruku.html in maruku-0.3.0

- old
+ new

@@ -1,118 +1,683 @@ -<?xml version='1.0' ?> +<?xml version='1.0' encoding='utf-8'?> <!DOCTYPE html PUBLIC '-//W3C//DTD XHTML 1.0 Strict//EN' 'http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd'> -<html lang='en' xml:lang='en' xmlns='http://www.w3.org/1999/xhtml'><head><title>Maruku: a Markdown interpreter</title><link href='style.css' rel='stylesheet' type='text/css' /></head><head><title>Maruku: a Markdown interpreter</title><link href='style.css' rel='stylesheet' type='text/css' /></head><body><h1 id='maruku_a_markdown_interpreter'>Mar<strong>u</strong>k<strong>u</strong>: a Markdown interpreter</h1><p><a href='http://maruku.rubyforge.org/&gt;'>Maruku</a> is a Markdown interpreter written in <a href='http://www.ruby-lang.org'>Ruby</a>.</p><p>Maruku allows you to write in an easy-to-read-and-write syntax, like this:</p><blockquote><p><a href='http://maruku.rubyforge.org/maruku.md'>This document in Markdown</a></p></blockquote><p>Then it can be translated to HTML:</p><blockquote><p><a href='http://maruku.rubyforge.org/maruku.html'>This document in HTML</a></p></blockquote><p>or LaTeX, which is then converted to PDF:</p><blockquote><p><a href='http://maruku.rubyforge.org/maruku.pdf'>This document in PDF</a></p></blockquote><p>Maruku implements:</p><ul><li><p>the original <a href='http://daringfireball.net/projects/markdown/syntax'>Markdown syntax</a> (<a href='http://maruku.rubyforge.org/markdown_syntax.html'>HTML</a> o <a href='http://maruku.rubyforge.org/markdown_syntax.pdf'>PDF</a>, translated by Maruku)</p></li><li><p>all the improvements in <a href='http://www.michelf.com/projects/php-markdown/extra/'>PHP Markdown Extra</a>.</p></li><li><p>a new <a href='#meta'>meta-data syntax</a></p></li><li><p>some ideas from <a href='http://fletcher.freeshell.org/wiki/MultiMarkdown'>MultiMarkdown</a></p><ul><li>attributes in image links</li></ul></li></ul><p>The <a href='http://maruku.rubyforge.org/tests/'>test directory</a> is quite messy but it shows every capability.</p><h3 id='authors'>Authors</h3><p>Maruku has been developed so far by <a href='http://www.dis.uniroma1.it/~acensi/'>Andrea Censi</a>. Contributors are most welcome!</p><hr /><p>Table of contents: (<strong>auto-generated by Maruku!</strong>)</p><div class='maruku_toc'><ul style='list-style: none;'><li><span class='maruku_section_number'>1. </span><a href='#download' class='head'>Download</a><ul style='list-style: none;'><li><span class='maruku_section_number'>1.1. </span><a href='#bugs_report'>Bugs report</a></li></ul></li><li><span class='maruku_section_number'>2. </span><a href='#usage'>Usage</a><ul style='list-style: none;'><li><span class='maruku_section_number'>2.1. </span><a href='#from_the_command_line'>From the command line</a></li></ul></li><li><span class='maruku_section_number'>3. </span><a href='#extra'>Examples of PHP Markdown Extra syntax</a></li><li><span class='maruku_section_number'>4. </span><a href='#maruku-and-bluecloth'>Maruku and Bluecloth</a></li><li><span class='maruku_section_number'>5. </span><a href='#meta'>New meta-data syntax</a><ul style='list-style: none;'><li><span class='maruku_section_number'>5.1. </span><a href='#metadata_for_the_document'>Meta-data for the document</a></li><li><span class='maruku_section_number'>5.2. </span><a href='#metadata_for_elements'>Meta-data for elements</a></li><li><span class='maruku_section_number'>5.3. </span><a href='#shortcuts'>Shortcuts</a></li><li><span class='maruku_section_number'>5.4. </span><a href='#metalist'>List of meta-data</a></li><li><span class='maruku_section_number'>5.5. </span><a href='#examples'>Examples</a></li></ul></li><li><span class='maruku_section_number'>6. </span><a href='#features'>Other Features</a><ul style='list-style: none;'><li><span class='maruku_section_number'>6.1. </span><a href='#automatic_generation_of_the_table_of_contents'>Automatic generation of the table of contents</a></li><li><span class='maruku_section_number'>6.2. </span><a href='#this_header_contains_emphasis_strong_text_and_'>This header contains <em>emphasis</em> <strong>strong text</strong> and <tt style='background-color: #f0f0e0;'>code</tt></a></li><li><span class='maruku_section_number'>6.3. </span><a href='#use_html_entities'>Use HTML entities</a></li></ul></li><li><span class='maruku_section_number'>7. </span><a href='#todo_list'>TODO list</a></li><li><span class='maruku_section_number'>8. </span><a href='#future'>Future developments</a><ul style='list-style: none;'><li><span class='maruku_section_number'>8.1. </span><a href='#a_syntax_for_specifying_metadata_for_spanlevel_elements'>A syntax for specifying meta-data for span-level elements</a></li><li><span class='maruku_section_number'>8.2. </span><a href='#a_syntax_for_commenting_parts_of_the_document'>A syntax for commenting parts of the document</a></li><li><span class='maruku_section_number'>8.3. </span><a href='#a_syntax_for_adding_math'>A syntax for adding math</a></li></ul></li></ul></div><hr /><h2 class='head' id='download'><span class='maruku_section_number'>1. </span>Download</h2><p>The development site is <a href='http://rubyforge.org/projects/maruku/'>http://rubyforge.org/projects/maruku/</a>.</p><p>Install with:</p><pre style='background-color: #f0f0e0;'>$ gem install maruku -</pre><p>Released files can also be seen at <a href='http://rubyforge.org/frs/?group_id=2795'>http://rubyforge.org/frs/?group_id=2795</a>.</p><p>Anonymous access to the repository is possible with:</p><pre style='background-color: #f0f0e0;'>$ svn checkout svn://rubyforge.org/var/svn/maruku -</pre><p>If you want commit access to the repository, just create an account on Rubyforge and <a href='http://www.dis.uniroma1.it/~acensi/contact.html'>drop me a mail</a>.</p><h3 id='bugs_report'><span class='maruku_section_number'>1.1. </span>Bugs report</h3><p>Use the <a href='http://rubyforge.org/tracker/?group_id=2795'>tracker</a> or <a href='http://www.dis.uniroma1.it/~acensi/contact.html'>drop me an email</a>.</p><h2 id='usage'><span class='maruku_section_number'>2. </span>Usage</h2><p>This is the basic usage:</p><pre class='ruby' style='background-color: #f0f0e0;'><span class='ident'>require</span> <span class='punct'>'</span><span class='string'>rubygems</span><span class='punct'>'</span> +<html lang='en' xml:lang='en' xmlns='http://www.w3.org/1999/xhtml'> +<head> +<title>Maruku: a Markdown-superset interpreter</title> + +<link href='style.css' rel='stylesheet' type='text/css' /> +</head> +<body> +<h1 id='maruku_a_markdownsuperset_interpreter'>Mar<strong>u</strong>k<strong>u</strong>: a Markdown-superset interpreter</h1> + +<p><a href='http://maruku.rubyforge.org/&gt;'>Maruku</a> is a Markdown interpreter written in <a href='http://www.ruby-lang.org'>Ruby</a>.</p> + +<p>Maruku allows you to write in an easy-to-read-and-write syntax, like this:</p> + +<blockquote> +<p><a href='http://maruku.rubyforge.org/maruku.md'>This document in Markdown</a> </p> +</blockquote> + +<p>Then it can be translated to HTML:</p> + +<blockquote> +<p><a href='http://maruku.rubyforge.org/maruku.html'>This document in HTML</a></p> +</blockquote> + +<p>or LaTeX, which is then converted to PDF:</p> + +<blockquote> +<p><a href='http://maruku.rubyforge.org/maruku.pdf'>This document in PDF</a></p> +</blockquote> + +<p>Maruku implements:</p> + +<ul> +<li> +<p>the original <a href='http://maruku.rubyforge.org/markdown_syntax.html'>Markdown syntax</a> (<a href='http://maruku.rubyforge.org/markdown_syntax.html'>HTML</a> or <a href='http://maruku.rubyforge.org/markdown_syntax.pdf'>PDF</a>), translated by Maruku).</p> +</li> + +<li> +<p>all the improvements in <a href='http://www.michelf.com/projects/php-markdown/extra/'>PHP Markdown Extra</a>. </p> +</li> + +<li> +<p>a new <a href='#meta'>meta-data syntax</a></p> +</li> +</ul> + +<p><strong>Authors</strong>: Maruku has been developed so far by <a href='http://www.dis.uniroma1.it/~acensi/'>Andrea Censi</a>. Contributors are most welcome!</p> + +<p><strong>The name of the game</strong>: Maruku is the <a href='http://en.wikipedia.org/wiki/Romaji'>romaji</a> translitteration of the <a href='http://en.wikipedia.org/wiki/Katakana'>katakana</a> translitteration of &quot;Mark&quot;, the first word in Markdown. I chose this name because Ruby is Japanese, and also the sillable &quot;ru&quot; appears in Maruku.</p> + +<hr /> + +<p>Table of contents: (<strong>auto-generated by Maruku!</strong>)</p> + +<div class='maruku_toc'> +<ul style='list-style: none;'> +<li><span class='maruku_section_number'>1. </span><a href='#release_notes'>Release notes - version 0.3.0 (January 3rd, 2007)</a></li> + +<li><span class='maruku_section_number'>2. </span><a href='#download'>Download</a> +<ul style='list-style: none;'> +<li><span class='maruku_section_number'>2.1. </span><a href='#bugs_report'>Bugs report</a></li> +</ul> +</li> + +<li><span class='maruku_section_number'>3. </span><a href='#usage'>Usage</a> +<ul style='list-style: none;'> +<li><span class='maruku_section_number'>3.1. </span><a href='#from_the_command_line'>From the command line</a></li> +</ul> +</li> + +<li><span class='maruku_section_number'>4. </span><a href='#extra'>Examples of PHP Markdown Extra syntax</a></li> + +<li><span class='maruku_section_number'>5. </span><a href='#maruku-and-bluecloth'>Maruku and Bluecloth</a></li> + +<li><span class='maruku_section_number'>6. </span><a href='#meta'>New meta-data syntax</a> +<ul style='list-style: none;'> +<li><span class='maruku_section_number'>6.1. </span><a href='#metadata_for_the_document'>Meta-data for the document</a></li> + +<li><span class='maruku_section_number'>6.2. </span><a href='#metadata_for_elements'>Meta-data for elements</a></li> + +<li><span class='maruku_section_number'>6.3. </span><a href='#shortcuts'>Shortcuts</a></li> + +<li><span class='maruku_section_number'>6.4. </span><a href='#metalist'>List of meta-data</a></li> + +<li><span class='maruku_section_number'>6.5. </span><a href='#examples'>Examples</a></li> +</ul> +</li> + +<li><span class='maruku_section_number'>7. </span><a href='#features'>Other Features</a> +<ul style='list-style: none;'> +<li><span class='maruku_section_number'>7.1. </span><a href='#automatic_generation_of_the_table_of_contents'>Automatic generation of the table of contents</a></li> + +<li><span class='maruku_section_number'>7.2. </span><a href='#this_header_contains_emphasis_strong_text_and_'>This header contains <em>emphasis</em> <strong>strong text</strong> and <code>code</code></a></li> + +<li><span class='maruku_section_number'>7.3. </span><a href='#use_html_entities'>Use HTML entities</a></li> +</ul> +</li> + +<li><span class='maruku_section_number'>8. </span><a href='#future'>Future developments</a> +<ul style='list-style: none;'> +<li><span class='maruku_section_number'>8.1. </span><a href='#a_syntax_for_adding_math'>A syntax for adding math</a></li> +</ul> +</li> +</ul> +</div> + +<hr /> + +<h2 id='release_notes'><span class='maruku_section_number'>1. </span>Release notes - version 0.3.0 (January 3rd, 2007)</h2> + +<p>Note: Maruku seems to be very robust, nevertheless it is still beta-level software. So if you want to use it in production environments, please check back in a month or so, while we squash the remaining bugs.</p> + +<p>In the meantime, feel free to toy around, and please signal problems, request features, by <a href='http://www.dis.uniroma1.it/~acensi/contact.html'>contacting me</a> or using the <a href='http://rubyforge.org/tracker/?group_id=2795'>tracker</a>. For issues about the Markdown syntax itself and improvements to it, please write to the <a href='http://six.pairlist.net/mailman/listinfo/markdown-discuss'>Markdown-discuss mailing list</a>.</p> + +<p>Have fun!</p> + +<p>Changes in 0.3.0:</p> + +<ul> +<li> +<p>A real parser is used instead of a regexp-based system, also for span-level elements.</p> + +<p>Now Maruku is almost 2x faster than Bluecloth, while having more features.</p> + +<p>Here are some benchmarks:</p> + +<pre><code>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</code></pre> + +<p>This is the result of running <code>lib/maruku/tests/benchmark.rb</code> on the Markdown specification.</p> +</li> + +<li> +<p>Prettier HTML output by adding whitespace.</p> +</li> + +<li> +<p>Added a full suite of unit-tests for the span-level parser.</p> +</li> + +<li> +<p>Error management: Having a real parser, Maruku warns you about syntax issues.</p> + +<p>The default action is to warn and try to continue. If you do this:</p> + +<pre><code>Maruku.new(string, {:on_error =&gt; :raise}) +</code></pre> + +<p>then syntax errors will cause an exception to be raised (you can catch this and retry).</p> +</li> + +<li> +<p>Fixed a series of bugs in handling inline HTML code.</p> +</li> +</ul> + +<p>Immediate TODO-list:</p> + +<ul> +<li> +<p>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.</p> + +<p>For example: in the HTML version, you should see accented characters in this parenthesis: </p> + +<blockquote> +<p>(àèìòù)</p> +</blockquote> + +<p>and Japanese text in these other parentheses: </p> + +<blockquote> +<p>(カタカナで 私の 名前は アンドレア チェンシ です).</p> + +<p>(日本のガルは 大好き、でも、日本語は難しですから、そうぞ 英語話すガルを おしえてください).</p> +</blockquote> + +<p>In the LaTeX version, these do not appear. I know how to do LaTeX with ISO-8859-1 encoding (European characters), but I&apos;m struggling with half-baked solutions for UTF-8 encoded documents.</p> +</li> + +<li> +<p>Implement the <a href='http://maruku.rubyforge.org/proposal.html'>new meta-data proposal</a>.</p> +</li> + +<li> +<p>Exporting to Markdown (pretty printing).</p> +</li> + +<li> +<p>Exporting to HTML splitting in multiple files.</p> +</li> + +<li> +<p>RubyPants.</p> +</li> + +<li> +<p>Support for images in PDF.</p> +</li> +</ul> + +<h2 id='download'><span class='maruku_section_number'>2. </span>Download</h2> + +<p>The development site is <a href='http://rubyforge.org/projects/maruku/'>http://rubyforge.org/projects/maruku/</a>.</p> + +<p>Install with:</p> + +<pre><code>$ gem install maruku +</code></pre> + +<p>Released files can also be seen at <a href='http://rubyforge.org/frs/?group_id=2795'>http://rubyforge.org/frs/?group_id=2795</a>.</p> + +<p>Anonymous access to the repository is possible with:</p> + +<pre><code>$ svn checkout svn://rubyforge.org/var/svn/maruku +</code></pre> + +<p>If you want commit access to the repository, just create an account on Rubyforge and <a href='http://www.dis.uniroma1.it/~acensi/contact.html'>drop me a mail</a>.</p> + +<h3 id='bugs_report'><span class='maruku_section_number'>2.1. </span>Bugs report</h3> + +<p>Use the <a href='http://rubyforge.org/tracker/?group_id=2795'>tracker</a> or <a href='http://www.dis.uniroma1.it/~acensi/contact.html'>drop me an email</a>.</p> + +<h2 id='usage'><span class='maruku_section_number'>3. </span>Usage</h2> + +<p>This is the basic usage:</p> + +<pre class='ruby'><span class='ident'>require</span> <span class='punct'>'</span><span class='string'>rubygems</span><span class='punct'>'</span> <span class='ident'>require</span> <span class='punct'>'</span><span class='string'>maruku</span><span class='punct'>'</span> <span class='ident'>doc</span> <span class='punct'>=</span> <span class='constant'>Maruku</span><span class='punct'>.</span><span class='ident'>new</span><span class='punct'>(</span><span class='ident'>markdown_string</span><span class='punct'>)</span> -<span class='ident'>puts</span> <span class='ident'>doc</span><span class='punct'>.</span><span class='ident'>to_html</span> -</pre><p>The method <tt style='background-color: #f0f0e0;'>to_html</tt> outputs only an HTML fragment, while the method <tt style='background-color: #f0f0e0;'>to_html_document</tt> outputs a complete XHTML 1.0 document:</p><pre class='ruby' style='background-color: #f0f0e0;'><span class='ident'>puts</span> <span class='ident'>doc</span><span class='punct'>.</span><span class='ident'>to_html_document</span></pre><p>You can have the REXML document tree with:</p><pre class='ruby' style='background-color: #f0f0e0;'><span class='ident'>tree</span> <span class='punct'>=</span> <span class='ident'>doc</span><span class='punct'>.</span><span class='ident'>to_html_document_tree</span> -</pre><h3 id='from_the_command_line'><span class='maruku_section_number'>2.1. </span>From the command line</h3><p>There are two command-line programs installed: <tt style='background-color: #f0f0e0;'>maruku</tt> and <tt style='background-color: #f0f0e0;'>marutex</tt>.</p><ul><li><p><tt style='background-color: #f0f0e0;'>maruku</tt> converts Markdown to HTML:</p><pre style='background-color: #f0f0e0;'>$ maruku file.md # creates file.html</pre></li><li><p><tt style='background-color: #f0f0e0;'>marutex</tt> converts Markdown to LaTeX, then calls <tt style='background-color: #f0f0e0;'>pdflatex</tt> to transform to PDF</p><pre style='background-color: #f0f0e0;'>$ marutex file.md # creates file.tex and file.pdf</pre></li></ul><h2 id='extra'><span class='maruku_section_number'>3. </span>Examples of PHP Markdown Extra syntax</h2><ul><li><p>tables</p><pre style='background-color: #f0f0e0;'>Col1 | Very very long head | Very very long head| +<span class='ident'>puts</span> <span class='ident'>doc</span><span class='punct'>.</span><span class='ident'>to_html</span></pre> + +<p>The method <code>to_html</code> outputs only an HTML fragment, while the method <code>to_html_document</code> outputs a complete XHTML 1.0 document:</p> + +<pre class='ruby'><span class='ident'>puts</span> <span class='ident'>doc</span><span class='punct'>.</span><span class='ident'>to_html_document</span></pre> + +<p>You can have the REXML document tree with:</p> + +<pre class='ruby'><span class='ident'>tree</span> <span class='punct'>=</span> <span class='ident'>doc</span><span class='punct'>.</span><span class='ident'>to_html_document_tree</span></pre> + +<h3 id='from_the_command_line'><span class='maruku_section_number'>3.1. </span>From the command line</h3> + +<p>There are two command-line programs installed: <code>maruku</code> and <code>marutex</code>.</p> + +<ul> +<li> +<p><code>maruku</code> converts Markdown to HTML:</p> + +<pre><code>$ maruku file.md # creates file.html</code></pre> +</li> + +<li> +<p><code>marutex</code> converts Markdown to LaTeX, then calls <code>pdflatex</code> to transform to PDF</p> + +<pre><code>$ marutex file.md # creates file.tex and file.pdf</code></pre> +</li> +</ul> + +<h2 id='extra'><span class='maruku_section_number'>4. </span>Examples of PHP Markdown Extra syntax</h2> + +<ul> +<li> +<p>tables</p> + +<pre><code>Col1 | Very very long head | Very very long head| -----|:-------------------:|-------------------:| cell | center-align | right-align | -</pre><table class='example'><thead><tr><th>Col1</th><th>Very very long head</th><th>Very very long head</th></tr></thead><tbody><tr><td style='text-align: left;'>cell</td><td style='text-align: center;'>center-align</td><td style='text-align: right;'>right-align</td></tr></tbody></table></li><li><p>footnotes <sup id='fnref:1'><a href='#fn:1' rel='footnote'>1</a></sup></p><pre style='background-color: #f0f0e0;'>* footnotes [^foot] +</code></pre> -[^foot]: I really was missing those.</pre></li><li><p>Markdown inside HTML elememnts</p></li></ul><pre class='xml' style='background-color: #f0f0e0;'><span class='punct'>&lt;</span><span class='tag'>div</span> <span class='attribute'>markdown</span><span class='punct'>=&quot;</span><span class='string'>1</span><span class='punct'>&quot;</span> <span class='attribute'>style</span><span class='punct'>=&quot;</span><span class='string'>border: solid 1px black</span><span class='punct'>&quot;&gt;</span> +<table class='example'> +<thead> +<tr><th>Col1</th><th>Very very long head</th><th>Very very long head</th></tr> +</thead> +<tbody> +<tr> +<td style='text-align: left;'>cell</td> + +<td style='text-align: center;'>center-align</td> + +<td style='text-align: right;'>right-align</td> +</tr> +</tbody></table> +</li> + +<li> +<p>footnotes <sup id='fnref:1'><a href='#fn:1' rel='footnote'>1</a></sup></p> + +<pre><code>* footnotes [^foot] + +[^foot]: I really was missing those.</code></pre> +</li> + +<li> +<p>Markdown inside HTML elememnts</p> +</li> +</ul> + +<pre class='xml'><span class='punct'>&lt;</span><span class='tag'>div</span> <span class='attribute'>markdown</span><span class='punct'>=&quot;</span><span class='string'>1</span><span class='punct'>&quot;</span> <span class='attribute'>style</span><span class='punct'>=&quot;</span><span class='string'>border: solid 1px black</span><span class='punct'>&quot;&gt;</span> This is a div with Markdown **strong text** -<span class='punct'>&lt;/</span><span class='tag'>div</span><span class='punct'>&gt;</span> -</pre><div style='border: solid 1px black'><p>This is a div with Markdown <strong>strong text</strong></p></div><ul><li><p>header ids</p><pre style='background-color: #f0f0e0;'>## Download ## {#download}</pre><p>For example, <a href='#download'>a link to the download</a> header.</p><p>Note that you can use also the new <a href='#meta'>meta-data syntax</a> for the same purpose:</p><pre style='background-color: #f0f0e0;'>@ id: download -## Header ## </pre></li><li><p>definition lists</p><pre style='background-color: #f0f0e0;'>Definition list +<span class='punct'>&lt;/</span><span class='tag'>div</span><span class='punct'>&gt;</span></pre> + +<div style='border: solid 1px black'> +<p>This is a div with Markdown <strong>strong text</strong></p> +</div> + +<ul> +<li> +<p>header ids</p> + +<pre><code>## Download ## {#download} +</code></pre> + +<p>For example, <a href='#download'>a link to the download</a> header.</p> + +<p>Note that you can use also the new <a href='#meta'>meta-data syntax</a> for the same purpose:</p> + +<pre><code>@ id: download +## Header ## </code></pre> +</li> + +<li> +<p>definition lists</p> + +<pre><code>Definition list : something very hard to parse -</pre><dl><dt>Definition list</dt><dd>something very hard to parse</dd></dl></li><li><p>abbreviations or <abbr title='Simply an abbreviation'>ABB</abbr> for short.</p></li></ul><h2 id='maruku-and-bluecloth'><span class='maruku_section_number'>4. </span>Maruku and Bluecloth</h2><p>The other Ruby implementation of Markdown is <a href='http://www.deveiate.org/projects/BlueCloth'>Bluecloth</a>.</p><p>Maruku is much different in philosophy from Bluecloth: the biggest difference is that <em>parsing</em> is separated from <em>rendering</em>. 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 <tt style='background-color: #f0f0e0;'>gsub</tt> to transform to HTML.</p><p>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).</p><p>Other improvements over Bluecloth:</p><ul><li><p>the HTML output is provided also as a <tt style='background-color: #f0f0e0;'>REXML</tt> document tree.</p></li><li><p>PHP Markdown Syntax support.</p></li></ul><h2 id='meta'><span class='maruku_section_number'>5. </span>New meta-data syntax</h2><p>Maruku implements a syntax that allows to attach &quot;meta&quot; information to objects.</p><h3 id='metadata_for_the_document'><span class='maruku_section_number'>5.1. </span>Meta-data for the document</h3><p>Meta-data for the document itself is specified through the use of email headers:</p><pre style='background-color: #f0f0e0;'>Title: A simple document containing meta-headers +</code></pre> + +<dl> +<dt>Definition list</dt> + +<dd>something very hard to parse</dd> +</dl> +</li> + +<li> +<p>abbreviations or <abbr title='Simply an abbreviation'>ABB</abbr> for short.</p> +</li> +</ul> + +<h2 id='maruku-and-bluecloth'><span class='maruku_section_number'>5. </span>Maruku and Bluecloth</h2> + +<p>The other Ruby implementation of Markdown is <a href='http://www.deveiate.org/projects/BlueCloth'>Bluecloth</a>. </p> + +<p>Maruku is much different in philosophy from Bluecloth: the biggest difference is that <em>parsing</em> is separated from <em>rendering</em>. 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 <code>gsub</code> to transform to HTML.</p> + +<p>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).</p> + +<p>Other improvements over Bluecloth:</p> + +<ul> +<li> +<p>the HTML output is provided also as a <code>REXML</code> document tree.</p> +</li> + +<li> +<p>PHP Markdown Syntax support.</p> +</li> +</ul> + +<h2 id='meta'><span class='maruku_section_number'>6. </span>New meta-data syntax</h2> + +<p>Maruku implements a syntax that allows to attach &quot;meta&quot; information to objects.</p> + +<h3 id='metadata_for_the_document'><span class='maruku_section_number'>6.1. </span>Meta-data for the document</h3> + +<p>Meta-data for the document itself is specified through the use of email headers:</p> + +<pre><code>Title: A simple document containing meta-headers CSS: style.css Content of the document -</pre><p>When creating the document through</p><pre class='ruby' style='background-color: #f0f0e0;'><span class='constant'>Maruku</span><span class='punct'>.</span><span class='ident'>new</span><span class='punct'>(</span><span class='ident'>s</span><span class='punct'>).</span><span class='ident'>to_html_document</span> -</pre><p>the title and stylesheet are added as expected.</p><p>Meta-data keys are assumed to be case-insensitive.</p><h3 id='metadata_for_elements'><span class='maruku_section_number'>5.2. </span>Meta-data for elements</h3><p>Maruku introduces a new syntax for attaching metadata to paragraphs, tables, and so on.</p><p>For example, consider the creation of two paragraphs:</p><pre style='background-color: #f0f0e0;'>Paragraph 1 is a warning. +</code></pre> +<p>When creating the document through </p> + +<pre class='ruby'><span class='constant'>Maruku</span><span class='punct'>.</span><span class='ident'>new</span><span class='punct'>(</span><span class='ident'>s</span><span class='punct'>).</span><span class='ident'>to_html_document</span></pre> + +<p>the title and stylesheet are added as expected.</p> + +<p>Meta-data keys are assumed to be case-insensitive.</p> + +<h3 id='metadata_for_elements'><span class='maruku_section_number'>6.2. </span>Meta-data for elements</h3> + +<p>Maruku introduces a new syntax for attaching metadata to paragraphs, tables, and so on.</p> + +<p>For example, consider the creation of two paragraphs:</p> + +<pre><code>Paragraph 1 is a warning. + Paragraph 2 -</pre><p>Now you really want to attach a &apos;class&apos; attribute to the paragraphs (for example for CSS styling). Maruku allows you to use:</p><pre style='background-color: #f0f0e0;'>@ class: warning +</code></pre> + +<p>Now you really want to attach a &apos;class&apos; attribute to the paragraphs (for example for CSS styling). Maruku allows you to use:</p> + +<pre><code>@ class: warning Paragraph 1 is a warning Paragraph 2 -</pre><p>You can add more by separating with a <tt style='background-color: #f0f0e0;'>;</tt>:</p><pre style='background-color: #f0f0e0;'>@ class: warning; id: warning1 +</code></pre> + +<p>You can add more by separating with a <code>;</code>:</p> + +<pre><code>@ class: warning; id: warning1 Paragraph 1 is a warning -</pre><p>A meta-data declaration is composed of</p><ol><li>newline</li><li>an at-symbol <tt style='background-color: #f0f0e0;'>@</tt></li><li>a series of name-value pairs. Each name-value is separated by a colon <tt style='background-color: #f0f0e0;'>:</tt>, pairs are separated by semi-colons <tt style='background-color: #f0f0e0;'>;</tt></li></ol><p>Many declaration can be used, and they refer to <em>the following</em> object:</p><pre style='background-color: #f0f0e0;'>@ class: warning +</code></pre> + +<p>A meta-data declaration is composed of </p> + +<ol> +<li>newline</li> + +<li>an at-symbol <code>@</code></li> + +<li>a series of name-value pairs. Each name-value is separated by a colon <code>:</code>, pairs are separated by semi-colons <code>;</code> </li> +</ol> + +<p>Many declaration can be used, and they refer to <em>the following</em> object:</p> + +<pre><code>@ class: warning @ id: warning1 Paragraph 1 is a warning -</pre><p>These can also be separated by newlines:</p><pre style='background-color: #f0f0e0;'>@ class: warning +</code></pre> +<p>These can also be separated by newlines:</p> + +<pre><code>@ class: warning + @ id: warning1 Paragraph 1 is a warning -</pre><h3 id='shortcuts'><span class='maruku_section_number'>5.3. </span>Shortcuts</h3><p>This:</p><pre style='background-color: #f0f0e0;'>@ .xyz +</code></pre> + +<h3 id='shortcuts'><span class='maruku_section_number'>6.3. </span>Shortcuts</h3> + +<p>This:</p> + +<pre><code>@ .xyz Paragraph -</pre><p>is equivalent to:</p><pre style='background-color: #f0f0e0;'>@ class: xyz +</code></pre> + +<p>is equivalent to:</p> + +<pre><code>@ class: xyz Paragraph -</pre><p>This:</p><pre style='background-color: #f0f0e0;'>@ #xyz +</code></pre> + +<p>This:</p> + +<pre><code>@ #xyz Paragraph -</pre><p>is equivalent to:</p><pre style='background-color: #f0f0e0;'>@ id: xyz +</code></pre> + +<p>is equivalent to:</p> + +<pre><code>@ id: xyz Paragraph -</pre><p>Also, if the value is not present, it defaults to <tt style='background-color: #f0f0e0;'>true</tt>:</p><pre style='background-color: #f0f0e0;'>@ test +</code></pre> +<p>Also, if the value is not present, it defaults to <code>true</code>:</p> + +<pre><code>@ test + This paragraph has the attribute `test` set to `true`. -</pre><hr /><h3 id='metalist'><span class='maruku_section_number'>5.4. </span>List of meta-data</h3><dl><dt><strong><tt style='background-color: #f0f0e0;'>title</tt>, <tt style='background-color: #f0f0e0;'>subject</tt></strong></dt><dd><p>(document) Sets the title of the document (HTML: used in the <tt style='background-color: #f0f0e0;'>TITLE</tt> element).</p></dd><dt><strong><tt style='background-color: #f0f0e0;'>use_numbered_headers</tt></strong></dt><dd><p>(document) If <tt style='background-color: #f0f0e0;'>true</tt>, headers are numbered (just like this document). Default is <tt style='background-color: #f0f0e0;'>false</tt>.</p></dd><dt><strong><tt style='background-color: #f0f0e0;'>css</tt></strong></dt><dd><p>(document, HTML) Url of stylesheet.</p></dd><dt><strong><tt style='background-color: #f0f0e0;'>html_use_syntax</tt></strong></dt><dd><p>(document, HTML) If set, use the <a href='http://syntax.rubyforge.org/'>Ruby <tt style='background-color: #f0f0e0;'>syntax</tt> library</a> to add source highlighting.</p></dd><dt><strong><tt style='background-color: #f0f0e0;'>latex_use_listings</tt></strong></dt><dd><p>(document, LaTeX) If set, use the fancy <a href='http://www.ctan.org/tex-archive/macros/latex/contrib/listings/'><tt style='background-color: #f0f0e0;'>listings</tt> package</a> for better displaying code blocks.</p><p>If not set, use standard <tt style='background-color: #f0f0e0;'>verbatim</tt> environment.</p></dd><dt><strong><tt style='background-color: #f0f0e0;'>style</tt>, <tt style='background-color: #f0f0e0;'>id</tt>, <tt style='background-color: #f0f0e0;'>class</tt></strong></dt><dd><p>(any block object, HTML) Standard CSS attributes are copied.</p></dd><dt><strong><tt style='background-color: #f0f0e0;'>lang</tt></strong></dt><dd><p>(code blocks) Name of programming language (<tt style='background-color: #f0f0e0;'>ruby</tt>) for syntax highlighting.</p><p>Default for this is <tt style='background-color: #f0f0e0;'>code_lang</tt> in document.</p><p>Syntax highlighting is delegated to the <a href='http://syntax.rubyforge.org/'><tt style='background-color: #f0f0e0;'>syntax</tt> library</a> for HTML output and to the <a href='http://www.ctan.org/tex-archive/macros/latex/contrib/listings/'><tt style='background-color: #f0f0e0;'>listings</tt> package</a> for LaTeX output.</p></dd><dt><strong><tt style='background-color: #f0f0e0;'>code_show_spaces</tt></strong></dt><dd><p>Shows tabs and newlines (default is read in the document object).</p></dd><dt><strong><tt style='background-color: #f0f0e0;'>code_background_color</tt></strong></dt><dd><p>Background color for code blocks. (default is read in the document object).</p><p>The format is either a named color (<tt style='background-color: #f0f0e0;'>green</tt>, <tt style='background-color: #f0f0e0;'>red</tt>) or a CSS color of the form <tt style='background-color: #f0f0e0;'>#ff00ff</tt>.</p><ul><li><p>for <strong>HTML output</strong>, the value is put straight in the <tt style='background-color: #f0f0e0;'>background-color</tt> CSS property of the block.</p></li><li><p>for <strong>LaTeX output</strong>, if it is a named color, it must be a color accepted by the LaTeX <tt style='background-color: #f0f0e0;'>color</tt> packages. If it is of the form <tt style='background-color: #f0f0e0;'>#ff00ff</tt>, Maruku defines a color using the <tt style='background-color: #f0f0e0;'>\color[rgb]{r,g,b}</tt> macro.</p><p>For example, for <tt style='background-color: #f0f0e0;'>#0000ff</tt>, the macro is called as: <tt style='background-color: #f0f0e0;'>\color[rgb]{0,0,1}</tt>.</p></li></ul></dd></dl><h3 id='examples'><span class='maruku_section_number'>5.5. </span>Examples</h3><p>An example of this is the following:</p><pre style='background-color: #f0f0e0;'>@&not;code_show_spaces;&not;code_background_color:&not;green +</code></pre> +<hr /> + +<h3 id='metalist'><span class='maruku_section_number'>6.4. </span>List of meta-data</h3> + +<dl> +<dt><strong><code>title</code>, <code>subject</code></strong></dt> + +<dd> +<p>(document) Sets the title of the document (HTML: used in the <code>TITLE</code> element).</p> +</dd> + +<dt><strong><code>use_numbered_headers</code></strong></dt> + +<dd> +<p>(document) If <code>true</code>, headers are numbered (just like this document). Default is <code>false</code>.</p> +</dd> + +<dt><strong><code>css</code></strong></dt> + +<dd> +<p>(document, HTML) Url of stylesheet.</p> +</dd> + +<dt><strong><code>html_use_syntax</code></strong></dt> + +<dd> +<p>(document, HTML) If set, use the <a href='http://syntax.rubyforge.org/'>Ruby <code>syntax</code> library</a> to add source highlighting.</p> +</dd> + +<dt><strong><code>latex_use_listings</code></strong></dt> + +<dd> +<p>(document, LaTeX) If set, use the fancy <a href='http://www.ctan.org/tex-archive/macros/latex/contrib/listings/'><code>listings</code> package</a> for better displaying code blocks.</p> + +<p> If not set, use standard <code>verbatim</code> environment.</p> +</dd> + +<dt><strong><code>style</code>, <code>id</code>, <code>class</code></strong></dt> + +<dd> +<p>(any block object, HTML) Standard CSS attributes are copied.</p> +</dd> + +<dt><strong><code>lang</code></strong></dt> + +<dd> +<p>(code blocks) Name of programming language (<code>ruby</code>) for syntax highlighting.</p> + +<p> Default for this is <code>code_lang</code> in document.</p> + +<p> Syntax highlighting is delegated to the <a href='http://syntax.rubyforge.org/'><code>syntax</code> library</a> for HTML output and to the <a href='http://www.ctan.org/tex-archive/macros/latex/contrib/listings/'><code>listings</code> package</a> for LaTeX output.</p> +</dd> + +<dt><strong><code>code_show_spaces</code></strong></dt> + +<dd> +<p>Shows tabs and newlines (default is read in the document object).</p> +</dd> + +<dt><strong><code>code_background_color</code></strong></dt> + +<dd> +<p>Background color for code blocks. (default is read in the document object).</p> + +<p>The format is either a named color (<code>green</code>, <code>red</code>) or a CSS color of the form <code>#ff00ff</code>. </p> + +<ul> +<li> +<p>for <strong>HTML output</strong>, the value is put straight in the <code>background-color</code> CSS property of the block.</p> +</li> + +<li> +<p>for <strong>LaTeX output</strong>, if it is a named color, it must be a color accepted by the LaTeX <code>color</code> packages. If it is of the form <code>#ff00ff</code>, Maruku defines a color using the <code>\color[rgb]{r,g,b}</code> macro. </p> + +<p>For example, for <code>#0000ff</code>, the macro is called as: <code>\color[rgb]{0,0,1}</code>.</p> +</li> +</ul> +</dd> +</dl> + +<h3 id='examples'><span class='maruku_section_number'>6.5. </span>Examples</h3> + +<p>An example of this is the following:</p> + +<pre><code>@&not;code_show_spaces;&not;code_background_color:&not;green + &raquo;&nbsp;&nbsp;&nbsp;&not;One&not;space &raquo;&nbsp;&nbsp;&nbsp;&not;&not;Two&not;spaces &raquo;&nbsp;&nbsp;&nbsp;&raquo;&nbsp;&nbsp;&nbsp;&not;&raquo;&nbsp;&nbsp;&nbsp;Tab,&not;space,&not;tab &raquo;&nbsp;&nbsp;&nbsp;&raquo;&nbsp;&nbsp;&nbsp;&raquo;&nbsp;&nbsp;&nbsp;&raquo;&nbsp;&nbsp;&nbsp;Tab,&not;tab,&not;tab&not;and&not;all&not;is&not;green! -</pre><p>That will produce:</p><pre style='background-color: green;'>&not;One&not;space +</code></pre> + +<p>That will produce:</p> + +<pre style='background-color: green;'><code>&not;One&not;space &not;&not;Two&not;spaces &raquo;&nbsp;&nbsp;&nbsp;&not;&raquo;&nbsp;&nbsp;&nbsp;Tab,&not;space,&not;tab &raquo;&nbsp;&nbsp;&nbsp;&raquo;&nbsp;&nbsp;&nbsp;&raquo;&nbsp;&nbsp;&nbsp;Tab,&not;tab,&not;tab&not;and&not;all&not;is&not;green! -</pre><p>Example with css-style color:</p><pre style='background-color: #f0f0e0;'>@ code_background_color: #455678 +</code></pre> +<p>Example with css-style color:</p> + +<pre><code>@ code_background_color: #455678 + A strange color -</pre><p>produces:</p><pre style='background-color: #455678;'>A strange color -</pre><p>Or highlighting (does not work well yet):</p><pre style='background-color: #f0f0e0;'>@ lang: xml +</code></pre> + +<p>produces:</p> + +<pre style='background-color: #455678;'><code>A strange color +</code></pre> + +<p>Or highlighting (does not work well yet):</p> + +<pre><code>@ lang: xml &lt;div style=&quot;text-align:center&quot;&gt;Div&lt;/div&gt; -</pre><p>produces:</p><pre class='xml' style='background-color: #f0f0e0;'><span class='punct'>&lt;</span><span class='tag'>div</span> <span class='attribute'>style</span><span class='punct'>=&quot;</span><span class='string'>text-align:center</span><span class='punct'>&quot;&gt;</span>Div<span class='punct'>&lt;/</span><span class='tag'>div</span><span class='punct'>&gt;</span> +</code></pre> +<p>produces:</p> -</pre><hr /><h2 id='features'><span class='maruku_section_number'>6. </span>Other Features</h2><h3 id='automatic_generation_of_the_table_of_contents'><span class='maruku_section_number'>6.1. </span>Automatic generation of the table of contents</h3><p>If you create a list, and then set the <tt style='background-color: #f0f0e0;'>toc</tt> attribute, when rendering Maruku will create an auto-generated table of contents.</p><pre style='background-color: #f0f0e0;'>@ toc +<pre class='xml'><span class='punct'>&lt;</span><span class='tag'>div</span> <span class='attribute'>style</span><span class='punct'>=&quot;</span><span class='string'>text-align:center</span><span class='punct'>&quot;&gt;</span>Div<span class='punct'>&lt;/</span><span class='tag'>div</span><span class='punct'>&gt;</span></pre> + +<hr /> + +<h2 id='features'><span class='maruku_section_number'>7. </span>Other Features</h2> + +<h3 id='automatic_generation_of_the_table_of_contents'><span class='maruku_section_number'>7.1. </span>Automatic generation of the table of contents</h3> + +<p>If you create a list, and then set the <code>toc</code> attribute, when rendering Maruku will create an auto-generated table of contents.</p> + +<pre><code>@ toc * This will become a table of contents (this text will be scraped). -</pre><p>You can see an example of this at the beginning of this document.</p><h3 id='this_header_contains_emphasis_strong_text_and_'><span class='maruku_section_number'>6.2. </span>This header contains <em>emphasis</em> <strong>strong text</strong> and <tt style='background-color: #f0f0e0;'>code</tt></h3><p>Note that this header contains formatting and it still works, also in the table of contents.</p><p>And <a href='#features'>This is a <em>link</em> with <strong>all</strong> <strong><em>sort</em></strong> of <tt style='background-color: #f0f0e0;'>weird stuff</tt></a> in the text.</p><h3 id='use_html_entities'><span class='maruku_section_number'>6.3. </span>Use HTML entities</h3><p>If you want to use HTML entities, go on! We will take care of the translation to LaTeX:</p><table><thead><tr><th>Entity</th><th>Result</th></tr></thead><tbody><tr><td style='text-align: left;'><tt style='background-color: #f0f0e0;'>&amp;copy;</tt></td><td style='text-align: left;'>&copy;</td></tr><tr><td style='text-align: left;'><tt style='background-color: #f0f0e0;'>&amp;pound;</tt></td><td style='text-align: left;'>&pound;</td></tr><tr><td style='text-align: left;'><tt style='background-color: #f0f0e0;'>a&amp;nbsp;b</tt></td><td style='text-align: left;'>a&nbsp;b</td></tr><tr><td style='text-align: left;'><tt style='background-color: #f0f0e0;'>&amp;lambda;</tt></td><td style='text-align: left;'>&lambda;</td></tr><tr><td style='text-align: left;'><tt style='background-color: #f0f0e0;'>&amp;mdash;</tt></td><td style='text-align: left;'>&mdash;</td></tr></tbody></table><h2 id='todo_list'><span class='maruku_section_number'>7. </span>TODO list</h2><ul><li><p>Export to HTML</p><ol><li><p>Add <tt style='background-color: #f0f0e0;'>-split</tt> options to <tt style='background-color: #f0f0e0;'>maruku</tt> that splits the document over multiple pages.</p><p>This should require the possibility of specifying a template for navigational elements. Investigate template engine.</p></li><li><p>Include RubyPants</p></li></ol></li><li><p>Export to PDF</p><ul><li>support for images</li></ul></li><li><p>Export to Markdown (pretty-printing)</p></li></ul><h2 id='future'><span class='maruku_section_number'>8. </span>Future developments</h2><p>I think that <a href='http://sophos.berkeley.edu/macfarlane/pandoc/'>Pandoc</a> and <a href='http://fletcher.freeshell.org/wiki/MultiMarkdown'>MultiMarkdown</a> are very cool projects. However, they are written in Haskell and Perl, respectively. I would love to have an equivalent in Ruby.</p><h3 id='a_syntax_for_specifying_metadata_for_spanlevel_elements'><span class='maruku_section_number'>8.1. </span>A syntax for specifying meta-data for span-level elements</h3><p>Maybe something like this:</p><pre style='background-color: #f0f0e0;'>This is a paragraph. Really, a normal paragraph. The second -line of this paragraph has the last element {with meta data}@ class: important_span -and the paragraph continues... -</pre><p>So the idea is:</p><ul><li><p>Only elements at the end of the line can have meta data.</p></li><li><p>Syntax is:</p><ol><li>Opening brace <tt style='background-color: #f0f0e0;'>{</tt>.</li><li>Any string that does not contain the sequence <tt style='background-color: #f0f0e0;'>}@</tt>.</li><li>Closing brace and at-symbol <tt style='background-color: #f0f0e0;'>}@</tt>.</li><li>Attributes specification like the block-level metadata.</li></ol></li></ul><p>Or, we could allow metadata specified <strong>after the text</strong>. In the following, three fragments are marked as &quot;special&quot;, and, after their containing block-level elements, their attributes are set:</p><pre style='background-color: #f0f0e0;'>Lorem ipsum dolor sit @{amet}, consectetuer adipiscing -elit. Donec sit amet sapien vitae augue @{interdum hendrerit.} -Maecenas tempor ultrices nisl. @{Praesent laoreet tortor sit -amet est.} Praesent in nisl eu libero sodales bibendum. +</code></pre> -@{1} id: amet -@{2} style: &quot;font-style: bold&quot; -@{3} class: warning -</pre><p>We can be much liberal in the syntax. For example, instead of numeric references to the part in the text, we could write:</p><pre style='background-color: #f0f0e0;'>Lorem ipsum dolor sit @{amet}, consectetuer adipiscing -elit. Donec sit amet sapien vitae augue @{interdum hendrerit.} -Maecenas tempor ultrices nisl. @{Praesent laoreet tortor sit -amet est.} Praesent in nisl eu libero sodales bibendum. +<p>You can see an example of this at the beginning of this document.</p> -@{amet} id: amet -@{interdum ...} style: &quot;font-style: bold&quot; -@{Praesent ...} class: warning -</pre><p>with <tt style='background-color: #f0f0e0;'>...</tt> acting as a wildcard, to match a long phrase (<tt style='background-color: #f0f0e0;'>{ Praesent laoreet tortor sit amet est.}</tt>) without specifying the full text.</p><p>I feel this is very readable and not intrusive. But then again, subjective tastes vary. Let me know of any comments and suggestions. I want to wait for feedback before implementing this.</p><h3 id='a_syntax_for_commenting_parts_of_the_document'><span class='maruku_section_number'>8.2. </span>A syntax for commenting parts of the document</h3><pre style='background-color: #f0f0e0;'>This is a paragraph -% This is a comment -</pre><p>Or <tt style='background-color: #f0f0e0;'>%</tt> on a line by itself comments the following block:</p><pre style='background-color: #f0f0e0;'>% The following paragraph is ignored +<h3 id='this_header_contains_emphasis_strong_text_and_'><span class='maruku_section_number'>7.2. </span>This header contains <em>emphasis</em> <strong>strong text</strong> and <code>code</code></h3> -% -Lorem ipsum dolor sit amet, consectetuer adipiscing -elit. Donec sit amet sapien vitae augue interdum hendrerit. -Maecenas tempor ultrices nisl. Praesent laoreet tortor sit -amet est. Praesent in nisl eu libero sodales bibendum. +<p>Note that this header contains formatting and it still works, also in the table of contents.</p> -This paragraph is not ignored. -</pre><h3 id='a_syntax_for_adding_math'><span class='maruku_section_number'>8.3. </span>A syntax for adding math</h3><p>Something inspired from LaTeX should be familiar to all:</p><pre style='background-color: #f0f0e0;'>This is inline math: $\alpha$ +<p>And <a href='#features'>This is a <em>link</em> with <strong>all</strong> <strong><em>sort</em></strong> of <code>weird stuff</code></a> in the text.</p> +<h3 id='use_html_entities'><span class='maruku_section_number'>7.3. </span>Use HTML entities</h3> +<p>If you want to use HTML entities, go on! We will take care of the translation to LaTeX:</p> + +<table> +<thead> +<tr><th>Entity</th><th>Result</th></tr> +</thead> +<tbody> +<tr> +<td style='text-align: left;'><code>&amp;copy;</code></td> + +<td style='text-align: left;'>&copy;</td> +</tr> + +<tr> +<td style='text-align: left;'><code>&amp;pound;</code></td> + +<td style='text-align: left;'>&pound;</td> +</tr> + +<tr> +<td style='text-align: left;'><code>a&amp;nbsp;b</code></td> + +<td style='text-align: left;'>a&nbsp;b</td> +</tr> + +<tr> +<td style='text-align: left;'><code>&amp;lambda;</code></td> + +<td style='text-align: left;'>&lambda;</td> +</tr> + +<tr> +<td style='text-align: left;'><code>&amp;mdash;</code></td> + +<td style='text-align: left;'>&mdash;</td> +</tr> +</tbody></table> + +<h2 id='future'><span class='maruku_section_number'>8. </span>Future developments</h2> + +<p>I think that <a href='http://sophos.berkeley.edu/macfarlane/pandoc/'>Pandoc</a> and <a href='http://fletcher.freeshell.org/wiki/MultiMarkdown'>MultiMarkdown</a> are very cool projects. However, they are written in Haskell and Perl, respectively. I would love to have an equivalent in Ruby.</p> + +<h3 id='a_syntax_for_adding_math'><span class='maruku_section_number'>8.1. </span>A syntax for adding math</h3> + +<p>Something inspired from LaTeX should be familiar to all:</p> + +<pre><code>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) +This is a reference to equation: please see (eq:1)</code></pre> -</pre><div class='footnotes'><hr /><ol><li id='fn:1'><p>I really was missing those.<a href='#fnref:1' rev='footnote'>&#8617;</a></p></li></ol></div><div class='maruku_signature'><hr /><span style='font-size: small; font-style: italic'>Created by <a href='http://maruku.rubyforge.org' title='Maruku: a Markdown interpreter'>Maruku</a> at 16:59 on Friday, December 29th, 2006.</span></div></body></html> +<div class='footnotes'> +<hr /> + +<ol> +<li id='fn:1'> +<p>I really was missing those.<a href='#fnref:1' rev='footnote'>&#8617;</a></p> +</li> +</ol> +</div> + +<div class='maruku_signature'> +<hr /> +<span style='font-size: small; font-style: italic'>Created by <a href='http://maruku.rubyforge.org' title='Maruku: a Markdown interpreter'>Maruku</a> at 00:33 on Wednesday, January 03rd, 2007.</span></div> +</body></html>