%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%                                                                             %
%  caged_process='tex $F$M'                                                   %
%                                                                             %
%  caged_date='R%    Last edit $X by $U'                                      %
%    Last edit Jan 21, 1987 3:23 am by dave
%                                                                             %
%  CS10 1987 2nd term                                                         %
%  David Gillespie                                                            %
%                                                                             %
\input labmac                                                                 %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%                                                                             %
%  Documentation for labmac.tex                                               %
%                                                                             %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%



\internaldefs

\def\cmd<{
   \smallbreak
   \begingroup
   \let>=\cmd@
   \it
   \hskip-1em
}
\def\cmd@{
   \endgroup
   \vadjust{\nobreak}
   \par
   \continuegraf
}

\normaldefs


\class{}
\handout{Labmac documentation}{Documentation for the LABMAC macros}



\section{General notes}

A \labmac\ document is arranged as follows:
\display \it
||\input /lib/tex/labmac||
Optional definitions
||\handout|| or similar command
Optional definitions
Text of the document
||\bye||
\done
The text of the document contains all normal Plain \TeX\ and HP\TeX\ commands,
plus other commands described below.  Many \labmac\ commands take the form:
\display \it
||\||command options-and-declarations
Body of the command
||\done||
\done
\index{Environments}
and are called <environments>.  Environments are isolated from the rest
of the document by grouping.  Which <options-and-declarations> are allowed
varies according to the environment.

\index{<Restricted> text}
Commands that take arguments in |{|braces|}| are called <restricted>
if certain kinds of verbatim text may not appear in the argument.  For
example, if you used |\|$debug$\|| in a restricted argument, the |$|'s
would still be interpreted as math-mode characters.  Most Plain \TeX\ and
HP\TeX\ commands are restricted, but most \labmac\ commands are not.



\section{Fonts used}

\index{Apple fonts}
\index{Fonts}
By default, \labmac\ uses the Apple Laserwriter's built-in fonts, except
that Plain \TeX's ||\tt|| font is used for examples.  Somewhere buried
deep inside the file |labmac.tex| is the command,
\fvexample
\appletrue
\done
To use non-Apple fonts, just change this to
\fvexample
\applefalse
\done
in your own <private> copy of |labmac.tex|.



\section{Header commands}

One of the following three commands must always appear at the beginning
of the document:

\vindex{\handout}
\cmd<||\handout{||short-title||}{||full-title||}||>
This is a generic class handout.  The <short-title> appears at the
bottom of every page.  The <full-title> appears at the top of the first
page.

\vindex{\assignment}
\cmd<||\assignment{||short-title||}{||sub-title||}||>
This is a course assignment.  The <short-title> should be something like
``Lab~3'' or ``Homework~2.''  This and the <sub-title> appear at the
top of the first page.

\vindex{\lab}
\cmd<||\lab{||lab-number||}{||sub-title||}||>
This is a lab assignment.  The short title will be ``lab <lab-number>'',
and the <full-title>, along with the lab number, appears at the top of the
first page.

\medskip
In addition, the following ``global'' commands may be used:

\vindex{\class}
\cmd<||\class{||class-name||}||>
This gives the name of the class.  The default class name of ``CS10''
is used if ||\class|| does not appear.  The argument <class-name> may
be blank.

\vindex{\smallprint}
\cmd<||\smallprint||>
This appears somewhere in the header to select ten-point instead
of twelve-point print.

\vindex{\nopagenumbers}
\cmd<||\nopagenumbers||>
This command from Plain \TeX\ suppresses the page numbers and the
date/title lines at the bottom of the page.



\section{Mode-switch characters}

In addition to the usual \TeX\ |$| and |$$| math-mode characters, \labmac\
provides the following:
\list{|..|text|..| }
\item{|\||<text>|\||}
\index{|Verbatim| text}
The <text> is set in <verbatim> mode, in which the characters
\example
  $  &  #  ~  ^  _  %  {  }  <  >
