Return to TOOLKIT CVS log

Up to [CSRG BSD Unix] / 43BSDTahoe / man / tools

Annotation of 43BSDTahoe/man/tools/TOOLKIT, revision 1.1

1.1     ! root        1: This directory contains 14 shell procedures designed to carry out
        !             2: various verification and regeneration tasks on the UNIX User's
        !             3: Manual.  The outputs of all procedures are left in files in
        !             4: /_u_s_r/_m_a_n/_t_m_p; `tocrc (see below) also leaves output in
        !             5: /_u_s_r/_m_a_n/_m_a_n_0.  By default, these procedures operate on all 8
        !             6: sections of the manual.  The options `-s' and `-f' are available
        !             7: (except in `mgrep' and `tocrc') to restrict the list of sections
        !             8: and/or files to be used.  For example:
        !             9: 
        !            10:           ckspell -s 1 2 3 -f a\*
        !            11: 
        !            12: will check spelling in all files whose names begin with `a' in
        !            13: Sections 1-3.  Two additional options, `-m' and `-t', can be used
        !            14: to change the shell procedures' idea of where the manual and its
        !            15: `tmp' directory reside.  For example:
        !            16: 
        !            17:           list -m /usr/aman -t /usr/aman/tmp
        !            18: 
        !            19: might be meaningful if, for instance, an alternate manual is
        !            20: located in /_u_s_r/_a_m_a_n.  These options are also useful when a new
        !            21: manual is being built in a secluded place.
        !            22: 
        !            23: Note that some of the shell procedures produce 8 result files,
        !            24: one for each section of the manual.  In particular, the 4 shell
        !            25: procedures prefaced with `ck', which perform different types of
        !            26: verification, produce a unique sorted list for each section, as
        !            27: opposed to a file-by-file list.  This means that one must search
        !            28: all the files in a section (using `grep', most likely) for
        !            29: occurrences of a particular string.
        !            30: 
        !            31: Occasionally, some of these procedures will produce lines of
        !            32: spurious output.  This happens when, for instance, some text
        !            33: looks like a cross-reference or a file name, e.g., `array(3)' or
        !            34: `nroff/troff'.
        !            35: 
        !            36: The following describes these 14 procedures:
        !            37: 
        !            38: 1.  ckcrefs
        !            39:     Locates all cross-references to other manual entries and
        !            40:     checks to see whether the referenced pages exist.  Produces
        !            41:     files _b_a_d_c_r_e_f[_1-_8] containing all bad cross-references in
        !            42:     each section.  Also produces files _l_o_w_e_r._s_u_f[_1-_8], containing
        !            43:     occurrences of lower-case section suffixes, i.e., 1c, 1m, 3c,
        !            44:     which should be changed to upper-case (1C, 1M, 3C, etc.).
        !            45: 
        !            46: 2.  ckfrefs
        !            47:     Locates all references in the FILES portion of manual entries
        !            48:     and checks to see whether the referenced files exist in the
        !            49:     running system.  Produces files _b_a_d_f_r_e_f[_1-_8] containing
        !            50:     references to non-existent files.  Note that file references
        !            51:     under headings other than FILES are _n_o_t checked.  Temporary
        !            52:     files will, of course, not be found.
        !            53: 
        !            54: 3.  cknames
        !            55:     Performs various checks on the `.TH' line and the NAME
        !            56:     section of entries.  Note that the files produced by this
        !            57:     procedure contain the file names of entries that fail the
        !            58:     corresponding check:
        !            59: 
        !            60:         Checks to see that the entry contains a `.SH NAME'
        !            61:         section, producing files _n_o._N_A_M_E[_1-_8].
        !            62: 
        !            63:         Checks the NAME section of the entry to insure that it is
        !            64:         exactly one line long (multi-line NAMEs will severely
        !            65:         confuse `tocrc'), producing files _n_o_t._o_n_e._l_i_n_e[_1-_8].
        !            66: 
        !            67:         Checks to see that the entry contains a `.TH' line,
        !            68:         producing files _n_o._T_H[_1-_8].
        !            69: 
        !            70:         Checks that the entry name and section given on the TH
        !            71:         line match the file name of that entry.  For example, a
        !            72:         file containing `.TH GURP 1M' should be called `gurp.1m'.
        !            73:         Produces files _f_i_l_e._m_a_t_c_h[_1-_8].
        !            74: 
        !            75:         Checks that the first name appearing on the NAME line is
        !            76:         the same as the entry name on the TH line (`ckso' below
        !            77:         assumes that this is always true).  Produces files
        !            78:         _n_a_m_e._o_r_d_e_r[_1-_8].
        !            79: 
        !            80: 4.  ckso
        !            81:     This procedure performs two types of verification of _n_r_o_f_f
        !            82:     `.so' pointers in /_u_s_r/_m_a_n/_m_a_n[_1-_8].  It first locates files
        !            83:     that contain only a `.so' reference to a real entry, and
        !            84:     checks to see whether that file (entry) exists.  Bad
        !            85:     references are written to the files _b_a_d_s_o[_1-_8].  Secondly,
        !            86:     `ckso' verifies the reverse; it locates each real entry,
        !            87:     looks at the NAME portion to see whether more than one name
        !            88:     appears there, and checks whether a file with a `.so'
        !            89:     reference exists for all such names other than the first.
        !            90:     Missing `.so' entries are written to the files _n_e_e_d_s_o[_1-_8].
        !            91: 
        !            92: 5.  ckspell
        !            93:     Utilizes _s_p_e_l_l to check for spelling errors in manual
        !            94:     entries.  Produces file _s_p._e_r_r_s containing a section-by-
        !            95:     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
        !            96:     to eliminate strings that appear often in the manual and are
        !            97:     normally flagged as errors by `spell'.
        !            98: 
        !            99: 6.  list
        !           100:     Produces file _l_i_s_t containing a `long' listing with block
        !           101:     counts (`ls -ls') for each section of the manual.
        !           102: 
        !           103: 7.  mcmp
        !           104:     Compares two versions of the manual and reports what files
        !           105:     are unique to each and whether or not the common files have
        !           106:     changed.  If the `-d' option is given, _d_i_f_f-style listings
        !           107:     are generated for each common file instead.  The `-o' option
        !           108:     is used to specify the name of the second manual directory;
        !           109:     /_u_s_r/_n_m_a_n is the default.  Produces files _c_m_p[_1-_8] or
        !           110:     _d_i_f_f[_1-_8].
        !           111: 
        !           112: 8.  mgrep
        !           113:     Searches entire manual for the patterns specified as
        !           114:     arguments (i.e., `mgrep "typewriter"').  Produces file _g_r_e_p_s,
        !           115:     containing section-by-section list for each pattern.
        !           116: 
        !           117: 9.  mklinks
        !           118:     Creates files containing appropriate `.so' links to major
        !           119:     entries where necessary.  These links point to their own
        !           120:     directory; don't run this procedure anywhere else than in
        !           121:     /_u_s_r/_m_a_n.  Should resolve all errors noted in _n_e_e_d_s_o[_1-_8]
        !           122:     (see `ckso' above).
        !           123: 
        !           124: 10. mroff
        !           125:     Utilizes the _m_a_n command to _t_r_o_f_f and typeset manual entries.
        !           126:     The `-p' (yes, `-p'!) option is used to produce entries in a
        !           127:     6x9 inch format, as opposed to the default 8.5x11.  Produces
        !           128:     files _m_l_o_g[_1-_8] containing logs of the files that were
        !           129:     processed.  _M_r_o_f_f ignores files that contain only a `.so'
        !           130:     line.
        !           131: 
        !           132: 11. pgcnt
        !           133:     Produces files _p_a_g_e_s[_1-_8] containing page counts for each
        !           134:     entry.  Also produces _t_o_t_a_l_p_g_s containing totals for each
        !           135:     section and a grand total.  The `-p' option should be used to
        !           136:     count pages in the small format (see `mroff' above).  Uses
        !           137:     the C program _p_a_g_e_s (compiled from _p_a_g_e_s._c).
        !           138: 
        !           139: 12. prnames
        !           140:     Produces files _n_a_m_e_s[_1-_8] containing the NAME portion of each
        !           141:     entry.
        !           142: 
        !           143: 13. prsynops
        !           144:     Produces files _s_y_n_o_p_s[_1-_8] containing the SYNOPSIS portion of
        !           145:     each entry.  A question mark means that the entry has no
        !           146:     SYNOPSIS portion.
        !           147: 
        !           148: 14. tocrc
        !           149:     Regenerates input for Table of Contents and Permuted Index.
        !           150:     Use `tocrc all' to regenerate both from scratch, `tocrc t' to
        !           151:     regenerate both from existing input files _t_o_c_x[_1-_8] in
        !           152:     /_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,
        !           153:     the corresponding input file _t_o_c_x[_1-_8].  The `-p' option
        !           154:     should be used when preparing the table of contents and/or
        !           155:     index in the small (6x9 inch) format (this option, if
        !           156:     present, _m_u_s_t be the first argument to `tocrc').  See
        !           157:     description in /_u_s_r/_m_a_n/_R_E_A_D._M_E of the files in
        !           158:     /_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
        !           159:     /_u_s_r/_m_a_n/_t_o_o_l_s.
        !           160: 
        !           161: The file ._p_a_r_a_m is described in /_u_s_r/_m_a_n/_R_E_A_D._M_E.  The files
        !           162: _M._f_o_l_i_o and _M._t_a_b_s are self-explanatory.
        !           163: 
        !           164: 
        !           165: 
        !           166: 
        !           167: 
        !           168: 
        !           169: 
        !           170: 
        !           171: 
        !           172: 
        !           173: 
        !           174: 
        !           175: 
        !           176: 
        !           177: 
        !           178: 
        !           179: 
        !           180: 
        !           181: 
        !           182: 
        !           183: 
        !           184: 
        !           185: 
        !           186: 
        !           187: 
        !           188: 
        !           189: 
        !           190: 
        !           191: 
        !           192: 
        !           193: 
        !           194: 
        !           195: 
        !           196: 
        !           197: 
        !           198: 

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.