Location of man pages:
	debian: /usr/share/man

-----------------------------------------------------------------------------

How do I get a plain text man page without all that ^H^_ stuff?

Have a look at col(1), because col can filter out backspace sequences. Just
in case you can't wait that long:

	groff -t -e -mandoc -Tascii manpage.1 | col -bx > manpage.txt

The -t and -e switches tell groff to preprocess using tbl and eqn. This is
overkill for man pages that don't require preprocessing but it does no harm
apart from a few CPU cycles wasted. On the other hand, not using -t when it
is actually required does harm: the table is terribly formatted. You can even
find out (well, "guess" is a better word) what command is needed to format a
certain groff document (not just man pages) by issuing:

	grog /usr/man/man7/signal.7
	groff -t -man /usr/man/man7/signal.7

"grog" stands for "GROff Guess", and it does what it says--guess. If it were
perfect we wouldn't need options any more. I've seen it guess incorrectly on
macro packages and on preprocessors. Here is a little perl script I wrote
that can delete the page headers and footers, thereby saving you a few pages
when printing long and elaborate man pages. Save it as "strip-headers" and
chmod 755:

#!/usr/bin/perl -wn
#  make it slurp the whole file at once:
undef $/;
#  delete first header:
s/^\n*.*\n+//;
#  delete last footer:
s/\n+.*\n+$/\n/g;
#  delete page breaks:
s/\n\n+[^ \t].*\n\n+(\S+).*\1\n\n+/\n/g;
#  collapse two or more blank lines into a single one:
s/\n{3,}/\n\n/g;
#  send to STDOUT:
print;

You have to use it as the first filter after the man command as it relies on
the number of newlines being output by groff. For example:

	man bash | strip-headers | col -bx > bash.txt

-----------------------------------------------------------------------------

How do I get a high quality PostScript man page?

funnyprompt$ groff -t -e -mandoc -Tps manpage.1 > manpage.ps

Print or view that using your favorite PostScript printer/viewer. See 
question 10) for an explanation of the options.

-----------------------------------------------------------------------------

Polishing your man page

Following are some guidelines that increase reliability, readability and
'formatability' of your documentation.

  * Test examples to make sure they work (use cut and paste to give your
    shell the exact wording from the man page). Copy the output of your
    command into your man page, don't just type what you think your program
    will print.

  * Proof read, ispell, and have someone else read it, especially if you are
    not a native English speaker. The HOWTO you are reading has passed the
    latter test (special thanks to Michael Miller for a particular heroic
    contribution! All the remaining rough edges are entirely my fault).
    Additional volunteers are always welcome.

  * Test your man page: Does groff complain when you format your man page?
    It's nice to have the groff command line in a comment. Does the man(1)
    command complain when you call man yourprog? Does it produce the expected
    result? Will xman(1x) and tkman(1tk) cope with your manual? XFree86 3.1
    has xman 3.1.6 - X11R6, it will try to uncompress usinggzip -c -d < %s >
    %s zcat < %s > %s

  * Will makewhatis(8) be able to extract the one-line description from the
    NAME section?

  * Translate your man page to HTML format using rman from [http://
    polyglotman.sourceforge.net/] http://polyglotman.sourceforge.net/, and
    view the result with a a set of web browsers (netscape, mozilla, opera,
    lynx, ...) Check that the cross-references among your man pages work as
    hyperlinks in the generated HTML. If your software package has a web
    site, post its man pages there, and keep them up-to-date.

  * The rman utility can also translate man pages into LaTeX, RTF, SGML, and
    other formats; check these out if you want to incorporate your man pages
    in a book or other larger document.

  * Try translating your man page to HTML using man2html, which has been part
    of the Linux man package since man-1.4. The man2html utility is a less
    ambitious translator than rman, but almost every Linux user has it
    already, so it is worth making sure that man2html does not choke on your
    man page.