\done
are considered normal text characters.  Line breaks and multiple
spaces are preserved.  The text is set in the
fixed-width ||\tt|| font.  Also, the |\\\|| and |\\\\| sequences
produce the characters |\|| and |\\|.  If verbatim text appears in
a restricted argument, the text is set in ||\tt|| font, but the
characters shown above do not lose their normal meanings.
\index{|Full-verbatim| text}
\item{|\|\||<text>|\|\||}
The <text> is set in <full-verbatim> mode, which is similar to normal
verbatim mode except the following characters are also considered to
be normal text:  |\\|, and |\|| not immediately followed by another |\||.
\index{<Italic> text}
\item{|<|<text>|>|}
The <text> is set in italics.  The <text> may include uses of the other
mode-switch characters shown here.
\indexas{<.Small-caps.> text}{Small-caps text}
\item{|<.|<text>|.>|}
The <text> is set in <.Caps And Small Caps.>.  The <text> may include
other mode-switch characters, but the text is ``restricted'' with respect
to verbatim mode.
\done  % with list



\section{Simple commands}

Here are some simple commands (not involved with environments).

\vindex{\frac}
\cmd<||\frac{||numerator||}{||denominator||}||>
Typeset a fraction, like \frac{1}{2} or \frac{a}{b}.  This works in or
out of math-mode.

\vindex{\badbreak}
\cmd<||\badbreak||>
Mark this place as a bad, but not impossible, place to break the line
or page.  Not as strong as Plain \TeX's ||\nobreak||.

\vindex{\missinglines}
\cmd<||\missinglines||>
Typesets the symbol,
\example
\missinglines
\done
which is supposed to be used in line-oriented displays like ||\example||.

\vindex{\today}
\cmd<||\today||>
Typesets the current date, in the form ``\today''.

\vindex{\centerline}
\cmd<||\centerline{||text||}||>
\centerline{This command has been modified to break text into multiple
lines if it won't fit.  The argument is <not> restricted.  (The
||\leftline|| and ||\rightline|| commands are the same as in Plain \TeX, so
they overflow the page on long lines, and their arguments are restricted.)}

\vindex{\small}
\cmd<||\small{||text||}||>
This command sets the <text> in somewhat \small{Smaller Letters}.

\vindex{\smcaps}
\cmd<||\smcaps{||text||}||>
This command sets the <text> as caps-and-small-caps text.  The argument
is restricted.  Equivalent to ||<.||<text>||.>||.

\vindex{\labmac}
\cmd<||\labmac||>
This command sets the word, \labmac.

\vindex{\CAGED}
\cmd<||\CAGED||>
This command sets the word, \CAGED.

\vindex{\arrow}
\indexas{||\Arrow||}{\arrowx}
\vindex{\bullet}
\vindex{\bull}
\vindex{\]}
\cmd<||\arrow||, ||\Arrow||, ||\bullet||, ||\bull||, ||\]||>
These commands produce, respectively, the following symbols:
\display
\arrow \qquad \Arrow \qquad \bullet \qquad \bull \qquad \]
\done
They work either in or out of math mode.

\vindex{\inbox}
\cmd<||\inbox{||text||}||>
The <text> is set inside of a \inbox{rectangular box}.  The argument is restricted.

\vindex{\hangbox}
\cmd<||\hangbox{||text||}||>
The <text> is set in a box which is hanging to the left of the current
position.  Should be used at the beginning of a paragraph, line, or
list item.

\vindex{\section}
\cmd<||\section{||text||}||>
Begins a new section of the document.  The <text> is set in large
italics.

\index{Underscores}
\cmd<|_  |(the underscore character)>
Underscores are now allowed outside of math mode, where they print as
underscores.  This is shorthand for where verbatim mode is awkward, or
not allowed.



\index{Indexing}
\section{The index}

The \labmac\ package includes the ability to make a sorted, formatted index
at the end of the document.  The index is processed entirely automatically.
The system uses the temporary files, |index.tex| and |index2.tex|.

