The Teetotaller

The legacy of the lightweight markup languages is on: Markdown and reStructuredText (reST) documents (I’ve written on both markups before) are highly fit for multi target publishing, the markup is pretty intuitive and extremely easy to read, high class documents (not only for software documentation) could be created with minimal effort, while having all the advantages of simple, source code like, most portable plain text files (applying revision control, using patches for corrections and suggestions, using programming tools like grep and sed, etc.), like with LaTeX. The Emacs Wiki claims about reST: perhaps the smartest smart ASCII yet devised.

Markdown: Basic lightweight-ing with Pandoc

Markdown originated as Perl tool for the convenient writing of HTML pages. If you would like to employ that plain text formatting syntax [1] for you own e-documenting toolchain you are going to come across the excellent markup converter Pandoc [2] (thanks Edgard for pointer!). Next to reST and other markups, Pandoc accepts Markdown and puts out several formats like HTML, LaTeX, Open Document Format (.odt), and EPUB. The wrapper markdown2pdf which is shipped with Pandoc creates PDFs right from the Markdown source with LaTeX, and a processed pandoctest.md results in this PDF here [3]. With Pandoc, another decent way to get a proper typesetted output is of course to save the Open Document Format and to employ e.g. LibreOffice to typeset a PDF out of it (through its PDF export function), like this one here. Please note that the original Markdown syntax lacks things like tables and footnotes, but Pandoc employs an own set of extensions [4].

[1] A complete syntax sheet of the core Markdown (for the extensions sets see [4]) is available on the project page. On the console, there is a manpage pandoc_markdown.

[2] In Tugboat 32,11, there is an article on Markdown with Pandoc by Axel Kielhorn). In Linux User 12 of 2010, there is a German article of Pandoc. On PhilTeX there is a nice post on using Markdown/Pandoc instead of LaTeX.

[3] Alternatively, foo.pdf could be given as output file. Next to pdfTeX, XeTeX could be chosen as LaTeX engine (through the –xetex switch). By the way, pandoc -f markdown -t latex -o pandoctext.tex pandoctest.md puts out only the raw LaTeX body, for a full fledged document the switch -s (standalone) must be given. pandoc -D latex spits out the full LaTeX template (the templates are developed independently, see here).

[4] There are several Markdown expansion sets around – if you would need some of them that certainly has its influence on your tool chain. Pandoc itself employs some Markdown extensions (see the Pandoc extensions), which could be suppressed with the option –strict. Another set of extensions was invented for Multimarkdown (note: the converter itself isn’t yet available for Debian, see here, but the MMD extensions are available through the Perl module Text::Multimarkdown, see here).

reST: Generating classy booklets with Sphinx

reStructuredText [5] originated in Python source code documentation, and so the Docutils suite comes with several self standing markup conversion tools like rst2html, rst2latex, etc. Pandoc – like said – is also capable of working with reST markup. But especially the Python documentation system Sphinx is highly capable of creating high-end electronic documents from reST source [6]. After the Sphinx package has been installed, switch into a random folder and to sphinx-quickstart to create a full Sphinx environment (you can accept the suggested default values throughout, but of course the title and author, and also a revision number have to be given). After that, some files and folders appeared. The file conf.py contains the Options for LaTeX output, which could be modified here. To create a nice booklet from an example.rst (which has been converted from Markdown to reST with Pandoc), that file must be added to index.rst below toctree, and after that a make latexpdf builds a PDF out of it in _build/latex – of course the basic LaTeX packages are needed for that. Sphinx is highly expandable through extensions which makes a pretty versatile document preparation system also beyond Python source documentation.

[5] See the Docutils primer, and the also the more exhaustive specification. Also the Sphinx documentation of course includes a reST primer.

[6] On e-documenting with Sphinx, see sampledoc tutorial from the Matplotlib guys, the article of Sphinx on IBM developer works, and (most sophisticated on documenting Python stuff) Doug Hellmann’s marvelous blog post.

reST: Lightweight markup for ultra productive presentations

Another way to get a PDF from reST source is the converter rst2pdf, which makes use of the ReportLab PDF library for Python [7]. That makes up a lean, very effective e-document solution because it totally saves from running even a basic LaTeX distribution in the background to render the PDFs. Lately I came across a very nice blog post on creating presentations with reST and rst2pdf in an ultra effective manner which is very useful and which certainly beats Beamer and the others in terms of effectiveness – if you can spare things like breaks in lists and you just need simple and robust presentations slides on PDF bases very quickly it looks like there isn’t nothing better [8]. A crucial feature of rst2pdf for this purpose is the use of custom templates resp. themes. For everything, please check out Alexis’ example and the rst2pdf manual.

[7] I’ve written on ReportLab before, see here. Rst2pdf have be announced lately to get proper further developed in the future, see here, which is all right because it’s a very fine piece of software! By the way, rst2pdf could be also employed as engine for Sphinx.

[8] As a matter of fact, Pandoc supports S5 and other browser based slide show formats. Sniffing around for reST stuff I came across the presentation framework Bruce, which makes use of reST and which renders directly to the display, but unfortunately the project looks pretty dead (the pip download fails, latest uploads was and the given copyrights expired 2009, etc.). By the way, another very fine piece of Python based software for presentations is Impressive, the “Chuck Norris of presentation software” – a luxurier for PDF based slides with pure sex-like high-end features (like an expiring time bar which changes its color!) really makes a king of a conference!

Lightweight-ing with the Emacs

Things like lightweight markup-ed plain text files are certainly the domain of the Emacs editor, and there are of course modes available for reST (rst.el, part of python-doctutils), as much as for editing Markdown (markdown-mode.el, part of emacs-goodies.el). These modes put some convenience into editing reST and Markdown. In a random buffer, switch to the rsST mode with M-x rst-mode, and after that, things like syntax highlighting, helpers for decorations (like underline completion), a helper for the table of contents, and many other things are available. But really helpful is Emacs when it comes to tables, which – following the paradigm of classic ASCII tables – are a real pain to write because the whole thing has to be “painted” [9]. But as a matter of fact, the Emacs table mode handles ASCII tables pretty well, like it is explained on the mode’s homepage and in the table.el tutorial on the Emacs Wiki [10].

[9] While within reST, tables are part of the specification (cf. the reST specification), but tables are extensions of Markdown (e.g. cf. Tables in the Pandoc manual).

[10] The table mode is part of a standard current Emacs, but to get it into charge you have to add the line (require ‘table) to /etc/emacs/site-start.el.

Markdown at WordPress

Markdown libraries are available for several programming languages, e.g. for Python, for C there is Sundown, for Ruby there are several ones like Redcarpet and Bluecloth, and for Lua there is a standard library and Lunamark, and finally, also the PHP implementation PHP Markdown. The PHP Markdown library is said to generally work together with WordPress, so I just test drived the latest revision of PHP Markdown Extra (which also employs an own extension set) with a test instance of WordPress 3.3.1: the library markdown.php has to be putted into wp-content/plugins, after that the Plugin Markdown Extra appears and Markdown syntax really becomes available in the HTML editing mode of your blog posts – great!