4.3BSD-Tahoe/usr/src/man/tools/TOOLKIT
This directory contains 14 shell procedures designed to carry out
various verification and regeneration tasks on the UNIX User's
Manual. The outputs of all procedures are left in files in
/_u_s_r/_m_a_n/_t_m_p; `tocrc (see below) also leaves output in
/_u_s_r/_m_a_n/_m_a_n_0. By default, these procedures operate on all 8
sections of the manual. The options `-s' and `-f' are available
(except in `mgrep' and `tocrc') to restrict the list of sections
and/or files to be used. For example:
ckspell -s 1 2 3 -f a\*
will check spelling in all files whose names begin with `a' in
Sections 1-3. Two additional options, `-m' and `-t', can be used
to change the shell procedures' idea of where the manual and its
`tmp' directory reside. For example:
list -m /usr/aman -t /usr/aman/tmp
might be meaningful if, for instance, an alternate manual is
located in /_u_s_r/_a_m_a_n. These options are also useful when a new
manual is being built in a secluded place.
Note that some of the shell procedures produce 8 result files,
one for each section of the manual. In particular, the 4 shell
procedures prefaced with `ck', which perform different types of
verification, produce a unique sorted list for each section, as
opposed to a file-by-file list. This means that one must search
all the files in a section (using `grep', most likely) for
occurrences of a particular string.
Occasionally, some of these procedures will produce lines of
spurious output. This happens when, for instance, some text
looks like a cross-reference or a file name, e.g., `array(3)' or
`nroff/troff'.
The following describes these 14 procedures:
1. ckcrefs
Locates all cross-references to other manual entries and
checks to see whether the referenced pages exist. Produces
files _b_a_d_c_r_e_f[_1-_8] containing all bad cross-references in
each section. Also produces files _l_o_w_e_r._s_u_f[_1-_8], containing
occurrences of lower-case section suffixes, i.e., 1c, 1m, 3c,
which should be changed to upper-case (1C, 1M, 3C, etc.).
2. ckfrefs
Locates all references in the FILES portion of manual entries
and checks to see whether the referenced files exist in the
running system. Produces files _b_a_d_f_r_e_f[_1-_8] containing
references to non-existent files. Note that file references
under headings other than FILES are _n_o_t checked. Temporary
files will, of course, not be found.
3. cknames
Performs various checks on the `.TH' line and the NAME
section of entries. Note that the files produced by this
procedure contain the file names of entries that fail the
corresponding check:
Checks to see that the entry contains a `.SH NAME'
section, producing files _n_o._N_A_M_E[_1-_8].
Checks the NAME section of the entry to insure that it is
exactly one line long (multi-line NAMEs will severely
confuse `tocrc'), producing files _n_o_t._o_n_e._l_i_n_e[_1-_8].
Checks to see that the entry contains a `.TH' line,
producing files _n_o._T_H[_1-_8].
Checks that the entry name and section given on the TH
line match the file name of that entry. For example, a
file containing `.TH GURP 1M' should be called `gurp.1m'.
Produces files _f_i_l_e._m_a_t_c_h[_1-_8].
Checks that the first name appearing on the NAME line is
the same as the entry name on the TH line (`ckso' below
assumes that this is always true). Produces files
_n_a_m_e._o_r_d_e_r[_1-_8].
4. ckso
This procedure performs two types of verification of _n_r_o_f_f
`.so' pointers in /_u_s_r/_m_a_n/_m_a_n[_1-_8]. It first locates files
that contain only a `.so' reference to a real entry, and
checks to see whether that file (entry) exists. Bad
references are written to the files _b_a_d_s_o[_1-_8]. Secondly,
`ckso' verifies the reverse; it locates each real entry,
looks at the NAME portion to see whether more than one name
appears there, and checks whether a file with a `.so'
reference exists for all such names other than the first.
Missing `.so' entries are written to the files _n_e_e_d_s_o[_1-_8].
5. ckspell
Utilizes _s_p_e_l_l to check for spelling errors in manual
entries. Produces file _s_p._e_r_r_s containing a section-by-
section list of errors. Uses file /_u_s_r/_m_a_n/_t_o_o_l_s/_s_p._i_g_n_o_r_e
to eliminate strings that appear often in the manual and are
normally flagged as errors by `spell'.
6. list
Produces file _l_i_s_t containing a `long' listing with block
counts (`ls -ls') for each section of the manual.
7. mcmp
Compares two versions of the manual and reports what files
are unique to each and whether or not the common files have
changed. If the `-d' option is given, _d_i_f_f-style listings
are generated for each common file instead. The `-o' option
is used to specify the name of the second manual directory;
/_u_s_r/_n_m_a_n is the default. Produces files _c_m_p[_1-_8] or
_d_i_f_f[_1-_8].
8. mgrep
Searches entire manual for the patterns specified as
arguments (i.e., `mgrep "typewriter"'). Produces file _g_r_e_p_s,
containing section-by-section list for each pattern.
9. mklinks
Creates files containing appropriate `.so' links to major
entries where necessary. These links point to their own
directory; don't run this procedure anywhere else than in
/_u_s_r/_m_a_n. Should resolve all errors noted in _n_e_e_d_s_o[_1-_8]
(see `ckso' above).
10. mroff
Utilizes the _m_a_n command to _t_r_o_f_f and typeset manual entries.
The `-p' (yes, `-p'!) option is used to produce entries in a
6x9 inch format, as opposed to the default 8.5x11. Produces
files _m_l_o_g[_1-_8] containing logs of the files that were
processed. _M_r_o_f_f ignores files that contain only a `.so'
line.
11. pgcnt
Produces files _p_a_g_e_s[_1-_8] containing page counts for each
entry. Also produces _t_o_t_a_l_p_g_s containing totals for each
section and a grand total. The `-p' option should be used to
count pages in the small format (see `mroff' above). Uses
the C program _p_a_g_e_s (compiled from _p_a_g_e_s._c).
12. prnames
Produces files _n_a_m_e_s[_1-_8] containing the NAME portion of each
entry.
13. prsynops
Produces files _s_y_n_o_p_s[_1-_8] containing the SYNOPSIS portion of
each entry. A question mark means that the entry has no
SYNOPSIS portion.
14. tocrc
Regenerates input for Table of Contents and Permuted Index.
Use `tocrc all' to regenerate both from scratch, `tocrc t' to
regenerate both from existing input files _t_o_c_x[_1-_8] in
/_u_s_r/_m_a_n/_t_m_p, or `tocrc [1-8]' to create, in /_u_s_r/_m_a_n/_t_m_p,
the corresponding input file _t_o_c_x[_1-_8]. The `-p' option
should be used when preparing the table of contents and/or
index in the small (6x9 inch) format (this option, if
present, _m_u_s_t be the first argument to `tocrc'). See
description in /_u_s_r/_m_a_n/_R_E_A_D._M_E of the files in
/_u_s_r/_m_a_n/_m_a_n_0. Uses files _b_r_e_a_k and _i_g_n_o_r_e in
/_u_s_r/_m_a_n/_t_o_o_l_s.
The file ._p_a_r_a_m is described in /_u_s_r/_m_a_n/_R_E_A_D._M_E. The files
_M._f_o_l_i_o and _M._t_a_b_s are self-explanatory.