% loop.doc  --- version 1.0 (15 April 1991)
% This is the documentation for loop.tex.
% To read this file, process it with (plain) TeX: tex loop.doc
% (To do that, you need manmac.tex, which has
% the macros for typesetting the TeXbook, as explained in appendix E.
% It comes free with the standard distribution of TeX.)
%
% NOTE: Processing this file with TeX will create empty files
%       index.tex and answers.tex in your directory. And if you
%	have a file pages.tex in your directory, TeX will probably
%	get very confused.
%	The manmac format will try to load a font called cmman; if
%	TeX complains that it cannot find that font you can savely
%	ignore that, since the font is not actually used.
%
% This file: copyright (c) 1991  Marcel van der Goot.
%	You may redistribute this file and printed versions of it.
%
% original: csvax.cs.caltech.edu [131.215.131.131] in pub/tex
%           (use anonymous ftp). Also in various archives.
%
% Marcel van der Goot
% marcel@cs.caltech.edu
%   Caltech 256--80
%   Pasadena, CA 91125
%   (818) 356--4603

% ------ definitions for manual pages:
% The documentation is typeset using Knuth's ``manmac'' macros, with a
% few additional things defined here. You are free to use or adapt these
% extra definitions.

\input manmac % the macros used for typesetting The TeXbook (appendix E)
\catcode`^=7 % manmac makes ^ active for creating an index
	% we don't make an index, and we need ^ to be non-active

{\catcode`\^^M=12 \endlinechar=-1 % 12 = other
\long\gdef\manpagehead#1^^M#2^^M#3^^M^^M% tex-file, description, version
   {\egroup % matches \bgroup in \manpage
    \par\vfill\eject
    \edef\rhead{\manualname: #1\unskip}%
    \setbox1=\hbox{\titlefont #1\quad}%
    \setbox3=\vtop{\advance\hsize by-\wd1 \parindent=0pt \raggedright
		   #2\par
		   #3\par
		   \cnotice
		  }%
    \line{\box1\box3}%
    \bigskip\bigskip\bigskip\noindent
   }%
} % restore \catcode`\^^M

\outer\def\manpage
   {\bgroup\catcode`\^^M=12
    \manpagehead
   }

\hsize=6.5in\vsize=8.9in % default plain TeX values
\pagewidth=\hsize \pageheight=\vsize

\def\cnotice{Copyright \copyright\ 1991 Marcel R. van der Goot}
\def\manualname{Midnight Macros}

% LaTeX logo, from latex.tex (except for the capital `A': manmac
% doesn't have a real smallcaps font)
\def\LaTeX{{\rm L\kern-.36em\raise.3ex\hbox{\sc A}\kern-.15em
    T\kern-.1667em\lower.7ex\hbox{E}\kern-.125emX}}

\tenpoint

% (end of extra definitions)

% -------------------- loop.doc:

\pageno=8 % follows gloss.doc

\manpage loop.tex
A simple looping construct (meta-macros).
Version: 1.0 (15 April 1991) (doc: 15 Apr 1991)

The macros in loop.tex are intended to help you write your own
macros, rather than to typeset text directly. Consequently, it is
assumed that you have some experience writing macros; In other words,
assume that this whole section is preceded by a ``dangerous bend'' symbol.
These macros are kept
simple and are not very robust: if you decide
to use them in a different way than described below you are
entirely responsible for what happens\footnote{$^1$}{Not that the
author assumes any responsibility even if you {\sl do\/}
obey the rules.}.

Loop.tex defines an alternative to plain \TeX's |\loop| construct.
(It can also be used with, e.g., \LaTeX.)
Plain \TeX's |\loop| is often awkward to use because of the
limited form of tests in \TeX. The new construct tries to alleviate
this problem by allowing a more flexible use of tests in the loop.
To execute a loop, you say |\Loop ... \Pool|\footnote{$^2$}{We use
initial capital letters to prevent confusion with plain \TeX's |\loop|.
Although you don't need |\loop| anymore, there may still be macros
that depend on it (e.g., plain \TeX's tabbing macros).}.
This will normally
execute the loop `body', i.e., the commands corresponding to the dots,
infinitely many times.
There are two special commands you can use within the loop,
|\Break| and |\Continue|. When a |\Break| command is
executed, the rest of the body is ignored, and the loop is terminated.
Execution of a |\Continue| command also causes the rest of the body
to be ignored, but then the loop is started again from the beginning.

Both |\Break| and |\Continue| must be followed by a number. This
number should be the number of |\if...| constructs that are terminated
by the command. In other words, it is the number of |\fi|'s that
has to be `executed' to get proper balancing of all |\if...| tests.
It is somewhat unfortunate that this number has to be supplied,
but there seems to be no way to close all |\if...| tests automatically.
Here is an example similar to one from the \TeX book.
\begintt
\def\yes{Yes } \def\no{No }
\Loop\message{Are you happy? }
     \read-1 to\answer
     \ifx\answer\yes \Break1
     \else\ifx\answer\no \Continue2
     \fi  \fi
     \message{(Please type Yes or No.)}
\Pool
\endtt
At the position of |\Break| the nesting level of |\if...| tests
is 1, at the position of |\Continue| the level is 2.
If you forget the number you will (usually) get a `|missing number|' error
message, but possibly at an unexpected point in the program. The
wrong number typically results in either an `|Extra \fi|' or
an `|\if... was incomplete|' message.

There can be any number of |\Break| and |\Continue| commands in
a loop, although it is wise to have at least one |\Break| command.
The text following any of these commands up till the |\Pool| at the
end of the loop must have balanced braces, and the loop body itself
must also have balanced braces. If this causes a problem, you
can use |\bgroup| and |\egroup| instead of |{| and |}|. If you
want to nest two loops, you will have to enclose the inner loop within
a group. (Incidentally, these restrictions on balancing braces and
nesting loops also apply to plain \TeX's |\loop| construct.)

\bye