\vindex{\index}
\cmd<||\index{||word||}||>
Enter a <word> into the index.  If the word contains control sequences,
you should use ||\indexas|| instead.  The following characters do not
participate in the alphabetical sort:
\example
  \\  |  <  >  .  $  ~  "  \]
\done
(where \] is a blank space).  The argument must contain balanced braces.

\vindex{\indexas}
\cmd<||\indexas{||text||}{||word||}||>
Enter the <text> into the index, alphabetized as if it were <word>.
The <word> is subject to the constraints shown above, but nearly anything
that fits on a line may go into <text>, with the peculiar exception that
|~|, the unbreakable space, is not allowed.  Both arguments must contain
balanced braces.

\vindex{\vindex}
\cmd<||\vindex{||word||}||>
Essentially, this enters |\|\||<word>|\|\|| into the index.

\vindex{\doindex}
\cmd<||\doindex|| num>
Begin a new page and print the index.  Ordinarily, this is the last
command before the final ||\bye||.  The <num> must one of the following
numbers:
\list{0:} \indented
\item{0:}
Suppress the index entirely.  The file is created, but not used.
\item{1:}
Print the index in unsorted order.  This is good for rough drafts.
\item{2:}
Sort and print the index.  This uses a simple file-based sort, so it can
handle an arbitrarily long index, but it will be arbitrarily slow ($<1$
hour for a one-page index).  It's best to leave this until the final copy
is printed.
\done  % with list



\section{Environments}

\vindex{\done}
An ``environment'' begins with one of the commands in this section, and
ends with ||\done||.  The text in between is called the <body>, and is
typically set aside from the normal text by a bit of blank space, and
sometimes indentation.  In general, environments may be nested inside
one another in any way.

\vindex{\twocolumns}
\cmd<||\twocolumns||>
The body is set in two balanced columns.  This is just an interface to the
HP\TeX\ column facility.

\vindex{\threecolumns}
\cmd<||\threecolumns||>
The body is set in three balanced columns.

\vindex{\display}
\cmd<||\display||>
The body is indented a small amount.  Line breaks and multiple spaces are
preserved.  The rest of the line after ||\display|| may contain options
as follows:
\list{||\linenumbers||}
\item{||\linenumbers||}
\vindex{\linenumbers}
\vindex{\nolinenumber}
Small line numbers, counting from one, are set to the left of each line.
The command ||\nolinenumber||, which may be used anywhere in the display,
suppresses the number on the following line (but that line is still
counted.)
\item{||\packed||}
\vindex{\packed}
Causes blank lines to produce a little less vertical space than normal.
\done  % with list
In a line of the form,
\vindex{\nodisplay}
\display \it
||\nodisplay{||stuff||}||
\done
the argument <stuff> is read according to the normal interpretation of
spaces and line breaks.

You can also put regular \TeX\ commands in the header line.  For example,
\display
||\display \it||
   \missinglines
||\done||
\done
sets the body of the display in italics.

\vindex{\parindent}
Displays interact with paragraphs in the same way as math displays: the
display is part of the preceding and following paragraphs only if there are
no intervening blank lines.  This affects whether extra inter-paragraph
space is added before and after the display.  It also affects whether
the first line following the display is indented (except that the default
||\parindent|| for \labmac\ is zero).


\vindex{\example}
\cmd<||\example||>
This produces a verbatim display.  The ||\tt|| font is used, and 
special characters are un-specialized just as in |\| \||-style verbatim
mode.  Note that |\\| stays the same as always, but |{}| become text
characters, so only commands without arguments may be used.


\vindex{\fvexample}
\cmd<||\fvexample||>
This produces a full-verbatim display, in which |\\| is also a text
character (except in the ||\done|| at the end).


