maruku 0.2

data/docs/maruku.tex

@@ -0,0 +1,548 @@
+\documentclass{article}
+
+\usepackage{listings}
+
+\usepackage{hyperref}
+%\usepackage[x11names]{xcolor}
+\usepackage[usenames,dvipsnames]{color}
+\hypersetup{colorlinks=true}
+\begin{document} 
+\section*{Mar{\bf u}k{\bf u}: a Markdown interpreter}
+
+Maruku is a Markdown interpreter written in \href{http://www.ruby-lang.org}{Ruby}.
+
+Maruku allows you to write in an easy-to-read-and-write syntax, like this:
+
+\begin{quote}%
+\href{http://maruku.rubyforge.org/maruku.md}{This document in Markdown}
+
+
+\end{quote}
+Then it can be translated to HTML:
+
+\begin{quote}%
+\href{http://maruku.rubyforge.org/maruku.html}{This document in HTML}
+
+
+\end{quote}
+or Latex, which is then converted to PDF:
+
+\begin{quote}%
+\href{http://maruku.rubyforge.org/maruku.pdf}{This document in PDF}
+
+
+\end{quote}
+Maruku implements the original \href{http://daringfireball.net/projects/markdown/syntax}{Markdown syntax} (\href{http://maruku.rubyforge.org/markdown_syntax.html}{HTML} or \href{http://maruku.rubyforge.org/markdown_syntax.pdf}{PDF}, translated by Maruku).
+
+Markdown implements also all the improvements in \href{http://www.michelf.com/projects/php-markdown/extra/}{PHP Markdown Extra}.
+
+Moreover, it implements ideas from \href{http://fletcher.freeshell.org/wiki/MultiMarkdown}{MultiMarkdown}.
+
+
+\vspace{.5em} \hrule \vspace{.5em}
+{\em Table of contents}:
+
+\begin{itemize}%
+\item \hyperlink{download}{Download}
+
+
+\item \hyperlink{usage}{Usage}
+
+
+\item \hyperlink{extra}{Examples of PHP Markdown extra syntax}
+
+
+\item \hyperlink{meta}{New metadata syntax}
+
+
+\item \hyperlink{metalist}{List of metadata}
+
+
+\item \hyperlink{maruku-and-bluecloth}{Maruku and Bluecloth}
+
+
+\item \hyperlink{future}{Future developments}
+
+\begin{itemize}%
+\item \hyperlink{future-export}{Export to other formats}
+\item \hyperlink{future-syntax}{Syntax additions}
+
+\end{itemize}
+
+
+\end{itemize}
+
+\vspace{.5em} \hrule \vspace{.5em}
+\hypertarget{download}{}\subsection*{{Download}}
+
+The development site is \href{http://maruku.rubyforge.net/}{http://maruku.rubyforge.net/}.
+
+Download current \href{http://rubygems.rubyforge.org/}{gem} at \href{http://maruku.rubyforge.net/gem1.0}{http://maruku.rubyforge.net/gem1.0}
+
+\subsection*{Usage}
+
+This is the basic usage:
+
+\lstset{columns=fixed,frame=shadowbox}\lstset{showspaces=false,showtabs=false}
+\definecolor{maruku_color0}{rgb}{0.941176470588235,0.941176470588235,0.87843137254902}
+\lstset{backgroundcolor=\color{maruku_color0}}
+\lstset{basicstyle=\ttfamily\footnotesize}
+\lstset{language=ruby}
+
+\begin{lstlisting}
+require 'maruku'
+
+doc = Maruku.new(markdown_string)
+puts doc.to_html
+
+\end{lstlisting}or, if you install through RubyGems,
+
+\lstset{columns=fixed,frame=shadowbox}\lstset{showspaces=false,showtabs=false}
+\lstset{backgroundcolor=\color{maruku_color0}}
+\lstset{basicstyle=\ttfamily\footnotesize}
+\lstset{language=ruby}
+
+\begin{lstlisting}
+require 'rubygems'
+require 'maruku'
+
+\end{lstlisting}This outputs a complete XHTML 1.0 document:
+
+\lstset{columns=fixed,frame=shadowbox}\lstset{showspaces=false,showtabs=false}
+\lstset{backgroundcolor=\color{maruku_color0}}
+\lstset{basicstyle=\ttfamily\footnotesize}
+\lstset{language=ruby}
+
+\begin{lstlisting}
+puts doc.to_html_document
+\end{lstlisting}You can have the REXML document tree with:
+
+\lstset{columns=fixed,frame=shadowbox}\lstset{showspaces=false,showtabs=false}
+\lstset{backgroundcolor=\color{maruku_color0}}
+\lstset{basicstyle=\ttfamily\footnotesize}
+\lstset{language=ruby}
+
+\begin{lstlisting}
+tree = doc.to_html_document_tree
+
+\end{lstlisting}\subsubsection*{From the command line}
+
+There are two command-line programs installed: \colorbox{maruku_color0}{\tt \char109\char97\char114\char117\char107\char117} and \colorbox{maruku_color0}{\tt \char109\char97\char114\char117\char116\char101\char120}
+
+\colorbox{maruku_color0}{\tt \char109\char97\char114\char117\char107\char117} converts Markdown in HTML:
+
+\lstset{columns=fixed,frame=shadowbox}\lstset{showspaces=false,showtabs=false}
+\lstset{backgroundcolor=\color{maruku_color0}}
+\lstset{basicstyle=\ttfamily\footnotesize}
+\lstset{language={}}
+
+\begin{lstlisting}
+$ maruku file.md  # creates file.html
+
+\end{lstlisting}\colorbox{maruku_color0}{\tt \char109\char97\char114\char117\char116\char101\char120} converts Markdown in TeX, then calls \colorbox{maruku_color0}{\tt \char112\char100\char102\char108\char97\char116\char101\char120} to transform to PDF:
+
+\lstset{columns=fixed,frame=shadowbox}\lstset{showspaces=false,showtabs=false}
+\lstset{backgroundcolor=\color{maruku_color0}}
+\lstset{basicstyle=\ttfamily\footnotesize}
+\lstset{language={}}
+
+\begin{lstlisting}
+$ marutex file.md  # creates file.tex and file.pdf
+
+
+\end{lstlisting}\hypertarget{extra}{}\subsection*{{Examples of PHP Markdown Extra syntax}}
+
+\begin{itemize}%
+\item tables
+
+\lstset{columns=fixed,frame=shadowbox}\lstset{showspaces=false,showtabs=false}
+\lstset{backgroundcolor=\color{maruku_color0}}
+\lstset{basicstyle=\ttfamily\footnotesize}
+\lstset{language={}}
+
+\begin{lstlisting}
+Col1 | Very very long head | Very very long head|
+-----|:-------------------:|-------------------:|
+cell | center-align        | right-align        |
+
+\end{lstlisting}\begin{tabular}{l|c|r}
+Col1&Very very long head&Very very long head\\
+\hline 
+cell&center-align&right-align\\
+\end{tabular}
+
+
+\item footnotes \footnote{I really was missing those.} 
+
+\lstset{columns=fixed,frame=shadowbox}\lstset{showspaces=false,showtabs=false}
+\lstset{backgroundcolor=\color{maruku_color0}}
+\lstset{basicstyle=\ttfamily\footnotesize}
+\lstset{language={}}
+
+\begin{lstlisting}
+*footnotes [^foot]
+
+[^foot]: I really was missing those.
+\end{lstlisting}
+\item Markdown inside HTML elememnts
+
+
+
+\end{itemize}
+\lstset{columns=fixed,frame=shadowbox}\lstset{showspaces=false,showtabs=false}
+\lstset{backgroundcolor=\color{maruku_color0}}
+\lstset{basicstyle=\ttfamily\footnotesize}
+\lstset{language=html}
+
+\begin{lstlisting}
+<div markdown="1" style="border: solid 1px black">
+   This is a div with Markdown **strong text**
+</div>
+
+\end{lstlisting}{\bf Raw HTML removed in latex version }\begin{itemize}%
+\item header ids
+
+\lstset{columns=fixed,frame=shadowbox}\lstset{showspaces=false,showtabs=false}
+\lstset{backgroundcolor=\color{maruku_color0}}
+\lstset{basicstyle=\ttfamily\footnotesize}
+\lstset{language={}}
+
+\begin{lstlisting}
+## Header ##     {#id}
+\end{lstlisting}For example, \hyperlink{download}{a link to the download} header.
+
+
+\item definition lists
+
+\lstset{columns=fixed,frame=shadowbox}\lstset{showspaces=false,showtabs=false}
+\lstset{backgroundcolor=\color{maruku_color0}}
+\lstset{basicstyle=\ttfamily\footnotesize}
+\lstset{language={}}
+
+\begin{lstlisting}
+Definition list
+: something very hard to parse
+
+\end{lstlisting}\begin{description}
+
+\item[Definition list] something very hard to parse 
+\end{description}
+
+\item abbreviations or ABB for short.
+
+
+
+\end{itemize}
+\hypertarget{maruku-and-bluecloth}{}\subsection*{{Maruku and Bluecloth}}
+
+The other Ruby implementation of Markdown is \href{http://www.deveiate.org/projects/BlueCloth}{Bluecloth}.
+
+Maruku is much different in philosophy from Bluecloth: the biggest difference is that {\em parsing} is separated from {\em 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 \colorbox{maruku_color0}{\tt \char103\char115\char117\char98} to transform to HTML.\footnote{"a different philosophy" stands for "ugly" \colorbox{maruku_color0}{\tt \char58\char45\char41}} 
+
+The in-memory representation makes it very easy to export to various formats (altough, for, now)
+
+Other improvements over Bluecloth:
+
+\begin{itemize}%
+\item the HTML output is provided also as a \colorbox{maruku_color0}{\tt \char82\char69\char88\char77\char76} document tree.
+
+
+\item PHP Markdown Syntax support.
+
+
+
+\end{itemize}
+\hypertarget{meta}{}\subsection*{{New meta-data syntax}}
+
+Maruku implements a syntax that allows to attach "meta" information to objects.
+
+\subsubsection*{Meta-data for the document}
+
+Meta-data for the document itself is specified through the use of email headers:
+
+\lstset{columns=fixed,frame=shadowbox}\lstset{showspaces=false,showtabs=false}
+\lstset{backgroundcolor=\color{maruku_color0}}
+\lstset{basicstyle=\ttfamily\footnotesize}
+\lstset{language={}}
+
+\begin{lstlisting}
+Title: A simple document containing meta-headers
+CSS: style.css
+
+Content of the document
+
+\end{lstlisting}When creating the document through
+
+\lstset{columns=fixed,frame=shadowbox}\lstset{showspaces=false,showtabs=false}
+\lstset{backgroundcolor=\color{maruku_color0}}
+\lstset{basicstyle=\ttfamily\footnotesize}
+\lstset{language=ruby}
+
+\begin{lstlisting}
+Maruku.new(s).to_html_document
+
+\end{lstlisting}the title and stylesheet are added as expected.
+
+\subsubsection*{Meta-data for elements}
+
+Maruku introduces a new syntax for attaching metadata to paragraphs, tables, and so on.
+
+For example, consider the creation of two paragraphs:
+
+\lstset{columns=fixed,frame=shadowbox}\lstset{showspaces=false,showtabs=false}
+\lstset{backgroundcolor=\color{maruku_color0}}
+\lstset{basicstyle=\ttfamily\footnotesize}
+\lstset{language={}}
+
+\begin{lstlisting}
+Paragraph 1 is a warning.
+
+Paragraph 2
+
+\end{lstlisting}Now you really want to attach a 'class' attribute to the paragraphs (for example for CSS styling). Maruku allows you to use:
+
+\lstset{columns=fixed,frame=shadowbox}\lstset{showspaces=false,showtabs=false}
+\lstset{backgroundcolor=\color{maruku_color0}}
+\lstset{basicstyle=\ttfamily\footnotesize}
+\lstset{language={}}
+
+\begin{lstlisting}
+@ class: warning
+Paragraph 1 is a warning
+
+Paragraph 2
+
+
+\end{lstlisting}You can add more by separating with a \colorbox{maruku_color0}{\tt \char59}:
+
+\lstset{columns=fixed,frame=shadowbox}\lstset{showspaces=false,showtabs=false}
+\lstset{backgroundcolor=\color{maruku_color0}}
+\lstset{basicstyle=\ttfamily\footnotesize}
+\lstset{language={}}
+
+\begin{lstlisting}
+@ class: warning; id: warning1
+Paragraph 1 is a warning
+
+\end{lstlisting}A meta-data declaration is composed of
+
+\begin{enumerate}%
+\item newline
+\item an at-symbol '@'
+\item a series of name-value pairs. Each name-value is separated by a colon \colorbox{maruku_color0}{\tt \char58}, pairs are separated by semi-colons \colorbox{maruku_color0}{\tt \char59}
+
+\end{enumerate}
+Many declaration can be used, and they refer to {\em the following} object:
+
+\lstset{columns=fixed,frame=shadowbox}\lstset{showspaces=false,showtabs=false}
+\lstset{backgroundcolor=\color{maruku_color0}}
+\lstset{basicstyle=\ttfamily\footnotesize}
+\lstset{language={}}
+
+\begin{lstlisting}
+@ class: warning
+@ id: warning1
+Paragraph 1 is a warning
+
+\end{lstlisting}These can also be separated by newlines:
+
+\lstset{columns=fixed,frame=shadowbox}\lstset{showspaces=false,showtabs=false}
+\lstset{backgroundcolor=\color{maruku_color0}}
+\lstset{basicstyle=\ttfamily\footnotesize}
+\lstset{language={}}
+
+\begin{lstlisting}
+@ class: warning
+
+@ id: warning1
+
+Paragraph 1 is a warning
+
+\end{lstlisting}Also, if the value is not present, it defaults to \colorbox{maruku_color0}{\tt \char116\char114\char117\char101}:
+
+\lstset{columns=fixed,frame=shadowbox}\lstset{showspaces=false,showtabs=false}
+\lstset{backgroundcolor=\color{maruku_color0}}
+\lstset{basicstyle=\ttfamily\footnotesize}
+\lstset{language={}}
+
+\begin{lstlisting}
+@ test
+
+This paragraph has the attribute 'test' set.
+
+\end{lstlisting}
+\vspace{.5em} \hrule \vspace{.5em}
+\hypertarget{metalist}{}\subsection*{{List of meta-data}}
+
+\begin{description}
+
+\item[{\bf \colorbox{maruku_color0}{\tt \char116\char105\char116\char108\char101}, \colorbox{maruku_color0}{\tt \char115\char117\char98\char106\char101\char99\char116}}] (document) Sets the title of the document use in \colorbox{maruku_color0}{\tt \char116\char105\char116\char108\char101} element.
+
+ 
+
+\item[{\bf \colorbox{maruku_color0}{\tt \char99\char115\char115}}] (document, HTML) Url of stylesheet.
+
+ 
+
+\item[{\bf \colorbox{maruku_color0}{\tt \char108\char97\char116\char101\char120\char95\char117\char115\char101\char95\char115\char121\char110\char116\char97\char120}}] (document, HTML) Use the [\colorbox{maruku_color0}{\tt \char115\char121\char110\char116\char97\char120} library][syntax] to add source highlighting.
+
+ 
+
+\item[{\bf \colorbox{maruku_color0}{\tt \char108\char97\char116\char101\char120\char95\char117\char115\char101\char95\char108\char105\char115\char116\char105\char110\char103\char115}}] (document, LaTex) Use fancy \colorbox{maruku_color0}{\tt \char108\char105\char115\char116\char105\char110\char103} package for better displaying code blocks.
+
+ 
+
+\item[{\bf \colorbox{maruku_color0}{\tt \char115\char116\char121\char108\char101}, \colorbox{maruku_color0}{\tt \char105\char100}, \colorbox{maruku_color0}{\tt \char99\char108\char97\char115\char115}}] (any block object, HTML) Standard CSS attributes are copied.
+
+ 
+
+\item[{\bf \colorbox{maruku_color0}{\tt \char108\char97\char110\char103}}] (code blocks) Name of programming language (\colorbox{maruku_color0}{\tt \char114\char117\char98\char121}) for syntax highlighting (does not work yet)
+
+Default for this is \colorbox{maruku_color0}{\tt \char99\char111\char100\char101\char95\char108\char97\char110\char103} in document.
+
+ 
+
+\item[{\bf \colorbox{maruku_color0}{\tt \char99\char111\char100\char101\char95\char115\char104\char111\char119\char95\char115\char112\char97\char99\char101\char115}}] Shows tabs and newlines (default is read in the document object).
+
+ 
+
+\item[{\bf \colorbox{maruku_color0}{\tt \char99\char111\char100\char101\char95\char98\char97\char99\char107\char103\char114\char111\char117\char110\char100\char95\char99\char111\char108\char111\char114}}] Background color for code blocks. (default is read in the document object).
+
+The format is either a named color (\colorbox{maruku_color0}{\tt \char103\char114\char101\char101\char110}, \colorbox{maruku_color0}{\tt \char114\char101\char100}) or a CSS color of the form \colorbox{maruku_color0}{\tt \char35\char102\char102\char48\char48\char102\char102}.
+
+\begin{itemize}%
+\item for {\bf HTML output}, the value is put straight in the \colorbox{maruku_color0}{\tt \char98\char97\char99\char107\char103\char114\char111\char117\char110\char100\char45\char99\char111\char108\char111\char114} CSS property of the block.
+
+
+\item for {\bf LaTeX output}, if it is a named color, it must be a color accepted by the latex \colorbox{maruku_color0}{\tt \char99\char111\char108\char111\char114} packages. If it is of the form \colorbox{maruku_color0}{\tt \char35\char102\char102\char48\char48\char102\char102}, Maruku defines a color using the \colorbox{maruku_color0}{\tt \char92\char100\char101\char102\char105\char110\char101\char99\char111\char108\char111\char114} macro.
+
+For example, for \colorbox{maruku_color0}{\tt \char35\char48\char48\char48\char48\char102\char102}, the macro is called as:
+
+\lstset{columns=fixed,frame=shadowbox}\lstset{showspaces=false,showtabs=false}
+\lstset{backgroundcolor=\color{maruku_color0}}
+\lstset{basicstyle=\ttfamily\footnotesize}
+\lstset{language=tex}
+
+\begin{lstlisting}
+\definecolor{DummyName}{rgb}{0,0,1} 
+\end{lstlisting}
+
+\end{itemize}
+ 
+\end{description}
+\subsubsection*{Examples}
+
+An example of this is the following:
+
+\lstset{columns=fixed,frame=shadowbox}\lstset{showspaces=true,showtabs=true}
+\lstset{backgroundcolor=\color{maruku_color0}}
+\lstset{basicstyle=\ttfamily\footnotesize}
+\lstset{language={}}
+
+\begin{lstlisting}
+@ code_show_spaces; code_background_color: green
+
+	 One space
+	  Two spaces
+		 	Tab, space, tab
+				Tab, tab, tab and all is green!
+
+\end{lstlisting}That will produce:
+
+\lstset{columns=fixed,frame=shadowbox}\lstset{showspaces=true,showtabs=true}
+\lstset{backgroundcolor=\color{green}}
+\lstset{basicstyle=\ttfamily\footnotesize}
+\lstset{language={}}
+
+\begin{lstlisting}
+ One space
+  Two spaces
+	 	Tab, space, tab
+			Tab, tab, tab and all is green!
+
+\end{lstlisting}Example with css-style color:
+
+\lstset{columns=fixed,frame=shadowbox}\lstset{showspaces=false,showtabs=false}
+\lstset{backgroundcolor=\color{maruku_color0}}
+\lstset{basicstyle=\ttfamily\footnotesize}
+\lstset{language={}}
+
+\begin{lstlisting}
+@ code_background_color: #455678
+
+	A strange color
+
+\end{lstlisting}produces:
+
+\lstset{columns=fixed,frame=shadowbox}\lstset{showspaces=false,showtabs=false}
+\definecolor{maruku_color1}{rgb}{0.270588235294118,0.337254901960784,0.470588235294118}
+\lstset{backgroundcolor=\color{maruku_color1}}
+\lstset{basicstyle=\ttfamily\footnotesize}
+\lstset{language={}}
+
+\begin{lstlisting}
+A strange color
+
+\end{lstlisting}Or highlighting (does not work well yet):
+
+\lstset{columns=fixed,frame=shadowbox}\lstset{showspaces=false,showtabs=false}
+\lstset{backgroundcolor=\color{maruku_color0}}
+\lstset{basicstyle=\ttfamily\footnotesize}
+\lstset{language={}}
+
+\begin{lstlisting}
+@ lang: xml
+	<div style="text-align:center">Div</div>
+
+\end{lstlisting}produces:
+
+\lstset{columns=fixed,frame=shadowbox}\lstset{showspaces=false,showtabs=false}
+\lstset{backgroundcolor=\color{maruku_color0}}
+\lstset{basicstyle=\ttfamily\footnotesize}
+\lstset{language=xml}
+
+\begin{lstlisting}
+<div style="text-align:center">Div</div>
+
+\end{lstlisting}
+\vspace{.5em} \hrule \vspace{.5em}
+\hypertarget{future}{}\subsection*{{Future developments}}
+
+I think that \href{http://sophos.berkeley.edu/macfarlane/pandoc/}{Pandoc} and \href{http://fletcher.freeshell.org/wiki/MultiMarkdown}{MultiMarkdown} are very cool projects. However, they are written in Haskell and Perl, respectively. I would love to have an equivalent in Ruby.
+
+\hypertarget{future-syntax}{}\subsubsection*{{Syntax improvements}}
+
+Things I'm thinking about:
+
+\begin{itemize}%
+\item a syntax for commenting parts of the document:
+
+\lstset{columns=fixed,frame=shadowbox}\lstset{showspaces=false,showtabs=false}
+\lstset{backgroundcolor=\color{maruku_color0}}
+\lstset{basicstyle=\ttfamily\footnotesize}
+\lstset{language={}}
+
+\begin{lstlisting}
+This is a paragraph
+% This is a comment
+\end{lstlisting}
+\item choose a syntax for adding math:
+
+\lstset{columns=fixed,frame=shadowbox}\lstset{showspaces=false,showtabs=false}
+\lstset{backgroundcolor=\color{maruku_color0}}
+\lstset{basicstyle=\ttfamily\footnotesize}
+\lstset{language={}}
+
+\begin{lstlisting}
+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)
+\end{lstlisting}
+
+\end{itemize}
+
+\end{document}