Creating Man Pages with Groff Formatting

	Sign In Sign-Up

Creating Man Pages with Groff Formatting

I'll use a fictional man page for the mongrel command as an example of how to create man pages for your Linux system. First Let me show you The finished man page:

$ man mongrel

MONGREL(7)               mongrel.20m.com               MONGREL(7)


NAME
       mongrel - worthless orphaned process with parents of mixed
       origin.

SYNOPSIS
       mongrel [OPTIONS] [PID]

DESCRIPTION
       mongrel - create or interact with a worthless runaway  pro-
       cess PID.

       The  process can be captured in the dogpound daemon, or it
       may be a stray process. The stray process may occasionally
       show  up  on  a  potential parent processes doorstep where
       with the right amount of coaxing will become  a  child  to
       the  said  process. If the stray process is allowed to run
       free for to long it  runs  the  chance  of  breeding  with
       another process, creating more mongrel processes.

OPTIONS
       -f --feed
            Feeding  the stray process is usually the best way to
            befriend and adopt it.

       -c --chase
            Chase the runaway process out of your sight.

       -n --name=NAME
            Call the process by NAME for  future  references.  It
            will not always respond the NAME you give it

       -r --report
            Report  the  process  to the dogpound daemon for cap-
            ture.

       -C --Capture
            Attempt to capture the mongrel yourself  (be  careful
            this is a good way to get bit).

       -f --fix
            Spay or Neuter a captured mongrel so it can not spawn
            and child processes.

       -v --vaccinate
            Vaccinate captured mongrel  for  infectious  diseases
            which may be dangerous to you or the stray process.

       -w --worm
            Treat process for internal parasites, increasing it's
            health.

       -t --train
            Train mongrel process making it more obediant.

       -s --school
            Have a professional train process  at  a  high  cost.
            Occasionally this has proven to be a waste of time.

WARNINGS
       Be  careful  although  a  stray  process can make a great,
       loyal pet, many may be unpredictable. Some are wild,  with
       no fear of humans because of their domestic origins. Chil-
       dren should be told never to pet a strange process.

       Be advised that a stray process may carry disease.  It  is
       best  to leave the handling of stray processes to the dog-
       pound daemon. Once captured and checked for and infectious
       diseases  you  can still adopt a mongrel process if you so
       desire. It is suggested that you always have all your pro-
       cesses spayed or neutered to avoid unwanted processes.

AUTHOR
       Written by Anthony Ventimiglia.

REPORTING BUGS
       Report Bugs to <bugzilla@mongrel.20m.com>

COPYRIGHT
       Copyright  C 2001 by MultiDogMediA. This is Free Software;
       see source code for copying conditions. There is  NO  WAR-
       RANTY.

SEE ALSO
       Other Commands for handling a stray process: vaccinate(8),
       dogpound(8), adopt(7), euthanize(8).

V 4.20                     Sept 26 2001                         1

Now here is the code that produced the mongrel man page, you can use any basic text editor (vi or emacs) to write this.

