Hosting Manpages and Project Documentation

To host my project documentation here, I setup OpenBSD’s man.cgi(8) which they use to host their manpages. While it’s not installed by default, if you have the source tree it’s very easy to go to /usr/src/usr.bin/mandoc/ and install it following the instructions in the Makefile:

1. Copy cgi.h.example to cgi.h and configure it
2. Run make man.cgi
3. Run make installcgi as root
4. Read man.cgi(8)

I’ve outlined the setup below for reference.

The Setup

As you’ll see later, httpd(8) is configured to expect man.cgi in /var/www/htdocs/man.jacobedwards.org. It also inserts the script name by rewriting requests, so SCRIPT_NAME is set to an empty string in cgi.h:

#define SCRIPT_NAME ""
#define MAN_DIR "/man"
#define CSS_DIR ""
#define CUSTOMIZE_TITLE "Manual pages with mandoc"

Once it’s installed, create an OpenBSD manual tree by copying /usr/share/man to /var/www/man/openbsd and creating a manpath.conf:

$ mkdir -p /var/www/man
$ cd /var/www/man
$ cp -a /usr/share/man openbsd
$ echo openbsd > manpath.conf

You’ll also need to enable slowcgi(8) to translate FastCGI requests and add something like this to your httpd.conf(5) :

server "man.jacobedwards.org" {
        listen on * tls port 443
        tls {
                certificate "/etc/ssl/jacobedwards.org.pem"
                key "/etc/ssl/private/jacobedwards.org.key"
        }
        fastcgi socket "/var/www/run/slowcgi.sock"
        root "/htdocs/man.jacobedwards.org"
        location "/mandoc.css" {
                no fastcgi
        }
        location match "(.*)" {
           request rewrite "/man.cgi/%1"
        }
}

Optionally add some CSS in mandoc.css¹ and once you reload httpd everything should work.

Automatically Creating a Manual Tree for Your Projects

To automatically generate a manual tree from my repositories, I wrote gitman.² It simply creates a manual tree from files matching the regular expression “.[0-9]$” in a bare git repository and uses makewhatis(8) to create a mandoc.db database.

So just add another manual tree to /var/www/man, update the manpath.conf³ and put a call to gitman in the post-update hooks for each repository you want to source the manuals from. Alternatively, create a central hook location like this

$ git config --global core.hooksPath ~/.git/hooks

and put a simple post-update script in it:

#!/bin/sh

! test -e "$GIT_DIR"/git-daemon-export-ok &&
	exit

stagit-hook
gitman