The showlabels package^{∗}

Norman Gray

                 norman@astro.gla.ac.uk

1999/02/22

This is the showlabels package.

This package introduces no new commands, it just helps you keep track of all the labels by putting the name of the new label into the margin whenever either the \label command is used, or an equation is automatically numbered (by replacing the internal \@eqnnum command). There are therefore no usage instructions. You invoke this package with the command \usepackage{showlabels} in the preamble, and you may give the options inner or outer (the default) to have the labels placed in the inner or outer margin of the text. If you don’t use the twoside option, then all pages are ‘right-hand’ pages, and the ‘outer margin’ is the right hand one.

The package will also work in the presence of the twocolumn option. In this case, the options inner and outer will be ignored, and the label will be placed in the nearer margin.

In version 1.1, the package was modified to conform to the slightly different mechanism that amsmath uses to produce equation numbers. I don’t habitually use amsmath, so I won’t discover any bugs or weaknesses with its support here, and I’d consequently be glad to be informed of any that appear. Do note that the \usepackage{showlabels} command must appear after the \usepackage{amsmath}. Note also that, since these additions appeared, AMS-L^{A}TEX and the amstex package seem to have been declared ‘obsolete’. This package now claims conformance with the amsmath package alone.

If you want to change the font the labels appear in, use something along the

lines of \renewcommand{\showlabelsfont}{\small\slfamily}.

For reasonably obvious reasons, this package will not work at all well with the multicol package, and for possibly less obvious reasons, it won’t work with the leqno option either (at some point it should be modified to at least recognise and warn of the conflict in either case, though it’s not obvious to me how to do that).

The package might still work with L^{A}TEX2.09, but that’s not supported, nor even tested.

1 History and Credits

For version 1.3, I received comments and bug reports from:

   • David R. Leal Valmana <david@quijote.uc3m.es>

∗This file has version number v1.3, last revised 1999/02/22, documentation dated 1999/02/22

• Sungmo Park <smp@dingo.etri.re.kr>
• Olivier Michel <Olivier.Michel@lri.fr>
• Jiri Vesely <jvesely@karlin.mff.cuni.cz>
• Patrick Sibille <sibille@amoco.saclay.cea.fr>
• Hagen Kleinert <kleinert@physik.fu-berlin.de>
• Francis M. C. Ching <fmcching@kingcong.uwaterloo.ca>
• Michael Friendly <friendly@hotspur.psych.yorku.ca>

Back in 29-Jan-92, Darrel Hankerson <hank@ducvax.auburn.edu>, made the update to NFSS, and changed the name to ‘showlabel.sty’.

Originally released 21-Sep-91 by me, under the name labels.sty.

2 The driver file

Nothing fancy.

1 ⟨∗driver⟩

2 \documentclass{ltxdoc}
3 \EnableCrossrefs

Some commonly used abbreviations for option names, filenames, counters and packages.

