Classic Shell Scripting - Arnold Robbins [229]
to avoid lots of complaints from the spellchecker about troff markup. Other handy tools for catching hard-to-spot errors in documentation are a doubled-word finder[8] and a delimiter-balance checker.[9]
* * *
[8] Available at http://www.math.utah.edu/pub/dw/.
[9] Available at http://www.math.utah.edu/pub/chkdelim/.
Manual-Page Format Conversion
Conversion to HTML, Texinfo, Info, XML, and DVI files is simple:
man2html pathfind.man
man2texi --batch pathfind.man
makeinfo pathfind.texi
makeinfo --xml pathfind.texi
tex pathfind.texi
We don't show the output .html, .texi, .info, and .xml files here because of their length. If you are curious, make them yourself and peek inside them to get an idea of what those markup formats look like.
Manual-Page Installation
Historically, the man command expected to find manual pages in subdirectories of a search path defined by the environment variable MANPATH, typically something like /usr/man:/usr/local/man.
Some recent man versions simply assume that each directory in the program search path, PATH, can be suffixed with the string /../man to identify a companion manual-page directory, eliminating the need for MANPATH.
In each manual-page directory, it is common to find pairs of subdirectories prefixed man and cat and suffixed with the section number. Within each subdirectory, filenames are also suffixed by the section number. Thus, /usr/man/man1/ls.1 is the troff file that documents the ls command, and /usr/man/cat1/ls.1 holds nroff's formatted output. man use the latter, when it exists, to avoid rerunning the formatter unnecessarily.
While some vendors have since adopted quite different organization of the manual-page trees, their man implementations still recognize the historical practice. Thus, installation of most GNU software puts executables in $prefix/bin and manual pages in $prefix/man/man1, where prefix defaults to /usr/local, and that seems to work nicely everywhere.
System managers normally arrange to run catman or makewhatis at regular intervals to update a file containing the one-line descriptions from the manual-page NAME sections. That file is used by the apropos, man -k, and whatis commands to provide a simple index of manual pages. If that doesn't turn up what you're looking for, then you may have to resort to a full-text search with grep.
Appendix B. Files and Filesystems
Effective use of computers requires an understanding of files and filesystems. This appendix presents an overview of the important features of Unix filesystems: what a file is, how files are named and what they contain, how they are grouped into a filesystem hierarchy, and what properties they have.
What Is a File?
Simply put, a file is a collection of data that resides in a computer system, and that can be referenced as a single entity from a computer program. Files provide a mechanism for data storage that survives process execution, and generally, restarts of the computer.[1]
In the early days of computers, files were external to the computer system: they usually resided on magnetic tape, paper tape, or punched cards. Their management was left up to their owner, who was expected to try very hard not to drop a stack of punched cards on the floor!
Later, magnetic disks became common, and their physical size decreased sharply, from as large as the span of your arms, to some as small as the width of your thumb, while their capacity increased by several orders of magnitude, from about 5MB in the mid-1950s to about 400,000MB in 2004. Costs and access times have dropped by at least three orders of magnitude. Today, there are about as many magnetic disks in existence as there are humans.
Optical storage devices, such as CD-ROMs and DVDs, are inexpensive and capacious: in the 1990s, CD-ROMs largely replaced removable flexible magnetic disks (floppies) and tapes for commercial software distribution.
Nonvolatile solid-state storage devices are also available; they may eventually replace devices that have moving mechanical parts, which