Switch to pandoc for all documentation

pandoc can generate stand-alone HTML, an automatic TOC, and
the only Markdown processor I know of capable of generating
manpages.

Markdown is also a more standard syntax than txt2man and
appropriate for generating HTML versions of manpages.

3 files changed, 113 insertions, 85 deletions

diff --git a/Makefile b/Makefile
index d846d32..f896181 100644
--- a/Makefile
+++ b/Makefile
@@ -5,7 +5,10 @@ prefix = $(HOME)
 bindir = $(prefix)/bin
 mandir = $(prefix)/share/man
 INSTALL = install
-TXT2MAN = txt2man
+PANDOC = pandoc
+PANDOC_OPTS = -s -f markdown --email-obfuscation=none --sanitize-html
+pandoc = $(PANDOC) $(PANDOC_OPTS)
+pandoc_html = $(pandoc) --toc -t html --no-wrap
 STRIP ?= strip
 GIT-VERSION-FILE: .FORCE-GIT-VERSION-FILE
         @./GIT-VERSION-GEN
@@ -42,13 +45,17 @@ install-strip: strip
         $(MAKE) install
 
 %.1: %.1.txt
-        $(TXT2MAN) -r 'pcu $(GIT_VERSION)' \
-          -v 'Page Cache Utilities Reference Manual' \
-          -t $(basename $@) -s 1 < $< > $@+
+        $(pandoc) -t man < $< > $@+
+        mv $@+ $@
+%.1.html: %.1.txt
+        $(pandoc_html) -T $(basename $@) < $< > $@+
         mv $@+ $@
 
 man1 := $(addsuffix .1,$(PCU_BIN))
+html := index.html $(addsuffix .html, $(man1))
+html: $(html)
 man: $(man1)
+doc: html man
 install-man: install-man1
 install-man1: $(man1)
         $(INSTALL) -d -m 755 '$(DESTDIR)$(mandir)/man1'
@@ -60,12 +67,11 @@ dist: GIT-VERSION-FILE
         mv $(DISTNAME).tar.gz+ $(DISTNAME).tar.gz
 clean:
         $(RM) $(PCU_BIN) $(DISTNAME).tar.gz* GIT-VERSION-FILE
-        $(RM) $(man1)
+        $(RM) $(man1) $(html)
 
 index.html: title = $(shell sed -ne 1p < $<)
 index.html: README
-        markdown $< | (tidy -q 2>/dev/null || true) | \
-          sed 's,<title></title>,<title>$(title)</title>,' > $@+
+        $(pandoc_html) -T "$(title)" < $< > $@+
         mv $@+ $@
 
 .PHONY: .FORCE-GIT-VERSION-FILE install install-man man
