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.




































