diff options
Diffstat (limited to 'Master/texmf-dist/doc/eplain/base/userdef.texi')
-rw-r--r-- | Master/texmf-dist/doc/eplain/base/userdef.texi | 2538 |
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 |