Referenceable Numbering for Plain TEX

A Macro Package by Russell Lyons

based on earlier versions by James Nearing and Michael Lacey with contributions from Oded Schramm

Referencing Objects

This package is called Ref.macros. Everything you number can be given a label, which can consist of numbers, letters, and symbols. The label must identify the object being labelled in the following manner:

The object  The label
Chapter  C.name
Section  s.name
Equation  e.name
Theorem  t.name
Lemma  l.name
Proposition p.name
Corollary  c.name
Conjecture  g.name [g for guess]
Definition  d.name
Remark  r.name
Example  x.name
Question  q.name
Bib. item  b.name
Bib. item  B.name [alternative typesetting]
Figure  f.name

To reference the theorem labelled t.main, you only have to type \ref t.main/ to generate the output “Theorem 3.4”. That is, because of the form of the name, \ref knows to put “Theorem” into the output. The same holds for sections, lemmas, definitions, etc. If you don’t want the word “Theorem”, use \briefref instead. For equations, if you type \ref e.456/ , you’ll get the equation number in parentheses: (2.6). Note that \ref knows when the name ends only by encountering the slash /. Thus, / cannot be a part of the name. Also, because of the way labels are generated, the symbols . \ { } # % cannot be used as part of the name, nor can blank spaces.

If you use the same label for two different equations, then \ref will give the number of the most recent use of that label. So reserve a simple name for equations or theorems that you will refer to just once. If you want to be warned when a label is being redefined, set the switch \warnifredefinedtrue, as explained later.

Original version published by James Nearing in TUGboat 10 (1989), pages 82–88. I (R. L.) have not tested everything and cannot vouch for everything in this documentation either, but would appreciate hearing about bugs, improvements, or better versions: rdlyons@indiana.edu.

Labelling Equations

Here’s how to label equations. For single line displays, write

$$
X = 2y \label e.x=y
$$

It’s important that a blank space end the equation’s label! If you type \label e.x=y$$, then the equation’s name is “e.x=y$$” and TEX will not exit math display mode, which will cause a bizarre error in the next few lines of code.

In TEX, giving an equation a number works differently in multiline displays. But we wanted these macros to work in a uniform way, as far as labelling went. So, instead of $$\eqalignno{…}$$, type $$\eqaln{…}$$. For example:

$$\eqaln{
1+x &= 10 \cr
17-4 &= 13 \label e.arithmetic \cr
}$$

Notice that \label works the same way as for single line displays; no blank lines should be present (just as with Plain TEX); there is no & before the label; and there is a space after the label. For especially long equations split over two lines, where you want to put the label between the two lines, type

$$\eqaln{
A &= a+b+c+d+e+f+g+h+i+j+k+l+m \cr
\noalign {\vskip-8pt}
& \label e.alphabet \cr
\noalign {\vskip-8pt}
& \hskip 1in +n+o+p+q+r+s+t+u+v+w+x+y+z \cr
& = Z \cr
}$$

To label the whole display with a single label, revert to the usual \eqalign as follows:

$$\eqalign{
1+x &= 10 \cr
17-4 &= 13 \cr
}\label e.arithmetic
$$

An alternative to $$\eqaln{…}$$ is \begineqalno … \endeqalno. The disadvantage of the latter is that if your editor shows syntax, it will not pick up the fact that this is going into math mode. The advantage of the latter, however, is that you don’t have to write $$ or enclose the displayed lines inside of {…}.

If you want to label some equations in a display but don’t want to align the equations, you can write something like this:

$$\vbox{\eqaln{
\noalign{\centerline{\hbox{the first property holds}}}
if and only if & \label e.alphabet \cr
\noalign{\centerline{\hbox{the second property holds}}}
}}$$

Labelling Theorems, Etc.

To label and begin theorems, lemmas, propositions, corollaries, and so on, type

    \procl TYPE.name . . . \endprocl

where TYPE should be the first letter (t, l, p, c, g, d, r, x, q) of the object. The macro \procl (a modified version of \proclaim) inserts a medium skip, begins a new line with Theorem (or whatever) and theorem number, then changes to italic font. You need to say when the theorem ends, so say \endprocl to change back to a roman font and insert another medium skip. You don’t give the label name when calling up \endprocl. If you want to add a name to the proclamation of a theorem or other item, type \procname{name} before the body of the theorem. The macro \proclaim is still available for use when numbering is not desired or when something fancy is desired: e.g., if t.thm1 gets the label “Theorem 3.4” and we desire to label another theorem “Theorem 3.4′”, simply use

    \proclaim \ref t.thm1/$'$.

