Documentation for TOC version 2
             Copyright 16 Jul 1990 by Carson Wilson
              Sysop, Antelope Freeway RAS, Chicago
                          312/764-5162


1.  OVERVIEW.

Table of Contents (TOC) version 2 is my adaptation of TBLCTENT, 
copyright 1985 by Dean A. Fields.  Both are Turbo Pascal-80 
programs which extract material from text files to tables of 
contents.  However, as TOC2 fixes several problems in TBLCTENT, 
and goes beyond TBLCTENT in a number of ways I feel justified in 
claiming it as my own work for copyright purposes.  See the 
(misnamed) TOC.LBR for Dean Fields' TBLCTENT.DOC and 
TBLCTENT.PAS.

Enhancements in TOC2 include:

     o  Prompt user for fence character
     o  Index labels in assembly language source code
     o  Retain last page number for restart with ZCPR GO command
     o  Expert mode and built-in help
     o  Now processes WordStar4 .TC index lines
     o  Patchable defaults for most items
     o  Separate Index mode

I have also sped up processing and made user input more friendly 
and goof-proof.  You may freely copy and distribute TOC2.LBR in 
its present form only and only for private use.  For commercial 
or other rights, please contact me by modem at Antelope Freeway 
Remote Access System.


2.  SYSTEM REQUIREMENTS.

TOC2 requires a CP/M compatible computer, and uses TPA memory 
through 7100 hex.  Most 64 kilobyte CP/M equipment has more than 
enough memory.  No installation is necessary.


3.  PURPOSE.

TOC2 will generate a table of contents or an index from any ASCII 
or WordStar text file.  The entries to be extracted to the table 
or index must be marked in one or more of several ways.  First of 
all, they may be marked with a "fence character."  WordStar uses 
the control-K character (entered by typing control-P followed by 
K) as its index fence character, and this is the default used by 
TOC2.  You may also select a different fence at runtime or 
install another default fence character using a file patch 
program (see below).

A second means of marking entries is by means of WordStar's .TC 
dot command.  Any lines beginning with this dot command are 
automatically included in the a table of contents (but not in an 
index) generated by TOC2.  Except for the first space, all 
characters on a line following the .TC dot command are included 
as the next line in the table of contents file.  If there is a 
"#" character in the .TC line, it is replaced with the page 
number of the line before the line on which the .TC dot command 
appeared, and the rest of the line is dropped.  (Note to users of 
NewWord or older versions of WordStar: since only WordStar4 
recognizes .TC entries, this command may generate Table of 
Contents entries if you use it in conjunction with the .CP dot 
command).

Finally, you may specify (or install) the colon (":") as the 
fence character, as a means of generating indices to assembly 
language source code files.  If the fence character is a colon, 
TOC2 includes only characters which appear BEFORE the first 
colon, space, semicolon, or tab (whichever comes first) of lines 
including colons in the index or table of contents.

TOC2 also uses a variety of methods to determine where new pages 
of printed output will begin.  This is critical in building a 
table of contents or index, whose purpose is to tell the reader 
on what pages material is located.  Normally, TOC2 increments the 
page count every time the installed number of lines per page is 
passed.  There are several important exceptions, however.  First, 
if a formfeed (control-L) is detected in column one of the text, 
a new page is assumed unconditionally.  Otherwise, TOC2 is 
sensitive to the following WordStar dot commands:


  COMMAND      RESULT
  -------      ------
     .CP       If the file was created with WordStar or NewWord 
               and resulted in a conditional page break, the 
               current page number is incremented.

     .OP       The current page number is retained, and no new
               table of contents or index entries are generated
               until a .PN dot command is detected.

     .PN n     The current page number is changed to n, where n
               is up to four decimal digits.  TOC2 aborts with an
               error message and displays the errant line if it
               encounters an illegal .PN command.

     .PA       The current page number is incremented by one.

     .TC       The rest of the line becomes a .TOC entry.  "#" in 
               TC lines is replaced with the page number,and 
               terminates the entry.

     ..        Comment lines (and all lines beginning with ".")
               do not count towards page length.

