How can I add man page entries for my own power tools?

Question

I have no idea about how I can make my home-grown specialist scripts (written mostly in Bash and Perl) available through the man pages.

What procedure would I have to follow, and is there a particular format that the documentation needs to be written in for me to be able to do this?

Answer 1

I've found that using Perl's POD is much easier than writing man pages directly, and you can create a man page from the POD file with the pod2man utility (part of the base Perl package). Since some of your executables are already written in Perl, you can add POD formatting directly to your scripts and they can be turned into POD files directly. I've also seen several projects use POD format even though their code is written in other languages, due to POD's simplicity.

To add an additional directory of man pages, you can set the $MANPATH environment variable. Prefix $MANPATH with a : to have it added to the list of already-configured man paths. Use the manpath command to see the currently defined man paths.

Answer 2

In brief, see man groff_man for the file format (web version).

Save it in /usr/local/man/man1 or /usr/share/man/man1 if that doesn't work.

See the Man Page HOWTO for more details.

Answer 3

I've been using for a while this quick and easy tutorial for creating custom man pages.

The general process is like this:

1. Create a text file with markup
2. Pass it through a sed script to format it for nroff
3. Pass it through nroff

You can then optionally (b|g)zip it and put it in the appropriate man directory.