Polishing your man page

Linux Man Page Howto
Prev |  | Next

# 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 using`gzip -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.

Prev | Home | Next
What are the font conventions? |  | How do I get a plain text man page without all that ^H^_ stuff?