Please note that TOC2 will not scan lines beginning with 
formfeeds for index or table of contents information.

               
4.  OPERATION.

TOC2 requires no terminal installation.  From the command line, 
it runs in three modes: help mode, prompt mode, and expert mode.  
To run TOC2 in help mode, type "TOC2 //" at the command line.  
This produces a short usage message.  Most of the time you will 
want to use prompt mode by typing "TOC2" only.  Expert mode 
allows you to specify a filename at the command line, and causes 
TOC2 to run immediately without prompting for any further 
information.  This is intended primarily as a means of allowing 
multiple executions of TOC2 and/or of allowing TOC2 to be 
controlled by batch commands or command scripts.


4.1.  PROMPT MODE.

Typing "TOC2" alone or "TOC2" followed by an input file 
specification on the command line causes TOC2 to prompt you for 
information before proceeding.  You may abort TOC2 at any time by 
pressing control-C.  If you did not specify a file on the command 
line, the first prompt appears as follows:

Enter input filename ==>

Respond with the full name of the file for which you wish to 
generate an index or table of contents.  You may also specify a 
drive letter if the file is on another drive at the same user 
area, as "d:filename", where "d" is the drive letter for your 
file.  If the file is not found, TOC2 allows you to re-enter the 
name.

Once the input file is located, TOC2 searches the current 
directory for a file with the name of the input file and the type 
".TOC", if you are generating a table of contents, or ".IDX" if 
you are generating an index.  If the file exists, you will be 
asked if you wish to overwrite it.  If you do not wish to do so, 
TOC2 aborts, allowing you to rename or back up the current .TOC 
or .IDX file before proceeding.

Next, TOC2 prompts you for information about the input file and 
what kind of output you wish.  The values in parentheses are 
installable defaults.  Press RETURN to use them, or enter new 
values at the prompt.  When you are through entering the 
information, TOC2 asks you to verify that all of the information 
is correct.  If not, TOC2 re-prompts you for the information, 
this time using your previous responses as the defaults.  You may 
re-enter the material any number of times.  The prompts appear as 
follows:

   Lines per page (  54):

Be careful to choose the correct number of lines per page.  This 
should correspond to the number of text lines the program you use 
to print your document will include on one sheet of paper.  You 
MUST specify the proper number of lines, even when processing 
WordStar-type files.

    Starting page (   1):

This is the page number TOC2 begins its count with, NOT the page 
number at which it begins searching for index or table of 
contents entries (you can control this with the .OP command, see 
above).  Normally this will be page 1, unless you are processing 
a series of subfiles to be included in one master index or table 
of contents.  If so, you will want to instruct TOC2 to begin its 
count with the last page number of the preceding file.  This can 
be specified when reloading TOC2, or is assumed when TOC2 is 
restarted with ZCPR's GO command.

  Fence character   (^K):

Unless you are using WordStar4's .TC dot commands (see above) to 
form a table of contents, this is the character which turns 
generation of index or table of contents entries on and off.  
When TOC2 sees a fence character, it begins adding text to the 
index or table of contents for that page (unless the .OP command 
is active, see above).  The entry terminates when a second fence 
character is detected, or at the end of a line, whichever comes 
first.

Although TOC2 will accept any ASCII value as a fence character, 
normally you will use control characters for the purpose of 
fencing index or table of contents entries (see your word 
processor's manual for instructions on entering control 
characters).  To specify a control character in response to 
TOC2's prompt, enter it directly by holding down on the control 
key and pressing the corresponding keyboard character.

If you are using both the .TC dot command for Table of Contents 
entries and a fence character to mark index entries, be sure to 
specify something other than your index fence character at this 
prompt when generating a table of contents (see below).  
Otherwise TOC2 will include BOTH the .TC entries AND the index 
entries in your Table of Contents (TOC2 is smart enough to 
exclude .TC entries if you are generating an index, however).