.\" Man page for fictional mongrel command
.\" These first two lines are comments and will not be seen in the man page
.TH MONGREL 7 "Sept 26 2001" "V 4.20" "mongrel.20m.com"
.SH NAME
mongrel \- worthless orphaned process with parents of mixed origin.
.SH SYNOPSIS
.B mongrel
[\fIOPTIONS\fR] [\fIPID\fR]
.SH DESCRIPTION
.B mongrel
creates or interact with a worthless runaway process
.B PID.
.PP
The process can be captured in the
.B dogpound
daemon, or it may be a stray process. The stray process may occasionally show up on a potential parent processes doorstep where with the right amount of coaxing will become a child to the said process. If the stray process is allowed to run free for to long it runs the chance of breeding with another process, creating more
.B mongrel
processes.
.SH OPTIONS
.TP 5
.B \-f \-\-feed
Feeding the stray process is usually the best way to befriend and adopt it.
.TP
.B \-c \-\-chase
Chase the runaway process out of your sight.
.TP
.B \-n \-\-name=NAME
Call the process by
.B NAME
for future references. It will not always respond the
.B NAME
you give it
.TP
.B \-r \-\-report
Report the process to the
.B dogpound
daemon for capture.
.TP
.B \-C \-\-Capture
Attempt to capture the mongrel yourself (be careful this is a good way to get bit).
.TP
.B \-f \-\-fix
Spay or Neuter a captured mongrel so it can not spawn and child processes.
.TP
.B \-v \-\-vaccinate
Vaccinate captured mongrel for infectious diseases which may be dangerous to you or the stray process.
.TP
.B \-w \-\-worm
Treat process for internal parasites, increasing it's health.
.TP
.B \-t \-\-train
Train \fBmongrel\fR process making it more obediant.
.TP
.B \-s \-\-school
Have a professional train process at a high cost. Occasionally this has proven to be a waste of time.
.SH WARNINGS
Be careful although a stray process can make a great, loyal pet, many may be unpredictable. Some are wild, with no fear of humans because of their domestic origins. Children should be told never to pet a strange process.
.PP
Be advised that a stray process may carry disease. It is best to leave the handling of stray processes to the
.B dogpound
daemon. Once captured and checked for and infectious diseases you can still adopt a
.B mongrel
process if you so desire. It is suggested that you always have all your processes spayed or neutered to avoid unwanted processes.
.SH AUTHOR
Written by Anthony Ventimiglia.
.SH REPORTING BUGS
Report Bugs to <bugzilla@mongrel.20m.com>
.SH COPYRIGHT
Copyright C 2001 by MultiDogMediA. This is Free Software; see source code for copying conditions. There is NO WARRANTY.
.SH SEE ALSO
Other Commands for handling a stray process: \fBvaccinate(8)\fR, \fBdogpound(8)\fR, \fBadopt(7)\fR, \fBeuthanize(8)\fR.
.br

Now I'll explain the groff man macros in the order they are used in the example man page.

.\"

Comment - Text up until new line is treated as a comment and doesn't appear in the final document. You can also add comments to the end of a line using \" alone. Anything following \" is treated as a comment.

.TH

Title Heading. Arguments are as follows:

Title - printed at top right and left sides.
Section - printed in parentheses to left of title.
Option 1 - centered at bottom of page.
Option 2 - left aligned at bottom of page.
Option 3 - centered at top of page.

Text contained in quotes count as one argument. In this example MONGREL is the title, 7 is the section number, "Sept 26 2001" is option 1, "V 4.20" is option 2 and "mongrel.20m.com" is option 3.

.SH

Section Heading, output in boldface names are uppercase by convention.

\-

Prints a hyphen '-', although my system doesn't need hyphens to be preceeded by a backslash, I noticed that it was used in some of the GNU man pages.

.B

Boldface, Text following tag will be printed in bold face until the end of line. A single space is printed before and after the text marked-up with the .B tag.

\fI

Begin italic, this is an inline tag. you could also use .I to print italics, however using the inline tag does not add spaces around the marked-up text. Text will be printed italic until another inline tag is used or until end of line. Under my text-only terminal italics show up the same as bold face, but are underlined on my X terminal.

\fR

Regular text, also an inline tag \fR turns off bold or italics and returns to normal text.

.PP

Begin new paragraph.

.TP

Tagged Paragraph (uses hanging indent) if followed by a numerical argument specifies the amount to indent. Paragraph begins on the next line.

\fB

Bold - inline, acts same as \fI using boldface instead of italics.

There are additional tags which I didn't use in this example. Here they are:

.I: Use Italic type until newline.
.IP: Indented Paragraph, similar to .TP but paragraph starts on the same line as the tag.
.HP: Begin hanging indent.
.DT: Set default tabs.
.I: Italics, behaves similar as .B
.PD: Set distance between paragraphs
.LP: Begin Paragraph, same as .PP
.RS: Begin relative indent.
.RE: End relative indent.
.SM: Small Text
.SS: Subheading within a .SH heading

Well that should get you started making man pages, next I'll get in to installing your local man pages into your directory structure so your pages will be accessible through the man and apropos commands.

back