Jérôme Belleman
Home  •  Tools  •  Posts  •  Talks  •  Travels  •  Graphics  •  About Me

Writing Man Pages with Pandoc

24 Dec 2014

Pandoc offers a very effective and comfortable way to write UNIX manual pages with, for instance, Markdown, which is much more affordable than using groff.

Pandoc is a markup converter and understands a wealth of languages. One of them is Markdown which, so far, I've found to be the most comfortable to work with.

1 Sample Man Page

You can add some useful information about the man page with the title block, e.g. the page name (make sure to specify the section number, lest it shows up as an empty pair of brackets, ()), the author and the date:

% Jérôme Belleman
% June 2013


snowplough – shovel off ServiceNow tickets




**snowplough** is a simple-minded tool which creates indices and
body-searches vast quantities of ServiceNow tickets, which is useful to
find out how someone before you solved one particular problem.


**-h**, **--help**
:   Display a friendly help message.

For some reason I can't quite understand yet, you'll want to use non-breaking spaces (Vim users, that's CTRL-KNS) instead of regular spaces in usage lines which have quick sequences of markup. This is to avoid a parsing problem whereby stars (*) are displayed verbatim instead of being interpreted as style.

Sections and subsections are understood and turned into something useful. Maybe even more levels. Use definition lists for e.g. option lists. Other types of lists are understood too.

Verbatim text (i.e. between backticks, `...`) doesn't show in any particular way – just treated verbatim, I suppose. Therefore, I like to display code in bold (**...**) and names italic/underlined (*...*). Code blocks (i.e. between triple backticks, ```) are treated verbatim too.

2 Rendering

While writing your man page, it's convenient to run this command every time you want to check what the rendered page looks like:

% pandoc snowplough.md -s -t man | /usr/bin/man -l -

3 Outlook

Pandoc allegedly being a universal converter, writing man pages with it means you can easily convert them into anything else you fancy, e.g. HTML documents, as I have done for newstar, fairshare, snowplough, python-cmdline and others.

4 Pandoc Availability

Pandoc is available in lxplus, aiadm and most RPM repositories. It's written in Haskell, which means it relies on hundreds of megabytes of library dependencies.

There's ronn too which is available in a package called ruby-ronn in Debian-like distributions. It's not bad – just found pandoc allowed for a nicer markup. Not to be confused with ronnjs which is what you'll find in Red Hat-like distributions in a package called nodejs-ronn. A JavaScript reimplementation of ronn, it just doesn't quite cut it, truth must be said.

5 References