Note: the argument of \procl ends with a space; that of \proclaim ends with a period followed by a space. The macros \eqno and \leqno are still available for similar purposes. If you want fonts different from the above defaults, then after you have \input Ref.macros, type such things as

\def\proctitlefont{\bf} (for Theorem, etc.)

\def\procbodyfont{\sl} (for the body in slant font),

    \def\procnumberfont{\bf} (for 3.4, etc.),

\def\procnamefont{\bf} (for the name of a Theorem, etc.),

\def\exnamefont{\bf} (for the name of an exercise). For remarks, examples and definitions, things work exactly the same way, but the font isn’t changed to italic.

If a proof immediately follows a theorem, simply type \proof (without a period). This inserts a medium break and prints out “Proof” in italics without indentation. For a proof that appears sometime after the statement of the theorem, use \proofof TYPE.name . Like \label, there must be a blank space following the name. For a right-justified black box, use \Qed. In a displayed equation that is not labelled, you can use the format $$⋯\Qed$$, $$\eqaln{…\Qed }$$, \begineqalno⋯\Qed\endeqalno, or $$\eqalign{⋯}\Qed$$, but not $$\eqaln{…}\Qed $$ or $$\eqalign{⋯\Qed}$$. Note: if you use math.macros, then that should be input before Ref.macros, since both define \Qed, and only the latter definition is fully compatible with Ref.macros.

Labelling Chapters and Sections

To declare a new chapter, and number, title and label it, type

\bchap{title}{C.name} There should be no extra spaces around C.name. This begins a new page, numbers the chapter, prints out the number and title in a large font, and inserts a skip. For sections, type

\bsection{sectiontitle}{s.name} There should be no extra spaces around s.name. This inserts a big skip, numbers the section, places sectiontitle in boldface on the center of a line, and inserts a smallskip and a noindent; however, if the switch \leftsectionheadtrue has been set (see below), then the heading is left justified, suitable as the first words of a new paragraph. A new section begins on a page iff the amount of space left is \sectionspace, which is set by default to .15\vsize or, if \leftsectionheadtrue, to .1\vsize. This can be changed to any desired value after \initialeqmacro (see below) and rechanged during the file, if desired. For example, \def\sectionspace{.2\vsize}. References to chapters and sections work just like items such as theorems and equations. If you want to refer to the current chapter or section number, such as in a headline, use \chapfolio or \sectionfolio. In fact, if you want a nice headline beginning at a certain point, type

    \beginniceheadline

In a work without chapters, this will put the section number and name in the headline, together with the page number. In a work with chapters, the section number and name will be replaced by the chapter number and name on even-numbered pages. In both cases, the first page is treated differently: The first page of a chapter will have only the page number. The first page of a work without chapters will put the page number in the footline, while \firstheader will be used in the headline. This is \hfil by default, but can be defined however you wish after the file Ref.macros is input. For example, presuming that \versiondate has been already defined, one may wish to use

