Creating man pages in linux

Linux and Unix-Like
1

need help to create man pages in linux

2

Hello,

This is certainly something you can do, though you might find it a bit of an unusual process if you're not familiar with the groff text formatting system. Essentially, man pages on Linux are documents written using particular groff macros for formatting purposes, and which always include certain sections and information that the man utility expects to find.

On most Linux systems, the majority of man pages are located beneath the /usr/share/man directory. Local man pages (that is, man pages for locally-written and locally-installed software) are intended on most Linux systems to go underneath /usr/local/share/man. To see where your system currently expects your man pages to be, check out the contents of your MANPATH environment variable, or the output of the manpath utility.

Now, as to how to actually write them. At their core, man pages are made of sections consisting of the appropriate groff macros, and with text formatted using the regular groff text formatting statements.

The very first line in a man page is usually the Title Heading macro .TH. This is used to specify fundamentally basic information about the man page in question. In order, the TH macro must supply:

  • The name of the thing being documented
  • The man section number that the page appears in (1 for User Commands, 8 for System Administration Commands, etc.)
  • The text to be displayed at the centre of the footer (typically the date)
  • The text to be displayed at the left of the footer (typically the package name, or utility version)
  • The text to be displayed at the centre of the header (typically a description of the type of utility or function being documented)

For example, if you had written a new utility called foo that was intended to act as a command-line calculator, your .TH macro line might look like:

.TH FOO "1" "May 2023" "Foo Calculator Utility v1.0" "User Commands"

Next, man pages are split into sections. These are not all strictly mandatory, but at a minimum a typical man page usually includes the following sections:

NAME

  • Tells you the name of the thing that this man page was written to document

SYNOPSIS

  • A quick short description of the purpose of the thing being documented

DESCRIPTION

  • A longer, more detailed description of the purpose of the thing being documented

OPTIONS

  • A detailed description of the options, flags, configuration directives, or whatever other optional things can be supplied by the user that affect the behaviour of the thing being documented

BUGS

  • Details of any known bugs, issues, or problems that would prevent the thing being documented from working as might otherwise be reasonably expected by the end user

AUTHOR

  • Details of the person or persons who wrote the man page, and who wrote the thing being documented

SEE ALSO

  • Lists of other appropriate man pages for anything that is related in any way to the thing being documented

These individual sections are all marked in your man page with the groff macro .SH. So to mark the start of the SYNOPSIS section, you would write a line like this:

.SH SYNOPSIS

Lasty, the actual text of each of these sections is just normal text, for the most part. Formatting instructions, such as whether text is to be in bold, italic, or anything else out of the ordinary, is accomplished with groff text formatting directives like \fB, \fI, \fR, and so on.

The easiest way to get your head around all this, to be honest, is just to look at an existing man page. Pick a simpler smaller one, like cat's man page (normally /usr/share/man/man1/cat.1.gz), and display its raw contents with zcat. You'll see what I mean about the .TH and .SH macros, as well as the basic text formatting directives that are used as well for changing highlighting and such.

Once you have your man page file written, you can preview it using groff. Again using a man page for a newly-written utility called foo as an example, you could preview it thusly:

cat foo.1 | groff -Tascii -man

This will show you in your terminal screen exactly what you'll get once this is a live man page on your system.

Lastly then, once your page is written and you're ready to install it, add it to the appropriate directory on your system. Sticking with our foo example, since it goes in Section 1 of the manual (User Commands), you could install it by doing this:

gzip foo.1
cp foo.1.gz /usr/local/share/man/man1/

So, that's a basic high-level overview of creating man pages on a Linux system. As you can see it's a surprisingly fiddly process, with a lot of new stuff to learn if you're not already familiar with how man and groff work. Taking a look at the raw text of existing man page files is the best way to get your head around it all however I'd say.

Anyway, good luck ! Let us know if you have any further questions and we'll see what we can do.

4

I would like to add to @drysdalk's excellent answer. Having done this my self, and struggling a bit with the format, I have a few tips to share that may help.

You can use existing MAN pages as inspiration on what to do and how to do it. Let's say that the crontab(5) has some formatting that you would like to emulate.
First, locate the file crontab.5.gz It will be under <base_path>/man/man5.
The directory <base_path> may depend on your OS.

man man

Should tell you where your system looks. On my Red Hat 7 box, I have files in /usr/share and in /usr/local/share

Next, copy the file to a working directory and unzip it

cp /usr/share/man/man5/crontab.5.gz ~/working
cd ~/working
gunzip crontab.5.gz

Pro Tip: You can do all of this in 1 step

gunzip -c  /usr/share/man/man5/crontab.5.gz > ~/working/crontab.5

Now, you can use your favorite text editor to view the file ~/working/crontab.5 and see the formatting commands.

To see what your man page will look like, without having to actually install it as a man page, you can do as @drysdalk suggested with the groff command, although I tweak it slightly to allow for the escape sequences to be interpreted and let me page through the output

cat foo.1 | groff -Tascii -man | less -R

In order for all of this to work, you need to be sure that groff groff-base are installed on your system.

Some helpful man pages are:
groff(7) groff(1) and groff_man(7)

Man pages are broken up into sections, 1-9. Each section is for a different type of man page. The section number follows the filename and determines which sub-directory it goes in to. For section 1, your file would be <base_dir/man/man1/foo.1.gz for section 5 it would be <base_dur>/man/man5/foo.5.gz.
The sections are documented in man(1)

If you want your man documents to be accessible by everyone on the system, you need to re-build the man database:

mandb -q

Good luck! There is a bit of a learning curve, but after that, it's fairly easy.