1 files changed, 198 insertions, 0 deletions
diff --git a/share/man/tools/README b/share/man/tools/README
new file mode 100644
index 0000000..ac139a1
--- /dev/null
+++ b/share/man/tools/README
@@ -0,0 +1,198 @@
+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.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+