[Slackbuilds-users] HTML man page mini-HOWTO

[B Watson]

This may end up on the slack docs wiki, I thought I'd write it up here
first & hopefully get some feedback. I might be the only one who even
thinks this is a good idea, I dunno (I'm one of those "everything needs
a man page" adherents).

It turns out that Slackware's man command knows how to display HTML pages,
using a browser as a pager. If you're packaging something that has no
man pages, but has a well-written readme.html or usage.html or such,
you can install the HTML file like so:

mkdir -p $PKG/usr/man/html1
gzip -9c < whatever.html > $PKG/usr/man/html1/$PRGNAM.1.html.gz

(change the 1 in html1 and .1.html.gz to whatever section number makes
sense, of course)

Alternatively, keep the file in /usr/doc/ and make a symlink:

# after copying the docs to /usr/doc
# (notice, no .gz extension here)
mkdir -p $PKG/usr/man/html1
ln -s ../../doc/$PRGNAM-$VERSION/whatever.html $PKG/usr/man/html1/$PRGNAM.1.html

man uses lynx to display it by default. You can set BROWSER in the
environment to use something else (even firefox, if you really want to).
There's also an HTMLPAGER variable that's only used when man's stdout
isn't a terminal (redirected or piped), which defaults to "lynx -dump".

If the source comes with a lot of HTML docs that link to each other, this
probably isn't a great idea: you'd have to patch or use sed to change
all the hyperlinks to whatever.1.html.gz, and maybe rename the files to
something users might expect a man page to be called (e.g. TechNotes.html
would want to be called ${PRGNAM}_technotes.1.html.gz).

Also if the HTML docs use lots of images (content-bearing ones, not
just decorations), it's probably not useful to pretend it's a man page
as most people will be using lynx to display it.