\vindex{\list}
\vindex{\item}
\cmd<||\list{||prototype-text||}||>
This produces an itemized list.  Each entry in the list appears on the
lefthand side of the page, with text in paragraph form on the right.
The left column is as wide as the <prototype-text>.  A simple example
list would be:
\display
||\list{1.}||
||\item{1.}||
||This is the first item of the list.||
||\item{2.}||
||This is the second item of the list.||
||\done||
\done
which produces a list like the following:
\list{1.}
\item{1.}
This is the first item of the list.
\item{2.}
This is the second item of the list.
\done
The text in an ||\item|| command is unrestricted and will wrap onto
several lines if it is too long to fit in the left column.  (But these
lines will never be broken across pages.)  The text following the
argument of ||\item|| may include several paragraphs, and may also
include displays, sublists, etc.  Verbatim and other mode switches
may appear in the arguments to ||\item|| and ||\list||.

To set the width of the left column explicitly, use an ||\hskip|| as
the <prototype-text>.

The following options may appear after the argument of ||\list||:
\list{||\preamble{||<text>||}|| }
\item{||\preamble{||<text>||}||}
\vindex{\preamble}
The <text> is prepended to each item.  Two simple applications for
preambles would be to make, say, a convenient bulleted list by putting the
bullet in the preamble and using ||\item{}|| for each item, and to
cause each item to be italic with a preamble of ||\it||.
The special command, ||\verbatim||, may be used in preambles to put
every item in verbatim mode (as if it were surrounded by |\| \||).
The ||\verbatim|| command leaves |{ }| as grouping, not textual, characters.
Remember that the <prototype-text> is not affected by the preamble, so
you must usually duplicate the preamble's effect there.
\vindex{\verbatim}
\item{||\indented||}
\vindex{\indented}
The list is indented by a small amount.  The items will no longer be flush
against the left margin.
\item{||\packed||}
\vindex{\packed}
The items are not separated by extra space.  Good for lists in which each
item takes up only one line.
\done  % with list
\vindex{\itemomit}
There is another command, ||\itemomit{||<text>||}||, which omits the
preamble and uses just <text> as the item tag.


\vindex{\figure}
\cmd<||\figure{||caption-text||}||>
This command makes a floating figure.  The body may include any amount
of text.  The caption will be centered, and should normally include a
figure number.  The figure will be placed in-line if possible, otherwise
it will be moved to the next page.


\vindex{\figpic}
\vindex{\pspic}
\vindex{\oldlabels}
\vindex{\newlabels}
\cmd<||\figpic{||width height filepath||}{||caption-text||}||>
This command makes a figure consisting of a <.PostScript.> picture.
It uses the standard ||\pspic|| command, which takes an argument similar
to the first of ||\figpic||'s, and which creates an hbox containing the
picture.  The <filepath> must be a complete path to the file.  If the
``|.lbl|'' feature was used, labels are unrestricted but rotation of
labels is not supported.  The ||\oldlabels|| command reverts to the
old label system, in which labels are restricted (can not contain
arbitrary verbatim text) but rotation is allowed.  ||\newlabels||
returns to the new conventions.


\vindex{\imported}
\cmd<||\imported{||declaration||}||>
This command is used to introduce procedures, functions, types, etc.
The <declaration> is set in italics, and typically includes verbatim-mode
text as well.  The body is indented.  For example,
\display
||\imported{|procedure foo(|bar|,| spam|);|}||
||This is the procedure |foo|.  It examines <bar> and <spam>, and||
||verifies that they are meaningless words.||
||\done||
\done
prints as
\imported{|procedure foo(|bar|,| spam|);|}
This is the procedure |foo|.  It examines <bar> and <spam>, and 
verifies that they are meaningless words.
\done


\vindex{\exercise}
\vindex{\doexercise}
\vindex{\exerciseno}
\vindex{\lastexercise}
\cmd<||\exercise||>
This makes a numbered exercise.  Numbering is done automatically.  There
is also ||\doexercise{||<text>||}||, in which the <text> is used instead
of ``Exercise $n$'' in the result.  Also, ||\exerciseno{||<text>||}|| sets
<text> in the font used for exercise numbers, and ||\lastexercise|| sets
the number of the last numbered exercise.






\doindex2


\bye