119 lines
4.4 KiB
Markdown
119 lines
4.4 KiB
Markdown
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
|