\def\firstheader{\eightpoint\ss\underbar{\raise2pt\line
    {\hfil Version of \versiondate}}
\beginniceheadline

(The last section to begin on a page is the one used. The switch \chapterstrue can, if needed, be turned on and off. It is automatically turned on when either \bchap or \booktoc is used.)

Options

The package is reasonably flexible. Let’s illustrate this with some of the lines of TEX commands you can have at the beginning of the file. (Actually, if you are willing to use only defaults, only the \input Ref.macros line is truly necessary.)

\input Ref.macros This is the name of the macro package.

\proofmodetrue
\chaprefwordytrue
\chapnumromantrue
\chapallnumtrue
\continuousnumberingtrue
\theoremcountingtrue
\sectionnumberstrue
\forwardreferencetrue
\checkdefinedreferencetrue
\warnifredefinedtrue
\lefteqnumberstrue
\leftsectionheadtrue
\tocgenerationtrue
\hyperstrue
\dvipdfmtrue
\nobracketcittrue
\citationgenerationtrue
\solutionstrue
\laterexerstrue
\textexerstrue

\initialeqmacro This line should come at the end! The default value for every switch is “false”. With \proofmodetrue, the head of each page has the time and date it was TEX’ed, the current chapter number and name (if the chapter number is greater than 0), the current section number and name, the name of the file, and the word “draft”. The margins of the page will have the label names, so that you can easily see what labels you used. When you are ready to print a final copy of the paper, either comment out the \proofmodetrue line, change it to \proofmodefalse, or remove it. The last line \initialeqmacro is a macro which sets the headline in proofmode. If forwardreferencetrue, it also reads the file \jobname.lbl if it exists to find the crossreferences and opens \jobname.lbl to be the output for the crossreferences. Note that if you want to create a separate file with only part of the whole manuscript, as when revising a chapter in a book, you may use \input bookfilename.lbl, where \bookfilename.lbl refers to the whole manuscript, and you won’t lose any references. (It is assumed here that the chapters are usually \input one after the other within the file bookfilename.tex.)

There are two ways to have chapter numbers included in references to items from other chapters: “(3.7) of Chapter II” if \chaprefwordytrue or “(II.3.7)” if \chaprefwordyfalse (which is the default). There are also two ways to have all chapter numbers: uppercase roman if \chapnumromantrue and arabic if \chapnumromanfalse (which is the default). Furthermore, if you want the chapter number included every time an item is given a label or referenced, then use the switch \chapallnumtrue, which supercedes \chaprefwordytrue; otherwise, the chapter number will be used only in referencing items from chapters other than the current chapter and in exercises. \continuousnumberingtrue makes the first equation of Section 2 be numbered, e.g., (7). Omit this line if you want that equation to have number (1), and if you want it to have number (2.1), keep \sectionnumberstrue. With \theoremcountingtrue, equations will have one counter, while theorems, corollaries, remarks, etc. will have another. That is, the paper will have Equation 1.1, Theorem 1.1, Definition 1.2, Corollary 1.3, Equation 1.2, etc.

The switch \forwardreferencetrue is for referring to Theorems, Sections, etc. that have not yet been labelled. In this case, a separate file called \jobname.lbl will be created. The macros will input this file and write the label macros into this file. The second time you run TEX on the file, all the numbers in the document will be correct. As noted earlier, if you want to be warned when a label is being redefined from an earlier definition in this job, set the switch \warnifredefinedtrue.

The switch \checkdefinedreferencetrue should be set if you want to be warned about every undefined reference; however, this will not do anything if \jobname.lbl is empty, as it would be the first time you run TEX. Note that undefined references are reported regardless of this switch if \forwardreferencetrue is not set.

The switch \lefteqnumberstrue is for those who want their equation numbers on the left.

If you want to label the appendices by letters, put the command \sectionno=-1 before the first appendix and use the \bsection command as for sections. This inserts the word “Appendix” automatically before the letter. (Currently, this can be used only like sections, not chapters.)

Table of Contents

If you want a table of contents automatically generated for either an article or a book, use the switch \tocgenerationtrue. In an article, type \articletoc where you want the contents to appear. In a book, type instead \booktoc where you want the table of contents to appear. You may want to type \pageno=-1 before the table appears and \pageno=1 after. You will have to run TEX twice to get proper output; likewise, if you make changes that change page numbers, you will have to rerun TEX twice. A file is created named \jobname.toc that has macros that produce the table of contents. Entries are automatically created by the macros \bchap (in a book) and \bsection. Additional ones can be made by

    \writetocentry{misc}{Entryname}.

(The word misc should not be replaced by another word.)

Figures

To number figures, write \figlabel{name}, which will produce Figure 2.3., for example; to refer to it, write \ref f.name/. The switch

    \figuresectionnumberstrue

does for figures what \sectionnumberstrue does for equations. The switch

    \continuousfigurenumberingtrue
is analogous to \continuousnumberingtrue.

Bibliography

The bibliography should start with \startbib, followed by a blank line, and end with \endbib, preceded by a blank line. Each item should start with \bibitem[cite-name]{ref-name}. In the body, you refer to such an item with \ref b.ref-name/. This produces the output “[cite-name]”, unless \nobracketcittrue is set, in which case it produces “cite-name”. An alternative is to use \ref B.ref-name/. This will set the switch \bibparenfalse, whereas the other command sets the switch true. If apaliketrue, then with \ref b., one gets “author (year)”, while with \ref B., one gets “author, year”. The latter is useful if the citation is already in parentheses.

In order to create output like “Author (year1, year2)”, type \refbmulti{ref-name1,ref-name2}. Any number of keys can be accomodated, as a comma-separated list without spaces.

If you want to refer only to the author’s name, use \refbauthor {ref-name}, whereas to refer only to the year of publication, use \refbyear {ref-name}. Note that in order for these latter to work, there must be somewhere a full reference of the form \ref b.ref-name/ — unless you have \citationgenerationtrue set, which we now explain.

If \citationgenerationtrue is set, then each use of \ref b.ref-name/, of \refbauthor {ref-name}, or of \refbyear {ref-name} causes \citation{ref-name} to be written to the file \jobname.aux. If you want a reference to appear in the bibliography that is not cited, then put \citeinc {ref-name} somewhere. This allows the automatic creation of bibliographies with BibTEX. In that case, you’d also want to use the commands \bibfile{name} and \bibsty{name}, to put in the aux file directions for BibTEX as to which .bib and .bst files to use (note that the .bst file must describe compatible output, so not every .bst is compatible with the Ref.macros package). I use myapalike.bst, which fixes some bugs in apalike.bst and is fully compatible with Ref.macros. In particular, it sets the switch \apaliketrue. Thus, near the beginning of the main file, I put \bibsty{myapalike}.

An alternative style is to set the switch \bibnamestrue, but this is not supported and needs additional work.

There are, in fact, two ways to refer to bibliographic items, and both may be used at once without any special commands. Namely, \ref b.ref-name/ actually refers to whatever the macro \csname BK@refname\endcsname expands to if this macro is defined, and otherwise to ref-name. Thus, rather than having to use the MR numbers as labels for BibTEX to operate with, one can use one’s own more easily remembered labels, and define them to be the corresponding MR number. For this purpose, the macro \bibkey ref-name ref-key is available; note that both arguments are delimited by spaces. If you need to use the ref-key in some other way, you may access it by \bibcode ref-name, which expands to ref-key. You might want to have a file \jobname.key that contains lines such as

    \bibkey Adams:trees MR91d:28041

You could also put your command \bibfile{name} there.

When you use BibTEX, under certain conditions, it will add an entry that does not in fact appear anywhere in what you wrote, except in a bib file that was used. This is a crossreference. You can suppress this feature by calling BibTEX with the option -min-crossrefs=number, where number is any sufficiently large number that no crossreference is mentioned that many times. On the other hand, if you like this feature, then what BibTEX also does is to use a \cite{crossref-label} command with the label it found in your bib file. Therefore, Ref.macros defines a \cite command. It acts like a \ref b.crossref-label/ command would at that point. In particular, when TEX is run again, the cross reference will go into your aux file. In addition, \cite will warn you that BibTEX has done this sneaky thing.

Sometimes BibTEX will alphabetize correctly, but that is not the order you want. For example, an author may have published two papers in the same year, but one preceded the other in time, yet not alphabetically. One way to get the order one wants is to add at the beginning of a title {\noop{z}}, which will make BibTEX use “z” as the first letter for the purpose of ordering, yet which will not appear in print. Don’t forget that you then have to put the first letter of the real title in braces in order that it be capitalized.

In order to have a hyperlink to a preprint (or other article), the macro \preprintref {URL} may be used. If the link is to the arXiv, then one can type just the abstract number with the macro \arXiv {number}, which prepends the URL http://www.arxiv.org/abs/ and makes it a hyperlink.

Hyperlinks

If \hyperstrue is set, then every \ref TYPE.name/ produces a hyperlink to the appropriate target. This will work only if your dvi previewer has hyperlink capabilities, of course. Even if not, you can convert to a PDF file either directly from dvi or via PostScript. Then hyperlinks should work.

For additional hyperlinks, provided that \hyperstrue is set, the command \htmlanchor{name}{text} makes text an html anchor; the command \htmllocref{name}{text} makes text a hyperlink to an anchor name appearing elsewhere in the output; and the command \htmlref{url}{text} makes text a hyperlink to an external URL. The command \emailwww{name@host.domain}{url} produces a sort of signature with email and url, appropriately hyperlinked. Note that in the url, it is best to use \string~ in place of ~, as the ordinary tilde acts as a tie for TEX, and other methods of placing “˜ ” would not work with hyperlinks. For just a hyperlinked email address, use \email{name@host.domain}.

If \dvipdfmtrue is set, then the chapters and sections will produce bookmarks when viewed as a pdf file, provided you use dvipdfm to convert the dvi file to a pdf file. It will also make the pdf file open with the bookmarks visible. If you want to add additional bookmarks, use the command \pdfbookmark{level}{text}, where the level is 1 for the highest level, 2 for a sublevel of 1, etc., while the text is what you want to appear as the name of the bookmark.

Exercises

Exercises are treated differently from other objects since, commonly, we do not want to bother labelling them. Furthermore, we may decide to have them automatically grouped at the end of a chapter or section, even if we don’t place them there ourselves, and we may want to put in solutions where the exercises appear, to be gathered and output elsewhere. It is assumed that these macros will be used only in a work with chapters.

To number and begin an exercise, write \exer. Finish it by \endexer. This will insert the exercise in a format similar to that of the TEXbook. If you want to label the exercise, begin instead by \exer \exlabel name. To refer to a labelled exercise, write \exref name/. Use \briefexref if you do not want the word “Exercise” prepended. If you want to add a name to the exercise, type \exname{name} before the body of the exercise.

If you want the exercise to be collected and appear in the dvi file later than where it appears in the tex file, use the switch \laterexerstrue when initializing and use \laterexer in place of \exer. This will copy everything until the next blank line into a file called \jobname.exr. Note that the exercise of \laterexer must begin on the same line as the macro, since otherwise, TEX will think it is done, having reached a blank line. (It suffices to use % after \laterexer and begin the text on the next line. If you forget, TEX will complain by saying that there is an extra \endgroup arising from \endexer and will finish the run inside a group at level 1.) When you want what is collected to appear, type \hereexer{name} (for example, at the end of a chapter). This will create a new section called “Additional Exercises” and input \jobname.exr. The exercises will appear in ninepoint roman. The section can be referred to (if ever desired)

by \ref s.exers-name/.

If you are collecting exercises for later and want to insert material in \jobname.exr (for example, some words about a series of exercises), type \laterexerinsert and everything until the next blank line will be inserted.

If you want to collect in-text exercises to duplicate later, then use \textexerstrue. This will make \exer serve double duty. The second duty is to copy everything until \endexer into a file called \jobname.txr. When you want what is collected to appear, type \heretextexer{name} (for example, at the end of a chapter). This will create a new section called “Collected In-Text Exercises” and input \jobname.txr. The exercises will appear in ninepoint roman. The section can be referred to (if ever desired) by \ref s.textexers-name/. An internal switch called \iftextcollect is used to determine whether the exercise is appearing for the second time. This temporarily changes the meaning of \label #1 to \eqno \ref #1/ (in case an equation is defined in the exercise) and allows different wording to be used in the two places the exercise appears. For example, you could use

    \exer Prove \iftextcollect \ref c.easy/. \else this. \fi

\endexer

The duplicate exercise has the same number and is hyperlinked back to the original exercise. A useful trick sometimes is to use \iftextcollect{} in order to avoid gobbling the space that will follow.

To have solutions collected and appear at the end, use the switch \solutionstrue when initializing. After any particular exercise whose solution you want treated this way, write \soln and follow it by the solution. The solution must begin on the same line as \soln and end with a blank line. If the solution is longer than one paragraph, separate the paragraphs by \item{}. Remember that if the solution is to a \laterexer, it should not be separated by a blank line from the exercise itself. The solutions will be written to a file called \jobname.sln.

When ready to input the solution file, write something like

\vfill\supereject
\immediate\closeout\solnfile
\openin\solnfile=\jobname.sln
\ifeof\solnfile\relax
\else
    \ifproofmode
    \else\headline={\tensc Comments on Exercises
\hfill\tenbf \folio}
    \fi
    \begingroup\parskip=3pt
    \vglue30pt
    \centerline{\chapfont Comments on Exercises}
    \vskip30pt
    \writetocentry{misc}{Comments on Exercises}
    \ninepoint
    \eqlabelno=0\theoremlabelno=0\figureno=0
        % This is in case the solutions use automatic labelling.
    \input \jobname.sln
    \vfill\eject
    \endgroup
\fi
\immediate\closein\solnfile

Miscellaneous

To begin a notes section, type \beginnotes{name}. This will begin a new section referenceable by \ref s.notes-name/. The section itself will appear in ninepoint. End the section with \endnotes.

The macro \today prints out today’s date and \timestring prints out the time in 12-hour format. Note: the ninepoint font environment used in certain places for books must be supplied if you want

it; there is one in math.macros, modified from one in manmac.tex. In proofmode, the headline uses an eightpoint environment; a simple one is provided by default, but a full one should be provided by defining \eightpoint if the user wants everything to appear properly. Again, one appears in math.macros.

The package redefines \end so that the overall warning about changes to labels comes at the end of the run. The old value of \end is saved in \END.