  This file documents the Eplain macros.

  Copyright (C) 1989, 90, 91, 92, 93, 94 Karl Berry.  Steven Smith
wrote the documentation for the commutative diagram macros.  (He also
wrote the macros.)

  Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

  Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided also that the
section entitled "GNU General Public License" is included exactly as in
the original, and provided that the entire resulting derived work is
distributed under the terms of a permission notice identical to this
one.

  Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that the section entitled "GNU General Public License"
may be included in a translation approved by the author instead of in
the original English.

Eplain
******

  The Eplain macros provide functionality that is intended to be useful
regardless of how your document is actually formatted.  This manual is
for Eplain version 2.6.

Introduction
************

  The "Eplain" macro package expands on and extends the definitions in
plain TeX.  This manual describes the definitions that you, as either
an author or a macro writer, might like to use.  It doesn't discuss the
implementation; see comments in the source code (`xeplain.tex') for
that.

  Eplain is not intended to provide "generic typesetting capabilities,
as do LaTeX (written by Leslie Lamport) or Texinfo (written by Richard
Stallman and others).  Instead, it provides definitions that are
intended to be useful regardless of the high-level commands that you
use when you actually prepare your manuscript.

  For example, Eplain does not have a command `\section', which would
format section headings in an "appropriate" way, such as LaTeX's
`\section'.  The philosophy of Eplain is that some people will always
need or want to go beyond the macro designer's idea of "appropriate".
Such canned macros are fine--as long as you are willing to accept the
resulting output.  If you don't like the results, or if you are trying
to match a different format, you are out of luck.

  On the other hand, almost everyone would like capabilities such as
cross-referencing by labels, so that you don't have to put actual page
numbers in the manuscript.  The author of Eplain is not aware of any
generally available macro packages that (1) do not force their
typographic style on an author, and yet (2) provide such capabilities.

  Besides such generic macros as cross-referencing, Eplain contains
another set of definitions: ones that change the conventions of plain
TeX's output.  For example, math displays in TeX are, by default,
centered.  If you want your displays to come out left-justified, you
have to plow through `The TeXbook' to find some way to do it, and then
adapt the code to your own needs.  Eplain tries to take care of the
messy details of such things, while still leaving the detailed
appearance of the output up to you.

  Finally, numerous definitions turned out to be useful as Eplain was
developed.  They are also documented in this manual, on the chance that
people writing other macros will be able to use them.

  You can send bug reports or suggestions to tex-eplain@cs.umb.edu.  The
current version number of Eplain is defined as the macro `\fmtversion'
at the end of the source file `eplain.tex'.  When corresponding, please
refer to it.

  To get on this mailing list yourself, email
`tex-eplain-request@cs.umb.edu' with a message whose body contains a
line
     subscribe YOU@YOUR.PREFERRED.ADDRESS

Installation
************

  The simplest way to install Eplain is simply to install the file
`eplain.tex' in a directory where TeX will find it.  What that
directory is obviously depends on your operating system and TeX
installation.  I personally install `eplain.tex' in a directory
`/usr/local/lib/texmf/tex/plain'.

  If you want, you can also create a format (`.fmt') file for Eplain,
which will eliminate the time spent reading the macro source file with
`\input'.  You do this by issuing a sequence of Unix commands something
like this:

     prompt$ touch eplain.aux
     prompt$ initex
     This is TeX, ...
     **&plain eplain
     (eplain.tex)
     *\dump
     ... MESSAGES ...

You must make sure that `eplain.aux' exists *before* you run `initex';
otherwise, warning messages about undefined labels will never be issued.

  You then have to install the resulting `eplain.fmt' in some system
directory or set an environment variable to tell TeX how to find it.  I
install the format files in `/usr/local/lib/texmf/ini'; the environment
variable for the Web2C port of TeX to Unix is `TEXFORMATS'.

  Some implementations of TeX (including Web2C) use the name by which
TeX is invoked to determine what format to read.  For them, you should
make a link to the `virtex' program named `etex', and then install the
format file with the name `etex.fmt'.  This lets users invoke TeX as
`etex' and get the format file read automatically, without having to
say `&eplain'.

  For convenience, the file `etex.tex' in the distribution directory
does `\input eplain' and then `\dump', so that if you replace `eplain'
with `etex' in the example above, the format file will end up with the
right name.

  The `install' target in the `Makefile' does all this properly for
Unix systems and Web2C.  You may have to change the pathnames.

  Under emtex, `eaj@acpub.duke.edu' says that

     tex386 -i ^&plain eplain \dump

produces a format file.

Invoking Eplain
***************

  The simplest way to use Eplain is simply to put:

     \input eplain

at the beginning of your input file.  The macro file is small enough
that reading it does not take an unbearably long time--at least on
contemporary machines.

  In addition, if a format (`.fmt') file has been created for Eplain
(see the previous section), you can eliminate the time spent reading
the macro source file.  You do this by responding `&eplain' or `&etex'
to TeX's `**' prompt.  For example:

     initex
     This is TeX, ...
     **&eplain myfile

  Depending on the implementation of TeX which you are using, you might
also be able to invoke TeX as `etex' and have the format file
automatically read.

  If you write something which you will be distributing to others, you
won't know if the Eplain format will be loaded already.  If it is, then
doing `\input eplain' will waste time; if it isn't, then you must load
it.  To solve this, Eplain defines the control sequence `\eplain' to be
the letter `t' (a convention borrowed from Lisp; it doesn't actually
matter what the definition is, only that the definition exists).
Therefore, you can do the following:
     \ifx\eplain\undefined \input eplain \fi
   where `\undefined' must never acquire a definition.

Eplain consists of several source files:
`xeplain.tex'
     most of the macros;

`arrow.tex'
     commutative diagram macros, see Arrow theoretic diagrams.
     (written by Steven Smith);

`btxmac.tex'
     bibliography-related macros, see Citations.;

`texnames.sty'
     abbreviations for various TeX-related names, see Logos.
     (edited by Nelson Beebe).

The file `eplain.tex' is all of these files merged together, with
comments removed.

  All of these files except `xeplain.tex' can be input individually, if
all you want are the definitions in that file.

  Also, since the bibliography macros are fairly extensive, you might
not want to load them, to conserve TeX's memory.  Therefore, if the
control sequence `\nobibtex' is defined, then the bibliography
definitions are skipped.  You must set `\nobibtex' before `eplain.tex'
is read, naturally.  For example, you could start your input file like
this:

     \let\nobibtex = t
     \input eplain

  By default, `\nobibtex' is undefined, and so the bibliography
definitions *are* made.

  Likewise, define `\noarrow' if you don't want to include the
commutative diagram macros from `arrow.tex', perhaps because you
already have conflicting ones.

  If you don't want to read or write an `aux' file at all, for any kind
of cross-referencing, define `\noauxfile' before reading `eplain.tex'.
This also turns off all warnings about undefined labels.

  Eplain conflicts with AMSTeX (more precisely, with `amsppt.sty') The
macros `\cite' and `\ref' are defined by both.

  If you want to use AMSTeX's `\cite', the solution is to define
`\nobibtex' before reading Eplain, as described above.

  If you have `amsppt.sty' loaded and use `\ref', Eplain writes a
warning on your terminal. If you want to use the AMSTeX `\ref', do
`\let\ref = \amsref' after reading Eplain.  To avoid the warning, do
`\let\ref = \eplainref' after reading Eplain and before using `\ref'.

User definitions
****************

  This chapter describes definitions that are meant to be used directly
in a document.  When appropriate, ways to change the default formatting
are described in subsections.

Diagnostics
===========

  Plain TeX provides the `\tracingall' command, to turn on the maximum
amount of tracing possible in TeX.  The (usually voluminous) output
from `\tracingall' goes both on the terminal and into the transcript
file.  It is sometimes easier to have the output go only to the
transcript file, so you can peruse it at your leisure and not obscure
other output to the terminal.  So, Eplain provides the command
`\loggingall'.  (For some reason, this command is available in
Metafont, but not in TeX.)

  It is also sometimes useful to see the complete contents of boxes.
`\tracingboxes' does this.  (It doesn't affect whether or not the
contents are shown on the terminal.)

  You can turn off all tracing with `\tracingoff'.

  You can also turn logging on and off globally, so you don't have to
worry about whether or not you're inside a group at the time of command.
These variants are named `\gloggingall' and `\gtracingall'.

  Finally, if you write your own help messages (see `\newhelp' in `The
TeXbook'), you want a convenient way to break lines in them.  This is
what TeX's `\newlinechar' parameter is for; however, plain TeX doesn't
set `\newlinechar'.  Therefore, Eplain defines it to be the character
`^^J'.

  For example, one of Eplain's own error messages is defined as follows:
     \newhelp\envhelp{Perhaps you forgot to end the previous^^J%
        environment? I'm finishing off the current group,^^J%
        hoping that will fix it.}%

Rules
=====

  The default dimensions of rules are defined in chapter 21 of the `The
TeXbook'.  To sum up what is given there, the "thickness" of rules is
0.4pt by default.  Eplain defines three parameters that let you change
this dimension: `\hruledefaultheight', `\hruledefaultdepth', and
`\vruledefaultwidth'.  By default, they are defined as `The TeXbook'
describes.

  But it would be wrong to redefine `\hrule' and `\vrule'.  For one
thing, some macros in plain TeX depend on the default dimensions being
used; for another, rules are used quite heavily, and the performance
impact of making it a macro can be noticeable.  Therefore, to take
advantage of the default rule parameters, you must use `\ehrule' and
`\evrule'.

Citations
=========

  Bibliographies are part of almost every technical document.  To handle
them easily, you need two things: a program to do the tedious
formatting, and a way to cite references by labels, rather than by
numbers.  The BibTeX program, written by Oren Patashnik, takes care of
the first item; the citation commands in LaTeX, written to be used with
BibTeX, take care of the second.  Therefore, Eplain adopts the use of
BibTeX, and virtually the same interface as LaTeX.

  The general idea is that you put citation commands in the text of your
document, and commands saying where the bibliography data is.  When you
run TeX, these commands produce output on the file with the same root
name as your document (by default) and the extension `.aux'.  BibTeX
reads this file.  You should put the bibliography data in a file or
files with the extension `.bib'. BibTeX writes out a file with the same
root name as your document and extension `.bbl'.  Eplain reads this file
the next time you run your document through TeX.  (It takes multiple
passes to get everything straight, because usually after seeing your
bibliography typeset, you want to make changes in the `.bib' file,
which means you have to run BibTeX again, which means you have to run
TeX again...)  An annotated example of the whole process is given below.

  If your document has more than one bibliography--for example, if it
is a collection of papers--you can tell Eplain to use a different root
name for the `.bbl' file by defining the control sequence
`\bblfilebasename'.  The default definition is simply `\jobname'.

  See the document `BibTeXing' (whose text is in the file `btxdoc.tex',
which should be in the Eplain distribution you got) for information on
how to write your .bib files.  Both the BibTeX and the Eplain
distributions contain several examples, also.

  The `\cite' command produces a citation in the text of your document.
The exact printed form the citation will take is under your control;
see Formatting citations..  `\cite' takes one required argument, a
comma-separated list of cross-reference labels (see
Cross-references., for exactly what characters are allowed in such
labels).  Warning: spaces in this list are taken as part of the
following label name, which is probably not what you expect.  The
`\cite' command also produces a command in the .aux file that tells
BibTeX to retrieve the given reference(s) from the .bib file.  `\cite'
also takes one optional argument, which you specify within square
brackets, as in LaTeX.  This text is simply typeset after the
citations.  (See the example below.)

  Another command, `\nocite', puts the given reference(s) into the
bibliography, but produces nothing in the text.

  The `\bibliography' command is next.  It serves two purposes:
