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, 0 insertions, 2538 deletions
diff --git a/Master/texmf-dist/doc/eplain/base/userdef.texi b/Master/texmf-dist/doc/eplain/base/userdef.texi
deleted file mode 100644
index dfc5fcc4497..00000000000
--- a/Master/texmf-dist/doc/eplain/base/userdef.texi
+++ /dev/null
@@ -1,2538 +0,0 @@
-@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