git-annex/doc/todo/cleaner_hack_for_man_pages.mdwn

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:

[[!format diff """
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:

* [scripting](http://pandoc.org/scripting.html)
* [preprocessors](https://github.com/jgm/pandoc/wiki/Pandoc-Extras#preprocessors)
  like gpp
* external filters

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`).

[here's the diff]: http://fpaste.org/353524/

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.

 [personnal git-annex repo]: http://src.anarc.at/git-annex.git/
 [patch]: http://src.anarc.at/git-annex.git/commitdiff/d8a8f42f5a7ec0458718d65b72f1f814862b125b