In recent history, we have realized that the small Perl script that generates the man pages from Markdown is fairly limited.

Two approaches have been considered:

  • go-md2man
  • pandoc

Here is how pandoc does it:

$ pandoc -f markdown -t man doc/git-annex-shell.mdwn | pastebinit
http://paste.debian.net/424341/

Both initially fail at setting a proper .TH line on top, but otherwise seem to work more or less correctly. --anarcat

Okay, update: the above commandline was incorrect for some reason. The proper incantation is:

pandoc -s -t man doc/git-annex-shell.mdwn -o git-annex-shell.1

For example:

$ pandoc -s -t man doc/git-annex-shell.mdwn | man -l - | pastebinit
http://paste.debian.net/430630/

So by default, there is no title or section header, which is, if you ask me a little stupid: pandoc could guess a little better and parse the .SH NAME section.

The workaround for this is to add Pandoc metadata either to the file, for example:

diff --git a/doc/git-annex-shell.mdwn b/doc/git-annex-shell.mdwn
index 9b3d126..13f64ae 100644
--- a/doc/git-annex-shell.mdwn
+++ b/doc/git-annex-shell.mdwn
@@ -1,3 +1,6 @@
+% git-annex-shell(1) Git-annex manual | Version 5
+% Joey Hess
+
 # NAME
 
 git-annex-shell - Restricted login shell for git-annex only SSH access

But Ikiwiki is likely to barf on such comments, so it's probably preferable to pass those parameters at build time:

$ pandoc -s -V title="git-annex-shell" -V section=1 -t man doc/git-annex-shell.mdwn  | man -l - | pastebinit
http://paste.debian.net/430632/

Looks better already! But we can improve on that even more!

$ pandoc -s -V title="git-annex-shell" -V section=1 \
    -V header="Git Annex manual" -V footer="Version 5.xxx" \
    -t man doc/git-annex-shell.mdwn  | man -l - | pastebinit
http://paste.debian.net/430633/

Much better. And the version can probably be passed in from the build system (or that footer can just be dropped).

So a more complete patch would involve fixing the build system to use (and depend on!) pandoc then remove the pesky warnings at the bottom of all Markdown files.

More investigation would probably be necessary to check the resulting man pages for syntax errors. For example, the above rendering, in the SEE ALSO section, has [git-annex] (1) instead of git-annex(1), since Pandoc doesn't know about ikiwiki links. Maybe some pre-processing would be necessary there? :/ It sure is useful to have those links working in the web version!

I hope that helps regardless.

Update: regarding preprocessing, it seems there are basically two options for preprocessing with pandoc:

Preprocessors don't support arbitrary patterns like Ikiwiki links, so they're out already. Scripting looks a little too complicated for us, but could be a more stable alternative in the long term (if not for Ikiwiki itself ;).

So I ended up using a simple sed(1) filter for now. It would be quite interesting to implement a better filter directly in Pandoc, if only for the benefit of Ikiwiki (which could then all be reimplemented in Haskell, No Big Deal™). But for now, I am afraid that will have to do.

The resulting manpages are quite different, here's the diff. It seems mostly better escapes and markup, in general. We get nicer bullet lists, cleaner command names (git-annex add instead of git-annex-add).

I have pushed a patch that implements a Pandoc build to my personnal git-annex repo. It also adds pandoc as a build-dep to the debian package - and I may be missing some parts of the build system, hopefully you will find the missing bits and fix them, if any.

Pandoc is awesome, and I think a great fit for this! --anarcat

Oh, and I forgot: another thing that is not handled through this (yet?) is the "Version" footer I was using in the above examples. I couldn't figure out how to pull that value out of the Makefile, but maybe I missed something obvious there. I also didn't notice the git-union-merge.1 manpage, but it seems to be broken anyways, as it is not in the man/ directory and there is a comment there saying it is "not built normally" so I ignored it.