% The TeX Programmer's Manual (version 0.0.2)
%  Andrew Marc Greene  4 Mar 1988
%
\input /mit/amgreene/texhax/man.sty
%
\newpage{Introduction}{{\TeX} as a Programming Language}
This document is a manual for {\TeX}, the text processing language
by Donald Knuth.  It assumes a basic knowledge of both {\TeX} and
programming.  If you are new to {\TeX}, you should stop by the
SIPB office and pick up a copy of {\it Mathematical Editing in
LaTeX} by Mark Eichin.  If you are new to programming, then you
should learn another language first.  {\TeX} is an ugly language, and
only veterans of many late-night hacking sessions should even
consider attacking it.

Now that you've been warned$\ldots\,\ldotp$
\newpage{Introduction}{Conventions Used in this Manual}
Each page in this manual has the same format, including this one.

The top contains two keys.  The first one, in large letters, is the
section (this page belongs to the {\bf Introduction}).  The second,
in smaller type, is the topic covered on that page.  Each page contains
one concept or group of commands.  This should make it easier to
follow the manual, as well as making it a better reference manual.

The text itself is set towards the left, leaving the right margin
for your personal notes.  Keywords \markey{Keywords} will also appear 
in this margin,
to enable you to flip through the manual and find the command you're
looking for quickly.

The text is set in Roman type (like this).  Commands and other things
that you type in are in |typewriter style|, and arguments to commands
are in <slanted type within angle brackets>.  Responses from the
computer are in \cmp{sans serif type}.

\dbbegin
Every once in a while, there will be a paragraph or a page of gory
detail.  This will be set in a smaller typeface, and surrounded by
a box.
\dbend

Finally, the bottom of the page contains the page number.

\newpage{Variables}{Variable Types}
There are five types of variables in \TeX.  These are macros, numbers,
dimensions, glue, and boxes.  Actually, there are more, but I
don't know them yet.  Erk.

{\bf Macros.}\ix{Macros (as strings)}\markey{Macros}
For the purposes of this section, macros serve as strings.  They also
can be used as procedures; this will be covered later.

