***********************************************************************
* *
* CHECKER *
* by R. Grothmann *
* *
***********************************************************************
Documentation
=============
Introduction
------------
Checker is a program designed for testing TeX files. Besides checking
the syntax, it features labels and automatic tag numbering. Just start
checker by entering
check -options infile outfile
On the Atari ST you have to click on check.ttp and enter the options
and files into the ttp box, appearing on the screen. "options" is a
sequence of the letters (capital or not) l,t,s,v,p,n or o. "infile"
and "outfile" (optional) are standard filenames. An example is
check -lt work.txt work.tex
The program will read in the file work.txt, check it and produce an
output to the file work.tex, thereby changing labels and tags to their
values. If you omit the outfile, the program will produce no output.
Labels
------
Labels belong to a group and have a name and a value, which is an
integer (positive or negative). They are defined in a program by
#=group.name
or
#={group.name}
The name is any alphanumeric string (consisting of lowercase or upper-
case letters or digits), not exceeding 15 characters. The group may
consist of several alphanumeric strings, seperated by "." and not ex-
ceeding 14 characters. An example is
#=1.1.a
or
#={1.1.a}
where "1.1" is the group and "a" is the name. The Value of the label
can be assigned to it by the sequence
#=group.name=value
or
#={group.name=value}
Remember that "value" has to be an integer. For example
#=refs.miller=10
If you do not assign a value to the label, it gets the value of the
previous label in the group plus 1. If there is no previous label, the
value will be 1. On the output, the whole definition of the label is
replaced by the value of the label. And so are all references of the
label. References are of the following form
#:group.name
or
#:{group.name}
Of course, you cannot assign a value to a reference. If a label is
immediately followed by an underbar "_", then this underbar disappears
from the output, for instance
#:test.a_a
will be replaced by "1a", if "test.a" has the value 1. The label feature
is only active, if the option "l" was given on the command line. Other-
wise the program will just read over any #.
Default Group
-------------
If a label is defined or referred to without a group (omitting both
the group and the "."), then it is assumed to be a label in the default
group. You can set the default group by
#=block.group
This is not a label definition. There is never a group named "block".
Instead, the default group is set to "group". As an example, let
#=block.refs
#=a
be a sequence from your file. Then the reference
#:a
is a reference to the label "refs.a", unless you have redefined the
default group. If you did so, you may refer to that label by
#:refs.a
Tags
----
Tags are a part of TeX's syntax. Checker assumes tags to be defined as
\tag group.name
or
\tag {group.name}
"group" and "name" obey the same syntax rules as in the definition of
labels above. They are referred to by
\thetag{group.name}
As with labels, you may assign a value to a tag. An example is
\tag 1.a=0
On the output, only the name of the tag is replaced by the value of the
tag. Thus the above tag would change to
\tag 1.0
Of course, all references (\thetag ...) are corrected too. As with
labels, the program checks for double definition of a tag. Tags may
be proteced by
\tag !something
or
\thetag !something
The the program will not change "something". Only the "!" will be left
out. What was said about default groups, holds for tags too. The tag
feature is active, if the option "t" is given in the command line. The
"_" works in the same way, as it does with labels.
Syntax checking
---------------
Unless the option "n" was given, the program checks the syntax in your
file for correct usage of "$". "$$", "{" and "}". The program is clever
enough to know that "\{" is different from "{". The first error will
abort the program and will be reported. Comments "%" are omitted. An
error does not abort the program if the option "e" was given int the
command line.
Output of Labels and Tags
-------------------------
Only labels and tags are written to the output file, if the option "o"
was given in the command line. This is done in such a way that the
output file can be read into a TeX file. All labels are written as
#;group.name=value
The tags look like
#;@group.name=value
The sequence "#;" starts a blind label. Such a label is defined, as
if "@;" was replaced by "@=". But on the output, it will not show up.
The same is true for tags. So you can just use the old label definitions
in a new TeX file. This may be used in a continuation of a previous
TeX text. If a blind label or tag occupies a complete line, then this
line will not go to output. Otherwise the rest of the line will be
in the output.
Other Options
-------------
You have control over the screen output of the program. Least printing
is produced with the option "s" (silent). The option "v" lists all the
syntax elements the program finds (verbose). The option "p" prints out
the complete text (print).
Internals
---------
Checker is a C program, which uses two passes. Pass 1 checks the syntax
and collects all labels and tags. Pass 2 corrects labels and tags and
produces the outfile. An existing outfile will be truncated without
backup. Reading and Writing is done via a buffer. The preformance is
best, when the files are on RAM disk or harddisk.
************************************************************************
If you have troubles with the program, contact
R. Grothmann
Ostenstr. 18
8078 Eichstaett
W-Germany
EMail:
[email protected]
*************************************************************************
