9. 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/, 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.