Writing Man Pages with Pandoc
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:
% SNOWPLOUGH(1)
% Jérôme Belleman
% June 2013
# NAME
snowplough – shovel off ServiceNow tickets
# SYNOPSIS
**snowplough** [**-h**] [**--configfile** *CONFIGFILE*] [**--sort**] [**--vim**] *keyword* [*keyword ...*]
# DESCRIPTION
**snowplough** is a simple-minded tool that creates indices and
body-searches vast quantities of ServiceNow tickets, which is useful to
find out how someone before you solved one particular problem.
# GENERAL OPTIONS
**-h**, **-\-help**
: Display a friendly help message.Note how I escaped one of --help's hyphens to stop Pandoc turning -- into an em-dash. (Thank you, Zachary Vance, for pointing this out to me!)
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.