Take the 2-minute tour ×
Unix & Linux Stack Exchange is a question and answer site for users of Linux, FreeBSD and other Un*x-like operating systems.. It's 100% free, no registration required.

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?

share|improve this question
    
+1 just for wanting to do this. asciidoc, Restructured Text, POD, docbook will all serve, just convert to man format. –  chiggsy Aug 8 '11 at 17:11
add comment

3 Answers 3

up vote 13 down vote accepted

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.

share|improve this answer
add comment

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.

share|improve this answer
    
I think that should read "man groff" –  chris Feb 4 '11 at 11:53
    
There are separate man pages for each file format supported by groff. The ones for man pages should be in groff_an or groff_man, but you might need to install a non-default package to get it. –  Mikel Feb 4 '11 at 11:56
    
But yes, I did briefly say groff_an, and for most people it will be groff_man if that's what you were referring to. :-) –  Mikel Feb 4 '11 at 12:03
add comment

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.

share|improve this answer
add comment

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.