docs/maruku.html in maruku-0.5.0 vs docs/maruku.html in maruku-0.5.1
- old
+ new
@@ -11,14 +11,16 @@
<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/'>Maruku</a> is a Markdown interpreter written in <a href='http://www.ruby-lang.org'>Ruby</a>.</p>
<blockquote id='news'>
-<p><a href='#release_notes'>Last release</a> is version 0.5.0 – 2007-01-23.</p>
+<p><a href='#release_notes'>Last release</a> is version 0.5.1 – 2007-01-24.</p>
<p>Use this command to update:</p>
-<pre><code>$ gem update maruku</code></pre></blockquote>
+
+<pre><code>$ gem update maruku</code></pre>
+</blockquote>
<hr />
<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>
@@ -71,17 +73,19 @@
<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>
+
+<pre style='background-color: #efefff;'><code class='sh' lang='sh'>$ 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/trunk
-</code></pre>
+
+<pre style='background-color: #efefff;'><code class='sh' lang='sh'>$ svn checkout svn://rubyforge.org/var/svn/maruku/trunk</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>
@@ -89,43 +93,52 @@
<h2 id='usage'><span class='maruku_section_number'>3. </span>Usage</h2>
<h3 id='embedded_maruku'><span class='maruku_section_number'>3.1. </span>Embedded Maruku</h3>
<p>This is the basic usage:</p>
-<pre><code>require 'rubygems'
-require 'maruku'
-doc = Maruku.new(markdown_string)
-puts doc.to_html
-</code></pre>
+<pre style='background-color: #efffef;'><code class='ruby' lang='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></code></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><code>puts doc.to_html_document
-</code></pre>
+
+<pre style='background-color: #efffef;'><code class='ruby' lang='ruby'><span class='ident'>puts</span> <span class='ident'>doc</span><span class='punct'>.</span><span class='ident'>to_html_document</span></code></pre>
+
<p>You can have the REXML document tree with:</p>
-<pre><code>tree = doc.to_html_document_tree
-</code></pre>
+
+<pre style='background-color: #efffef;'><code class='ruby' lang='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></code></pre>
+
<h3 id='from_the_command_line'><span class='maruku_section_number'>3.2. </span>From the command line</h3>
<p>There is one command-line program installed: <code>maruku</code>.</p>
<p>Without arguments, it converts Markdown to HTML:</p>
-<pre><code>$ maruku file.md # creates file.html</code></pre>
+
+<pre style='background-color: #efefff;'><code class='sh' lang='sh'>$ maruku file.md # creates file.html</code></pre>
+
<p>With the <code>--pdf</code> arguments, it converts Markdown to LaTeX, then calls <code>pdflatex</code> to transform to PDF:</p>
-<pre><code>$ maruku --pdf file.md # creates file.tex and file.pdf</code></pre>
+
+<pre style='background-color: #efefff;'><code class='sh' lang='sh'>$ maruku --pdf file.md # creates file.tex and file.pdf</code></pre>
+
<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 <code>gsub</code> to transform to HTML.</p>
<p>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).</p>
<p>This is the canonical benchmark (the Markdown specification), executed with Ruby 1.8.5 on a Powerbook 1.5GhZ:</p>
+
<pre><code>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)
</code></pre>
+
<p>Please note that Maruku has a lot more features and therefore is looking for much more patterns in the file.</p>
<h2 id='maruku_summary_of_features'><span class='maruku_section_number'>5. </span>Maruku summary of features</h2>
<ul>
@@ -199,28 +212,32 @@
<p>See <a href='http://maruku.rubyforge.org/proposal.html'>this proposal</a> for how to attach metadata to the elements.</p>
<p>See the <a href='exd.html'>documentation for supported attributes</a>.</p>
<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
+
+<pre style='background-color: #ffefef;'><code>Title: A simple document containing meta-headers
CSS: style.css
-Content of the document
-</code></pre>
+Content of the document</code></pre>
+
<p>When creating the document through</p>
-<pre><code>Maruku.new(s).to_html_document
-</code></pre>
+
+<pre style='background-color: #efffef;'><code class='ruby' lang='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></code></pre>
+
<p>the title and stylesheet are added as expected.</p>
<p>Meta-data keys are assumed to be case-insensitive.</p>
<h3 id='toc-generation'><span class='maruku_section_number'>5.2. </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>* This will become a table of contents (this text will be scraped).
{:toc}
</code></pre>
+
<p>You can see an example of this at the beginning of this document.</p>
<h3 id='entities'><span class='maruku_section_number'>5.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>
@@ -240,41 +257,51 @@
<h2 id='extra'><span class='maruku_section_number'>6. </span>Examples of PHP Markdown Extra syntax</h2>
<ul>
<li>
<p>tables</p>
-<pre><code>Col1 | Very very long head | Very very long head|
+
+<pre style='background-color: #ffefef;'><code>Col1 | Very very long head | Very very long head|
-----|:-------------------:|-------------------:|
-cell | center-align | right-align |</code></pre><table><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>
+cell | center-align | right-align |</code></pre>
+<table><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>
+<pre style='background-color: #ffefef;'><code>* footnotes [^foot]
+
+[^foot]: I really was missing those.</code></pre>
+</li>
</ul>
<ul>
<li>
<p>Markdown inside HTML elements</p>
-<pre><code><div markdown="1" style="border: solid 1px black">
+
+<pre><code class='xml' lang='xml'><span class='punct'><</span><span class='tag'>div</span> <span class='attribute'>markdown</span><span class='punct'>="</span><span class='string'>1</span><span class='punct'>"</span> <span class='attribute'>style</span><span class='punct'>="</span><span class='string'>border: solid 1px black</span><span class='punct'>"></span>
This is a div with Markdown **strong text**
-</div></code></pre><div style='border: solid 1px black'>
+<span class='punct'></</span><span class='tag'>div</span><span class='punct'>></span></code></pre>
+<div style='border: solid 1px black'>
<p>This is a div with Markdown <strong>strong text</strong></p>
</div></li>
<li>
<p>header ids</p>
-<pre><code>## Download ## {#download}</code></pre>
+
+<pre style='background-color: #ffefef;'><code>## Download ## {#download}</code></pre>
+
<p>For example, <a href='#download'>a link to the download</a> header.</p>
</li>
<li>
<p>definition lists</p>
-<pre><code>Definition list
+
+<pre style='background-color: #ffefef;'><code>Definition list
: something very hard to parse</code></pre>
+
<dl>
<dt>Definition list</dt>
<dd>something very hard to parse</dd>
</dl>
@@ -294,6 +321,6 @@
[Pandoc]: http://sophos.berkeley.edu/macfarlane/pandoc/
[MultiMarkdown]: http://fletcher.freeshell.org/wiki/MultiMarkdown
--><div class='footnotes'><hr /><ol><li id='fn:1'>
<p>I really was missing those.</p>
-<a href='#fnref:1' rev='footnote'>↩</a></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-superset interpreter for Ruby'>Maruku</a> at 14:11 on Tuesday, January 23rd, 2007.</span></div></body></html>
+<a href='#fnref:1' rev='footnote'>↩</a></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-superset interpreter for Ruby'>Maruku</a> at 13:51 on Wednesday, January 24th, 2007.</span></div></body></html>