pdp11v/usr/man/tools/TOOLKIT

'\" To get a copy of TOOLKIT, type:  mm TOOLKIT
.P
This directory contains shell procedures designed to carry out
various verification and regeneration tasks on the UNIX System User's
Manual
and the UNIX System Administrator's Manual.
The outputs of all procedures are left in files in directory
.I /usr/man/tmp
or any other specified temporary directory;
tocrc (see below) also leaves output in
.I /usr/man/u_man/man0
for the UNIX System User's Manual
and
.I /usr/man/a_man/man0
for the UNIX System Administrator's Manual.
By default, these procedures operate on all
sections of the designated manual.
The options `-s' and `-f' are available
to restrict the list of sections
and/or files to be used.
For example:
.DS I
ckspell -s 1 2 3 -f a\*
.DE
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:
.DS I
list -m /usr/man/a_man -t /usr/man/altmp
.DE
may be used to list (see below) the sections of the UNIX System Administrator's Manual.
The default values for the `-m' and `-t' options are 
.I /usr/man/u_man
and
.IR /usr/man/tmp ,
respectively.
These options are also useful when a new
manual is being built in a secluded place.
.P
Note that most of the shell procedures produce results-files,
one for each section of the manual.
In particular, the 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.
.P
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'.
.P
The following describes these procedures:
.VL 10
.LI ckcrefs
Locates all cross-references to other manual entries and
checks to see whether the referenced pages exist.
Produces
files
.I badcref?
containing all bad cross-references in
each section.
Also produces files
.IR lower.suf? ,
containing
occurrences of lower-case section suffixes, i.e., 1c, 1m, 3c,
which should be changed to upper-case (1C, 1M, 3C, etc.).
.LI 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
.I badfref?
containing
references to non-existent files.
Note that file references
under headings other than FILES are not checked.
Temporary
files will, of course, not be found.
.LI 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
.IR no.NAME? .
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
.IR not.one.line? .
Checks to see that the entry contains a `.TH' line,
producing files
.IR no.TH? .
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
.IR file.match? .
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
name.order?.
.LI ckso
This procedure performs two types of verification of nroff
`.so' pointers in /usr/man/[au]_man/man?.
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
.IR badso? .
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
.IR needso? .
.LI ckspell
Utilizes spell to check for spelling errors in manual
entries.
Produces file sp.errs containing a section-by-
section list of errors.
Uses file /usr/man/tools/sp.ignore
to eliminate strings that appear often in the manual and are
normally flagged as errors by `spell'.
.LI cleanup
Cleans up the litter of temporary files that had no diagnostic
output contained within them.
More exactly,
any file in the specified temporary directory (i.e., /usr/man/tmp)
that has 2 or fewer lines of data is taken to be nohup.out-type file
or a file just containing a `date' line and a new-line.
Do not run cleanup, unless you are sure that all other checking procedures
have finished; the results of removing an interim tmp-file will taint
the accuracy of the diagnostics.
.LI folio.mk
Uses the files produced by pgcnt (see below) and creates a folio list
(printer's instructions) in the selected temporary directory.
The
.I pages?
files are left untouched, and a file
.I M.folio
is created that can be run off using `mm -t'.
Twelve (12) pitch is recommended.
.LI list
Produces file list containing a `long' listing with block
counts (`ls -ls') for each section of the manual.
.LI 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, diff-style listings
are generated for each common file instead.
The `-o' option
is used to specify the name of the second manual directory;
/usr/nman is the default.
Produces files
.I cmp?
or
diff?.
.LI mgrep
Searches entire manual for the patterns specified as
arguments (i.e., `mgrep "typewriter"').
Produces file
.IR greps ,
containing section-by-section list for each pattern.
.LI 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
/usr/man.
Should resolve all errors noted in
.I needso?
(see `ckso' above).
.LI mroff
Utilizes the man command to troff and typeset manual entries.
The `-p' (yes, `-p'!) option is used to produce entries in a
8.5x11 inch format, as opposed to the default 6x9.
Produces
files
.I mlog?
containing logs of the files that were
processed.
Mroff ignores files that contain only a `.so'
line.
.LI pgcnt
Produces files
.I pages?
containing page counts for each
entry.
Also produces
.I totalpgs
containing totals for each
section and a grand total.
The `-p' option should be used to
count pages in the large format (see `mroff' above).
Uses
the C program pages (compiled from pages.c).
.LI prnames
Produces files
.I names?
containing the NAME portion of each
entry.
.LI prsynops
Produces files
.I synops?
containing the SYNOPSIS portion of
each entry.
A question mark (?) means that the entry has no
SYNOPSIS portion.
.LI purge
Lists all the file names in the selected manual that do not
appear to be valid manual entry names.
Likely candidates are ed.hup, nohup.out, core(?).
The only valid name to date that doesn't fit the naming algorithm is
a.out.4 whose existence is reckoned with.
With the `-c' option, purge will clean out all the listed names.
.LI rm.so
Removes all files that are `.so' links of another entry.
This is useful when doing a major overhaul on the manuals and you
want `mklinks' to do all the dirty work.
.LI runcks
Runs a standard regression of the above tests against the manual.
Tests that are not required should be commented out of the procedure.
It is designed to keep a log of its history; hence, its output
should be directed to a file, usually in the same temporary directory
that the check procedures are using.
.LI 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
.I tocx?
in
/usr/man/tmp, or `tocrc ?' to create, in /usr/man/tmp,
the corresponding input file
.IR tocx? .
The `-p' option
should be used when preparing the table of contents and/or
index in the large (8.5x11 inch) format (this option, if
present, must be the first argument to `tocrc'); the small (6x9 inch)
format is the default.
See
description in /usr/man/READ.ME of the files in
/usr/man/[ua]_man/man0.
Uses files break and ignore in
/usr/man/tools.
.LE
.P
The file .param is described in /usr/man/READ.ME.
The files
M.folio and M.tabs are self-explanatory.
.\"	@(#)TOOLKIT	5.2 of 5/19/82