9. Polishing your man
pageFollowing 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/, 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.
|
|