producing the typeset bibliography, and telling BibTeX the root names
of the .bib files.  Therefore, the argument to `\bibliography' is a
comma separated list of the .bib files (without the `.bib').  Again,
spaces in this list are significant.

  You tell BibTeX the particular style in which you want your
bibliography typeset with one more command: `\bibliographystyle'.  The
argument to this is a single filename STYLE, which tells BibTeX to look
for a file STYLE.bst.  See the document `Designing BibTeX styles'
(whose text is in the `btxhak.tex') for information on how to write
your own styles.

  Eplain automatically reads the citations from the .aux file when your
job starts.

  If you don't want to see the messages about undefined citations, you
can say `\xrefwarningfalse' before making any citations.  Eplain
automatically does this if the .aux file does not exist.  You can
restore the default by saying `\xrefwarningtrue'.

  Here is a TeX input file that illustrates the various commands.

     \input eplain                    % Reads the .aux file.
     Two citations to Knuthian works:
       \cite[note]{surreal,concrete-math}.
     \beginsection{References.}\par   % Title for the bibliography.
     \bibliography{knuth}             % Use knuth.bib for the labels.
     \bibliographystyle{plain}        % Number the references.
     \end                             % End of the document.

  If we suppose that this file was named `citex.tex' and that the
bibliography data is in `knuth.bib' (as the `\bibliography' command
says), the following commands do what's required.  (`$ ' represents the
shell prompt.)

     $ tex citex       (produces undefined citation messages)
     $ bibtex citex    (read knuth.bib and citex.aux, write citex.bbl)
     $ tex citex       (read citex.bbl, still have undefined citations)
     $ tex citex       (one more time, to resolve the references)

  The output looks something like (because we used the plain
bibliography style):

     Two citations to Knuthian works: [2,1 note].

     References

     [1] Ronald L. Graham, Donald E. Knuth, and Oren Patashnik.
     Concrete Mathematics. Addison-Wesley, Reading, Massachusetts, 1989.

     [2] Donald E. Knuth. Surreal Numbers. Addison-Wesley, Reading,
     Massachusetts, 1974.

  See the BibTeX documentation for information on how to write the
