6.3 Objective 3: Write System Documentation

Through daily activity as a system administrator, you have a unique opportunity to observe the needs of multiple users on your systems. Based on that vantage point, you will probably be writing scripts and other utilities specific to your location and business. Such things can be as simple as login or shell scripts, or as complex as full-featured applications. As these tools make their way into the lives of other people, the need to document your work becomes a necessary part of being a system administrator. To be useful, such documentation should appear in locations where end users will expect to find it. In effect, creating a tool that is intended for an audience beyond yourself implies the responsibility to document that tool.

6.3.1 Creating Manpages

System manpages are an excellent place to create local documentation. Manpages are simple to create; the mechanism is well known, and your users will be comfortable using it. You can produce formatted documentation, including bold and underlined text from nroff source files. These text files contain extra markup information that controls the display formatting on screen. However, you can also use plain text files by employing a special performance feature of the man system.

Typically, the raw files used by man are processed from their raw nroff form to create the displayable form. At one time, this processing took a long time, particularly for large manpages. To make manpage access faster for subsequent requests for the same manpage, the system often would save a version of the formatted page on disk. The raw, unformatted system pages are stored in /usr/man/man.1, /usr/man/man.2, and so on for each section in the manual. In addition, the directories /usr/cat/cat.1, /usr/cat/cat.2, and so on, can hold the previously formatted files. The cat directory setup on your system may be different and is defined by /etc/man.config. Wherever they are, these directories can contain text files for use with man rather than raw nroff files.

You can take advantage of this feature to create simple manpages for your own system. Simply generate a text file that looks like a typical manpage (sans fancy formatting) and place it in the appropriate cat directory. The file must be named with a trailing dot and the section name, just as the formatted files are. This method couldn't get any easier and yields a result expected by the end user. The missing formatting probably won't be noticed.

For those of you needing to get a little more serious and generate formatted manpages, you may want to start with an existing manpage to use as a template. To do this, simply find a manpage that makes a suitable starting point and copy it to the appropriate name in the appropriate man directory. Again, the name must have the trailing dot and man section. For example, we could copy the existing file /usr/man/man1/ln.1 to /usr/local/man/man1/mycmd.1:

cp /usr/man/man1/ln.1 /usr/local/man/man1/mycmd.1 

Edit the file with a text editor, changing sections and text as needed but leaving the formatting macros intact. When editing your new file, you'll find a number of man macros inside that handle complex text formatting. The macros consist of a dot (.) and one or two characters representing the formatting feature. Some of the more important macros are listed in Table 6-6.

Table 6-6. Commonly Used man Macros

Macro	Function
.TH	A manpage header. Includes title, section, date, description, and author.
.SH	A section heading. You can add your own sections to the standard sections as required.
.PP	A paragraph separator. Without this macro, lines of text will flow together.
.TP	A hanging indent macro, used for command options.
.B	Everything on the line following this macro is bold.
.I	Everything on the line following this macro is italic (or sometimes underlined).
\fB	This inline macro makes text following on the line bold.
\fI	This inline macro makes text following on the line italic (or sometimes underlined).
\fR	This inline macro returns the text to the default style.

Using these macros, you can create and format your own manpages. Example 6-1 contains an example of a very simple manpage using these macros.

Example 6-1. Sample Source for a Manpage

.\" This is a comment line.
.\"
.\" .TH defines your man page header, including
.\" the title, manual section, date, description, and author.
.TH MYPAGE 1 "TheDate" "My Page Description" "Me"
.\"
.\" .SH defines a section.  This is the NAME section.
.SH NAME
mypage \- make your own manpage
.\"
.\" This is the SYNOPSIS section.
.SH SYNOPSIS
.\"
.\" .B is a font change macro, yielding bold for 
.\" everything on the line.
.B mypage
.\"
.\" \fI, \fB, and \fR are in-line font changes for italic, 
.\" bold, and roman, respectively.
.\" 
.\" 
.\" This is the DESCRIPTION section.
.SH DESCRIPTION
.\"
This is paragraph 1 of your description.
.\" 
.\" .PP is a paragraph separator.
.PP
This is paragraph 2 of your description.
To create a manpage, the most important man macros 
are \fB.TH\fR
.\" 
.\" .TP precedes command options.
.TP
\fB\-a\fR
option a
.TP
\fB\-b\fR
option b
.\"
.\" This is the multiword "reporting bugs" section,
.\" which is why it is quoted.
.SH "REPORTING BUGS"
Report bugs to <[email protected]>.
.\"
.\" This is the multiword "see also" section.
.SH "SEE ALSO"
.\"
.B yourpage(1)

Your manpages will most likely go in the directory reserved for local additions to the system, /usr/local/man. While there's nothing preventing you from storing your manpages in the system /man directories, you may forget about customizations you make there -- therefore, you could lose customizations when you upgrade your system and that directory gets overwritten with newer manpages.

At the time of this writing, there are no questions for Section 6.3 Write System Documentation," on the LPIC Level 1 Exam.