Adding Local man Pages
There’s an old and somewhat scatological saying about a job not being finished until thepaperwork is done.[11] In the case of creating scripts and programs, this means writing some sort of documentation. Tools you create can be documented in many different ways, but the usual Unix practice is to produce an online manual page. We’ll conclude this chapter with a brief look at creating manual pages for the tools you develop.
Manual-page files are named for the command or utility that they
describe, and they are given an extension that matches the number or
letter of the man subdirectory in which they
reside. For example, a manual-page file for the wgrep
command placed into
man1 subdirectory would be named
wgrep.1.[12]
The simplest possible manual page is just a text file describing a
command or topic. However, if you’d like to create something a bit more
elaborate, and more like the other manual pages typically found on Unix
systems, it is very easy to do so. Manual-page source files are designed
for the nroff
text formatting system,[13] and they combine the text of the manual page with nroff
directives specifying how to format the
text. (Not all Unix versions provide the text formatting utilities by
default or at all.)
The best way to figure out what the various nroff
directives do is to see them in context.
In general, they are placed at the beginning of a line and start with a
period. Here is a brief manual page source file for the wgrep
command, which can also ...
Get Essential System Administration, 3rd Edition now with the O’Reilly learning platform.
O’Reilly members experience books, live events, courses curated by job role, and more from O’Reilly and nearly 200 top publishers.