Bookmark and Share

Using Multimarkdown in Windows and in Ubuntu

Some of us simply don’t like using WYSIWYG word processors such as Microsoft Word or OpenOffice.org Writer. They’re far too complex tools, drawing your focus from writing to things that are irrelevant at the moment of writing (like formatting and layout). The documents feel fragile (“move this thing here and your whole layout breaks and you’ll spend an hour fixing it”). The document format is unstable: have you ever tried to open a .doc file created with some other version of Word than the one that you currently happen to use? How about opening a 10-year old document? There’s no way to easily see the differences between several versions of a document—like you can with version control / diff tools that programmers use—and so on.

Many serious writers refuse to use such lousy tools. For instance, in technical and scientific academia the de facto system for making publications is LaTeX, not least because of its unrivalled equation typesetting capability and beautiful output quality. Also, there’s the general idea of separating content from form, letting the writer just write for now and worry about the exact layout, fonts etc. later on. This kind of tools appeal especially to programmers; they’re not afraid of markup rules, and they like and care about working on plain text editors because they work that way most of the time anyway.

LaTeX is great for writing a scientific article or a book. But for most everyday purposes it’s way overkill: writing a letter or writing a book are kind of different things. And the syntax is… oh, well. You can do anything with it—provided that you can! I can’t, and besides, I would rather concentrate on writing. Separating content and presentation is a beautiful idea, in principle, but since people (including me) care about presentation, they also tend to think in terms of presentation. People may say they want a word in cursive when they really mean that they want to emphasize it. Html <em> element is typically (but not necessarily) rendered as italic (cursive) text. But the visual result is the natural way to think about it.

So, could we use a more human input syntax with less ceremony, and still get LaTeX quality output and the benefits of keeping source files in plain text? Yes, we can! There are several capable tools for this. Let’s have a look at MultiMarkdown. It’s a set of Perl scripts that can turn Markdown formatted documents into XHTML, PDF, and some other formats. One human readable source file, many beautifully typeset output formats. Excellent!

Markdown syntax is simple and effective. Limited, yes, which can also be a blessing: if you can’t express yourself with simple means, consider refactoring your thoughts before blaming the tool. The end result could be better and clearer that way.

MultiMarkdown (MMD) syntax adds some features to Markdown (MD) syntax, but the latter is a valid subset of MMD syntax, so the fundamental simplicity of basic MD is retained.

Here is a good presentation explaining MultiMarkdown in more detail:

http://github.com/fletcher/MultiMarkdown-Gallery/raw/master/What-Is-MMD/what_is_mmd.pdf

Producing PDF documents works like this:

  1. You create a (Multi)Markdown formatted document using your favorite text editor.
  2. MultiMarkdown converts that document to a LaTeX document.
  3. pdflatex (part of the LaTeX system) converts that document to a PDF file.

Sounds a bit complicated, but once set up it works smoothly. A little problem is that MultiMarkdown is really just a bunch of Perl scripts and some template files. Good enough for programmers, but how about the other people? The author’s own pages are somewhat Mac biased, and offer little help for people not using Mac. So, here’s how to actually set up MultiMarkdown in Windows and in Ubuntu Linux. It’s indeed worth it.

Windows

You’ll need the following packages:

After installing Perl and MiKTeX, check that at least perl and pdflatex are properly on the path. Things should look something like this on the command prompt:

C:\Users\jmp>perl -v
This is perl, v5.10.1 (*) built for MSWin32-x86-multi-thread
etc...

C:\Users\jmp>pdflatex -version
MiKTeX-pdfTeX 2.8.3563 (1.40.10) (MiKTeX 2.8)
etc...

I had to manually add C:\strawberry\c\bin;C:\strawberry\perl\bin to the system path, the installer didn’t make it for some reason. See http://win32.perl.org/wiki/index.php?title=Strawberry_Perl for help.

Now that the environment is ready, you need to install MultiMarkdown itself. So just extract the .zip package to anywhere: to C:\Program Files\multimarkdown, for instance. Then go (via the command prompt) to that place, and type the following:

perl bin\mmd2PDF.pl "Documentation\MultiMarkdown User's Guide.md"

At the first run MiKTeX will download install some necessary extra packages missing from the base installation. There may also be some errors regarding \includexmp{CCAttributionShareAlike}, but just hit Enter to skip them. Soon you’ll have two new files in the Documentation directory: a .tex file, which is an intermediate product, and a .pdf file, which is the final product (MultiMarkdown’s User Guide, actually).

All right, it (hopefully) works now, but sure you’re not going to surf to command line and type the same commands again and again as a part of your daily workflow? While waiting for someone to invent a better solution, we can use the following trick.

Create a desktop shortcut with the following target property: <path_to_your_perl_exe> <path_to_the_mmd_script> %1. For instance, C:\strawberry\perl\bin\perl.exe C:\Program Files\multimarkdown\bin\mmd2PDF.pl %1. Now just drag an .mmd file to be converted and drop it on the shortcut. The output .tex and .pdf files will go into the same directory as the source .mmd file. You need to create separate shortcuts for each output format you want to use.

Next, let’s see how to accomplish the same in Ubuntu:

Ubuntu Linux

You’ll need the following packages:

  • Perl
  • TeX Live LaTeX Extra (The texlive-latex-base package seems not to be enough for MultiMarkdown; at least layouts.sty is missing.)
  • MultiMarkdown (Get the .zip package or clone the repository locally.)

After installing Perl and Tex Live, check that at least perl and pdflatex work properly. Things should look something like this on the command prompt:

jpulakka@turboahdin:~$ perl -v
This is perl, v5.10.0 built for i486-linux-gnu-thread-multi
etc...

jpulakka@turboahdin:~$ pdflatex -version
pdfTeX using libpoppler 3.141592-1.40.3-2.2 (Web2C 7.5.6)
etc...

Now that the environment is ready, you need to install MultiMarkdown itself (unless you cloned the repository—in which case you already have “installed” it). So just extract the .zip package to somewhere. Then go to that place, and type the following:

bin/mmd2PDF.pl "Documentation/MultiMarkdown User's Guide.md"

There will be some errors regarding \includexmp{CCAttributionShareAlike}, but just hit Enter to skip them. Soon you’ll have two new files in the Documentation directory: a .tex file, which is an intermediate product, and a .pdf file, which is the final product (MultiMarkdown’s User Guide, actually).

It’s convenient to add the bin/ directory of the MultiMarkdown distribution to the system’s PATH, so that it can be similarly run from any other directory. I just added the following to the end of my .bashrc:

PATH=~/MultiMarkdown/bin:”${PATH}”

Editor concerns

There are Markdown modes for Emacs as well as for Vim. Both of these support the basic Markdown syntax, but the full MultiMarkdown syntax is currently unsupported outside the TextMate scene (that is, Apple only). This is not a big deal, given that “support” here mostly means just proper syntax highlighting. Plain Markdown highlighting works well enough most of the time.

Other similar tools

Pandoc looks quite an attractive alternative. Maybe I’ll have a look at it some time soon.

Last modified: 2010-02-21 16:03 +0200


blog comments powered by Disqus