Unix & Linux Stack Exchange is a question and answer site for users of Linux, FreeBSD and other Un*x-like operating systems. Join them; it only takes a minute:

Sign up
Here's how it works:
  1. Anybody can ask a question
  2. Anybody can answer
  3. The best answers are voted up and rise to the top

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
I read info is the new man. – Cees Timmerman Oct 27 '14 at 11:32
up vote 15 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

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

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

According to this page, it's easy:

nano nuseradd

Then paste and modify an example like this one. This page (or man 7 mdoc) explains the formatting options:

.\" Manpage for nuseradd.
.\" Contact vivek@nixcraft.net.in to correct errors or typos.
.TH man 8 "06 May 2010" "1.0" "nuseradd man page"
nuseradd \- create a new LDAP user
nuseradd [USERNAME]
nuseradd is high level shell program for adding users to LDAP server.  On Debian, administrators should usually use nuseradd.debian(8) instead.
The nuseradd does not take any options. However, you can supply username.
useradd(8), passwd(5), nuseradd.debian(8)
No known bugs.
Vivek Gite (vivek@nixcraft.net.in)

Then simply gzip and copy your new man page to the proper man section:

1   Executable shell commands
2   System calls (functions provided by the kernel)
3   Library calls (functions within program libraries)
4   Special files (usually found in /dev)
5   File formats and conventions eg /etc/passwd
6   Games
7   Miscellaneous (including macro packages and conventions), e.g. man(7), groff(7)
8   System administration commands (usually only for root)
9   Kernel routines [Non standard]

As the example is an admin tool, it goes in section 8:

cat nuseradd |gzip > /usr/local/man/man8/nuseradd.1

Or have people read it from another location, e.g. locally: man ./nuseradd

share|improve this answer

Your Answer


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.