43BSDTahoe/man/tools/TOOLKIT - annotate

Return to TOOLKIT CVS log

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

Annotation of 43BSDTahoe/man/tools/TOOLKIT, revision 1.1.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:

unix.superglobalmegacorp.com

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