share/man/tools/README

   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 /_\bu_\bs_\br/_\bm_\ba_\bn/_\bt_\bm_\bp; `tocrc (see below) also leaves output in
   5 /_\bu_\bs_\br/_\bm_\ba_\bn/_\bm_\ba_\bn_\b0.  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 /_\bu_\bs_\br/_\ba_\bm_\ba_\bn.  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 _\bb_\ba_\bd_\bc_\br_\be_\bf[_\b1-_\b8] containing all bad cross-references in
  42     each section.  Also produces files _\bl_\bo_\bw_\be_\br._\bs_\bu_\bf[_\b1-_\b8], 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 _\bb_\ba_\bd_\bf_\br_\be_\bf[_\b1-_\b8] containing
  50     references to non-existent files.  Note that file references
  51     under headings other than FILES are _\bn_\bo_\bt 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 _\bn_\bo._\bN_\bA_\bM_\bE[_\b1-_\b8].
  62
  63         Checks the NAME section of the entry to ensure that it is
  64         exactly one line long (multi-line NAMEs will severely
  65         confuse `tocrc'), producing files _\bn_\bo_\bt._\bo_\bn_\be._\bl_\bi_\bn_\be[_\b1-_\b8].
  66
  67         Checks to see that the entry contains a `.TH' line,
  68         producing files _\bn_\bo._\bT_\bH[_\b1-_\b8].
  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 _\bf_\bi_\bl_\be._\bm_\ba_\bt_\bc_\bh[_\b1-_\b8].
  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         _\bn_\ba_\bm_\be._\bo_\br_\bd_\be_\br[_\b1-_\b8].
  79
  80 4.  ckso
  81     This procedure performs two types of verification of _\bn_\br_\bo_\bf_\bf
  82     `.so' pointers in /_\bu_\bs_\br/_\bm_\ba_\bn/_\bm_\ba_\bn[_\b1-_\b8].  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 _\bb_\ba_\bd_\bs_\bo[_\b1-_\b8].  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 _\bn_\be_\be_\bd_\bs_\bo[_\b1-_\b8].
  91
  92 5.  ckspell
  93     Uses _\bs_\bp_\be_\bl_\bl to check for spelling errors in manual
  94     entries.  Produces file _\bs_\bp._\be_\br_\br_\bs containing a section-by-
  95     section list of errors.  Uses file /_\bu_\bs_\br/_\bm_\ba_\bn/_\bt_\bo_\bo_\bl_\bs/_\bs_\bp._\bi_\bg_\bn_\bo_\br_\be
  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 _\bl_\bi_\bs_\bt 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, _\bd_\bi_\bf_\bf-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     /_\bu_\bs_\br/_\bn_\bm_\ba_\bn is the default.  Produces files _\bc_\bm_\bp[_\b1-_\b8] or
 110     _\bd_\bi_\bf_\bf[_\b1-_\b8].
 111
 112 8.  mgrep
 113     Searches entire manual for the patterns specified as
 114     arguments (i.e., `mgrep "typewriter"').  Produces file _\bg_\br_\be_\bp_\bs,
 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     /_\bu_\bs_\br/_\bm_\ba_\bn.  Should resolve all errors noted in _\bn_\be_\be_\bd_\bs_\bo[_\b1-_\b8]
 122     (see `ckso' above).
 123
 124 10. mroff
 125     Uses the _\bm_\ba_\bn command to _\bt_\br_\bo_\bf_\bf 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 _\bm_\bl_\bo_\bg[_\b1-_\b8] containing logs of the files that were
 129     processed.  _\bM_\br_\bo_\bf_\bf ignores files that contain only a `.so'
 130     line.
 131
 132 11. pgcnt
 133     Produces files _\bp_\ba_\bg_\be_\bs[_\b1-_\b8] containing page counts for each
 134     entry.  Also produces _\bt_\bo_\bt_\ba_\bl_\bp_\bg_\bs 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 _\bp_\ba_\bg_\be_\bs (compiled from _\bp_\ba_\bg_\be_\bs._\bc).
 138
 139 12. prnames
 140     Produces files _\bn_\ba_\bm_\be_\bs[_\b1-_\b8] containing the NAME portion of each
 141     entry.
 142
 143 13. prsynops
 144     Produces files _\bs_\by_\bn_\bo_\bp_\bs[_\b1-_\b8] 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 _\bt_\bo_\bc_\bx[_\b1-_\b8] in
 152     /_\bu_\bs_\br/_\bm_\ba_\bn/_\bt_\bm_\bp, or `tocrc [1-8]' to create, in /_\bu_\bs_\br/_\bm_\ba_\bn/_\bt_\bm_\bp,
 153     the corresponding input file _\bt_\bo_\bc_\bx[_\b1-_\b8].  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, _\bm_\bu_\bs_\bt be the first argument to `tocrc').  See
 157     description in /_\bu_\bs_\br/_\bm_\ba_\bn/_\bR_\bE_\bA_\bD._\bM_\bE of the files in
 158     /_\bu_\bs_\br/_\bm_\ba_\bn/_\bm_\ba_\bn_\b0.  Uses files _\bb_\br_\be_\ba_\bk and _\bi_\bg_\bn_\bo_\br_\be in
 159     /_\bu_\bs_\br/_\bm_\ba_\bn/_\bt_\bo_\bo_\bl_\bs.
 160
 161 The file ._\bp_\ba_\br_\ba_\bm is described in /_\bu_\bs_\br/_\bm_\ba_\bn/_\bR_\bE_\bA_\bD._\bM_\bE.  The files
 162 _\bM._\bf_\bo_\bl_\bi_\bo and _\bM._\bt_\ba_\bb_\bs 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