4 \newcommand\Lopt[1]{\textsf {#1}}
5 \newcommand\file[1]{\texttt {#1}}
6 \newcommand\Lcount[1]{\textsl {\small#1}}
7 \newcommand\pstyle[1]{\textsl {#1}}
8 \date{\docdate}

The body of the style. Include all the details.

9 \begin{document}
10 % \OnlyDescription %uncomment to suppress the source listing
11 \DocInput{showlabels.dtx}
12 \PrintIndex
13 \PrintChanges
14 \end{document}

15 ⟨/driver⟩

3 The package

16 ⟨∗package⟩

17 \NeedsTeXFormat{LaTeX2e}
18 \ProvidesPackage{showlabels}[1999/02/22 v1.3]
19 \typeout{Package: `showlabels' v1.3\space<1999/02/22>}
20 \wlog{Documentation}

Before we do anything else, find out if we’re using AMS-L^{A}TEX. … Note that, since these additions appeared, AMS-L^{A}TEX and the amstex package seem to have been declared ‘obsolete’. This package now claims conformance with the amsmath package.

21 \newif\ifSL@AMS
22 \expandafter\ifx\csname maketag@@@\endcsname\relax
23 \SL@AMSfalse
24 \else
25 \SL@AMStrue
26 \typeout{with AMS-LaTeX equation tags}
27 \fi

\@eqnnum This replacement for \@eqnnum will produce a note, sticking into the margin beside the equation number, showing the equation’s label. \SL@labeln@me is initialised to \relax, redefined within the \label macro, and reset to \relax here. If it’s already equal to \relax here, the equation number hasn’t been labelled, and so ‘???’ is put in the margin. Don’t do this for the AMS-L^{A}TEX case as it artfully incorporates the \maketag@@@ mechanism into a redefined \@eqnnum.

28 \ifSL@AMS

AMS-L^{A}TEXuses \maketag@@@, to form tags in equations. All we have to do is hook into the \maketag@@@ macro, and use \df@label, which is pre-defined with the current label name.

29 \let\@maketag@@@=\maketag@@@
30 \def\maketag@@@#1{\@maketag@@@{#1}%
31 \ifx\df@label\@empty
32 %    \SL@eqnlrtext{???}%
33 \else
34  \SL@eqnlrtext{\df@label}%
35 \fi}
36 \else

The ‘normal’ case, without AMS-LaTeX

37 \let\@@eqnnum=\@eqnnum
38 \def\@eqnnum{\@@eqnnum
39 \ifx\SL@labeln@me\relax
40  \SL@eqnlrtext{???}%
41 \else
42  \SL@eqnlrtext{\SL@labeln@me}%
43  \global\def\SL@labeln@me{\relax}%
44 \fi}

And initialise the value of \labeln@me to \relax, so that \@eqnnum starts off behaving the right way.

45 \global\def\SL@labeln@me{\relax}
46 \fi

Labels are printed with the font specified by \showlabelfont, which can be overridden within the document:

47 \def\showlabelfont{\small\tt}

Leave this as \small\tt, to avoid a pointless incompatibility with L^{A}TEX2.09.

For the benefit of \prlabelname, define \SL@gobblethree to do nothing other than eat three tokens.

48 \def\SL@gobblethree#1#2#3{}

\prlabelname Expansion is label name with all catcodes ‘other’ (Appendix D trickery abounds!). Use \r@#1, rather then just \#1 to avoid defining any new control sequences.

49 \def\prlabelname#1{%
50 \expandafter\expandafter\expandafter\SL@gobblethree
51  \expandafter\string\csname r@#1\endcsname}

\@makecaption Simple replacement for the \@makecaption command. This simply issues the original \@makecaption command after redefining \label. This does not put the label name in the margin (that’s too complicated for the moment), but instead inserts it as part of the caption.

52 \let\@@makecaption\@makecaption
53 \long\def\@makecaption#1#2{{\def\label##1{{\showlabelfont
54 \{\prlabelname{##1}\}\space}\SL@label{##1}}%

… and follows it with the original, saved, \@makecaption.

55 \@@makecaption{#1}{#2}}}

\label This is the central bit of this package. Depending on the mode, put the current label name in the margin in one of a variety of ways. First of all, issue the saved

\SL@label command.
56 \let\SL@label\label
57 \def\label#1{\@bsphack\SL@label{#1}%

In maths mode, produce a label name alongside the equation number. If we’re not using AMS-L^{A}TEX, then save the label name in \SL@labelname. If we are using AMS-L^{A}TEX, then we don’t have to worry, because it’s saved in \df@label for us.

58 \ifmmode
59  \ifSL@AMS\else
60  \xdef\SL@labeln@me{\prlabelname{#1}}%
61  \fi

Otherwise, create a box with zero height and depth, and the same width as the page. Put all this in braces, to contain the setting of \box0 (which probably shouldn’t be necessary).

62 \else
63  {\setbox0=\vbox to 0pt{\vss
64  \hbox to \columnwidth{\SL@lrtext{#1}}}%
65  \dp0=0pt

and attach it below the last one, using \nointerlineskip if we’re in vertical mode, or \vadjust otherwise.

66  \ifvmode
67  \nointerlineskip\box0\nobreak
68  \else
69  \vadjust{\box0\nobreak}%
70  \fi}%

That’s it. Finish off the \ifmmode and give the partner to \@bsphack.

71 \fi
72 \@esphack}

\margintext Set the actual text of the label. Use \prlabelname here: without this, a label command given outside of an equation or a \caption will appear wrongly if the label has things like underscores within it.

73 \def\SL@margintext#1{{\showlabelfont\{\prlabelname{#1}\}}}

But where is the marginal text actually set? It can be in the left margin, the right one, or can alternate. \SL@lrtext, used in the \vbox above, is set, under

the control of \if@outerlabels below, to one of \SL@lefttext, \SL@righttext
or \SL@alternatetext.
\SL@righttext
\SL@lefttext
74 \def\SL@righttext#1{\hfill\rlap{\quad\SL@margintext{#1}}}
75 \def\SL@lefttext #1{\llap{\SL@margintext{#1}\quad}\hfill}

The code for \SL@alternatetext doesn’t work perfectly, as it sometimes manages to get things on the wrong side of the text near the top of a new page. This is a venial slip, however, as this package should never be used in a final version.

\SL@alternatetext
76 \def\SL@alternatetext{%
77 \if@outerlabels
78  \ifodd\c@page
79  \let\SL@next\SL@righttext\else
80  \let\SL@next\SL@lefttext\fi
81 \else
82  \ifodd\c@page
83  \let\SL@next\SL@lefttext\else
84  \let\SL@next\SL@righttext\fi
85 \fi
86 \SL@next}

The case where the twocolumn option is set is slightly different. There we have to switch between placing the note in the left and right margins, depending on whether we’re setting the first or second column. This macro, and \SL@eqntwocoltext below, uses the switch \if@firstcolumn to decide whether it’s in the first or the second column of the text (I suppose it’ll get terribly confused if we use multicol.sty along with this). This is defined and maintained in the base file ltoutput.dtx. It’s not part of the defined interface, however (there doesn’t seem to be one, grump), so I don’t suppose we should really rely on it. There isn’t an option, however.

\SL@twocoltext
87 \def\SL@twocoltext{%
88 \if@firstcolumn
89  \let\SL@next\SL@lefttext
90 \else
91  \let\SL@next\SL@righttext
92 \fi
93 \SL@next}

We have very similar things for equations, except that they are set in place, rather than within a zero depth box. This code ASSUMES that equation numbers are going to be on the right hand side of the page. It should probably check for the existence of the leqno option (how?).

\SL@eqnrighttext
\SL@eqnlefttext
94 \def\SL@eqnrighttext#1{\rlap{\quad\SL@margintext{#1}}}
95 \def\SL@eqnlefttext #1{\hbox to 0pt{\kern -\columnwidth
96 \llap{\SL@margintext{#1}\quad}\hss}}

Now do the analogues for the equation numbers, in the case of the alternate page selection…

\SL@eqnalternatetext
 97 \def\SL@eqnalternatetext{%
 98 \if@outerlabels
 99  \ifodd\c@page
100  \let\SL@next\SL@eqnrighttext\else
101  \let\SL@next\SL@eqnlefttext\fi
102 \else
103  \ifodd\c@page
104  \let\SL@next\SL@eqnlefttext\else
105  \let\SL@next\SL@eqnrighttext\fi
106 \fi
107 \SL@next}

… and the twocolumn option

\SL@eqntwocoltext
108 \def\SL@eqntwocoltext{%
109 \if@firstcolumn
110  \let\SL@next\SL@eqnlefttext
111 \else
112  \let\SL@next\SL@eqnrighttext
113 \fi
114 \SL@next}

To keep track of things, declare the \if@outerlabels switch, and set it true by default.

115 \newif\if@outerlabels
116 \@outerlabelstrue

We select between the various possibilities using the outer and inner options and, implicitly, the twoside option.

117 \DeclareOption{outer}{\@outerlabelstrue}
118 \DeclareOption{inner}{\@outerlabelsfalse}

Process any options that have been set.

119 \ProcessOptions

and use the values of \if@outerlabels and if@twoside which may have been set by those options, to set \SL@lrtext to be the appropriate control sequence. The presence of the twocolumn option means that we ignore the inner and outer options.

120 \if@twocolumn
121 \let\SL@lrtext\SL@twocoltext
122 \let\SL@eqnlrtext\SL@eqntwocoltext
123 \else
124 \if@outerlabels
125  \if@twoside
126 \let\SL@lrtext\SL@alternatetext
127 \let\SL@eqnlrtext\SL@eqnalternatetext
128  \else
129  \let\SL@lrtext\SL@righttext
130  \let\SL@eqnlrtext\SL@eqnrighttext

131  \fi
132 \else
133  \if@twoside
134 \let\SL@lrtext\SL@alternatetext
135 \let\SL@eqnlrtext\SL@eqnalternatetext
136  \else
137  \let\SL@lrtext\SL@lefttext
138  \let\SL@eqnlrtext\SL@eqnlefttext
139  \fi
140 \fi
141 \fi

That’s us.

142 ⟨/package⟩