diff --git a/pcu-fadvise.1.txt b/pcu-fadvise.1.txt
index 9e10c8b..6a0cd1c 100644
--- a/pcu-fadvise.1.txt
+++ b/pcu-fadvise.1.txt
@@ -1,44 +1,57 @@
-NAME
-  pcu-fadvise - predeclare an access pattern on given files
-SYNOPSIS
-  pcu-fadvise [-a advice] [-o offset] [-l length] FILE...
-DESCRIPTION
-  A command-line interface to the posix_fadvise(2) syscall to tell
-  the kernel to optimize access patterns for specified files.
-OPTIONS
-  -a advice
-
-  File access pattern advice.
-  The advice must be one of the following:
-
-    normal
-    sequential
-    random
-    noreuse
-    willneed
-    dontneed
-
-  The default advice is normal.
-
-  -o offset
-
-  Apply advice only to the given byte offset.
-  This offset rounded down to the previous page offset.
-  The default offset is zero (beginning of the file)
-
-  -l length
-
-  Apply advice only to the given length in bytes.
-  This length is rounded up next page offset.
-  The default is to scan the entire file.
-
-OUTPUT
-  Errors only.
-ENVIRONMENT
-  none
-SEE ALSO
-  posix_fadvise(2)
-BUGS
-  None known. Email the author if you find any.
-AUTHOR
-  Eric Wong <normalperson@yhbt.net>
+% PCU-FADVISE(1) Page Cache Utilities Manual
+% Eric Wong <normalperson@yhbt.net>
+% July 26, 2009
+
+# NAME
+
+pcu-fadvise - predeclare an access pattern on given files
+
+# SYNOPSIS
+
+pcu-fadvise [*-a ADVICE*] [*-o OFFSET*] [*-l LENGTH*] FILE...
+
+# DESCRIPTION
+
+A command-line interface to the posix_fadvise(2) syscall to tell
+the kernel to optimize access patterns for specified files.
+
+# OPTIONS
+
+-a *ADVICE*
+:   File access pattern advice.
+
+:   *ADVICE* must be one of the following:
+
+      * normal
+      * sequential
+      * random
+      * noreuse
+      * willneed
+      * dontneed
+
+     The default advice is `normal`.
+
+-o *OFFSET*
+:   Apply advice only to the given byte offset.
+    This offset rounded down to the previous page offset.
+    The default offset is zero (beginning of the file).
+
+-l *LENGTH*
+:   Apply advice only to the given length in bytes.
+    This length is rounded up next page offset.
+    The default is to scan the entire file.
+
+# OUTPUT
+
+Errors only.
+
+# ENVIRONMENT
+
+none
+
+# SEE ALSO
+[`posix_fadvise`(2)](http://linux.die.net/man/2/posix_fadvise)
+
+# BUGS
+
+None known. Email <pcu@librelist.com> if you find any.
diff --git a/pcu-mincore.1.txt b/pcu-mincore.1.txt
index d2334e5..db4f071 100644
--- a/pcu-mincore.1.txt
+++ b/pcu-mincore.1.txt
@@ -1,34 +1,43 @@
-NAME
-  pcu-mincore - shows cache status for given files
-SYNOPSIS
-  pcu-mincore [-o offset] [-l length] FILE...
-DESCRIPTION
-  A command-line interface to the mincore(2) syscall to inspect
-  whether or not certain pages belonging to a file are cached in
-  resident memory.
-OPTIONS
-  -o offset
-
-  Scan only pages on or after the given offset.
-  This offset is rounded down to the previous page offset.
-  The default offset is zero (beginning of the file)
-
-  -l length
-
-  Check only the given length in bytes.
-  This length is rounded up next page offset.
-  The default is to scan the entire file.
-OUTPUT
-  One line for every page scanned in the following format:
-
-  <filename>: <offset> <incore>
-
-  offset is a hexadecimal number for a given range of PAGE_SIZE bytes.
-  incore is a boolean value indicating whether or not the page beginning
-  at a particular offset is cached in resident memory or not.
-SEE ALSO
-  mincore(2)
-BUGS
-  None known. Email the author if you find any.
-AUTHOR
-  Eric Wong <normalperson@yhbt.net>
+% PCU-MINCORE(1) Page Cache Utilities Manual
+% Eric Wong <normalperson@yhbt.net>
+% July 26, 2009
+
+# NAME
+pcu-mincore - shows cache status for given files
+
+# SYNOPSIS
+pcu-mincore [-o OFFSET] [-l LENGTH] FILE...
+
+# DESCRIPTION
+A command-line interface to the mincore(2) syscall to inspect
+whether or not certain pages belonging to a file are cached in
+resident memory.
+
+# OPTIONS
+-o OFFSET
+:   Scan only pages on or after the given offset.
+    This offset is rounded down to the previous page offset.
+    The default offset is zero (beginning of the file)
+
+-l LENGTH
+:    Check only the given length in bytes.
+    This length is rounded up next page offset.
+    The default is to scan the entire file.
+
+# OUTPUT
+One line for every page scanned in the following format:
+
+   \<filename\>: \<offset\> \<incore\>
+
+offset is a hexadecimal number for a given range of PAGE_SIZE bytes.
+incore is a boolean value indicating whether or not the page beginning
+at a particular offset is cached in resident memory or not.
+
+# ENVIRONMENT
+none
+
+# SEE ALSO
+[`mincore`(2)](http://linux.die.net/man/2/mincore)
+
+# BUGS
+None known. Email <pcu@librelist.com> if you find any.