{\bf Numbers.}\ix{Numbers}\markey{Numbers}
A number in {\TeX} is, for out purposes, simply a constant with an
optional leading sign.  A more rigourous definition is given on page
\tbp{269} of the \tb.  Hexadecimal may be specified by a leading
double quote (e.g., |"3FC| is 1020 decimal), octal with a leading
single close quote (e.g. |'377| is 255).  Numbers must be integers
with magnitude less than $2^31$.%
\ix{Numbers (magnitude)}\ix{Numbers (range)}\ix{Range of numbers}%
\ix{Magnitude of numbers (must be less than $2^31$)}%
\ix{Hexadecimal constants}\ix{Octal constants}\ix{Constants}%
\ix{Constants (hexadecimal)}\ix{Constants (octal)}

{\bf Dimensions.}\ix{Dimensions}\markey{Dimensions}
A dimension is a number, with optional decimal fraction, followed by
a unit such as |pt|, |mm|, or |in|.\tbp{270}  If the unit is |mu|, 
the dimension is a {\bf mudimen} insted.%
\markey{Mudimens}\ix{Mudimens}\ix{mu/}

{\bf Glue.}\ix{Glue}\markey{Glue}
Glue is a dimension withe ``shrinkability'' and ``stretchability.''
These two adjustments are each optional and are assumed to be zero
if not present.  Glue is specified by a <dimensions> followed by
|plus| and the stretchability and/or |minus| and the
shrinkability.  Glue that uses |mu| units is {\bf muglue}.\tbp{271}%
\markey{Muglue}\ix{Muglue}\ix{mu/}\ix{shrinkability}\ix{plus/}%
\ix{stretchability}\ix{minus/}

{\bf Boxes.}\ix{Boxes}\markey{Boxes}
Boxes are the things {\TeX} puts together.  They are arranged within
other boxes, and eventually get placed on the page.  This description
is not very good, and will have to be revised.

\newpage{Program Control}{Conditionals}
The general form of a conditional structure in {\TeX} is

\hfill\hbox{<conditional command><code for true case> 
{\bf [}|\else|<code for false case>{\bf ]} |\fi|}\hfill
\ix{if}\ix{if/}\ix{fi/}\ix{else/}

The following is a list of the <conditional>'s:

\medskip
\halign{\strut#\hfil&\quad\vtop{\hsize=.4\hsize\lineskip=10pt
\baselineskip=\lineskip\relax#}\cr
|\ifnum|<number-1><relation><number-2> &
Compares the given numbers; <relation> is either |<|, |=|, or |>| \cr
|\ifdim|<dimen-1><relation><dimen-2> &
Compares the given dimensions; <relation> is either |<|, |=|, or |>| \cr
|\ifodd|<number> &
True if <number> is odd, false if even \cr
|\ifvmode| &
True if in vertical mode \cr
|\ifhmode| &
True if in horizontal mode \cr
|\ifmmode| &
True if in math mode \cr
|\ifinner| &
True if in internal vertical mode, restricted horizontal mode,
or nondisplay math mode \cr
|\if|<token-1><token-2> &
True if the two tokens expand to the same characters \cr
|\ifcat|<token-1><token-2> &
True if the two tokens expand to the same category codes \cr
|\ifx|<token-1><token-2> &
True if the two tokens are the same \cr
|\ifvoid|<number> & 
True if |box|<number> is void \cr
|\ifhbox|<number> &
True if |box|<number> is an hbox \cr
|\ifvbox|<number> &
True if |box|<number> is a vbox \cr
|\ifeof|<number> &
True if file <number> is at its end \cr
|\iftrue| & Always true \cr
|\iffalse| & Always false \cr }

\bigskip

There is also a command called |\ifcase|, which selects from a number of
possible choices based on its argument:

\hfil\halign{\hfill#&#\hfill \cr
|\ifcase|<number>& <code for case 0> \cr
|\or|&<code for case 1> \cr
&$\qquad\vdots$ \cr
|\else|&<code for all other cases> \cr
|\fi|& \cr}\hfil

\dbbegin
Knuth warns on page \tbp{211} that |\if| constructions without matching
|\fi|'s, such as |\let\ifabc=\iftrue|, should be avoided in conditional
text.  {\TeX} will not see the |\let|, but it will continue to keep
track of outstanding |\if|'s and expect two |\fi|'s.  Knuth's
recommended solution is to put the unmatched conditionals in macros,
where they won't be expanded if not invoked.
\dbend

\newpage{Program Control}{User-Defined Conditionals}

You can define your own conditionals with the |\newif| command:

\hfil|\newif\if|<symbolic name>\hfil

will create three macros.  |\if|<symbolic name> will now test the
flag <symbolic name>, which should be set by |\|<symbolic name>|true|
and |\|<symbolic name>|false|; the flag is initialized to |false|.

\newpage{Program Control}{Loops}

The format of {\TeX}'s looping structure is as follows (see \tbp{217}):

\medskip
\hfil|\loop|<main body>|\if|<condition><code for true case>|\repeat|\hfil
\medskip

The <main body> is executed, then the <condition> is evaluated.  If it
is true, the <code for true case> is executed and the loop starts again.
Otherwise, the <code for true case> is omitted and program execution
resumes after the |\repeat|.

You may not nest |\loop| structures without enclosing inner levels
within groupings.

\dbbegin
The implementation of |\loop| and |\repeat| is described on page
\tbp{219} of the \tb.  They are not primitives, but are macros written
in Plain \TeX.  Actually, |\repeat| isn't a macro at all but
merely acts as a delimeter for |\loop|.  The definition of |\loop| is

\medskip
\hfil|\def\loop#1\repeat{\def\body{#1}\iterate}|\hfil

\medskip
The definition of |\iterate| is also clever, in that it simply expands
|\body| and expects it to end with a conditional:

\medskip
\hss|\def\iterate{\body\let\next=\iterate\else\let\next=\relax\fi\next}|\hss

\medskip
Yet, these simple macros act entirely like |\loop| and |\repeat|
commands should.  An obvious caveat, however --- don't use |\body| or
|\iterate| or |\next| in a file that will require |\loop|
structures.  This is also why you cannot nest |\loop| structures ---
|\body| will be redefined by the inner structure, and (unless the
inner structure is contained within its own group) the second
|\repeat| will execute the {\bd wrong} |\body|.  This loses.

\dbend

\newpage{Program Control}{Macros as Procedures}

This page is intended to clarify argument passing to macros, and to
provide guidelines for the use of macros as procedures.  For the full
story, as told by Knuth, read Chapter 20 of the \tb.

There are three ways to specify an argument in the |\def| statement.

\hfil|\def|<macro name>|#1#2|<expansion>\hfil

This method will take each group after the <macro name> appears in the
body, and allocate it to |#1|, |#2|, and so in, in sequence.

\hfil|\def|<macro name><required tokens>|#1|<terminator><required tokens>%
<expansion>\hfil

This method allows you to set up delimeters of your own choosing
(see the section on {\bf Program Control / Loops} for an excellent
example involving the definition of |\loop|).

\hfil|\def|<macro name>|#1#|<expansion>\hfil

This method will use the close brace |}| to terminate the argument,
but will include the |}| as the last character of the argument.