bibliography databases, and the bibliography styles that are available.
(If you want your references printed with names, as in [Knu74], instead
of numbered, the bibliography style is `alpha'.)

Formatting citations
--------------------

  You may wish to change Eplain's formatting of citations; i.e., the
result of your `\cite' commands.  By default, the citation labels are
printed one after another, separated by commas and enclosed in
brackets, using the main text font.  Some formats require other styles,
such as superscripted labels.  You can accomodate such formats by
redefining the following macros.

`\printcitestart'
`\printcitefinish'
     Eplain expands these macros at the begining and end of the list of
     citations for each `\cite' command.  By default, they produce a
     `[' and `]', respectively.

`\printbetweencitations'
     If a `\cite' command has multiple citations, as in
     `\cite{acp,texbook}', Eplain expands this macro in between each
     pair of citations.  By default, it produces a comma followed by a
     space.

`\printcitenote'
     This macro takes one argument, which is the optional note to the
     `\cite' command.  If the `\cite' command had no note, this macro
     isn't used.  Otherwise, it should print the note.  By default, the
     note is preceded with a comma and a space.

  Here is an example, showing you could produce citations as
superscripted labels, with the optional notes in parentheses.

     \def\printcitestart{\unskip $^\bgroup}
     \def\printbetweencitations{,}
     \def\printcitefinish{\egroup$}
     \def\printcitenote#1{\hbox{\sevenrm\space (#1)}}

Formatting bibliographies
-------------------------

  You may wish to change Eplain's formatting of the bibliography,
especially with respect to the fonts that are used.  Therefore, Eplain
provides the following control sequences:

`\biblabelwidth'
     This control sequence represents a `\dimen' register, and its value
     is the width of the widest label in the bibliography.  Although it
     is unlikely you will ever want to redefine it, you might want to
     use it if you redefine `\biblabelprint', below.

`\biblabelprint'
     This macro takes one argument, the label to print.  By default, the
     label is put in a box of width `\biblabelwidth', and is followed by
     an enspace.  When you want to change the spacing around the
     labels, this is the right macro to redefine.

`\biblabelcontents'
     This macro also takes one argument, the label to print.  By
     default, the label is printed using the font `\bblrm' (below), and
     enclosed in brackets.  When you want to change the appearance of
     the label, but not the spacing around it, this is the right macro
     to redefine.

`\bblrm'
     The default font used for printing the bibliography.

`\bblem'
     The font used for printing the titles and other "emphasized"
     material.

`\bblsc'
     In some styles, authors' names are printed in a caps-and-small-caps
     font.  In those cases, this font is used.

`\bblnewblock'
     This is invoked between each of the parts of a bibliography entry.
     The default is to leave some extra space between the parts; you
     could redefine it to start each part on a new line (for example).
     A part is simply a main element of the entry; for example, the
     author is a part.  (It was LaTeX that introduced the (misleading,
     as far as I am concerned) term `block' for this.)

`\biblabelextraspace'
     Bibliography entries are typeset with a hanging indentation of
     `\biblabelwidth' plus this.  The default is `.5em', where the em
     width is taken from the `\bblrm' font.  If you want to change
     this, you should do it inside `\bblhook'.

`\bblhook'
     This is expanded before reading the .bbl file.  By default, it
     does nothing.  You could, for example, define it to set the
     bibliography fonts, or produce the heading for the references.  Two
     spacing parameters must be changed inside `\bblhook': `\parskip',
     which produces extra space between the items; and
     `\biblabelextraspace', which is described above.  (By the way,
     `\hookappend' won't work with `\bblhook', despite the names. Just
     use `\def'.)

  If you are really desperate, you can also hand-edit the .bbl file
that BibTeX produces to do anything you wish.

Displays
========

  By default, TeX centers displayed material.  (Displayed material is
just whatever you put between `$$''s--it's not necessarily
mathematics.)  Many layouts would be better served if the displayed
material was left-justified.  Therefore, Eplain provides the command
`\leftdisplays', which indents displayed material by `\parindent' plus
`\leftskip', plus `\leftdisplayindent'.

  You can go back to centering displays with `\centereddisplays'.  (It
is usually poor typography to have both centered and left-justified
displays in a single publication, though.)

  `\leftdisplays' also changes the plain TeX commands that deal with
alignments inside math displays, `\displaylines', `\eqalignno', and
`\leqalignno', to produce left-justified text.  You can still override
this formatting by inserting `\hfill' glue, as explained in `The
TeXbook'.

Formatting displays
-------------------

  If you want some other kind of formatting, you can write a definition
of your own, analogous to `\leftdisplays'.  You need only make sure
that `\leftdisplaysetup' is called at the beginning of every display
(presumably by invoking it in TeX's `\everydisplay' parameter), and to
define `\generaldisplay'.

  `\leftdisplays' expands the old value of `\everydisplay' before
calling `\leftdisplaysetup', so that any changes you have made to it
won't be lost.  That old token list as available as the value of the
token register `\previouseverydisplay'.

Time of day
===========

  TeX provides the day, month, and year as numeric quantities (unless
your TeX implementation is woefully deficient).  Eplain provides some
control sequences to make them a little more friendly to humans.

  `\monthname' produces the name of the current month, abbreviated to
three letters.

  `\fullmonthname' produces the name of the current month,
unabbreviated (in English).

  `\timestring' produces the current time, as in `1:14 p.m.'

  `\timestamp' produces the current date and time, as in `23 Apr 64
1:14 p.m.'.  (Except the spacing is slightly different.)

  `\today' produces the current date, as in `23 April 1964'.

Lists
=====

  Many documents require lists of items, either numbered or simply
enumerated.  Plain TeX defines one macro to help with creating lists,
`\item', but that is insufficient in many cases.  Therefore, Eplain
provides two pairs of commands:

`\numberedlist ... \endnumberedlist'
`\orderedlist ... \endorderedlist'
     These commands (they are synonyms) produce a list with the items
     numbered sequentially, starting from one.  A nested `\numberedlist'
     labels the items with lowercase letters, starting with `a'.
     Another nested `\numberedlist' labels the items with roman
     numerals.  Yet more deeply nested numbered lists label items with
     `*'.

`\unorderedlist ... \endunorderedlist'
     This produces a list with the items labelled with small black boxes
     ("square bullets"). A nested `\unorderedlist' labels items with
     em-dashes.  Doubly (and deeper) nested unordered lists label items
     with `*'s.

  The two kinds of lists can be nested within each other, as well.

  In both kinds of lists, you begin an item with `\li'.  An item may
continue for several paragraphs.  Each item starts a paragraph.

  You can give `\li' an optional argument, a cross-reference label.
It's defined to be the "marker" for the current item.  This is useful
if the list items are numbered.  You can produce the value of the label
with `\xrefn'.  See Cross-references.

  You can also say `\listcompact' right after `\numberedlist' or
`\unorderedlist'.  The items in the list will then not have any extra
space between them (see Formatting lists.).  You might want to do
this if the items in this particular list are short.

  Here is an example:
     \numberedlist\listcompact
     \li The first item.
     \li The second item.

     The second paragraph of the second item.
     \endnumberedlist

Formatting lists
----------------

  Several registers define the spacing associated with lists.  It is
likely that their default values won't suit your particular layout.

`\abovelistskipamount, \belowlistskipamount'
     The vertical glue inserted before and after every list,
     respectively.

`\interitemskipamount'
     The vertical glue inserted before each item except the first.
     `\listcompact' resets this to zero, as mentioned above.

`\listleftindent, \listrightindent'
     `\listrightindent' is the amount of space by which the list is
     indented on the right; i.e., it is added to `\rightskip'.
     `\listleftindent' is the amount of space, *relative to*
     `\parindent', by which the list is indented on the left.  Why treat
     the two parameters differently?  Because (a) it is more useful to
     make the list indentation depend on the paragraph indentation;
     (b) footnotes aren't formatted right if `\parindent' is reset to
     zero.

  The three vertical glues are inserted by macros, and preceded by
penalties: `\abovelistskip' does `\vpenalty\abovelistpenalty' and then
`\vskip\abovelistskip'.  `\belowlistskip' and `\interitemskip' are
analogous.

  In addition, the macro `\listmarkerspace' is called to separate the
item label from the item text.  This is set to `\enspace' by default.

  If you want to change the labels on the items, you can redefine these
macros: `\numberedmarker' or `\unorderedmarker'.  The following
registers might be useful if you do:

`\numberedlistdepth, \unorderedlistdepth'
     These keep track of the depth of nesting of the two kinds of lists.

`\itemnumber, \itemletter'
     These keep track of the number of items that have been seen in the
     current numbered list.  They are both integer registers.  The
     difference is that `\itemnumber' starts at one, and `\itemletter'
     starts at 97, i.e., lowercase `a'.

  You can also redefine the control sequences that are used internally,
if you want to do something radically different:  `\beginlist' is
invoked to begin both kinds of lists; `\printitem' is invoked to print
the label (and space following the label) for each item; and `\endlist'
is invoked to end both kinds of lists.

Verbatim listing
================

  It is sometimes useful to include a file verbatim in your document;
for example, part of a computer program.  The `\listing' command is
given one argument, a filename, and produces the contents of that file
in your document.  `\listing' expands `\listingfont' to set the current
font.  The default value of `\listingfont' is `\tt'.

  You can take arbitrary actions before reading the file by defining
the macro `\setuplistinghook'.  This is expanded just before the file
is input.

  If you want to have line numbers on the output, you can say
`\let\setuplistinghook = \linenumberedlisting'.  The line numbers are
stored in the count register `\lineno' while the file is being read.
You can redefine the macro `\printlistinglineno' to change how they are
printed.

  You can produce in-line verbatim text in your document with
`\verbatim'.  End the text with `|endverbatim'.  If you need a `|' in
the text, double it.  If the first character of the verbatim text is a
space, use `| '. (`| ' will work elsewhere in the argument, too, but
isn't necessary.)

  For example:

       \verbatim| ||\#%&!|endverbatim

produces ` |\#%&!'.

  Line breaks and spaces in the verbatim text are preserved.

  You can change the verbatim escape character from the default `|'
with `\verbatimescapechar CHAR'; for example, this changes it to `@'.

     \verbatimescapechar \@

The backslash is not necessary in some cases, but is in others,
depending on the catcode of the character.  The argument to
`\verbatimescapechar' is used as `\catcode `CHAR', so the exact rules
follow that for `\catcode'.

  Because `\verbatim' must change the category code of special
characters, calling inside a macro definition of your own does not work
properly.  For example:

     \def\mymacro{\verbatim &#%|endverbatim}% Doesn't work!

  To accomplish this, you must change the category codes yourself before
making the macro definition.  Perhaps `\uncatcodespecials' will help
you (see Category codes.).

Contents
========

  Producing a table of contents that is both useful and aesthetic is one
of the most difficult design problems in any work.  Naturally, Eplain
does not pretend to solve the design problem.  Collecting the raw data
for a table of contents, however, is much the same across documents.
Eplain uses an auxiliary file with extension `.toc' (and the same root
name as your document) to save the information.

  To write an entry for the table of contents, you say
`\writetocentry{PART}{TEXT}', where PART is the type of part this entry
is, e.g., `chapter', and TEXT is the text of the title.
`\writetocentry' puts an entry into the .toc file that looks like
`\tocPARTentry{TEXT}{PAGE NUMBER}'.  The TEXT is written unexpanded.

  A related command, `\writenumberedtocentry', takes one additional
argument, the first token of which is expanded at the point of the
`\writenumberedtocentry', but the rest of the argument is not expanded.
The usual application is when the parts of the document are numbered.
On the other hand, the one-level expansion allows you to use the
argument for other things as well (author's names in a proceedings,
say), and not have accents or other control sequences expanded.  The
downside is that if you *want* full expansion of the third argument,
you don't get it--you must expand it yourself, before you call
`\writenumberedtocentry'.

  For example:

     \writenumberedtocentry{chapter}{A $\sin$ wave}{\the\chapno}
     \writetocentry{section}{A section title}

Supposing `\the\chapno' expanded to `3' and that the `\write''s
occurred on pages eight and nine, respectively, the above writes the
following to the .toc file:

     \tocchapterentry{A $\sin$ wave}{3}{8}
     \tocsectionentry{A section title}{9}

  You read the .toc file with the command `\readtocfile'.  Naturally,
whatever `\toc... entry' commands that were written to the file must be
defined when `\readtocfile' is invoked.  Eplain has minimal definitions
for `\tocchapterentry', `\tocsectionentry', and `\tocsubsectionentry',
just to prevent undefined control sequence errors in common cases.
They aren't suitable for anything but preliminary proofs.

  After reading the .toc file, `\readtocfile' opens the file for
writing, thereby deleting the information from the previous run.  You
should therefore arrange that `\readtocfile' be called *before* the
first call to a `\writetoc...' macro.  On the other hand, if you don't
want to rewrite the .toc file, perhaps because you are only running TeX
on part of your manuscript, you can set `\rewritetocfilefalse'.

  By default, the `.toc' file has the root `\jobname'.  If your
document has more than one contents--for example, if it is a collection
of papers, some of which have their own contents--you can tell Eplain
to use a different root name by defining the control sequence
`\tocfilebasename'.

  In addition to the usual table of contents, you may want to have a
list of figures, list of tables, or other such contents-like list. You
can do this with `\definecontentsfile{ABBREV}'.  All of the above
commands are actually a special case that Eplain predefines with

     \definecontentsfile{toc}

The ABBREV is used both for the file extension and in the control
sequence names.

Cross-references
================

  It is often useful to refer the reader to other parts of your
document; but putting literal page, section, equation, or whatever
numbers in the text is certainly a bad thing.

  Eplain therefore provides commands for symbolic cross-references.  It
uses an auxiliary file with extension .aux (and the same root name as
your document) to keep track of the information.  Therefore, it takes
two passes to get the cross-references right--one to write them out,
and one to read them in.  Eplain automatically reads the .aux file at
the first reference; after reading it, Eplain reopens it for writing.

  You can control whether or not Eplain warns you about undefined
labels.  See Citations.

  Labels in Eplain's cross-reference commands can use characters of
category code eleven (letter), twelve (other), ten (space), three (math
shift), four (alignment tab), seven (superscript), or eight (subscript).
For example, `(a1 $&^_' is a valid label (assuming the category codes
of plain TeX), but `%#\{' has no valid characters.

  You can also do symbolic cross-references for bibliographic citations
and list items.  See Citations, and Lists.

Defining generic references
---------------------------

  Eplain provides the command `\definexref' for general
cross-references.  It takes three arguments: the name of the label (see
section above for valid label names), the value of the label (which can
be anything), and the "class" of the reference--whether it's a section,
or theorem, or what.  For example:

     \definexref{sec-intro}{3.1}{section}

Of course, the label value is usually generated by another macro using
TeX count registers or some such.

  `\definexref' doesn't actually define LABEL; instead, it writes out
the definition to the .aux file, where Eplain will read it on the next
TeX run.

  The CLASS argument is used by the `\ref' and `\refs' commands.  See
the next section.

Using generic references
------------------------

  To retrieve the value of the label defined via `\definexref' (see the
previous section), Eplain provides the following macros:

`\refn{LABEL}'
`\xrefn{LABEL}'
     `\refn' and `\xrefn' (they are synonyms) produce the bare
     definition of LABEL.  If LABEL isn't defined, issue a warning, and
     produce LABEL itself instead, in typewriter.  (The warning isn't
     given if `\xrefwarningfalse'.)

`\ref{LABEL}'
     Given the class C for LABEL (see the description of `\definexref'
     in the previous section), expand the control sequence `\C word'
     (if it's defined) followed by a tie.  Then call `\refn' on LABEL.
     (Example below.)

`\refs{LABEL}'
     Like `\ref', but append the letter `s' to the `\...word'.

  The purpose of the `\...word' macro is to produce the word `Section'
or `Figure' or whatever that usually precedes the actual reference
number.

  Here is an example:

     \def\sectionword{Section}
     \definexref{sec-intro}{3.1}{section}
     \definexref{sec-next}{3.2}{section}
     See \refs{sec-intro} and \refn{sec-next} ...

This produces `See Sections 3.1 and 3.2 ...'

Page references
===============

  Eplain provides two commands for handling references to page numbers,
one for definition and one for use.

`\xrdef{LABEL}'
     Define LABEL to be the current page number.  This produces no
     printed output, and ignores following spaces.

`\xref{LABEL}'
     Produce the text `p. PAGE-NUMBER', which is the usual form for
     cross-references.  The PAGE-NUMBER is actually LABEL's definition;
     if LABEL isn't defined, the text of the label itself is printed.

Equation references
-------------------

  Instead of referring to pages, it's most useful if equation labels
refer to equation numbers.  Therefore, Eplain reserves a `\count'
register, `\eqnumber', for the current equation number, and increments
it at each numbered equation.

  Here are the commands to define equation labels and then refer to
them:

`\eqdef{LABEL}'
     This defines LABEL to be the current value of `\eqnumber', and, if
     the current context is not inner, then produces a `\eqno' command.
     (The condition makes it possible to use `\eqdef' in an
     `\eqalignno' construction, for example.)  The text of the equation
     number is produced using `\eqprint'.  See Formatting equation references.

     If LABEL is empty, you still get an equation number (although
     naturally you can't reliably refer to it).  This is useful if you
     want to put numbers on all equations in your document, and you
     don't want to think up unique labels.

`\eqdefn{LABEL}'
     This is like `\eqdef', except it always omits the `\eqno' command.
     It can therefore be used in places where `\eqdef' can't; for
     example, in a non-displayed equation.  The text of the equation
     number is not produced, so you can also use it in the (admittedly
     unusual) circumstance when you want to define an equation label
     but not print that label.

`\eqref{LABEL}'
     This produces a formatted reference to LABEL.  If LABEL is
     undefined (perhaps because it is a forward reference), it just
     produces the text of the label itself.  Otherwise, it calls
     `\eqprint'.

`\eqrefn{LABEL}'
     This produces the cross-reference text for LABEL.  That is, it is
     like `\eqref', except it doesn't call `\eqprint'.

  Equation labels can contain the same characters that are valid in
general cross-references.

Formatting equation references
..............................

  Both defining an equation label and referring to it should usually
produce output.  This output is produced with the `\eqprint' macro,
which takes one argument, the equation number being defined or referred
to.  By default, this just produces `(NUMBER)', where NUMBER is the
equation number.  To produce the equation number in a different font,
or with different surrounding symbols, or whatever, you can redefine
`\eqprint'.  For example, the following definition would print all
equation numbers in italics.  (The extra braces define a group, to keep
the font change from affecting surrounding text.)

     \def\eqprint#1{{\it (#1)}}

  In addition to changing the formatting of equation numbers, you might
to add more structure to the equation number; for example, you might
want to include the chapter number, to get equation numbers like
`(1.2)'.  To achieve this, you redefine `\eqconstruct'.  For example:

     \def\eqconstruct#1{\the\chapternumber.#1}

(If you are keeping the chapter number in a count register named
`\chapternumber', naturally.)

  The reason for having both `\eqconstruct' and `\eqprint' may not be
immediately apparent.  The difference is that `\eqconstruct' affects
the text that cross-reference label is defined to be, while `\eqprint'
affects only what is typeset on the page.  The example just below might
help.

  Usually, you want equation labels to refer to equation numbers.  But
sometimes you might want a more complicated text.  For example, you
might have an equation `(1)', and then have a variation several pages
later which you want to refer to as `(1*)'.

  Therefore, Eplain allows you to give an optional argument (i.e.,
arbitrary text in square brackets) before the cross-reference label to
\eqdef.  Then, when you refer to the equation, that text is produced.
Here's how to get the example just mentioned:

     $$...\eqdef{a-eq}$$
     ...
     $$...\eqdef[\eqrefn{a-eq}*]{a-eq-var}$$
     In \eqref{a-eq-var}, we expand on \eqref{a-eq}, ...

  We use `\eqrefn' in the cross-reference text, not `\eqref', so that
`\eqprint' is called only once.

Subequation references
......................

  Eplain also provides for one level of substructure for equations.
That is, you might want to define a related group of equations with
numbers like `2.1' and `2.2', and then be able to refer to the group as
a whole: "... in the system of equations (2)...".

  The commands to do this are `\eqsubdef' and `\eqsubdefn'.  They take
one LABEL argument like their counterparts above, and generally behave
in the same way.  The difference is in how they construct the equation
number: instead of using just `\eqnumber', they also use another
counter, `\subeqnumber'.  This counter is advanced by one at every
`\eqsubdef' or `\eqsubdefn', and reset to zero at every `\eqdef' or
`\eqdefn'.

  You use `\eqref' to refer to subequations as well as main equations.

  To put the two together to construct the text that the label will
produce, they use a macro `\eqsubreftext'.  This macros takes two
arguments, the "main" equation number (which, because the equation
label can be defined as arbitrary text, as described in the previous
section, might be anything at all) and the "sub" equation number (which
is always just a number).  Eplain's default definition just puts a
period between them:
       \def\eqsubreftext#1#2{#1.#2}%

You can redefine `\eqsubreftext' to print however you like.  For
example, this definition makes the labels print as `2a', `2b', and so
on.
     \newcount\subref
     \def\eqsubreftext#1#2{%
       \subref = #2           % The space stops a <number>.
       \advance\subref by 96  % `a' is character code 97.
       #1\char\subref
     }

Sadly, we must define a new count register, `\subref', instead of using
the scratch count register `\count255', because `#1' might include
other macro calls which use `\count255'.