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 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. # GENERAL OPTIONS **-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.
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 -
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