summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/eplain/base/userdef.texi
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/eplain/base/userdef.texi')
-rw-r--r--Master/texmf-dist/doc/eplain/base/userdef.texi2538
1 files changed, 2538 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/eplain/base/userdef.texi b/Master/texmf-dist/doc/eplain/base/userdef.texi
new file mode 100644
index 00000000000..dfc5fcc4497
--- /dev/null
+++ b/Master/texmf-dist/doc/eplain/base/userdef.texi
@@ -0,0 +1,2538 @@
+@c This is part of the Eplain manual. Public domain.
+
+@node User definitions
+@chapter 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.
+
+@menu
+* Diagnostics:: Tracing information.
+* Rules:: Changing the default rule dimensions.
+* Citations:: Using BibTeX and Eplain to make bibliographies.
+* Displays:: Changing the formatting of math displays.
+* Time of day:: Producing the time of day.
+* Lists:: Producing numbered and unordered lists.
+* Verbatim listing:: Producing text just as it appears.
+* Contents:: Making a table of contents.
+* Cross-references:: Symbolic references to equations, figures, etc.
+* Page references:: Symbolic references to page numbers.
+* Equation references:: Symbolic references to equation numbers.
+* Indexing:: Creating and typesetting indexes.
+* Justification:: Ragged left, ragged right, centered.
+* Tables:: Producing ordered tables.
+* Margins:: Changing the margins directly.
+* Multiple columns:: Getting output in two columns.
+* Footnotes:: Autonumbered footnotes; changing formatting.
+* Fractions:: A better way to produce fractions in text.
+* Paths:: Allowing line breaks in pathnames.
+* Logos:: Various logos.
+* Boxes:: Producing filled or open rectangles.
+* Checking for PDF output:: Checking for pdfTeX in PDF mode.
+* Loading LaTeX packages:: Support for LaTeX packages under plain TeX.
+@end menu
+
+
+@node Diagnostics
+@section Diagnostics
+
+@cindex diagnostics
+@cindex tracing
+Plain @TeX{} provides the @code{\tracingall} command, to turn on the
+maximum amount of tracing possible in @TeX{}. The (usually voluminous)
+output from @code{\tracingall} goes both on the terminal and into the
+transcript file.
+@findex tracingall
+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 @code{\loggingall}.
+@findex 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.
+@code{\tracingboxes} does this. (It doesn't affect whether or not the
+contents
+@findex tracingboxes
+are shown on the terminal.)
+
+You can turn off all tracing with @code{\tracingoff}.
+@findex 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 @code{\gloggingall}
+@findex gloggingall
+and @code{\gtracingall}.
+@findex gtracingall
+
+Finally, if you write your own help messages (see @code{\newhelp}
+@cindex help messages
+@cindex error messages
+in @cite{The @TeX{}book}), you want a convenient way to break lines in
+them. This is what @TeX{}'s @code{\newlinechar} parameter is for;
+@cindex newlinechar
+however, plain @TeX{} doesn't set @code{\newlinechar}. Therefore,
+Eplain defines it to be the character @code{^^J}.
+
+For example, one of Eplain's own error messages is defined as follows:
+@example
+\newhelp\envhelp@{Perhaps you forgot to end the previous^^J%
+ environment? I'm finishing off the current group,^^J%
+ hoping that will fix it.@}%
+@end example
+
+
+@node Rules
+@section Rules
+
+The default dimensions of rules are defined in chapter@tie{}21 of the
+@cite{The @TeX{}book}. To sum up what is given there, the ``thickness''
+of rules is
+@cindex rule thickness
+0.4pt by default. Eplain defines three parameters that let you change
+this dimension: @code{\hruledefaultheight}, @code{\hruledefaultdepth},
+@findex hruledefaultheight
+@findex hruledefaultdepth
+and @code{\vruledefaultwidth}. By default, they are defined as
+@findex vruledefaultwidth
+@cite{The @TeX{}book} describes.
+
+But it would be wrong to redefine @code{\hrule} and @code{\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
+@code{\ehrule}
+@findex ehrule
+and @code{\evrule}.
+@findex evrule
+
+
+@node Citations
+@section Citations
+
+@cindex citations
+@cindex bibliographies
+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 Bib@TeX{} program, written by Oren Patashnik, takes care
+@cindex Bib@TeX{}
+@cindex Patashnik, Oren
+of the first item; the citation commands in @LaTeX{}, written to be used
+@cindex @LaTeX{}
+with Bib@TeX{}, take care of the second. Therefore,
+Eplain adopts the use of Bib@TeX{}, 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 @file{.aux}.
+@pindex .aux @r{file}
+@findex jobname
+Bib@TeX{} reads this file. You should put the bibliography data in a
+file or files with the extension @file{.bib}. Bib@TeX{} writes out a
+file with the same root
+@pindex .bib @r{file}
+name as your document and extension @file{.bbl}. Eplain reads this file
+@pindex .bbl @r{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 @file{.bib}
+file, which means you have to run Bib@TeX{} again, which means you have
+to run @TeX{} again@dots{}) 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 @file{.bbl} file by defining the control sequence
+@code{\bblfilebasename}.
+@findex bblfilebasename
+The default definition is simply @code{\jobname}.
+
+See the document @cite{Bib@TeX{}ing} (whose text is in the file
+@file{btxdoc.tex}, which should be in the Eplain distribution you got)
+for information on how to write your @t{.bib} files. Both the
+Bib@TeX{} and the Eplain distributions contain several examples, also.
+
+The @code{\cite}
+@findex cite
+command produces a citation in the text of your document. The exact
+printed form the citation will take is under your control;
+@pxref{Formatting citations}. @code{\cite} takes one
+required argument, a comma-separated list of cross-reference labels
+(@pxref{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.
+@cindex citations, undefined
+The @code{\cite} command also produces a command
+in the @t{.aux} file that tells Bib@TeX{} to retrieve the given reference(s)
+from the @t{.bib} file. @code{\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.)
+
+Eplain can create hypertext links for citations pointing to the relevant
+bibliography entries; @pxref{Citation hyperlinks}.
+
+Another command, @code{\nocite},
+@findex nocite
+puts the given reference(s) into the bibliography, but produces nothing
+in the text.
+
+The @code{\bibliography}
+@findex bibliography
+command is next. It serves two purposes: producing the typeset
+bibliography, and telling Bib@TeX{} the root names of the @t{.bib}
+files. Therefore, the argument to @code{\bibliography} is a comma
+separated list of the @t{.bib} files (without the @samp{.bib}). Again,
+spaces in this list are significant.
+
+You tell Bib@TeX{} the particular style in which you want your
+bibliography typeset with one more command:
+@code{\bibliographystyle}.
+@findex bibliographystyle
+The argument to this is a single filename @var{style}, which tells
+Bib@TeX{} to look for a file @var{style}@t{.bst}.
+@pindex .bst @r{files}
+See the document @cite{Designing Bib@TeX{} styles} (whose text is in the
+@file{btxhak.tex}) for information on how to write your own styles.
+
+Eplain automatically reads the citations from the @t{.aux} file when
+your job starts.
+
+If you don't want to see the messages about undefined citations, you
+can say @code{\xrefwarningfalse} before making any citations.
+@findex xrefwarningfalse
+Eplain automatically does this if the @t{.aux} file does not exist.
+You can restore the default by saying @code{\xrefwarningtrue}.
+
+Here is a @TeX{} input file that illustrates the various commands.
+
+@example
+\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.
+@end example
+@cindex Knuth, Donald Ervin
+@cindex Graham, Ronald L.
+@cindex numbered references
+@cindex references, numbered
+
+If we suppose that this file was named @file{citex.tex} and that the
+bibliography data is in @file{knuth.bib} (as the @code{\bibliography}
+command says), the following commands do what's required. (@samp{$ }
+represents the shell prompt.)
+
+@example
+$ 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)
+@end example
+
+@pindex texi2dvi
+@noindent (The @command{texi2dvi} program can help you automate this
+process, @pxref{Invoking Eplain}.)
+
+The output looks something like (because we used the @t{plain}
+bibliography style):
+
+@quotation
+Two citations to Knuthian works: [2,1 note].
+
+@b{References}
+@tex
+@frenchspacing
+@end tex
+
+[1] Ronald L. Graham, Donald E. Knuth, and Oren Patashnik. @i{Concrete
+Mathematics}. Addison-Wesley, Reading, Massachusetts, 1989.
+
+[2] Donald E. Knuth. @i{Surreal Numbers}. Addison-Wesley, Reading,
+Massachusetts, 1974.
+@end quotation
+
+See the Bib@TeX{} 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 @code{alpha}.)
+@cindex alphanumeric references
+@cindex references, alphanumeric
+
+@menu
+* Formatting citations:: Changing the way citations are printed.
+* Formatting bibliographies:: Changing the way bibliographies are printed.
+@end menu
+
+
+@node Formatting citations
+@subsection Formatting citations
+
+@cindex citations, formatting
+
+You may wish to change Eplain's formatting of citations; i.e., the
+result of your @code{\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.
+
+@table @code
+@itemx \printcitestart
+@item \printcitefinish
+@findex printcitestart
+@findex printcitefinish
+Eplain expands these macros at the begining and end of the list of
+citations for each @code{\cite} command. By default, they produce a
+@samp{[} and @samp{]}, respectively.
+
+@item \printbetweencitations
+@findex printbetweencitations
+If a @code{\cite} command has multiple citations, as in
+@code{\cite@{acp,texbook@}}, Eplain expands this macro in between each
+pair of citations. By default, it produces a comma followed by a space.
+
+@item \printcitenote
+@findex printcitenote
+This macro takes one argument, which is the optional note to the
+@code{\cite} command. If the @code{\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.
+@end table
+
+
+Here is an example, showing you could produce citations as
+superscripted labels, with the optional notes in parentheses.
+
+@example
+\def\printcitestart@{\unskip $^\bgroup@}
+\def\printbetweencitations@{,@}
+\def\printcitefinish@{\egroup$@}
+\def\printcitenote#1@{\hbox@{\sevenrm\space (#1)@}@}
+@end example
+
+
+@node Formatting bibliographies
+@subsection Formatting bibliographies
+
+@cindex bibliography, formatting the
+
+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:
+
+@table @code
+
+@item \biblabelwidth
+@findex biblabelwidth
+This control sequence represents a @code{\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 @code{\biblabelprint}, below.
+
+@item \biblabelprint
+@findex biblabelprint
+This macro takes one argument, the label to print. By default, the
+label is put in a box of width @code{\biblabelwidth}, and is followed by
+an enspace. When you want to change the spacing around the labels, this
+is the right macro to redefine.
+
+@item \biblabelcontents
+@findex biblabelcontents
+This macro also takes one argument, the label to print. By default, the
+label is printed using the font @code{\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.
+
+@item \bblrm
+@findex bblrm
+@cindex bibliography fonts
+The default font used for printing the bibliography.
+
+@item \bblem
+@findex bblem
+The font used for printing the titles and other ``emphasized'' material.
+
+@item \bblsc
+@findex bblsc
+In some styles, authors' names are printed in a caps-and-small-caps
+font. In those cases, this font is used.
+
+@item \bblnewblock
+@findex 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.)
+
+@item \biblabelextraspace
+@findex biblabelextraspace
+Bibliography entries are typeset with a hanging indentation of
+@code{\biblabelwidth} plus this. The default is @code{.5em}, where the
+em width is taken from the @code{\bblrm} font. If you want to change
+this, you should do it inside @code{\bblhook}.
+
+@item \bblhook
+@findex bblhook
+@cindex bibliography items, extra space between
+This is expanded before reading the @t{.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 @code{\bblhook}:
+@code{\parskip}, which produces extra space between the items; and
+@code{\biblabelextraspace}, which is described above.
+(By the way, @code{\hookappend} won't work with @code{\bblhook}, despite
+the names. Just use @code{\def}.)
+
+@end table
+
+If you are really desperate, you can also hand-edit the @t{.bbl} file
+that Bib@TeX{} produces to do anything you wish.
+
+
+@node Displays
+@section Displays
+
+@cindex displays, left-justifying
+@cindex mathematics displays, formatting
+@cindex left-justification of displays
+
+By default, @TeX{} centers displayed material. (Displayed material is
+just whatever you put between @code{$$}'s---it's not necessarily
+mathematics.) Many layouts would be better served if the displayed
+material was left-justified. Therefore, Eplain provides the command
+@code{\leftdisplays},
+@findex leftdisplays
+which indents displayed material by @code{\parindent} plus
+@code{\leftskip}, plus @code{\leftdisplayindent}.
+@findex leftdisplayindent
+
+You can go back to centering displays with @code{\centereddisplays}.
+@findex centereddisplays
+(It is usually poor typography to have both centered and left-justified
+displays in a single publication, though.)
+
+@code{\leftdisplays} also changes the plain @TeX{} commands that deal
+with alignments inside math displays,
+@code{\displaylines},
+@findex displaylines
+@code{\eqalignno},
+@findex eqalignno
+and @code{\leqalignno},
+@findex leqalignno
+to produce left-justified text. You can still override this formatting
+by inserting @code{\hfill} glue, as explained in @cite{The @TeX{}book}.
+
+@menu
+* Formatting displays:: General formatting of displays.
+@end menu
+
+
+@node Formatting displays
+@subsection Formatting displays
+
+If you want some other kind of formatting, you can write a definition
+of your own, analogous to @code{\leftdisplays}. You need only make sure
+that @code{\leftdisplaysetup}
+@findex leftdisplaysetup
+is called at the beginning of every display (presumably by invoking it
+in @TeX{}'s @code{\everydisplay} parameter), and to define
+@code{\generaldisplay}.
+@findex generaldisplay
+
+@code{\leftdisplays} expands the old value of @code{\everydisplay}
+before calling @code{\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 @code{\previouseverydisplay}.
+@findex previouseverydisplay
+
+
+@node Time of day
+@section Time of day
+
+@cindex time of day
+@cindex date
+
+@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.
+
+@code{\monthname}
+@findex monthname
+produces the name of the current month, abbreviated to three letters.
+
+@code{\fullmonthname}
+@findex fullmonthname
+produces the name of the current month, unabbreviated (in English).
+
+@code{\timestring}
+@findex timestring
+produces the current time, as in `1:14 p.m.'
+
+@code{\timestamp}
+@findex timestamp
+produces the current date and time, as in `23 Apr 64 1:14 p.m.'.
+(Except the spacing is slightly different.)
+
+@code{\today}
+@findex today
+produces the current date, as in `23 April 1964'.
+
+
+@node Lists
+@section Lists
+
+@cindex lists
+@cindex numbered lists
+@cindex ordered list
+@cindex unordered lists
+
+Many documents require lists of items, either numbered or simply
+enumerated. Plain @TeX{} defines one macro to help with creating lists,
+@code{\item}, but that is insufficient in many cases. Therefore,
+Eplain provides two pairs of commands:
+
+@table @code
+
+@itemx \numberedlist @dots{} \endnumberedlist
+@item \orderedlist @dots{} \endorderedlist
+@findex numberedlist
+@findex endnumberedlist
+@findex orderedlist
+@findex endorderedlist
+These commands (they are synonyms) produce a list with the items
+numbered sequentially, starting from one. A nested @code{\numberedlist}
+labels the items with lowercase letters, starting with `a'. Another
+nested @code{\numberedlist} labels the items with roman numerals. Yet
+more deeply nested numbered lists label items with @samp{*}.
+
+@item \unorderedlist @dots{} \endunorderedlist
+@findex unorderedlist
+@findex endunorderedlist
+This produces a list with the items labelled with small black boxes
+(``square bullets''). A nested @code{\unorderedlist} labels items with
+em-dashes. Doubly (and deeper) nested unordered lists label items with
+`*'s.
+
+@end table
+
+The two kinds of lists can be nested within each other, as well.
+
+In both kinds of lists, you begin an item with @code{\li}.
+@findex li
+An item may continue for several paragraphs. Each item starts a
+paragraph.
+
+You can give @code{\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 @code{\xrefn}. @xref{Cross-references}.
+
+Eplain can create hypertext links for the markers produced by
+@code{\xrefn} pointing to the relevant list item; @pxref{List
+hyperlinks}.
+
+You can also say @code{\listcompact}
+@findex listcompact
+right after @code{\numberedlist} or @code{\unorderedlist}. The items in
+the list will then not have any extra space between them
+(@pxref{Formatting lists}). You might want to do this if the items in
+this particular list are short.
+
+Here is an example:
+@example
+\numberedlist\listcompact
+\li The first item.
+\li The second item.
+
+The second paragraph of the second item.
+\endnumberedlist
+@end example
+
+@menu
+* Formatting lists:: Changing how the lists look.
+@end menu
+
+
+@node Formatting lists
+@subsection Formatting lists
+
+@cindex lists, formatting
+
+Several registers define the spacing associated with lists. It is
+likely that their default values won't suit your particular layout.
+
+@table @code
+@item \abovelistskipamount, \belowlistskipamount
+@findex abovelistskipamount
+@findex belowlistskipamount
+The vertical glue inserted before and after every list, respectively.
+
+@item \interitemskipamount
+@findex interitemskipamount
+The vertical glue inserted before each item except the first.
+@code{\listcompact} resets this to zero, as mentioned above.
+
+@item \listleftindent, \listrightindent
+@findex listleftindent
+@findex listrightindent
+@code{\listrightindent} is the amount of space by which the list is
+indented on the right; i.e., it is added to @code{\rightskip}.
+@code{\listleftindent} is the amount of space, @emph{relative to}
+@code{\parindent}, by which the list is indented on the left. Why treat
+the two parameters differently? Because (a)@tie{}it is more useful to
+make the list indentation depend on the paragraph indentation;
+(b)@tie{}footnotes aren't formatted right if @code{\parindent} is reset
+to zero.
+
+@end table
+
+The three vertical glues are inserted by macros, and preceded by
+penalties: @code{\abovelistskip}
+@findex abovelistskip
+does @code{\vpenalty\abovelistpenalty}
+@findex abovelistpenalty
+and then @code{\vskip\abovelistskip}. @code{\belowlistskip}
+@findex belowlistskip
+and @code{\interitemskip}
+@findex interitemskip
+are analogous.
+
+In addition, the macro @code{\listmarkerspace}
+@findex listmarkerspace
+is called to separate the item label from the item text. This is set to
+@code{\enspace} by default.
+
+If you want to change the labels on the items, you can redefine these
+macros:
+@code{\numberedmarker}
+@findex numberedmarker
+or @code{\unorderedmarker}.
+@findex unorderedmarker
+The following registers might be useful if you do:
+
+@table @code
+@item \numberedlistdepth, \unorderedlistdepth
+@findex numberedlistdepth
+@findex unorderedlistdepth
+These keep track of the depth of nesting of the two kinds of lists.
+
+@item \itemnumber, \itemletter
+@findex itemnumber
+@findex 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
+@code{\itemnumber} starts at one, and @code{\itemletter} starts at 97,
+i.e., lowercase `a'.
+
+@end table
+
+You can also redefine the control sequences that are used internally,
+if you want to do something radically different: @code{\beginlist}
+@findex beginlist
+is invoked to begin both kinds of lists; @code{\printitem}
+@findex printitem
+is invoked to print the label (and space following the label) for each
+item; and @code{\endlist}
+@findex endlist
+is invoked to end both kinds of
+lists.
+@cindex item labels, changing
+@cindex labels on items, changing
+
+
+@node Verbatim listing
+@section Verbatim listing
+
+@cindex verbatim listing
+@cindex listing files
+@cindex files, verbatim listing of
+It is sometimes useful to include a file verbatim in your document;
+for example, part of a computer program. The @code{\listing}
+@findex listing
+command is given one argument, a filename, and produces the contents of
+that file in your document. @code{\listing} expands @code{\listingfont}
+to set the current font. The default value of @code{\listingfont}
+@findex listingfont
+is @code{\tt}.
+
+You can take arbitrary actions before reading the file by defining the macro
+@code{\setuplistinghook}.
+@findex setuplistinghook
+This is expanded just before the file is input.
+
+If you want to have line numbers on the output, you can say
+@code{\let\setuplistinghook = \linenumberedlisting}.
+@findex linenumberedlisting
+The line numbers are stored in the count register @code{\lineno} while
+the file is being read. You can redefine the macro
+@code{\printlistinglineno} to change how they are printed.
+
+You can produce in-line verbatim text in your document with @code{\verbatim}.
+@findex verbatim
+End the text with @code{|endverbatim}. If you need a @samp{|} in the text,
+double it. If the first character of the verbatim text is a space, use
+@code{| }. (@code{| } will work elsewhere in the argument, too, but
+isn't necessary.)
+
+For example:
+
+@example
+\verbatim| ||\#%&!|endverbatim
+@end example
+
+@noindent produces @code{ |\#%&!}.
+
+Line breaks and spaces in the verbatim text are preserved.
+
+@findex verbatimescapechar
+@cindex escape character, changing verbatim
+You can change the verbatim escape character from the default @samp{|}
+with @code{\verbatimescapechar @var{char}}; for example, this changes
+it to @samp{@@}.
+
+@example
+\verbatimescapechar \@@
+@end example
+
+@noindent The backslash is not necessary in some cases, but is in
+others, depending on the catcode of the character. The argument to
+@code{\verbatimescapechar} is used as @code{\catcode `@var{char}}, so
+the exact rules follow that for @code{\catcode}.
+
+Because @code{\verbatim} must change the category code of special
+characters, calling inside a macro definition of your own does not work
+properly. For example:
+
+@example
+\def\mymacro@{\verbatim &#%|endverbatim@}% Doesn't work!
+@end example
+
+To accomplish this, you must change the category codes yourself before
+making the macro definition. Perhaps @code{\uncatcodespecials} will
+help you (@pxref{Category codes}).
+
+
+@node Contents
+@section Contents
+
+@cindex table of contents
+@cindex 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 @file{.toc}
+@pindex .toc @r{file}
+(and the same root name as your document) to save the information.
+
+To write an entry for the table of contents, you say
+@code{\writetocentry@{@var{part}@}@{@var{text}@}},
+@findex writetocentry
+where @var{part} is the type of part this entry is, e.g.,
+@samp{chapter}, and @var{text} is the text of the title.
+@code{\writetocentry} puts an entry into the @t{.toc} file that looks
+@findex toc@dots{}entry
+like @code{\toc@var{part}entry@{@var{text}@}@{@var{page number}@}}. The
+@var{text} is written unexpanded.
+
+@findex writenumberedtocentry
+A related command, @code{\writenumberedtocentry}, takes one additional
+argument, the first token of which is expanded at the point of the
+@code{\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 @emph{want} full expansion of the third
+argument, you don't get it---you must expand it yourself, before you
+call @code{\writenumberedtocentry}.
+
+For example:
+
+@example
+\writenumberedtocentry@{chapter@}@{A $\sin$ wave@}@{\the\chapno@}
+\writetocentry@{section@}@{A section title@}
+@end example
+
+@noindent Supposing @code{\the\chapno} expanded to @samp{3} and that the
+@code{\write}'s occurred on pages eight and nine, respectively, the
+above writes the following to the @t{.toc} file:
+
+@example
+\tocchapterentry@{A $\sin$ wave@}@{3@}@{8@}
+\tocsectionentry@{A section title@}@{9@}
+@end example
+
+@findex readtocfile
+You read the @t{.toc} file with the command @code{\readtocfile}.
+Naturally, whatever @code{\toc@dots{} entry} commands that were written
+to the file must be defined when @code{\readtocfile} is invoked. Eplain
+has minimal definitions for @code{\tocchapterentry},
+@code{\tocsectionentry}, and @code{\tocsubsectionentry}, just to prevent
+undefined control sequence errors in common cases. They aren't suitable
+for anything but preliminary proofs.
+
+Each of @code{\writetocentry} and @code{\writenumberedtocentry} opens
+the @t{.toc} file for writing, thereby deleting the information from the
+previous run. You should therefore arrange that @code{\readtocfile} be
+called @emph{before} the first call to a @code{\writetoc@dots{}} macro.
+@code{\readtocfile} does not itself delete the information
+from the @t{.toc} file, so that you can call it several times,
+e.g., to create both a short
+@cindex table of contents, short
+and normal table of contents. (To produce this in particular, define
+@code{\tocsectionentry} to produce nothing while you are reading
+@t{.toc} file for a short table of contents (@pxref{Macro arguments}).)
+
+On the other hand, if you don't want to rewrite the @t{.toc} file at
+all, perhaps because you are only running @TeX{} on part of your
+manuscript, you can set @code{\rewritetocfilefalse}.
+@findex ifrewritetocfile
+@findex rewritetocfile @r{(conditional)}
+
+By default, the @file{.toc} file has the root @code{\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
+@code{\tocfilebasename}.
+@findex tocfilebasename
+
+@cindex list of figures
+@cindex list of tables
+@findex definecontentsfile
+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 @code{\definecontentsfile@{@var{abbrev}@}}. All of the
+above commands are actually a special case that Eplain predefines with
+
+@example
+\definecontentsfile@{toc@}
+@end example
+
+@noindent The @var{abbrev} is used both for the file extension and in
+the control sequence names.
+
+
+
+@node Cross-references
+@section Cross-references
+
+@cindex 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 @t{.aux}
+@pindex .aux @r{file}
+(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 @t{.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. @xref{Citations}.
+
+@cindex labels, characters valid in
+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, @samp{(a1 $&^_} is a valid label (assuming the category
+codes of plain @TeX{}), but @samp{%#\@{} has no valid characters.
+
+You can also do symbolic cross-references for bibliographic citations
+and list items. @xref{Citations}, and @ref{Lists}.
+
+Eplain can create hypertext links for the cross-references;
+@pxref{Cross-reference hyperlinks}.
+
+@menu
+* Defining generic references::
+* Using generic references::
+@end menu
+
+
+@node Defining generic references
+@subsection Defining generic references
+
+@cindex defining general references
+@cindex references, defining general
+@cindex cross-references, defining general
+
+@findex definexref
+Eplain provides the command @code{\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:
+
+@example
+\definexref@{sec-intro@}@{3.1@}@{section@}
+@end example
+
+@noindent Of course, the label value is usually generated by another
+macro using @TeX{} count registers or some such.
+
+@code{\definexref} doesn't actually define @var{label}; instead, it
+writes out the definition to the @t{.aux} file, where Eplain will read
+it on the next @TeX{} run.
+
+The @var{class} argument is used by the @code{\ref} and @code{\refs}
+commands. See the next section.
+
+
+@node Using generic references
+@subsection Using generic references
+
+@cindex defining general references
+@cindex references, defining general
+@cindex cross-references, defining general
+
+To retrieve the value of the label defined via @code{\definexref} (see
+the previous section), Eplain provides the following macros:
+
+@table @code
+
+@findex refn
+@itemx \refn@{@var{label}@}
+@findex xrefn
+@item \xrefn@{@var{label}@}
+@code{\refn} and @code{\xrefn} (they are synonyms) produce the bare
+definition of @var{label}. If @var{label} isn't defined, issue a
+warning, and produce @var{label} itself instead, in typewriter. (The
+warning isn't given if @code{\xrefwarningfalse}.)
+@findex xrefwarning @r{conditional}
+
+@findex ref
+@item \ref@{@var{label}@}
+Given the class @var{c} for @var{label} (see the description of
+@code{\definexref} in the previous section), expand the control sequence
+@code{\@var{c} word} (if it's defined) followed by a tie. Then call
+@code{\refn} on @var{label}. (Example below.)
+
+@findex refs
+@item \refs@{@var{label}@}
+Like @code{\ref}, but append the letter @samp{s} to the
+@code{\@dots{}word}.
+
+@end table
+
+The purpose of the @code{\@dots{}word} macro is to produce the word
+`Section' or `Figure' or whatever that usually precedes the actual
+reference number.
+
+Here is an example:
+
+@example
+\def\sectionword@{Section@}
+\definexref@{sec-intro@}@{3.1@}@{section@}
+\definexref@{sec-next@}@{3.2@}@{section@}
+See \refs@{sec-intro@} and \refn@{sec-next@} @dots{}
+@end example
+
+@noindent This produces `See Sections 3.1 and 3.2 @dots{}'
+
+
+@node Page references
+@section Page references
+
+Eplain provides two commands for handling references to page numbers,
+one for definition and one for use.
+
+@table @code
+
+@item \xrdef@{@var{label}@}
+@findex xrdef
+Define @var{label} to be the current page number. This produces no
+printed output, and ignores following spaces.
+
+@item \xref@{@var{label}@}
+@findex xref
+Produce the text `p.@tie{}@var{pageno}', which is the usual form for
+cross-references. The @var{pageno} is actually @var{label}'s
+definition; if @var{label} isn't defined, the text of the label itself
+is printed. The `p.@tie{}' prefix is defined by @code{\xrefpageword}.
+@findex xrefpageword
+Its default definition is @code{p.\thinspace}.
+
+@end table
+
+Eplain can create hypertext links for the page references; @pxref{Page
+reference hyperlinks}.
+
+
+@node Equation references
+@section Equation references
+
+@cindex equations, references to
+@cindex equations, numbering
+Instead of referring to pages, it's most useful if equation labels
+refer to equation numbers. Therefore, Eplain reserves a @code{\count}
+register, @code{\eqnumber},
+@findex 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:
+
+@table @code
+
+@item \eqdef@{@var{label}@}
+@findex eqdef
+This defines @var{label} to be the current value of @code{\eqnumber},
+and, if the current context is not inner, then produces a @code{\eqno}
+command. (The condition makes it possible to use @code{\eqdef} in an
+@code{\eqalignno} construction, for example.) The text of the equation
+number is produced using @code{\eqprint}. @xref{Formatting equation
+references}.
+
+@cindex empty equation labels
+@cindex labels, empty equation
+@cindex equations, giving numbers to all
+If @var{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.
+
+@cindex empty equation labels, referring to
+@cindex labels, empty equation, referring to
+To refer to the last equation with the empty label, you just use the
+empty label in one of the equation reference macros (see below). This
+can be handy when you want to refer to an equation shortly after its
+definition, say, in the sentence following the displayed equation, and
+do not intend to refer to the equation later. But use this trick with
+extreme caution: if later you change the text and insert another
+empty definition between the original definition and the reference,
+the reference will start to refer to the new empty-labeled equation.
+
+@item \eqdefn@{@var{label}@}
+@findex eqdefn
+This is like @code{\eqdef}, except it always omits the @code{\eqno}
+command. It can therefore be used in places where @code{\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.
+
+@item \eqref@{@var{label}@}
+@findex eqref
+This produces a formatted reference to @var{label}. If @var{label} is
+undefined (perhaps because it is a forward reference), it just produces
+the text of the label itself. Otherwise, it calls @code{\eqprint}.
+
+@item \eqrefn@{@var{label}@}
+@findex eqrefn
+This produces the cross-reference text for @var{label}. That is, it
+is like @code{\eqref}, except it doesn't call @code{\eqprint}.
+
+@end table
+
+@cindex equation labels, characters valid in
+Equation labels can contain the same characters that are valid in
+general cross-references.
+
+Eplain can create hypertext links for the equation references;
+@pxref{Equation reference hyperlinks}.
+
+
+@menu
+* Formatting equation references::
+* Subequation references::
+@end menu
+
+
+@node Formatting equation references
+@subsection Formatting equation references
+
+@cindex equation numbers, formatting of
+Both defining an equation label and referring to it should usually
+produce output. This output is produced with the @code{\eqprint} macro,
+which takes one argument, the equation number being defined or referred
+to. By default, this just produces @samp{(@var{number})}, where
+@var{number} is the equation number. To produce the equation number in
+a different font, or with different surrounding symbols, or whatever,
+you can redefine @code{\eqprint}.
+@findex 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.)
+
+@example
+\def\eqprint#1@{@{\it (#1)@}@}
+@end example
+
+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 @code{\eqconstruct}.
+@findex eqconstruct
+For example:
+
+@example
+\def\eqconstruct#1@{\the\chapternumber.#1@}
+@end example
+
+@noindent
+(If you are keeping the chapter number in a count register named
+@code{\chapternumber}, naturally.)
+
+The reason for having both @code{\eqconstruct} and @code{\eqprint} may
+not be immediately apparent. The difference is that @code{\eqconstruct}
+affects the text that cross-reference label is defined to be, while
+@code{\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:
+
+@example
+$$@dots{}\eqdef@{a-eq@}$$
+@dots{}
+$$@dots{}\eqdef[\eqrefn@{a-eq@}*]@{a-eq-var@}$$
+In \eqref@{a-eq-var@}, we expand on \eqref@{a-eq@}, @dots{}
+@end example
+
+We use @code{\eqrefn} in the cross-reference text, not
+@code{\eqref}, so that @code{\eqprint} is called only once.
+
+
+@node Subequation references
+@subsection Subequation references
+
+@cindex equations, groups of
+@cindex subequations, referring to
+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:
+``@dots{} in the system of equations (2)@dots{}''.
+
+The commands to do this are @code{\eqsubdef} and
+@findex eqsubdef
+@code{\eqsubdefn}.
+@findex eqsubdefn
+They take one @var{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 @code{\eqnumber},
+they also use another counter, @code{\subeqnumber}.
+@findex subeqnumber
+This counter is advanced by one at every @code{\eqsubdef} or
+@code{\eqsubdefn}, and reset to zero at every @code{\eqdef} or
+@code{\eqdefn}.
+
+You use @code{\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 @code{\eqsubreftext}.
+@findex 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:
+@example
+\def\eqsubreftext#1#2@{#1.#2@}%
+@end example
+
+@noindent You can redefine @code{\eqsubreftext} to print however you
+like. For example, this definition makes the labels print as `2a',
+`2b', and so on.
+@example
+\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
+@}
+@end example
+
+@noindent Sadly, we must define a new count register, @code{\subref},
+instead of using the scratch count register @code{\count255}, because
+@samp{#1} might include other macro calls which use @code{\count255}.
+
+
+@node Indexing
+@section Indexing
+
+@cindex indexing
+@cindex sorting an index
+
+Eplain provides support for generating raw material for an index, and
+for typesetting a sorted index. A separate program must do the actual
+collection and sorting of terms, because @TeX{} itself has no support
+for sorting.
+
+Eplain can create hypertext links pointing from the index to the index
+terms; @pxref{Index hyperlinks}.
+
+@cindex URL for MakeIndex
+@pindex makeindex
+Eplain's indexing commands were designed to work with the program
+MakeIndex, available from CTAN hosts in
+@file{tex-archive/indexing/makeindex}; MakeIndex is also commonly
+included in prepackaged @TeX{} distributions. It is beyond the scope of
+this manual to explain how to run MakeIndex, and all of its many
+options. See @url{http://www.ctan.org/tex-archive/indexing/makeindex/}
+
+The basic strategy for indexing works like this:
+
+@enumerate
+
+@pindex .idx @r{files}
+@item For a document @file{foo.tex}, Eplain's indexing commands (e.g.,
+@code{\idx}; see the section `Indexing terms' below) write the raw index
+material to @file{foo.idx}.
+
+@pindex .ind @r{files}
+@item MakeIndex reads @file{foo.idx}, collects and sorts the index, and
+writes the result to @file{foo.ind}.
+
+@item Eplain reads and typesets @file{foo.ind} on a subsequent run of
+@TeX{}. See the section `Typesetting an index' below.
+
+@end enumerate
+
+@pindex texi2dvi
+@noindent The @command{texi2dvi} program can help you automate this
+process, @pxref{Invoking Eplain}.
+
+@cindex multiple indexes
+@cindex indexes, multiple
+@findex defineindex
+If your document needs more than one index, each must have its own
+file. Therefore, Eplain provides the command @code{\defineindex}, which
+takes an argument that is a single letter, which replaces @samp{i} in
+the filenames and in the indexing command names described below. For
+example,
+
+@example
+\defineindex@{m@}
+@end example
+
+@noindent defines the command @code{\mdx} to write to the file
+@file{foo.mdx}. Eplain simply does @code{\defineindex@{i@}} to define
+the default commands.
+
+@menu
+* Indexing terms:: Specifying what to index.
+* Typesetting an index:: Printing the sorted output.
+* Customizing indexing:: Creating commands and specifying extra actions.
+@end menu
+
+
+@node Indexing terms
+@subsection Indexing terms
+
+@cindex indexing terms
+@cindex silent indexing
+
+Indexing commands in Eplain come in pairs: one command that only
+writes the index entry to the @samp{.idx} file (see above section), and
+one that also typesets the term being indexed. The former always starts
+with @samp{s} (for ``silent''). In either case, the name always includes
+@samp{@var{I}dx}, where @var{I} is the index letter, also described
+above. Eplain defines the index @samp{i} itself, so that's what we'll
+use in the names below.
+
+@cindex subterm in indexing
+The silent form of the commands take a subterm as a trailing optional
+argument. For example, @code{\sidx@{truth@}[definition of]} on page 75
+makes an index entry that will eventually be typeset (by default) as
+
+@display
+truth
+ definition of, 75
+@end display
+
+@cindex trailing spaces and indexing commands
+@cindex spaces, trailing and indexing commands
+@cindex indexing and trailing spaces
+Also, the silent commands ignore trailing spaces. The non-silent ones do not.
+
+@menu
+* Indexing commands:: Making index entries.
+* Modifying index entries:: Ranges, see/see also, page number typesetting.
+* Proofing index terms:: Noting index entries in the margins.
+@end menu
+
+
+@node Indexing commands
+@subsubsection Indexing commands
+
+@cindex indexing commands
+Here are the commands.
+
+@itemize @bullet
+
+@item
+@findex sidx
+@findex idx
+@code{\sidx@{@var{term}@}[@var{subterm}]} makes an index entry for
+@var{term}, optionally with subterm @var{subterm}.
+@code{\idx@{@var{term}@}} also produces @var{term} as output. Example:
+
+@example
+\sidx@{truth@}[beauty of]
+The beauty of truth is \idx@{death@}.
+@end example
+
+Subterms at the second and further levels can also be
+specified in @var{subterm}, using the
+@code{\idxsubentryseparator} character to separate
+them. This character is by default @samp{!}.
+
+@item
+@findex sidxname
+@findex idxnameseparator
+@findex idxname
+@code{\sidxname@{@var{First M.}@}@{@var{von Last}@}[@var{subterm}]}
+makes an index
+entry for @samp{@var{von Last}, @var{First M.}}. You can change the
+@samp{, } by redefining @code{\idxnameseparator}.
+@code{\idxname@{@var{First M.}@}@{@var{von Last}@}} also produces @var{First M. von
+Last} as output. (These commands are useful special cases of @code{\idx}
+and @code{\sidx}.) Example:
+
+@example
+\sidxname@{Richard@}@{Stark@}
+\idxname@{Donald@}@{Westlake@} has written many kinds of novels, under
+almost as many names.
+@end example
+
+@item
+@findex sidxmarked
+@findex idxmarked
+@code{\sidxmarked\@var{cs}@{@var{term}@}[@var{subterm}]} makes an index
+entry for @code{@var{term}[@var{subterm}]}, but @var{term} will be put
+in the index as @code{\@var{cs}@{term@}}, but still sorted as just
+@var{term}. @code{\idxmarked\@var{cs}@{@var{term}@}} also typesets
+@code{\@var{cs}@{term@}}. This provides for the usual ways of changing
+the typesetting of index entries. Example:
+
+@example
+\def\article#1@{``#1''@}
+\sidxmarked\article@{Miss Elsa and Aunt Sophie@}
+Peter Drucker's \idxmarked\article@{The Polanyis@} is a remarkable
+essay about a remarkable family.
+@end example
+
+@item
+@findex idxsubmarked
+@findex sidxsubmarked
+@code{\sidxsubmarked@{@var{term}@}\@var{cs}@{subterm@}} makes an index
+entry for @var{term}, @var{subterm} as usual, but also puts @var{subterm} in
+the index as @code{\@var{cs}@{term@}}.
+@code{\idxsubmarked@{@var{term}@}\@var{cs}@{subterm@}} also typesets
+@code{@var{term} \@var{cs}@{subterm@}}, in the unlikely event that your
+syntax is convoluted enough to make this useful. Example:
+
+@example
+\def\title#1@{@{\sl #1@}@}
+\sidxsubmarked@{Anderson, Laurie@}\title@{Strange Angels@}
+The \idxsubmarked@{Anderson@}\title@{Carmen@} is a strange twist.
+@end example
+
+@end itemize
+
+@cindex index entry general sorting
+@cindex sorting of index entries
+The commands above rely on MakeIndex's feature for separating sorting of
+an index entry's from its typesetting. You can use this directly by
+specifying an index entry as @code{@var{sort}@@@var{typeset}}. For
+example:
+
+@example
+\sidx@{Ap-weight@@$A_\pi$-weight@}
+@end example
+
+@noindent will sort as @code{Ap-weight}, but print with the proper math.
+The @code{@@} here is MakeIndex's default character for this purpose.
+See @url{http://www.ctan.org/tex-archive/indexing/makeindex/}. To make an index
+entry with an @code{@@} in it, you have to escape it with a backslash;
+Eplain provides no macros for doing this.
+
+@findex afterindexterm @r{hook}
+@cindex whatsits made by index entries
+After any index command, Eplain runs
+@code{\hookaction@{afterindexterm@}}. Because the index commands always
+add a whatsit item to the current list, you may wish to preserve a
+penalty or space past the new item. For example, given a conditional
+@code{\if@@aftersctnhead} set true when you're at a section heading, you
+could do:
+
+@example
+\hookaction@{afterindexterm@}@{\if@@aftersctnhead \nobreak \fi@}
+@end example
+
+
+@node Modifying index entries
+@subsubsection Modifying index entries
+
+@cindex modifying index entries' page numbers
+@cindex index entries' page numbers, modifying
+
+All the index commands described in the previous section take an initial
+optional argument before the index term, which modify the index entry's
+meaning in various ways. You can specify only one of the following in
+any given command, except that @code{begin} and @code{end} can be
+specified together with @code{pagemarkup=@var{cs}} (separate them with
+a comma without a following space, like this:
+@code{[begin,pagemarkup=defn]}).
+
+These work via MakeIndex's ``encapsulation'' feature. @xref{Customizing
+indexing}, if you're not using the default characters for the
+MakeIndex operators. The other optional argument (specifying a subterm)
+is independent of these.
+
+Here are the possibilities:
+
+@table @code
+
+@item begin
+@itemx end
+@findex begin @r{for index entries}
+@findex end @r{for index entries}
+@cindex index entries and ranges
+@cindex ranges and index entry
+These mark an index entry as the beginning or end of a range. The index
+entries must match exactly for MakeIndex to recognize them.
+Example:
+
+@example
+\sidx[begin]@{future@}[Cohen, Leonard]
+@dots{}
+\sidx[end]@{future@}[Cohen, Leonard]
+@end example
+
+@noindent will typeset as something like
+
+@display
+future,
+ Cohen, Leonard, 65--94
+@end display
+
+@item see
+@findex see @r{for index entries}
+@cindex see, and index entries
+@cindex cross-referencing index entries
+@cindex index entries, and cross-referencing
+This marks an index entry as pointing to another; the real index term is
+an additional (non-optional) argument to the command. Thus you can
+anticipate a term readers may wish to look up, yet which you have
+decided not to index. Example:
+
+@example
+\sidx[see]@{analysis@}[archetypal]@{archetypal criticism@}
+@end example
+
+@noindent becomes
+
+@display
+analysis,
+ archetypal, @i{see} archetypal criticism
+@end display
+
+@item seealso
+@findex seealso @r{for index entries}
+Similar to @code{see} (the previous item), but also allows for normal
+index entries of the referencing term. Example:
+
+@example
+\sidx[seealso]@{archetypal criticism@}[elements of]@{dichotomies@}
+@end example
+
+@noindent becomes
+
+@display
+archetypal criticism,
+ elements of, 75, 97, 114, @i{see also} dichotomies
+@end display
+
+(Aside for the academically curious: The archetypally critical book I
+took these dichotomous examples from is Laurence Berman's @cite{The
+Musical Image}, which I happened to co-design and typeset.)
+
+@item pagemarkup=@var{cs}
+This puts @code{\@var{cs}} before the page number in the typeset index,
+thus allowing you to underline definitive entries, italicize examples,
+and the like. You do @emph{not} precede the control sequence @var{cs}
+with a backslash. (That just leads to expansive difficulties.) Naturally
+it is up to you to define the control sequences you want to use. Example:
+
+@example
+\def\defn#1@{@{\sl #1@}@}
+\sidx[pagemarkeup=defn]@{indexing@}
+@end example
+
+@noindent becomes something like
+
+@example
+indexing, @code{\defn@{75@}}
+@end example
+
+@end table
+
+
+@node Proofing index terms
+@subsubsection Proofing index terms
+
+@cindex proofing index terms
+@cindex index terms, proofing
+@cindex margins, index terms in
+
+As you are reading through a manuscript, it is helpful to see what terms
+have been indexed, so you can add others, catch miscellaneous errors,
+etc. (Speaking from bitter experience, I can say it is extremely
+error-prone to leave all indexing to the end of the writing, since it
+involves adding many @TeX{} commands to the source files.)
+
+@findex indexproofterm
+@findex indexprooffont
+@pindex cmtt8
+So Eplain puts index terms in the margin of each page, if you
+set @code{\indexproofingtrue}. It is @code{false} by default. The terms
+are typeset by the macro @code{\indexproofterm}, which takes a single
+argument, the term to be typeset. Eplain's definition of
+@code{\indexproofterm} just puts it into an @code{\hbox}, first doing
+@code{\indexprooffont}, which Eplain defines to select the font
+@code{cmtt8}. With this definition long terms run off the page, but
+since this is just for proofreading anyway, it seems acceptable.
+
+@findex pageno
+@findex insidemargin
+@findex hoffset
+@findex outsidemargin
+@findex indexsetmargins
+On the other hand, we certainly don't want the index term to run into
+the text of the page, so Eplain uses the right-hand side of the page
+rather than the left-hand page (assuming a language read left to right
+here). So @code{\ifodd\pageno}, Eplain kerns by @code{\outsidemargin},
+otherwise by @code{\insidemargin}. If those macros are undefined,
+@code{\indexsetmargins} defines them to be one inch plus @code{\hoffset}.
+
+@findex @@indexproof @r{insertion class}
+@findex indexproofunbox
+@findex makeheadline
+@cindex output routine and index proofing
+To get the proofing index entries on the proper page, Eplain defines a new
+insertion class @code{\@@indexproof}. To unbox any index proofing
+material, Eplain redefines @code{\makeheadline} to call
+@code{\indexproofunbox} before the original @code{\makeheadline}. Thus,
+if you have your own output routine, that redefines or doesn't use
+@code{\makeheadline}, it's up to you to call @code{\indexproofunbox} at
+the appropriate time.
+
+
+@node Typesetting an index
+@subsection Typesetting an index
+
+@cindex typesetting an index
+@cindex index typesetting
+@findex readindexfile
+
+The command @code{\readindexfile@{i@}} reads and typesets the
+@file{.ind} file that MakeIndex outputs (from the @file{.idx} file which
+the indexing commands in the previous sections write). Eplain defines a
+number of commands that support the default MakeIndex output.
+
+@findex indexfilebasename
+@findex jobname
+More precisely, @code{\readindexfile} reads
+@code{\indexfilebasename.@var{index-letter}nd}, where the
+@var{index-letter} is the argument. @code{\indexfilebasename} is
+@code{\jobname} by default, but if you have different indexes in
+different parts of a book, you may wish to change it, just as with
+bibliographies (@pxref{Citations}).
+
+@findex begin@{theindex@}
+@findex end@{theindex@}
+MakeIndex was designed to work with @LaTeX{}; therefore, by default the
+@file{.ind} file starts with @code{\begin@{theindex@}} and ends with
+@code{\end@{theindex@}}. If no @code{\begin} has been defined, Eplain
+defines one to ignore its argument and set up for typesetting the index
+(see below), and also defines a @code{\end} to ignore its argument. (In
+a group, naturally, since there is a primitive @code{\end}).
+
+@findex parindent @r{in indexes}
+@cindex index fonts
+@findex indexfonts
+@cindex double columns in indexes
+Eplain calls @code{\indexfonts}, sets @code{\parindent = 0pt}, and does
+@code{\doublecolumns} (@pxref{Multiple columns}) at the
+@code{\begin@{theindex@}}. @code{\indexfonts} does nothing by default;
+it's just there for you to override. (Indexes are usually typeset in
+smaller type than the main text.)
+
+@findex beginindex @r{hook}
+It ends the setup with @code{\hookrun@{beginindex@}}, so you can
+override anything you like in that hook (@pxref{Hooks}). For example:
+
+@example
+\hookaction@{beginindex@}@{\triplecolumns@}
+@end example
+
+@findex item @r{in indexes}
+@findex subitem @r{in indexes}
+@findex subsubitem @r{in indexes}
+@cindex index entry formatting
+@cindex formatting index entries
+@cindex space above index entries
+@cindex continued index entries
+@cindex index entry continuations
+MakeIndex turns each main index entry into an @code{\item}, subentries
+into @code{\subitem}, and subsubentries into @code{\subsubitem}. By
+default, the first line of main entries are not indented, and subentries
+are indented 1em per level. Main entries are preceded by a @code{\vskip}
+of @code{\aboveitemskipamount}, @code{0pt plus2pt} by default. Page
+breaks are encouraged before main entries (@code{\penalty -100}), but
+prohibited afterwards---Eplain has no provision for ``continued''
+index entries.
+
+All levels do the following:
+
+@findex hangindent @r{for index entries}
+@findex raggedright @r{for index entries}
+@findex hyphenpenalty @r{for index entries}
+@example
+\hangindent = 1em
+\raggedright
+\hyphenpenalty = 10000
+@end example
+
+@findex indexitem @r{hook}
+Each entry ends with @code{\hookrun@{indexitem@}}, so you can change any
+of this. For example, to increase the allowable rag:
+
+@example
+\hookaction@{indexitem@}@{\advance\rightskip by 2em@}
+@end example
+
+@findex indexspace
+@cindex index groupings
+Finally, MakeIndex outputs @code{\indexspace} between each group of
+entries in the @file{.ind} file. Eplain makes this equivalent to
+@code{\bigbreak}.
+
+
+@node Customizing indexing
+@subsection Customizing indexing
+
+@cindex customizing indexing
+
+@findex afterindexterm
+@cindex commas after index terms
+@cindex after index terms
+By default, MakeIndex outputs @samp{, } after each term in the index. To
+change this, you can add the following to your MakeIndex style
+(@file{.ist}) file:
+
+@example
+delim_0 "\\afterindexterm "
+delim_1 "\\afterindexterm "
+delim_2 "\\afterindexterm "
+@end example
+
+@noindent Eplain makes @code{\afterindexterm} equivalent to
+@code{\quad}.
+
+You can also change the keywords Eplain recognizes (@pxref{Modifying
+index entries}):
+
+@table @code
+
+@item \idxrangebeginword
+@findex idxrangebeginword
+`begin'
+
+@item \idxrangeendword
+@findex idxrangeendword
+`end'
+
+@item \idxseecmdword
+@findex idxseecmdword
+`see'
+
+@item \idxseealsocmdword
+@findex idxseealsocmdword
+`seealso'
+
+@end table
+
+You can also change the magic characters Eplain puts into the
+@file{.idx} file, in case you've changed them in the @code{.ist} file:
+
+@table @code
+
+@item \idxsubentryseparator
+@findex idxsubentryseparator
+@samp{!}
+
+@item \idxencapoperator
+@findex idxencapoperator
+@samp{|}
+
+@item \idxbeginrangemark
+@findex idxbeginrangemark
+@samp{(}
+
+@item \idxendrangemark
+@findex idxendrangemark
+@samp{)}
+
+@end table
+
+There is no macro for the @code{actual} (@samp{@@} by default)
+character, because it's impossible to make it expand properly.
+
+@findex idxpagenum
+@cindex see also index entries and sorting
+You can change the (imaginary) page number that ``see also''
+entries sort as by redefining @code{\idxmaxpagenum}. This is 99999 by
+default, which is one digit too many for old versions of MakeIndex.
+
+@findex indexseeword
+@findex indexseealsowords
+@findex seevariant
+@findex indexsee
+@findex indexseealso
+The words output by Eplain for ``see'' and ``see also'' index entries
+are defined by @code{\indexseeword} and @code{\indexseealsowords}
+respectively. You can change the typeface used for these words by
+redefining @code{\seevariant}. And finally, the macros
+@code{\indexsee} and @code{\indexseealso} actually produce the ``see
+@dots{}'' entries, so you can redefine them if you want something
+entirely different. If you do redefine them, make them take two
+parameters, the term being referenced and the @code{\idxmaxpagenum}
+(the latter should normally be ignored). See the example below.
+
+@findex see @r{for index entries}
+@cindex see, and index entries
+@cindex cross-referencing index entries
+@cindex index entries, and cross-referencing
+@cindex commas in cross-referencing index entries
+Unfortunately, it is impossible to reliably control the commas
+produced by MakeIndex in front of ``see @dots{}'' entries in the
+@file{.ind} file, either at MakeIndex level or at Eplain level.
+However, the
+@pindex sed
+@command{sed} script named @command{trimsee}
+@pindex trimsee
+distributed with Eplain in the @file{test} directory can be used to
+filter out these commas from the output of MakeIndex. For example,
+suppose you want the following style for your ``see @dots{}'' entries:
+
+@display
+analysis,
+ archetypal (@i{see} archetypal criticism)
+archetypal criticism,
+ elements of, 75, 97, 114 (@i{see also} dichotomies)
+@end display
+
+@noindent You would need to redefine these macros in your @TeX{}
+file:
+
+@example
+\def\indexsee#1#2@{(@{\seevariant \indexseeword\/ @}#1)@}
+\def\indexseealso#1#2@{(@{\seevariant \indexseealsowords\/ @}#1)@}
+@end example
+
+@noindent and then filter out the commas in front of the ``see @dots{}''
+entries by running the following command to produce the @file{.ind}
+file (assuming the name of the @file{.idx} file is @file{myfile.idx}
+and the @file{trimsee} script is placed in the current directory):
+
+@example
+prompt$ cat myfile.idx | makeindex | ./trimsee > myfile.ind
+@end example
+
+By default, @file{trimsee} uses default page list separators and
+default ``see @dots{}'' command names. If you set up MakeIndex to use
+different page list separator or change the names of @code{\indexsee}
+and @code{\indexseealso} commands, it is possible to adjust the
+@file{trimsee} script through its command line options, which are the
+following:
+
+@table @option
+@item -i @var{is}
+Use @var{is} as a regular expression matching separator before ``see
+@dots{}'' commands in the input (default: @samp{, \+}).
+
+@item -o @var{os}
+Use @var{os} as a separator to replace @var{is} before ``see @dots{}''
+commands (default: @samp{ }).
+
+@item -s @var{see}
+Use @var{see} as a regular expression matching ``see @dots{}''
+commands (default: @samp{\\indexsee}).
+
+@item -h
+@itemx --help
+Print a usage message.
+
+@item -v
+@itemx --version
+Print version.
+@end table
+
+@file{trimsee} reads input from the standard input, and directs its
+output to the standard output.
+
+
+@node Justification
+@section Justification
+
+@cindex centering
+@cindex left-justification
+@cindex right-justification
+@cindex justification
+Eplain defines three commands to conveniently justify multiple
+lines of text: @code{\flushright}, @code{\flushleft}, and
+@code{\center}.
+@findex flushright
+@findex flushleft
+@findex center
+
+They all work in the same way; let's take @code{\center} as the
+example. To start centering lines, you say @code{\center} inside a
+group; to stop, you end the group. Between the two commands, each
+end-of-line in the input file also starts a new line in the output file.
+
+The entire block of text is broken into paragraphs at blank lines,
+so all the @TeX{} paragraph-shaping parameters apply in the usual way.
+This is convenient, but it implies something else that isn't so
+convenient: changes to any linespacing parameters, such as
+@code{\baselineskip}, will have @emph{no effect} on the paragraph in
+which they are changed. @TeX{} does not handle linespacing changes
+within a paragraph (because it doesn't know where the line breaks are
+until the end of the paragraph).
+
+The space between paragraphs is by default one blank line's worth.
+You can adjust this space by assigning to @code{\blanklineskipamount};
+@findex blanklineskipamount @r{in justified text}
+this (vertical) glue is inserted after each blank line.
+
+Here is an example:
+@example
+@{\center First line.
+
+ Second line, with a blank line before.
+@}
+@end example
+
+This produces:
+
+@center First line.
+@center
+@center Second line, with a blank line before.
+
+You may wish to use the justification macros inside of your own
+macros. Just be sure to put them in a group. For example, here is how
+a title macro might be defined:
+
+@example
+\def\title@{\begingroup\titlefont\center@}
+\def\endtitle@{\endgroup@}
+@end example
+
+
+@node Tables
+@section Tables
+
+@cindex tables
+@cindex alignments
+Eplain provides a single command, @code{\makecolumns},
+@findex makecolumns
+to make generating one particular kind of table easier. More ambitious
+macro packages might be helpful to you for more difficult applications.
+The files @file{ruled.tex} and @file{TXSruled.tex}, available from
+@samp{lifshitz.ph.utexas.edu} in @file{texis/tables}, is the only one I
+know of.
+
+Many tables are homogenous, i.e., all the entries are semantically the
+same. The arrangement into columns is to save space on the page, not
+to encode different meanings. In this kind of the table, it is useful to
+have the column breaks chosen automatically, so that you can add or
+delete entries without worrying about the column breaks.
+
+@code{\makecolumns} takes two arguments: the number of entries in the
+table, and the number of columns to break them into. As you can see
+from the example below, the first argument is delimited by a slash, and
+the second by a colon and a space (or end-of-line). The entries for the
+table then follow, one per line (not including the line with the
+@code{\makecolumns} command itself).
+
+@code{\parindent} defines the space to the left of the
+table. @code{\hsize} defines the width of the table.
+So you can adjust the position of the table on the page by assignments
+to these parameters, probably inside a group.
+
+You can also control the penalty at a page break before the
+@code{\makecolumns} by setting the parameter
+@code{\abovecolumnspenalty}.
+@findex abovecolumnspenalty
+Usually, the table is preceded by some explanatory text. You wouldn't
+want a page break to occur after the text and before the table, so
+Eplain sets it to @code{10000}. But if the table produced by
+@code{\makecolumns} is standing on its own, @code{\abovecolumnspenalty}
+should be decreased.
+
+If you happen to give @code{\makecolumns} a smaller number of entries
+than you really have, some text beyond the (intended) end of the table
+will be incorporated into the table, probably producing an error
+message, or at least some strange looking entries. And if you give
+@code{\makecolumns} a larger number of entries than you really have,
+some of the entries will be typeset as straight text, probably also
+looking somewhat out of place.
+
+Here is an example:
+@example
+% Arrange 6 entries into 2 columns:
+\makecolumns 6/2: % This line doesn't have an entry.
+one
+two
+three
+four
+five
+six
+Text after the table.
+@end example
+
+This produces `one', `two', and `three' in the first column, and
+`four', `five', and `six' in the second.
+
+
+@node Margins
+@section Margins
+
+@cindex margins, changing
+@TeX{}'s primitives describe the type area in terms of an offset from
+the upper left corner, and the width and height of the type. Some
+people prefer to think in terms of the @dfn{margins} at the top, bottom,
+left, and right of the page, and most composition systems other than
+@TeX{} conceive of the page laid out in this way. Therefore, Eplain
+provides commands to directly assign and increment the margins.
+
+@table @code
+@itemx \topmargin = @var{dimen}
+@itemx \bottommargin = @var{dimen}
+@itemx \leftmargin = @var{dimen}
+@item \rightmargin = @var{dimen}
+@findex topmargin
+@findex bottommargin
+@findex leftmargin
+@findex rightmargin
+These commands set the specified margin to the @var{dimen} given.
+The @code{=} and the spaces around it are optional. The control
+sequences here are not @TeX{} registers, despite appearances;
+therefore, commands like @code{\showthe\topmargin} will not do what you
+expect.
+
+@itemx \advancetopmargin by @var{dimen}
+@itemx \advancebottommargin by @var{dimen}
+@itemx \advanceleftmargin by @var{dimen}
+@item \advancerightmargin by @var{dimen}
+@findex advancetopmargin
+@findex advancebottommargin
+@findex advanceleftmargin
+@findex advancerightmargin
+These commands change the specified margin by the @var{dimen} given.
+@end table
+
+Regardless of whether you use the assignment or the advance commands,
+Eplain always changes the type area in response, not the other margins.
+For example, when @TeX{} starts, the left and right margins are both one
+inch. If you then say @code{\leftmargin = 2in}, the right margin will
+remain at one inch, and the width of the lines (i.e., @code{\hsize})
+@findex hsize
+will decrease by one inch.
+
+When you use any of these commands, Eplain computes the old value of
+the particular margin, by how much you want to change it, and then
+resets the values of @TeX{}'s primitive parameters to correspond.
+Unfortunately, Eplain cannot compute the right or bottom margin without
+help: you must tell it the full width and height of the final output
+page. It defines two new parameters for this:
+
+@table @code
+@item \paperheight
+@findex paperheight
+The height of the output page; default is 11truein.
+
+@item \paperwidth
+@findex paperwidth
+The width of the output page; default is 8.5truein.
+@end table
+
+If your output page has different dimensions than this, you must
+reassign to these parameters, as in
+
+@example
+\paperheight = 11truein
+\paperwidth = 17truein
+@end example
+
+
+@node Multiple columns
+@section Multiple columns
+
+@cindex double column output
+@cindex triple column output
+@cindex quadruple column output
+@cindex multiple column output
+Eplain provides for double, triple, and quadruple column output: say
+@code{\doublecolumns},
+@findex doublecolumns
+@code{\triplecolumns},
+@findex triplecolumns
+or @code{\quadcolumns},
+@findex quadcolumns
+and from that point on, the manuscript will be
+set in columns. To go back to one column, say
+@code{\singlecolumn}.
+@findex singlecolumn
+
+@cindex column balancing with @code{\singlecolumn}
+@cindex balancing of columns with @code{\singlecolumn}
+You may need to invoke @code{\singlecolumn} to balance the columns
+on the last page of output.
+
+@findex columnfill
+@cindex column eject
+@cindex eject in multicolumns
+@findex pagetotal
+To do a ``column eject'', i.e., move to the top of the next column, do
+@code{\columnfill}. This does not actually force an eject, however: it
+merely inserts a kern of size @code{\@@normalvsize} minus
+@code{\pagetotal} (@code{\@@normalvsize} being the usual height of the
+page; to implement multicolumns, Eplain multiplies @code{\vsize} itself
+by the number of columns). In most circumstances, a column break will be
+forced after this kern (during the column splitting operation when the
+whole page is output), as desired.
+
+@findex gutter
+The columns are separated by the value of the dimen parameter
+@code{\gutter}. Default value is two picas.
+@findex gutterbox
+If you want to add vertical material between the columns, use
+@code{\gutterbox}. For example, to put a vertical line between columns,
+define
+@code{\gutterbox} as
+@example
+\def\gutterbox@{\vbox to \dimen0@{\vfil\hbox@{\vrule height\dimen0@}\vfil@}@}%
+@end example
+The dimension counter
+@code{\dimen0}
+contains the height of the column.
+
+All the @code{\@dots{}columns} macros insert the value of the glue parameter
+@code{\abovecolumnskip}
+@findex abovecolumnskip
+before the multicolumn text, and the value of the glue parameter
+@code{\belowcolumnskip}
+@findex belowcolumnskip
+after it. The default value for both of these parameters is
+@code{\bigskipamount}, i.e., one linespace in plain @TeX{}.
+
+The macros take into account only the insertion classes
+@cindex insertion classes
+defined by plain @TeX{}; namely, footnotes and @code{\topinsert}s. If
+you have additional insertion classes, you will need to change
+the implementation.
+
+Also, Eplain makes insertions the full page width. There is no
+provision for column-width insertions.
+
+
+@node Footnotes
+@section Footnotes
+
+@cindex footnotes, numbered
+The most common reference mark for footnotes is a raised number,
+incremented on each footnote. The @code{\numberedfootnote}
+@findex numberedfootnote
+macro provides this. It takes one argument, the footnote text.
+
+If your document uses only numbered footnotes, you could make typing
+@code{\numberedfootnote} more convenient with a command such as:
+
+@example
+\let\footnote = \numberedfootnote
+@end example
+
+After doing this, you can type your footnotes as
+@code{\footnote@{@var{footnote text}@}}, instead of as
+@code{\numberedfootnote@{@var{footnote text}@}}.
+
+Eplain keeps the current footnote number in the count register
+@code{\footnotenumber}. So, to reset the footnote number to zero,
+as you might want to do at, for example, the beginning of a chapter, you
+could say @code{\footnotenumber=0}.
+
+Plain @TeX{} separates the footnote marker from the footnote text by
+an en space (it uses the @code{\textindent} macro). In Eplain, you can
+change this space by setting the dimension register
+@code{\footnotemarkseparation}.
+@findex footnotemarkseparation
+The default is still an en.
+
+You can produce a space between footenotes by setting the glue
+register @code{\interfootnoteskip}.
+@findex interfootnoteskip
+The default is zero.
+
+@code{\parskip} is also set to zero by default before the beginning of
+each footnote (but not for the text of the footnote).
+
+You can also control footnote formatting in a more general way:
+Eplain expands the token register @code{\everyfootnote}
+@findex everyfootnote
+before a footnote is typeset, but after the default values for all the
+parameters have been established. For example, if you want your
+footnotes to be printed in seven-point type, indented by one inch, you
+could say:
+@example
+\everyfootnote = @{\sevenrm \leftskip = 1in@}
+@end example
+
+By default, an @code{\hrule} is typeset above each group of footnotes
+on a page. You can control the dimensions of this rule by setting
+the dimension registers @code{\footnoterulewidth}
+@findex footnoterulewidth
+and @code{\footnoteruleheight}.
+@findex footnoteruleheight
+The space between the rule and the first footnote on the page is
+determined by the dimension register @code{\belowfootnoterulespace}.
+@findex belowfootnoterulespace
+If you don't want any rule at all, set @code{\footenoteruleheight=0pt},
+and, most likely, @code{\belowfootnoterulespace=0pt}. The defaults for
+these parameters typeset the rule in the same way as plain @TeX{}: the
+rule is 0.4 points high, 2 true inches wide, with 2.6 points below it.
+
+The space above the rule and below the text on the page is controlled
+by the glue register @code{\skip\footins}. The default is a plain @TeX{}
+@code{\bigskip}.
+
+Eplain can create hypertext links for the footnote marks; @pxref{Footnote
+hyperlinks}.
+
+
+
+@node Fractions
+@section Fractions
+
+@cindex fractions
+Exercise 11.6 of @cite{The @TeX{}book} describes a macro @code{\frac}
+@findex frac
+for setting fractions, but @code{\frac} never made it into plain @TeX{}.
+So Eplain includes it.
+
+@code{\frac} typesets the numerator and denominator in
+@code{\scriptfont0}, slightly raised and lowered. The numerator and
+denominator are separated by a slash. The denominator must be enclosed
+in braces if it's more than one token long, but the numerator need not
+be. (This is a consequence of @code{\frac} taking delimited arguments;
+see page@tie{}203 of @cite{The @TeX{}book} for an explanation of
+delimited macro arguments.)
+
+For example, @code{\frac 23/@{64@}} turns `23/64' into
+@tex
+\leavevmode
+ \kern-.1em \raise .5ex \hbox{\the\scriptfont0 23}@comment
+ \kern-.1em $/$@comment
+ \kern-.15em \lower .25ex \hbox{\the\scriptfont0 64}@comment
+@end tex
+@ifinfo
+23/64 (you can't see the difference in the Info file)@comment
+@end ifinfo
+.
+
+
+@node Paths
+@section Paths
+
+@cindex pathnames, breaking
+@cindex filenames, breaking
+@cindex electronic mail addresses, breaking
+
+When you typeset long pathnames, electronic mail addresses, or other
+such ``computer'' names, you would like @TeX{} to break lines at
+punctuation characters within the name, rather than trying to find
+hyphenation points within the words. For example, it would be better to
+break the email address @code{letters@@alpha.gnu.ai.mit.edu} at the
+@samp{@@} or a @samp{.}, rather than at the hyphenation points in
+@samp{letters} and @samp{alpha}.
+
+@findex path
+If you use the @code{\path} macro to typeset the names, @TeX{} will find
+these good breakpoints. The argument to @code{\path} is delimited by
+any character other other than @samp{\} which does not appear in the
+name itself.
+@samp{|} is often a good choice, as in:
+@example
+\path|letters@@alpha.gnu.ai.mit.edu|
+@end example
+
+@findex discretionaries
+You can control the exact set of characters at which breakpoints will be
+allowed by calling @code{\discretionaries}. This takes the same sort of
+delimited argument; any character in the argument will henceforth be a valid
+breakpoint within @code{\path}. The default set is essentially all the
+punctuation characters:
+@example
+\discretionaries |~!@@$%^&*()_+`-=#@{@}[]:";'<>,.?\/|
+@end example
+
+@findex specialpathdelimiters @r{(conditional)}
+If for some reason you absolutely must use @code{\} as the delimiter
+character for @code{\path}, you can set
+@code{\specialpathdelimiterstrue}. (Other delimiter characters can
+still be used.) @TeX{} then processes the @code{\path} argument
+about four times more slowly.
+
+@cindex URL for @file{path.sty}
+The @code{\path} macro comes from @file{path.sty}, written by Nelson
+Beebe and Philip Taylor and available at
+@url{http://www.ctan.org/tex-archive/macros/latex/contrib/misc/path.sty}.
+
+
+@node Logos
+@section Logos
+
+@cindex logos
+@cindex names, of @TeX{} variants
+
+Eplain redefines the @code{\TeX}
+@findex TeX
+macro of plain @TeX{} to end with @code{\null}, so that the proper
+spacing is produced when @code{\TeX} is used at the end of a sentence.
+The other @dots{}@TeX{} macros listed here do this, also.
+
+Eplain defines
+@code{\AMSTeX},
+@cindex AMS@TeX{}
+@findex AMSTeX
+@code{\BibTeX}
+@cindex Bib@TeX{}
+@findex BibTeX
+@code{\AMSLaTeX},
+@cindex AMS@LaTeX{}
+@findex AMSLaTeX
+@code{\LAMSTeX},
+@cindex LAMS@TeX{}
+@findex LAMSTeX
+@code{\LaTeX}
+@cindex @LaTeX{}
+@findex LaTeX
+@code{\MF},
+@cindex Metafont
+@findex MF
+and @code{\SLiTeX}
+@cindex SLi@TeX{}
+@findex SLiTeX
+to produce their respective logos. (Sorry, the logos are not shown
+here.) Some spelling variants of these are also supported.
+
+@cindex URL for @file{texnames.sty}
+All these macros come from @file{texnames.sty}, compiled by Nelson
+Beebe and available at
+@url{http://www.ctan.org/tex-archive/info/biblio/texnames.sty}.
+
+
+@node Boxes
+@section Boxes
+
+@cindex black boxes
+@cindex rectangles
+The solid rectangle that Eplain uses as a marker in unordered lists
+(@pxref{Lists}) is available by itself: just say @code{\blackbox}.
+@findex blackbox
+
+You can create black boxes of arbitrary size with @code{\hrule} or
+@code{\vrule}.
+
+@cindex open boxes
+@cindex boxes, open
+You can also get unfilled rectangles with @code{\makeblankbox}.
+@findex makeblankbox
+This takes two explicit arguments: the height and depth of the rules that
+define the top and bottom of the rectangle. (The two arguments are
+added to get the width of the left and right borders, so that the
+thickness of the border is the same on all four sides.) It also uses,
+as implicit arguments, the dimensions of @code{\box0} to define the
+dimensions of the rectangle it produces. (The contents of @code{\box0}
+are ignored.)
+
+Here is an example. This small raised open box is suitable for
+putting next to numbers in, e.g., a table of contents.
+
+@example
+\def\openbox@{%
+ \ht0 = 1.75pt \dp0 = 1.75pt \wd0 = 3.5pt
+ \raise 2.75pt \makeblankbox@{.2pt@}@{.2pt@}
+@}
+@end example
+
+Finally, you can put a box around arbitrary text with @code{\boxit}.
+@findex boxit
+This takes one argument, which must itself be a (@TeX{}) box, and puts a
+printed box around it, separated by @code{\boxitspace}
+@findex boxitspace
+white space (3 points by default) on all four sides. For example:
+
+@example
+\boxit@{\hbox@{This text is boxed.@}@}
+@end example
+
+The reason that the argument must be a box is that when the text is
+more than one line long, @TeX{} cannot figure out the line length for
+itself. Eplain does set @code{\parindent} to zero inside @code{\boxit},
+since it is very unlikely you would want indentation there. (If you do,
+you can always reset it yourself.)
+
+@code{\boxit} uses @code{\ehrule} and @code{\evrule} so that you can
+easily adjust the thicknesses of the box rules. @xref{Rules}.
+
+
+@node Checking for PDF output
+@section Checking for PDF output
+
+@cindex URL for pdf@TeX{}
+@cindex PDF output
+@pindex pdftex
+@pindex .pdf @r{files}
+pdf@TeX{} is a @TeX{} variant that can output both @file{.dvi} and
+@file{.pdf} (Adobe's Portable Document Format) files (see
+@url{http://www.ctan.org/tex-archive/systems/pdftex/}). You might
+sometimes want to know whether the target format is @file{.pdf} or
+@file{.dvi}. The @code{\ifpdf}
+@findex ifpdf
+switch can be used to detect pdf@TeX{} in PDF mode:
+
+@example
+\ifpdf
+ This text is produced when pdfTeX is in PDF mode.
+\else
+ This text is produced when pdfTeX is in DVI mode,
+ or when some program other than pdfTeX is used.
+\fi
+@end example
+
+Keep in mind that @code{\ifpdf} is set based on the value of the
+@code{\pdfoutput}
+@findex pdfoutput
+primitive of pdf@TeX{} at the time Eplain is loaded. If you change
+the value of @code{\pdfoutput} after you load Eplain, @code{\ifpdf}
+will not reflect the change.
+
+@cindex URL for @file{ifpdf.sty}
+@cindex Oberdiek, Heiko
+Eplain defines @code{\ifpdf} by incorporating Heiko Oberdiek's
+@file{ifpdf.sty}, which is available at
+@url{http://www.ctan.org/tex-archive/macros/latex/contrib/oberdiek/ifpdf.sty}.
+
+
+@node Loading LaTeX packages
+@section Loading @LaTeX{} packages
+
+@cindex @LaTeX{} packages
+@cindex packages, @LaTeX{}
+@pindex .sty @r{files}
+@pindex .cls @r{files}
+Eplain provides a limited support for loading @LaTeX{} packages
+(@file{.sty} files---not @file{.cls}). This will mostly work for
+packages which were designed with plain @TeX{} compatibility in mind,
+which means that most @LaTeX{} packages cannot be loaded. The
+packages which are known to work are listed below (@pxref{Packages
+known to work}). If you discover a working package which is not in
+the list, please report it to the Eplain mailing list
+(@pxref{Introduction}).
+
+@cindex graphics collection, @LaTeX{}
+@cindex @LaTeX{} graphics collection
+@pindex miniltx.tex
+@cindex Carlisle, David
+@cindex Rahtz, Sebastian
+To set up a pseudo-@LaTeX{} environment for the packages, Eplain uses
+@file{miniltx.tex}
+(@url{http://www.ctan.org/tex-archive/macros/plain/graphics/miniltx.tex})
+from the @LaTeX{} graphics collection, written by David Carlisle and
+Sebastian Rahtz (the collection is available at
+@url{http://www.ctan.org/tex-archive/macros/latex/required/graphics/}).
+Eplain extends @file{miniltx.tex} to provide some additional features,
+e.g., support for package options.
+
+
+@menu
+* The \usepackage command:: Command to load packages.
+* Environment for loading packages:: Environment for the \usepackage commands.
+* Packages known to work:: Supported packages.
+* Packages known not to work:: Packages known not to work with Eplain.
+@end menu
+
+@node The \usepackage command
+@subsection The @code{\usepackage} command
+
+@findex usepackage
+@code{\usepackage} loads a @LaTeX{} package. Its syntax is similar to
+that of @LaTeX{}'s @code{\usepackage} command:
+
+@example
+\usepackage[@var{options}]@{@var{packages}@}[@var{version}]
+@end example
+
+@noindent where @var{options} is a comma-separated list of package
+options, @var{packages} is a comma-separated list of packages to load
+(without the @file{.sty} suffix), and @var{version} is a package
+version number given as a date in the format @samp{YYYY/MM/DD}. If an
+older version of the package is found, a warning is issued. If
+several packages are loaded within a single @code{\usepackage}
+command, the @var{options} will be applied to each of the packages.
+As usual, parameters in square brackets are optional and can be
+omitted (together with the square brackets).
+
+For example:
+
+@example
+\usepackage[foo,bar]@{pack1,pack2@}[2005/08/29]
+@end example
+
+@noindent will load packages @samp{pack1} and @samp{pack2}, each with
+the options @samp{foo} and @samp{bar}, and will check that each of the
+packages are dated 2005/08/29 or newer.
+
+
+@node Environment for loading packages
+@subsection Environment for loading packages
+
+@findex beginpackages
+@findex endpackages
+Some packages request that certain commands are executed after all
+packages have been loaded. In @LaTeX{}, this means that the commands
+are executed at the beginning of the document, after the so-called
+@dfn{preamble}. Neither plain @TeX{} nor Eplain have any kind of
+preamble; therefore, Eplain requires that all packages be loaded inside
+a @code{\beginpackages...\endpackages} block, for example:
+
+@example
+\beginpackages
+ \usepackage[foo,bar]@{pack1@}
+ \usepackage@{pack2@}
+\endpackages
+@end example
+
+@noindent This requirement enables Eplain to execute the ``delayed''
+commands at the end of the @code{\beginpackages...\endpackages} block.
+
+For the same reason, it is advisable to specify only one such block
+per document, just like there is only one preamble in @LaTeX{}.
+
+
+@node Packages known to work
+@subsection Packages known to work
+
+@cindex @LaTeX{} packages
+@cindex packages, @LaTeX{}
+The following table lists packages that had been tested and are known
+to work with Eplain, and locations where you can find manuals for
+these packages. Some of the short descriptions of the packages were
+taken from the documentation for those packages.
+
+@table @asis
+@item autopict (@samp{2001/06/04 v1.1j Picture mode autoload file})
+@pindex autopict.sty
+@url{http://tug.org/eplain/ltpictur.pdf}
+
+@cindex picture mode
+@findex begin@{picture@}
+@findex end@{picture@}
+This is the @LaTeX{} ``picture mode'', started by
+@code{\begin@{picture@}} and ended by @code{\end@{picture@}} (in
+@LaTeX{}, this package is not explicitly loaded since it is part of
+the @LaTeX{} kernel). It provides commands to draw simple figures
+inside your document without resorting to any external tools.
+
+@item color (@samp{1999/02/16 v1.0i Standard LaTeX Color (DPC)})
+@pindex color.sty
+@itemx graphics (@samp{2001/07/07 v1.0n Standard LaTeX Graphics (DPC,SPQR)})
+@pindex graphics.sty
+@itemx graphicx (@samp{1999/02/16 v1.0f Enhanced LaTeX Graphics (DPC,SPQR)})
+@pindex graphicx.sty
+@url{http://www.ctan.org/tex-archive/macros/latex/required/graphics/grfguide.pdf}
+
+@cindex graphics collection, @LaTeX{}
+@cindex @LaTeX{} graphics collection
+@cindex color
+@cindex rotation
+@cindex scaling
+These packages are from the @LaTeX{} graphics collection. They
+provide commands for changing text/page colors, text rotation and
+scaling, and much more.
+
+@item psfrag (@samp{1998/04/11 v3.04 PSfrag (MCG)})
+@pindex psfrag.sty
+@url{http://www.ctan.org/tex-archive/macros/latex/contrib/psfrag/pfgguide.pdf}
+
+@cindex Encapsulated PostScript
+@cindex EPS
+@pindex .eps @r{files}
+PSfrag allows the user to precisely overlay Encapsulated PostScript
+(EPS) files with arbitrary (La)@TeX{} constructions. In order to
+accomplish this, the user places a simple text ``tag'' in the graphics
+file, as a ``position marker'' of sorts. Then, using simple
+(La)@TeX{} commands, the user instructs PSfrag to remove that tag from
+the figure, and replace it with a properly sized, aligned, and rotated
+(La)@TeX{} equation.
+
+@item url (@samp{2005/06/27 ver 3.2 Verb mode for urls, etc.})
+@pindex url.sty
+@url{http://www.ctan.org/tex-archive/macros/latex/contrib/misc/url.sty}
+
+@cindex pathnames, breaking
+@cindex filenames, breaking
+@cindex electronic mail addresses, breaking
+This package provides a form of @code{\verbatim} that allows
+line breaks at certain characters or combinations of characters,
+accepts reconfiguration, and can usually be used in the argument to
+another command. It is intended for email addresses, hypertext links,
+directories/paths, etc., which normally have no spaces.
+
+Eplain can create hypertext links with the @code{\url} command;
+@pxref{URL hyperlinks}.
+@end table
+
+
+@node Packages known not to work
+@subsection Packages known not to work
+
+@cindex @LaTeX{} packages
+@cindex packages, @LaTeX{}
+The following packages are known not to work with Eplain:
+
+@table @asis
+@item pict2e (@samp{2005/07/15 v0.2r Improved picture commands (HjG,RN)})
+@pindex pict2e.sty
+@url{http://www.ctan.org/tex-archive/macros/latex/contrib/pict2e/}
+
+@item xcolor (@samp{2005/06/06 v2.03 LaTeX color extensions (UK)})
+@pindex xcolor.sty
+@url{http://www.ctan.org/tex-archive/macros/latex/contrib/xcolor/}
+@end table