Remember that the <expansion> must be delimited by |{| and |}|, but
that these don't count as grouping tokens after the macro has been
defined.

Because a macro is replaced by its <expansion> as soon as it is
used, tail recursion is possible in {\TeX}.  The |\loop| example
utilizes tail recursion.  You need not actually recurse, of course,
since whatever macro is last will simply be expanded after all
of the other tokens from the expansion of <expansion> have been
used up.

\newpage{Files}{Input}

You may have up to sixteen files open at one time in \TeX.  These are
assigned handles numbered from 0 to 15.  All other handles, as well as
unused handles and handles on empty files, correspond to standard
input.  Positive handles result in the user receiving a prompt
with the name of the <macro> to be filled (e.g. |\|\cmp{myname=}),
while negative handles will simply start reading in text.

\medskip
\halign{\strut#\hfil&\quad\vtop{\hsize=.4\hsize\lineskip=10pt
\baselineskip=\lineskip\relax#}\cr
|\newread|<symbolic name> & Allocate a new file handle \cr
|\openin|<symbolic name>=<filename> & Open the file for input \cr
|\read|<symbolic name>|to|<macro> & Read one (or more) line(s) from the file,
and cause <macro> to be a parameterless macro whose expansion text
is the inputted text.  One line will be read, unless there is an
unbalanced |{|, in which case lines are read until the braces are
balanced. \cr
|\closein|<symbolic name> & Close the input file \cr
}

\medskip
|\read| is local unless prefixed by |\global|.

\dbbegin
Unfortunately, the carriage return at the end of an input line gets
translated to a space, which sits at the end of the input string.
The following code solves this problem:

\hfil|\def\vread#1{\catcode`\^^M=9 \catcode`\ =12 \global\read-1 to #1}|\hfil

\dbend

(Most of this material appears in the \tb on pages \tbp{216f.})

\newpage{Files}{Output}

Standard output is easy to write to with the |\message| command,
which displays its argument (with macros expanded) on the screen.
It is also, of course, recorded in the |.log| file.

\dbbegin
Because the argument to |\message| is processed by {\TeX} and
expanded, I have found it useful to define a macro that treats
spaces as category 12.  This way, if I type two spaces, two
spaces are displayed.

\hfil|\def\vmsg#1{\catcode`\ =12 \message{#1}}|\hfil

\dbend

Output files may be referred to by handles.  These handles are completely
independent of those for input files.  Positive unused handles correspond
to standard output and |.log| file, negative handles correspond only to
the |.log| file.

\medskip
\halign{\strut#\hfil&\quad\vtop{\hsize=.4\hsize\lineskip=10pt
\baselineskip=\lineskip\relax#}\cr
|\newwrite|<symbolic name> & Allocate a handle \cr
|\openout|<symbolic name>=<filename> & Open the specified file for
output \cr
|\write|<symbolic name>|{|<token list>|}| & Expand <token list> and
appends it to the specified file \cr
|\closeout|<symbolic name> & Close the specified file \cr
}

There is a crucial difference between input and output, however.  Input
occurs immediately, but the above commands (except |\newwrite|)
 are placed in what {\TeX}
calls a ``whatsit.''\tbp{226f}  The whatsit is placed in the current
vertical or horizontal list, and the arguments to the commands are
not expanded.  When the current page gets shipped out, {\bf then} the
whatsits are evaluated, the arguments expanded, and the commands
executed.

The reason for this is that tables of contents and indicies can be
implemented by using |\write\foo{\count0}|; but the current page is
not known until it is shipped out!  Knuth says at the bottom of
\tbp{227} that it is possible for a whatsit to be expanded once, never,
or many times.

If one of these commands must be executed immediately, it should be
preceded by |\immediate|.

There is a difference between |\message| and |\immediate\write16|.
|\message| will put the text at the current location of the cursor,
separating the output with a space from the previous text.
|\write16| will start a new line each time.



\end

