Trailing-Edge
-
PDP-10 Archives
-
BB-M836A-BM
-
tools/dsr/toc.doc
There is 1 other file named toc.doc in the archive. Click here to see a list.
Notes for TOC, version 1(25)
January 7, 1981
1.0 INTRODUCTION
TOC is a Runoff-related utility program that is used to help generate a
table of contents.
To generate input for TOC specify the /CONTENTS switch on the Runoff
command line. See the description of the /CONTENTS switch that is
supplied with DEC Standard Runoff.
In order to use this version of TOC, you need DEC Standard Runoff (DSR),
version 1(54) or newer. Other Runoffs cannot generate the input needed
by TOC.
2.0 CHANGES
o These changes first appear in TOC version 1(25).
TOC asks two new questions. One of the new questions occurs in
the middle of the previous 1(23) question sequence. Thus This
version is incompatible from the point of view of command
files. The changes are:
- New question: "Do you want headers numbered?"
- New question: "Specify deepest header level for which you
want trailing dots and page number:"
- The keep-emphasis question has been reworded: "Keep
chapter/header underlining and bolding?"
- Informational messages, such as "[Illegal number]", have
been cast in square brackets [].
o These changes first appear in TOC version 1(23).
You can specify a maximum header-level depth for the table of
contents. It can include only level-0 entries (chapter/
appendix), levels 0-1, levels 0-1-2, and so on.
You can specify whether or not the table of contents should
include any emphasis (bolding and underlining) that may be
present in chapter and appendix titles and header levels. See
the Usage Hints section for tips on using emphasis in a table
of contents.
3.0 OPERATION
Use the /CONTENTS switch of Runoff to generate a binary table of
contents (i.e., .BTC file) for your document. Then run TOC. When TOC
requests the name of your input file, respond with the name of your .BTC
file. TOC assumes a file type of .BTC, unless you specify otherwise.
Output is always written to a file of type .RNT.
For example, suppose you said
RUNOFF ABC/CONTENTS
Then the binary table of contents file is called ABC.BTC. When TOC asks
for the name of your input specify either just ABC (in which case TOC
assumes .BTC) or you can specify .BTC in addition. TOC will create a
file called ABC.RNT.
TOC now proceeds to ask six questions, as follows.
Q1. Varying header-level indents? (Y or N)
If you respond with "y" or "Y" (without the quotes) you get
additional indentation for header-levels 3 through 6. Any
other response causes header-levels 2 through 6 to start in the
same column, with the result that headers having lots of
numbers may run into the header-level text.
Q2. Running page counter? (Y or N)
If you answer "y" or "Y" you get running page counters,
regardless of whether running page numbers appeared in the
original document. Otherwise, answering anything else gives
you normal page numbers.
Q3. Specify deepest header level to include:
If you hit just <RETURN> you get all header levels. TOC
notifies you by printing "[All header levels will be
included.]". If you specify a number, you get all headers
specified by .HL n, where n is not greater than the number you
specify to TOC. In other words, enter 1 if you just want
.HL1s, 2 if you want .HL1s and .HL2s, etc. Enter 0 (zero) if
you want just chapter/appendix titles. Entering anything other
than a number produces an error message. You get three tries
to enter a number, then TOC reverts to the default (displaying
all header levels in the table of contents). This feature
allows you to run TOC from a command file without danger of
getting into an infinite loop.
Q4. Specify deepest header level for which
to print trailing dots and page number:
This feature allows you to list lower-level topics in the table
of contents without unduly cluttering it up. If you hit just
<RETURN>, all header levels are displayed with trailing dots
and page numbers. TOC notifies you by printing "[Page numbers
will be given for all header levels.]". If you specify a
number n, you get trailing dots and page numbers for header
levels 0 to n. Headers at a greater depth than n are shown
without dots or page numbers.
Q5. Keep chapter/header underlining and bolding? (Y or N)
If you answer "Y" or "y", any underlining or bolding
information present in chapter titles, header levels, or
appendix titles is carried over to the table of contents. If
you answer anything else, any such emphasis does not appear in
the table of contents. The answer to this question has no
effect on any emphasis information you may insert into the
table of contents with SEND TOC commands. In addition,
overstriking (which is not considered "emphasis") is always
propogated to the table of contents. See the section titled
"Usage Hints" for hints on how to use this feature.
Q6. Do you want headers numbered? (Y or N)
If you answer this question with "N" or "n", headers are not
numbered in the table of contents. If you answer anything
else, or simply hit <RETURN>, all headers will be numbered the
same as they are numbered in the original document.
You can specify unnumbered headers in the table of contents
regardless of whether some or all of the headers are numbered
in the document.
4.0 CREATING A MASTER TABLE OF CONTENTS
TOC allows you to segment your document, Runoff each section separately,
and then generate a master table of contents later. To do this,
generate the .BTC files as usual. Then append the binary table of
contents files together in the same order in which you would arrange the
segments of your document. Then proceed as if you had just a single
.BTC file to process.
You can also process all the .BTC files separately, and then append the
resulting .RNT files together.
4.1 Output Processing
TOC generates a file with file type .RNT which is to be processed by
Runoff. You can
1. Process the .RNT file just like an ordinary .RNO file, in which
case Runoff generates a .MEC file, or
2. Use the .REQUIRE command (e.g., .REQUIRE "ABC.RNT") to include
the table of contents in your document.
5.0 RESTRICTIONS
This version of TOC does not have a "standard" command line. Further,
there are no command line switches. And you cannot override the name or
type of the output file generated.
6.0 GUARANTEES AND CAVEATS
It is guaranteed that a working version of TOC will be supplied with all
future versions of DEC Standard Runoff.
It is not guaranteed that this particular version of TOC will work with
later/earlier versions of DEC Standard Runoff and/or .BTC files
generated by such Runoffs.
For each system on which DEC Standard Runoff is supported, a copy of TOC
will be supplied.
Eventually the source code for TOC will be supplied. The source code
will serve as a model showing how to generate a table of contents.
Bugs in TOC will be fixed. But they will be fixed "as convenient" and
depending on their severity.
Requests for enhancements to TOC will be evaluated; but there is no
guarantee that any enhancements will be made.
7.0 MESSAGES
TOC contains few error messages. All I/O error messages cause TOC to
terminate. In addition, the message 'CONFUSED' is output if TOC doesn't
like the looks of your .BTC file. On TOPS-10, you will almost certainly
get the 'CONFUSED' message if you don't use the /B switch of PIP when
you append a bunch of files together to generate a master table of
contents.
TOC also knows whether or not it can understand the .BTC file generated
by your particular version of Runoff. If you get the message
INCOMPATIBLE VERSIONS OF RUNOFF AND TOC
you are trying to get TOC to process a .BTC file that is not in the
desired format; the results are undefined.
8.0 USAGE HINTS
8.1 Using Emphasis (Bolding / Underlining) In Tables Of Contents
"Emphasis" means flags or flag-pairs for bolding and/or underlining
text, such as *, ^*, &, \&, and so on. Overstriking is not considered
as emphasis, and is not germane to this discussion.
TOC makes a distinction between emphasis you include in headers (the
text of chapter titles, appendix titles, header levels) and emphasis you
insert with SEND TOC. Only the former is affected by the fourth
question in TOC's initial dialog. If you answer this question with "n",
any emphasis you may have used in headers/titles does not appear in
TOC's output (.RNT) file. Any emphasis you have sent with SEND TOC
always appears in the .RNT file.
TOC uses the Runoff default flag characters for bolding (*) and
underlining (&) in its output .RNT file. Use caution if you redefine
the bold or underline flags in your .RNO file. Using non-default
emphasis flags will work as expected if used only in headers, or if used
only in SEND TOC commands. Results may not be as you expect if you mix
these two modes of using emphasis.
If you redefine one of the emphasis flags, you must also redefine it in
the table of contents with a SEND TOC command. For example, suppose you
want to use ~ for the underline flag. The commands at the top of your
.RNO file would include:
.FLAGS UNDERLINE ~
.SEND TOC .FLAGS UNDERLINE ~
If you specify that you want to keep the emphasis in headers (answer "y"
or "Y" to the fourth question), then TOC inserts the characters \&\* at
the end of each header in the table of contents. This allows you to
control whether or not the header number (e.g., 3.4.2) is also
emphasized, as described below.
If you want only the titles bolded, but not the header numbers, your
input (.RNO) file would contain headers like the following:
.HL 2 ^*Bolded Header\*
and TOC's output .RNT file would contain, for example:
3.4.2 *B*o*l*d*e*d *H*e*a*d*e*r\&\* . . . . . . . . . . . . . . 3-9
If, on the other hand, you want both header number and header text to
appear bolded in the table of contents, use a SEND TOC command before
the HL command:
.SEND TOC ^*
.HL 2 ^*Bolded Header\*
and TOC's output .RNT file would contain:
^*
3.4.2 *B*o*l*d*e*d *H*e*a*d*e*r\&\* . . . . . . . . . . . . . . 3-9
The extra ^* in the .RNT file assures that the header numbers are also
bolded. The \&\* that TOC inserts after the header title turns off the
emphasis.
Note, however, that to use this strategem effectively you must answer
"y" to TOC's fourth question. If you do not, TOC will not insert \&\*
after each header, and the extra ^* from SEND TOC (in the above example)
would cause bold to be locked on indefinitely.
Another consequence of answering "y" to the fourth question is that TOC
inserts a .FLAGS BOLD command at the start of the .RNT file and a .NO
FLAGS BOLD command at its end. If you use the bold flag in your
document, you must turn it on again after the .REQUIRE "name.RNT"
command.
[End of TOC.RND]