The colon (":") is a special fence character which causes TOC2 to 
build an index of assembly language source code labels.  If the 
fence character is a colon, TOC2 includes only characters which 
appear BEFORE the first colon, space, semicolon, or tab 
(whichever comes first) of lines including colons in the index or 
table of contents.

Contents or Index    (C):

When it builds a table of contents, TOC2 produces a .TOC file 
consisting of the fenced text entries from the input file and 
their page numbers, right-justified, one entry per line.  TOC2 
can also be instructed to build a unsorted index by simply 
extracting all fenced text entries, followed by two spaces plus 
their page numbers, one entry per line.  Though the index will be 
of little use in its unalphabetized form, you may use SORT.COM, 
included in this library, to quickly alphabetize TOC2's output 
for a true index file.  To sort a TOC2 .IDX file, use SORT as 
follows:

     SORT -i <filename>.IDX

The "-i" parameter tells SORT to ignore the case of characters 
(i.e., "a" is the same as "A").  See SORT.HLP for more on the 
usage of SORT.COM.


4.2.  EXPERT MODE.

Expert mode instructs TOC2 to skip all prompts and begin running 
as soon as it has loaded from disk (or immediately with ZCPR's GO 
command).  This allows you to specify a filename at the command 
line, and is intended primarily as a means of allowing multiple 
executions of TOC2 and/or of allowing TOC2 to be controlled by 
batch commands or command scripts.  Expert mode is invoked as 
follows:

A>TOC2 [d:]filename *

TOC2 immediately searches for the specified filename, and, if 
found, begins processing it using the installed (or current with 
ZCPR's GO command) page length, starting page, fence character, 
and contents/index options.  You can easily build an index or 
table of contents to a series of subfiles under ZCPR with the 
following command script:

A>TOC2 subfile1;GO subfile2 *;GO subfile3 *;....

TOC2 will keep track of the page count between files to build a 
master table of contents or unsorted index which will correspond 
to all of the above subfiles when printed in the same order.  If 
a specified input file is missing, TOC2 immediately reverts to 
PROMPT MODE (see above).


4.3.  PROCESSING.

TOC2 processes your input file by analyzing it a line at a time 
and performing various actions depending on the content of each 
line.  It also reports the current page number to the screen.  
From time to time, TOC2 writes to the .TOC or .IDX file.  If disk 
space for the output file is inadequate, TOC2 first saves what 
has already been written to disk, then aborts with an error 
message.  When processing is complete, TOC2 closes the input and 
output files with a message and exits to the operating system.

If the DEBUG patch point is set to 01 hex, TOC2 also echoes to 
the screen the line number and first fifty characters of each 
input line as it is processed.  This aids in diagnosing problems 
by allowing you to pinpoint exactly where on each page TOC2 
is incrementing its page count (see PATCHING TOC2 below).


4.4.  PERFORMANCE.

Tests indicated that TOC2 running on a 4 Mhz Z80 ZSDOS system 
generates tables of contents at speeds comparable to WordPerfect 
5.0 running on an 8 MHz 80286 MS-DOS system.


5.  PROGRAM OUTPUT.

As detailed above, TOC2 produces either table of contents or 
unsorted index files.  These are ASCII text files which can be 
further edited with any word processing program.  See the files 
TOC2.TOC and TOC2.IDX for examples of output generated by running 
TOC2 on this file (TOC2.WS).


6.  PATCHING TOC2.

Though you do not need to patch TOC2, you may do so as a means of 
customizing it for your particular application.  All of the 
patchable option bytes are located immediately after the ASCII 
label "[PATCH>" at offset 2000 in TOC2.COM (2100 hex with most 
debuggers).  The bytes are as follows:

offset		default value	meaning		legal patch values 
------		-------------	-------		------------------ 
2100h		'[PATCH>'	(pointer) 
2107h		0B		fence char.	00..7F except 0D,0A 
2108h		36 00		lines/page	0...9999 decimal
210Ah		01 00		starting pg.	   "        "
210Ch		'C'		Contents/Index	'C' or 'I'
210Dh		00		debug		1 for debug

                         - end of file -