Debian Codegraph @

texmf-dist/source/latex/showlabels/showlabels.dtx

raw
1 % \iffalse % meta-comment
2 %
3 %% This is the showlabels package
4 %%
5 %%%% Copyright 1999, 2001-09, 2013-22, 2025, Norman Gray
6 %%
7 %% This work may be distributed and/or modified under the
8 %% conditions of the LaTeX Project Public Licence, either version 1.3c
9 %% of this licence or (at your option) any later version.
10 %% The latest version of this licence is in
11 %% http://www.latex-project.org/lppl.txt
12 %% and version 1.3c or later is part of all distributions of LaTeX
13 %% version 2005/12/01 or later.
14 %%
15 %% This work has the LPPL maintenance status `maintained'.
16 %%
17 %% The Current Maintainer of this work is Norman Gray <https://nxg.me.uk>
18 %%
19 %% This work consists of the files showlabels.dtx and showlabels.ins,
20 %% and the derived file showlabels.sty.
21
22 %%%% File: showlabels.dtx
23 %%%% Source: 66d69fa049ab, 2025-08-20T22:15:23+01:00
24
25 % This is revision 66d69fa049ab, 2025-08-20T22:15:23+01:00.
26 %<+package>\NeedsTeXFormat{LaTeX2e}
27 %<+package>\ProvidesPackage{showlabels}[2025/08/20\space v1.9.3]
28 %<+package>\typeout{Package: `showlabels' v1.9.3\space<2025/08/20>}
29 %
30 %<*driver>
31 \documentclass{ltxdoc}
32 \EnableCrossrefs
33 % \end{macrocode}
34 % Some commonly used abbreviations for option names, filenames,
35 % counters and packages.
36 % \begin{macrocode}
37 \newcommand\Lopt[1]{\textsf{#1}} % package options
38 \newcommand\file[1]{\texttt{#1}} % filename
39 %\newcommand\Lcount[1]{\textsl{\small#1}}
40 \newcommand\Lenv[1]{\textsl{\{#1\}}}
41 \newcommand\Lpackage[1]{\textsf{\{#1\}}} % packages
42 %% \url macro (url.sty does this better, but we don't want extra dependencies)
43 \def\setpathdots{\discretionary{.}{}{.}}
44 \def\setpathslash{\discretionary{/}{}{/}}
45 {\catcode`\.=\active
46 \catcode`\/=\active
47 \gdef\pathcats{%
48 \catcode`\%=12 \catcode`\~=12
49 \catcode`\.=\active \let.\setpathdots
50 \catcode`\/=\active \let/\setpathslash
51 \catcode`\#=12 \catcode`\_=12}%
52 }
53 \def\setpath#1{\ttfamily <\nobreak #1\nobreak>\endgroup}
54 \def\url{\begingroup\pathcats\setpath}
55 \begin{document}
56 % \OnlyDescription
57 \DocInput{showlabels.dtx}
58 \PrintIndex
59 \end{document}
60 %</driver>
61 %
62 % \fi
63 %
64 %
65 % \title{The \texttt{showlabels} package}
66 % \author{Norman Gray\\https://nxg.me.uk}
67 % \date{Version 1.9.3, 2025 August 20}
68 %
69 % \maketitle
70 %
71 % This package helps you keep track of all the labels you define, by
72 % putting the name of new labels into the margin whenever the
73 % |\label| command is used.
74 %
75 % You can do the same thing for other commands (see below).
76 % The only one for which this is \emph{obviously} useful is the
77 % |\cite| command, but it is also reasonable to do it with, for example,
78 % the |\ref| or |\begin| commands.
79 %
80 % Invoke this package with the command |\usepackage{showlabels}| in
81 % the preamble, and you may give the following options:
82 % \begin{quotation}
83 % \begin{tabular}{lp{25em}}
84 % \Lopt{outer} & [default] all notes are placed in the text's outer
85 % margin\\
86 % \Lopt{inner} & \dots inner margin\\
87 % \Lopt{left} & \dots left margin\\
88 % \Lopt{right} & \dots right margin\\
89 % \Lopt{marginal} & [default] put notes in the margin\\
90 % \Lopt{inline} & put notes inline, as much as possible, and ignore
91 % any of the margin-placement options above \\
92 % \Lopt{nolabel} & do not insert a marginal note for |\label| commands
93 % (see command |\showlabels| below)\\
94 % \Lopt{draft} & [default] does nothing, partner of\dots\\
95 % \Lopt{final} & turns off all the package's functionality
96 % \end{tabular}
97 % \end{quotation}
98 % If you don't use the \Lopt{twoside} option,
99 % then all pages are `right-hand' pages, and the `outer margin' is the
100 % right hand one.
101 %
102 % The package will also work in the presence of the \Lopt{twocolumn}
103 % option. In this case, the options \Lopt{inner}, \Lopt{outer},
104 % \Lopt{left} and \Lopt{right} will be ignored, and the label will be
105 % placed in the nearer margin.
106 %
107 % Finally, we have the options \Lopt{final} and \Lopt{draft}. The option
108 % \Lopt{final} turns off all the functionality of this package. This
109 % is included so that if that
110 % option is given globally in the |\documentclass| declaration then this
111 % package does respect it. The \Lopt{draft} option does nothing, and therefore
112 % simply continues the default behaviour of this package; it is here
113 % to partner the \Lopt{final} option. Note that if any of the
114 % packages in your document preamble are loaded with a \Lopt{final}
115 % option, it will be set for all subsequent packages.
116 %
117 % \DescribeMacro{\showlabels}
118 % If you wish the package to do its magic with another command |\foo|
119 % which takes at least one argument (for example |\cite|),
120 % then give the command |\showlabels{foo}|.
121 % The default behaviour of the package is to give the command
122 % |\showlabels{label}| internally; if you don't want this to happen --
123 % perhaps because you \emph{only} want |\cite| commands highlighted --
124 % then give the option \Lopt{nolabel} to the |\usepackage| command:
125 % |\usepackage[nolabel]{showlabels}|.
126 %
127 % You can call |\showlabels{foo}| with commands which have starred
128 % forms, |\foo*{arg}|, or optional arguments, |\foo[opt]{arg}|. A
129 % technical wrinkle is that, in each case, the |{arg}| is read with
130 % all of its characters being catcode `other'; I~can't think of a
131 % realistic case where this is a problem, since the commands typically
132 % given to |\showlabels| will almost certainly do something equivalent
133 % to this anyway, but it is a mild change from the default behaviour
134 % of the command |\foo|.
135 %
136 % You can do this |\showlabels| step even with commands that you
137 % invoke only implicitly. If, for example, you want to label each of the
138 % entries in your bibliography, then |\showlabels{bibitem}|
139 % will do this for each of the items that appear in the
140 % \Lenv{thebibliography} environment, whether it is writen by you or
141 % by \BibTeX\ (if you use the `biblatex' package, then the
142 % corresponding command would be
143 % |\makeatletter\showlabels{blx@bibitem}\makeatother|, but notice that
144 % this is in principle an undocumented internal of the `biblatex'
145 % package, so may change).
146 %
147 % By default, the package displays labels in the margin of the
148 % document, but as an alternative, labels can be kept inline as much
149 % as possible; this is much more legible when there are multiple
150 % labels on a single line. To select this, give the option
151 % \Lopt{inline}, and to select the default behaviour, use
152 % \Lopt{marginal}.
153 %
154 % \DescribeMacro{\showlabelsinline}
155 % It is sometimes convenient (for example when a document encounters a
156 % situation which this package mishandles) to force inline labels
157 % temporarily, within a block or environment. Use the
158 % |\showlabelsinline| macro to do that.
159 % \DescribeMacro{\showlabelsmarginal}
160 % The corresponding |\showlabelsmarginal| command has the opposite
161 % effect (included for symmetry; it's less likely to be useful).
162 %
163 % \section{Formatting}
164 %
165 % If you want to change the font the labels appear in, redefine the
166 % |\showlabelfont| command, which by default expands to
167 % |\small\ttfamily|. For example, to have labels in a slanted font,
168 % and green, you could include the definition
169 % \begin{quote}
170 % |\renewcommand{\showlabelfont}{\small\slshape\color{green}}|
171 % \end{quote}
172 % in the preamble of your document (as long as you have loaded the
173 % \Lpackage{color} package, of course).
174 %
175 % Alternatively, the |\showlabels| command has an optional argument containing
176 % formatting commands, which allows you to format |\cite| labels, for
177 % example, differently from |\label|. Thus:
178 % \begin{quote}
179 % |\showlabels[\color{green}]{cite}|
180 % \end{quote}
181 % The optional formatting command can be either a font-changing
182 % command, as illustrated here, \emph{or} a command which takes a
183 % single argument, such as
184 % \begin{quote}
185 % |\showlabels[\fbox]{cite}|
186 % \end{quote}
187 %
188 % If, finally, you want complete control over the labels, you can
189 % instead override |\showlabelsetlabel|, which initially expands to
190 % just |\showlabelfont #1|. You can use this mechanism to get a
191 % variety of effects. For example, if you say
192 % \begin{quote}
193 % |\usepackage{showlabels,rotating}|\\
194 % |\renewcommand{\showlabelsetlabel}[1]|\\
195 % \null\qquad |{\begin{turn}{60}\showlabelfont #1\end{turn}}|\\
196 % \end{quote}
197 % then you end up with your labels at a jaunty angle in the margin.
198 %
199 % The command |\showlabeltype| will expand to the current label type
200 % (ie, `label' or `cite', etc), so it would be possible for
201 % |\showlabelsetlabel| to conditionalise on that, if you felt that
202 % were necessary.\footnote{The support for a one-argument command in
203 % $\backslash$\texttt{showlabels}, and the presence of the
204 % $\backslash$\texttt{showlabeltype} macro, were added in version 1.9.}
205 %
206 % If instead you want to adjust how inline markings are displayed, you
207 % can change the definition of the
208 % |\showlabelrefline| rule from its default.
209 % For example, defining this to be
210 % \begin{quote}
211 % |\color{red}\hrule width 0.1em height 1.5ex depth 0pt |
212 % \end{quote}
213 % produces a fattish red line, and defining it to be
214 % \begin{quote}
215 % |\hrule width 0pt height 1.5ex depth 0pt|
216 % \end{quote}
217 % suppresses the line but still positions the text between the lines.
218 %
219 % \section{Compatibility with other packages, and other problems}
220 %
221 % The \Lpackage{showlabels} package works by redefining the |\label|
222 % command, along with a few internal \LaTeX\ commands. All the other commands it
223 % defines are `hidden' by prefixing them with `\texttt{SL@}', with
224 % the exception of the user commands |\showlabelfont| and
225 % |\showlabelsetlabel|. Each of
226 % the three redefined commands carefully includes its previous
227 % definition. The \Lpackage{showlabels} package should therefore come
228 % \emph{last} of the packages you include using |\usepackage|.
229 %
230 % In version 1.1, the package was modified to conform to the slightly
231 % different mechanism that \texttt{amsmath} uses to produce equation
232 % numbers. Do note that the
233 % |\usepackage{showlabels}| command \emph{must} appear after the
234 % |\usepackage{amsmath}| if it is to detect that you are using the
235 % \Lpackage{amsmath} package.
236 %
237 % In version 1.3e, the package became compatible with the
238 % \Lpackage{hyperref} package in particular, and in general with other
239 % packages which themselves modify the |\label| command. This will
240 % work, however, only if the \Lpackage{showlabels} package is loaded
241 % after other packages which do this. Notwithstanding Sebastian
242 % Rahtz's excellent general advice on this, \Lpackage{showlabels} should
243 % be loaded after \Lpackage{hyperref}.
244 %
245 % In version 1.7, the package became compatible with the
246 % equation-numbering mechanism of the \Lpackage{IEEEtrantools}
247 % package. As with \Lpackage{amsmath}, this involves a certain amount
248 % of special-casing.
249 %
250 % For reasonably obvious reasons, this package will not work at all
251 % well with the \Lpackage{multicol} package, and for possibly less obvious
252 % reasons, it won't work with the \Lopt{leqno} option either (at some point
253 % it should be modified to at least recognise and warn of the conflict in
254 % either case, though it's not obvious to me how to do that). The
255 % package \emph{should} now work with \Lpackage{wrapfig}, though I'm not
256 % sure that I've exhausted that package's various clevernesses, and
257 % there might be some spacing and layout bugs which manifest
258 % themselves in that context. Please report them; in the mean time,
259 % using option \Lopt{inline} should act as a workaround for any that
260 % appear.
261 %
262 % When labels appear in the margins, they sometimes appear on the
263 % `wrong' side in \Lopt{twoside} mode. This is a fairly inevitable
264 % side-effect of the way that \TeX\ builds pages, and a specific
265 % symptom of the general problem described in
266 % \url{http://www.tex.ac.uk/cgi-bin/texfaq2html?label=oddpage}.
267 % As that answer suggests, there are bear-traps involved in the
268 % standard solutions. Now, showlabels is (a)~permanently teetering
269 % on the edge of clashing with everything else that messes around with
270 % labels, and (b)~a draft-only package rather than anything that
271 % would appear in a final document. (a)~means that I'm rather nervous
272 % about putting too much cleverness in there, and incidentally shy of
273 % putting any dependencies on other packages; (b)~means that I feel it
274 % doesn't really matter enough to be worth removing robustness. So
275 % I'm afraid I don't plan to change this, and I simply put up with the
276 % occasional slip. Again the \Lopt{inline} option is a possible
277 % workaround.
278 %
279 % The package might still work with \LaTeX2.09, but that's neither
280 % supported, nor even still tested.
281 %
282 % This software is copyright, 1999, 2001-09, 2013-22, 2025 Norman Gray.
283 % It is released under the terms of the \LaTeX\ Project Public Licence.
284 % See the copyright declaration at the top of file \texttt{showlabels.dtx},
285 % and the file \texttt{lppl.txt}, for the licence conditions.
286 %
287 % The canonical home page of the package is
288 % \url{https://purl.org/nxg/dist/showlabels}, and it is on CTAN at
289 % \url{https://ctan.org/pkg/showlabels}. The source is in
290 % a repository online: \url{https://heptapod.host/nxg/showlabels}.
291 %
292 % \section{Other packages}
293 %
294 % The \Lpackage{showlabels} package has a large overlap in
295 % functionality with David Carlisle's \Lpackage{showkeys}, although
296 % the latter will only handle |\label| and |\cite| keys. If
297 % \Lpackage{showlabels} fails in some particular situation, you might
298 % want to try using \Lpackage{showkeys}, but please do mention the
299 % problem, typically by email to me.
300 %
301 % \section{History and Credits}
302 %
303 % I've received bug reports, fixes, or implementable suggestions from many
304 % people, including
305 % Andreas Balser,
306 % bartgol (on Stackexchange),
307 % Francesco Biccari,
308 % Francis M. C. Ching,
309 % Sven de Vries,
310 % A L Dukeman,
311 % Michael Friendly,
312 % Guillermo Garza,
313 % Romano Giannetti,
314 % Tino G\"ortem\"oller,
315 % Lester L. Helms,
316 % Boris Kheyfets,
317 % Hagen Kleinert,
318 % David R. Leal Valmana,
319 % Olivier Michel,
320 % Aaron Montgomery,
321 % Enno Nagel,
322 % Sungmo Park,
323 % Ignacy Sawicki,
324 % Mike Schroeder,
325 % Andrei Shelankov,
326 % Patrick Sibille,
327 % `Stirling' (on Stackexchange),
328 % Mariano Su\'arez-Alvarez,
329 % Ji\v ri Vesely,
330 % Elmar Walhorn,
331 % Alex Watson,
332 % Ben William Carabelli,
333 % Roland Winkler.
334 % Many thanks to all. If I've missed your name out of this list
335 % (or indeed if I've alphabetised you incorrectly),
336 % please accept my apologies, and do let me know.
337 %
338 % The package was originally released by me on 1991 September 21, under the name
339 % \texttt{labels.sty}.
340 % On 1992 January 29, Darrel Hankerson
341 % \url{[email protected]}, made the update to NFSS, and
342 % changed the name to `showlabel.sty'.
343 %
344 % \subsection{Release notes}
345 % \begingroup
346 % \iffalse the following are variously unsatisfactory
347 % \def~{\texttt{\textasciitilde}}
348 % \def~{$\sim$}
349 % \fi
350 % \catcode`\~=12
351 % \iffalse @RELEASENOTES@ \fi
352 % \begin{description}\item[1.9.3, 2025 August 20]\relax Feedback suggests the reported problems seems resolved in practice.
353 % No changes from 1.9.3-b1, beyond some minor documentation and
354 % bundling adjustments.\par \item[1.9.3-b1, 2025 August 10]\relax \P\thinspace Fixed an (invisible) duplication in the amsmath support.
355 % Thanks to the discussion on a
356 % LaTeX3 issue\footnote{\url{https://github.com/latex3/latex2e/issues/118}}
357 % for the clue here. \P\thinspace Fix: handling of colours
358 % (issue 3\footnote{\url{https://heptapod.host/nxg/showlabels/-/issues/3}};
359 % thanks to Aaron Montgomery for reporting). \P\thinspace Fix: when marking non-|\label| commands, if
360 % these were found within non-display maths mode, then they didn't
361 % appear as shown labels
362 % (issue 4\footnote{\url{https://heptapod.host/nxg/showlabels/-/issues/4}};
363 % thanks to Mike Schroeder for reporting). \P\thinspace Fix: labels were being spuriously reported when using
364 % amsmath's |\eqref| command
365 % (issue 6\footnote{\url{https://heptapod.host/nxg/showlabels/-/issues/6}};
366 % thanks to Tamas Lakoba for reporting)\par\item[1.9.2, 2022 July 18]\relax No code changes from 1.9.2-b1, but the documentation notes a new home repository.\par \item[1.9.2-b1, 2022 June 11]\relax \P\thinspace Fixed a spacing bug when used with the |wrapfig| package
367 % (issue 2\footnote{\url{https://heptapod.host/nxg/showlabels/-/issues/2}};.
368 % Thanks to Romano Giannetti for the report). \P\thinspace Added a |\showlabelsmarginal| command. \P\thinspace The code has moved (again) to
369 % heptapod.host\footnote{\url{https://heptapod.host}}: the new
370 % repository is
371 % https://heptapod.host/nxg/showlabels\footnote{\url{https://heptapod.host/nxg/showlabels}}.
372 % The issues links in the list below are therefore broken.\par\item[1.9.1, 2021 October 27]\relax Commands with optional arguments, such as
373 % |\bibitem[P\'olya]{polya_54}| are now handled with the
374 % correct catcodes.
375 % Fixes issue 1\footnote{\url{https://heptapod.host/nxg/showlabels/-/issues/1}}
376 % (\emph{Note:} new sequencing for issues, after a repo change).
377 % Thanks to Michael Levitin for the report here.\par \item[1.9, 2021 October 9]\relax \P\thinspace Robustness fix: macros in arguments are now handled, so that
378 % (after |\showlabel{index}|),
379 % |\index{Poincar\'e}| doesn't cause an error. \P\thinspace The |\showlabel[optarg]{command}| optional argument
380 % can now take a one-argument command. \P\thinspace The macro |\showlabeltype| expands to the current
381 % label type, for possible use in |\showlabelsetlabel|.\par\item[1.8, 2016 June 9]\relax The |ntheorem| package exposed an apparently
382 % long-standing incompleteness in the handling of |amsmath|
383 % documents.
384 % Fixes issue 9\footnote{\url{https://bitbucket.org/nxg/showlabels/issues/9/}}.\par \item[1.7, 2015 December 8]\relax Release v1.7.\par \item[1.7b2, 2015 December 7]\relax Make the combination of amsmath and [inline] mode work
385 % (fixes issue 8\footnote{\url{https://bitbucket.org/nxg/showlabels/issue/8/}}
386 % – thanks to A L Dukeman for the report;
387 % what is it about showlabels and 6 December?!).\par \item[1.7b1, 2014 December 6]\relax This is a much-delayed bugfix release (by coincidence
388 % \emph{exactly} a year after the previous release!).\par \P\thinspace Give |\showlabels| an optional formatting argument
389 % (implements issue 1\footnote{\url{https://bitbucket.org/nxg/showlabels/issue/1/}}
390 % – thanks to Francesco Biccari for the suggestion). \P\thinspace Special-case the IEEEtrantools package
391 % (fixes issue 2\footnote{\url{https://bitbucket.org/nxg/showlabels/issue/2/}}
392 % – thanks to Boris Kheyfets for the report and test case, and to
393 % Ben William Carabelli for additional analysis and a draft fix). \P\thinspace The |[final]| option now works with the
394 % |{amsmath}| package
395 % (fixes issue 3\footnote{\url{https://bitbucket.org/nxg/showlabels/issue/3/}}
396 % – thanks to Guillermo Garza and Enno Nagel for the report, and to
397 % Guillermo for the test case). \P\thinspace Handle the hyperref package's |\ref*{label}| variant
398 % (fixes issue 4\footnote{\url{https://bitbucket.org/nxg/showlabels/issue/4/}}
399 % – thanks to Alex Watson for the report and test case). \P\thinspace Handle the case where a label is in a display, but not in maths mode
400 % (fixes issue 5\footnote{\url{https://bitbucket.org/nxg/showlabels/issue/5/}}
401 % – thanks to ‘bartgol’ on Stackexchange for the report and test case).\par\item[1.6.6, 2013 December 6]\relax \P\thinspace Add configuration interface |\showlabelrefline| and
402 % ensure that |\color| works in
403 % |\showlabelfont|. \P\thinspace Various documentation tweaks. \P\thinspace Change licence from GPL to LPPL. \P\thinspace Fix link to repository.\par\item[1.6.5, 2009 May 27]\relax Fixed a bug in the way that labels including underscores (and
404 % other ‘exotic’ characters) were displayed.\par \item[1.6.4, 2008 October 10]\relax Fixed another poor interaction between eqnarray and amsart. Now
405 % we get equation labels in eqnarray, and we don't get marginal notes
406 % about |\eqref| (which is good; might this finally be fixed?).\par \item[1.6.3, 2008 July 24]\relax Release 1.6.2 broke compatibility with the \emph{rest} of
407 % amsmath (|eqnarray| became the only thing that worked
408 % within amsmath)! Fixed. Doh!\par \item[1.6.2, 2008 June 27]\relax The reimplementation of eqnarray within amsart was such that
409 % equation labels disappeared in that case. Fixed.\par \item[1.6.1, 2007 June 17]\relax Fix an errant test, which mangled equation labels starting
410 % with two identical letters.\par \item[1.6, 2006 May 26]\relax The |\showlabels| command will now work with commands
411 % (such as |\cite| or |\includegraphics|) which
412 % take an optional argument.\par \item[1.5a, 2005 March 17]\relax Defined |\showlabelfont| using
413 % |\ttfamily| rather than |\tt| (I'd
414 % avoided doing this before to avoid a seemingly pointless
415 % incompatibility with LaTeX 2.09, but (a) I imagine the
416 % package is incompatible with that for other reasons, and (b)
417 % it's really not worth the hassle...).\par \item[1.5, 2004 October 8]\relax Added |\showlabelfont| and
418 % |\showlabelsetlabel| commands, allowing
419 % customisation of the printed labels. Added and documented
420 % options [final], [draft] (the former makes this package do
421 % nothing; the latter is the default behaviour).\par \item[1.4a, 2003 January 28]\relax Acquired the |[left]| and
422 % |[right]| options, and fixed a bug which affected
423 % |\label| commands in captions.\par \item[1.4, 2001 July 24]\relax Became (more) compatible with the
424 % wrapfig package. Also, I added the
425 % |\showlabels| command, to have the package display
426 % references to commands other than |\label|
427 % (|\cite| and |\ref| are obvious ones),
428 % and an |[inline]| option to have labels (etc.)
429 % displayed inline where possible, rather than always in the
430 % margin.\par \item[1.3e, 2001 May 30]\relax Became compatible with the hyperref package in
431 % particular, and in general with other packages which
432 % themselves modify the |\label| command. This will
433 % work, however, only if the showlabels package is loaded after
434 % other packages which do this. Notwithstanding Sebastian
435 % Rahtz's excellent general advice on this, showlabels should
436 % indeed be loaded after hyperref.\par \item[1.3e, 2001 May 31]\relax After a long delay, here is an updated version of my showlabels
437 % package. It corrects all the reported bugs which I could reproduce,
438 % namely:\par \P\thinspace The package now formats labels correctly when the
439 % |\label| command appears outside either an equation or a
440 % |\caption| (silly of me). \P\thinspace A couple of people reported problems in the interaction with the
441 % amsmath package. Either these were confined to that package's earlier
442 % incarnations as AMS-LaTeX or the amstex package, or else there's some
443 % arcane circumstance I can't reproduce, so I haven't found anything to
444 % fix on this matter. Note that the
445 % |\usepackage{showlabels}| command must come \emph{after}
446 % the |\usepackage{amsmath}| command. Bug-sightings here
447 % will be warmly appreciated. \P\thinspace I haven't worried too much about the precise formatting of the
448 % labels – this is, after all, supposed to be a draft-only
449 % package.\par\item[1.1, 2001 January 1]\relax Modified to conform to the slightly
450 % different mechanism that |amsmath| uses to produce equation
451 % numbers. I don't habitually use |amsmath|, so I won't
452 % discover any bugs or weaknesses with its support here, and I'd
453 % consequently be glad to be informed of any that appear. Do note that
454 % the |\usepackage{showlabels}| command \emph{must} appear
455 % after the |\usepackage{amsmath}| if it is to detect that
456 % you are using the amsmath package. Note also that, since these
457 % additions appeared, AMS-LaTeX and the |amstex| package seem
458 % to have been declared ‘obsolete’ in favour of the |amsmath|
459 % package. This package now claims conformance with the
460 % |amsmath| package alone, though it will probably work with
461 % older versions in fact.\par This is the first version of the package to be distributed under
462 % the name |showlabels|.\par \item[Updated, 1992 January 29]\relax On 1992 January 29, Darrel Hankerson
463 % (|[email protected]|), made the update to NFSS, and
464 % changed the name to |showlabel.sty|.\par \item[Original, 1991 September 21]\relax The package was originally released by me on 1991 September 21, under the name
465 % |labels.sty|.\par \end{description}% \endgroup
466 %
467 % \MaybeStop
468 %
469 % \section{Implementation}
470 % \begin{macrocode}
471 %<*package>
472 % \end{macrocode}%
473 % \iffalse
474 % Update history:
475 % October 94: Norman Gray ([email protected]). Modified to be a
476 % \LaTeX2e package.
477 % 29-Jan-92 Darrel Hankerson ([email protected])
478 % Update to NFSS. Change name to `showlabel.sty'. Substitute
479 % \nintt -> \small\tt
480 % \sevit -> \scriptsize\it
481 % 21-Sep-91 Norman Gray [email protected]
482 % Original release of labels.sty
483 % \fi
484 %
485 % The principle command is |\SL@wrap@labeller|, which monkeypatches a
486 % command |\foo| by creating a command |\SL@origfoo| with the original
487 % definition, and (re)defining |\foo| to call that original version,
488 % while immediately including a call of a macro |\SL@set@text| which
489 % sets the argument of |\foo| appropriately.
490 %
491 % Without \Lpackage{amsmath}, the only thing remaining is to ensure
492 % (by default) a call |\SL@wrap@labeller{@eqnnum}|, to ensure that
493 % this happens to equation labels, too.
494 %
495 % \emph{With} \Lpackage{amsmath}, however, things are more
496 % complicated, since that package has an independent mechanism for
497 % setting equation labels. Almost all of the relevant
498 % \Lpackage{amsmath} code paths run through the command |\maketag@@@|,
499 % enough that this is really the only macro we need to patch. Most of
500 % the intricacy below comes from (i)~the slightly different sequence
501 % of the commands when labelling an equation in \Lpackage{amsmath},
502 % and (ii)~the fact that calls to |\maketag@@@| are not quite
503 % restricted to this case.
504 %
505 % Before we do anything else, find out if we're using \Lpackage{amsmath}.
506 % \begin{macrocode}
507 \newif\ifSL@AMS
508 \@ifundefined{maketag@@@}
509 \SL@AMSfalse
510 {\SL@AMStrue\typeout{with amsmath equation tags}}
511 % \end{macrocode}
512 %
513 % \begin{macro}{\SL@set@text}
514 % The command which sets equation text is |\SL@set@text|, which tests
515 % whether the content should be inline or not.
516 % \begin{macrocode}
517 \def\SL@set@text{%
518 \ifSL@labelsinline
519 \let\@tempa\SL@interlinetextleft
520 \else
521 \let\@tempa\SL@set@lrtext
522 \fi
523 \@tempa
524 }
525 % \end{macrocode}
526 % \end{macro}
527 %
528 % \begin{macro}{\SL@wrap@labeller}
529 % The |\SL@wrap@labeller| macro wraps the given macro in such a way
530 % that we display the label.
531 % |\SL@labelname| is initialised to |\relax|, redefined within the
532 % |\label| macro, and reset to |\relax| after use here. If it's
533 % already equal to |\relax| in this macro, the equation number hasn't
534 % been labelled, and so we avoid putting anything in the margin.
535 % \begin{macrocode}
536 \def\SL@wrap@labeller#1{%
537 \expandafter\let\csname SL@orig@#1\expandafter\endcsname\csname #1\endcsname
538 \expandafter\def\csname #1\endcsname{%
539 \csname SL@orig@#1\endcsname
540 \ifx\SL@labelname\relax
541 % do nothing
542 \else
543 \SL@set@text{\SL@labelname}%
544 \fi
545 \global\let\SL@labelname\relax}}
546 % \end{macrocode}
547 % \end{macro}
548 %
549 % First, deal with the case where the document uses the
550 % \Lpackage{amsmath} macros.
551 % \begin{macrocode}
552 \ifSL@AMS
553 % \end{macrocode}
554 %
555 % \begin{macro}{\maketag@@@}
556 % \Lpackage{amsmath} redefines |\label| to set the macro |\df@label|,
557 % and then uses |\maketag@@@{\df@label}| or |\tagform@| to form tags
558 % (ie, equation labels) in equations. The command |\tagform@| wraps
559 % |\maketag@@@|, so we needn't wrap both. Indeed, we \emph{mustn't}
560 % wrap both, or else we duplicate any side-effects that happen in
561 % there, such as typesetting the label! As discussed in a similar
562 % bugreport for \Lpackage{showkeys}
563 % (see \url{https://github.com/latex3/latex2e/issues/118} and test t/t21.tex),
564 % monkeypatching both commands ends up double-setting the equation
565 % label, which is invisible, but still wrong.
566 %
567 % If the |\df@label| is empty
568 % (almost certainly because the user has used the
569 % \Lenv{eqnarray} environment within \Lpackage{amsmath}),
570 % then fall back on the |\SL@labelname| contents instead.
571 % \iffalse See tests t2, t11 and t18. \fi
572 % We must make sure to leave |\SL@labelname| equal to |\relax| at the
573 % end of this macro, otherwise a |{eqnarray}| followed by an (amsmath)
574 % |\eqref| can end up with the wrong label being referred to by the
575 % |\maketag@@@| within |\eqref| (or something like that).
576 %
577 % The test here must be |\ifx\SL@labelname\relax| with
578 % |\global\let\SL@labelname\relax|, not |\expandafter\ifx\SL@...| and
579 % |\global\def\SL@labelname{\relax}| (as it once was), since the
580 % latter evaluates to true when |\SL@...| is |\relax| \emph{and} when
581 % |\SL@...| starts with two identical characters, which is wrong (it
582 % took embarrassingly many goes to get this right).
583 %
584 % The following is
585 % similar to the effect of |\SL@wrap@labeller|, but is not quite identical,
586 % because (a) |\maketag@@@| and |\tagform@| take an argument,
587 % and (b) we also have to check |\df@label|.
588 %
589 % This is happening \emph{before} we expand the |\label| that we have
590 % patched. That means that, at the time the equation text is set in
591 % |\SL@set@text|, we have not set the |\SL@fmt@| appropriately.
592 % Therefore, as part of the general special-casing of
593 % \Lpackage{amsmath} labels, we must do this explicitly here (see test t23).
594 %
595 % The final wrinkle here is that we must distinguish between this
596 % being called when |\displaywidth| is 0pt, and when it is non-zero.
597 % In the latter case, we are in a display, setting the equation
598 % number. The former case occurs because \Lpackage{amsmath}'s
599 % |\eqref| calls |\maketag@@@| via |\tagform@|, and if we don't detect
600 % this (by detecting that this is being called outside a display) then
601 % we get a spurious appearance of the printed label obscuring the text
602 % (see tests t2 and t17, and heptapod issue \#6).
603 %
604 % The \Lpackage{amsmath} package includes support for the
605 % \Lpackage{showkeys} package, by including hooks |\SK@...| for a few
606 % package functions. It might be reasonable, at some point, to
607 % examine these more closely, and possibly start monkeypatching \emph{these}.
608 % \begin{macro}{\SL@setlabel@ams}
609 % \begin{macrocode}
610 \def\SL@setlabel@ams{%
611 \let\SL@fmt@\SL@fmt@label
612 \ifdim\displaywidth>0pt
613 \ifx\df@label\@empty
614 \ifx\SL@labelname\relax
615 % do nothing
616 \else
617 \SL@set@text{\SL@labelname}%
618 \fi
619 \else
620 \SL@set@text{\df@label}%
621 \fi
622 \fi
623 \global\let\SL@labelname\relax
624 }
625 \let\SL@orig@maketag@@@=\maketag@@@
626 \def\SL@maketag@@@#1{%
627 \SL@orig@maketag@@@{#1}%
628 \SL@setlabel@ams
629 }
630 % \end{macrocode}
631 % \end{macro}
632 % \end{macro}
633 %
634 % \begin{macro}{\@eqnnum}
635 % Next, deal with the `normal' case, without \Lpackage{amsmath}.
636 % Package \Lpackage{amsmath} redefines |\@eqnnum| in terms of
637 % |\maketag@@@|, so we should avoid touching this in the
638 % non-\Lpackage{amsmath} case.
639 % \begin{macrocode}
640 \else
641 \SL@wrap@labeller{@eqnnum}
642 \fi
643 % \end{macrocode}
644 % \end{macro}
645 % And initialise the value of |\SL@labelname| to |\relax|, so that
646 % |\@eqnnum| starts off behaving the right way.
647 % \begin{macrocode}
648 \global\let\SL@labelname\relax
649 % \end{macrocode}
650 %
651 % Labels are printed with the font specified by |\showlabelfont|, which
652 % can be overridden within the document:
653 % Define this using |\ttfamily|, unless we're still using \LaTeX 2.09
654 % (surprising it still works!), in which case stick with |\tt|.
655 % \begin{macrocode}
656 \@ifundefined{ttfamily}
657 {\providecommand{\showlabelfont}{\small\tt}}
658 {\providecommand{\showlabelfont}{\small\ttfamily}}
659 % \end{macrocode}
660 %
661 % \begin{macro}{\showlabelsetlabel}
662 % If you want slightly more general control over the labels, you can
663 % instead override |\showlabelsetlabel|.
664 % \begin{macrocode}
665 \providecommand{\showlabelsetlabel}[1]{{\normalfont\showlabelfont\SL@fmt@{#1}}}
666 % \end{macrocode}
667 % \end{macro}
668 %
669 % For the benefit of |\SL@prlabelname|, define |\SL@gobblethree| to do nothing
670 % other than eat three tokens.
671 % \begin{macrocode}
672 \def\SL@gobblethree#1#2#3{}
673 % \end{macrocode}
674 %
675 % \begin{macro}{\SL@prlabelname}
676 % Expansion is label name with all catcodes `other' (Appendix~D trickery
677 % abounds!). Use |\r@#1| (defined by |\ref|), rather then just |\#1|
678 % to avoid defining any new control sequences.
679 %
680 % Note that this catcode magic, and the |\@sanitize| in
681 % |\SL@showlabels| below, are doing much the same job, and indeed are
682 % almost redundant with each other. But this |\SL@prlabelname|
683 % doesn't cope with eg |\index{Poincar\'e}|, and the |\@sanitize|
684 % below doesn't cope with |\section{\label{a_b}Foo}| (see tests t4 and t19).
685 % \begin{macrocode}
686 \def\SL@prlabelname#1{%
687 \expandafter\expandafter\expandafter\SL@gobblethree
688 \expandafter\string\csname r@#1\endcsname}
689 % \end{macrocode}
690 % \end{macro}
691 %
692 % \begin{macro}{\showlabels}
693 % Define the |\showlabels| command which allows us to redefine
694 % commands which are to have their arguments highlighted.
695 % That is, |\showlabels{foo}| means that the command |\foo{bar}| will
696 % write `bar' in the margin, as well as executing whatever |\foo| does
697 % normally.
698 %
699 % The net result of all this is that a |\showlabels{foo}| command
700 % arranges things so that, after |\begin{document}|, the original
701 % version of |\foo| is saved in |\SL@origfoo|, and |\foo{bar}| expands into
702 % |\SL@setlabel{bar}\SL@origfoo{bar}|.
703 %
704 % First, define a command |\SL@initfoo|, which, when executed, will
705 % save the current (at that time) behaviour of the command |\foo| as
706 % |\@SL@origfoo|, and then set |\foo| to be equivalent to |\SL@foo|,
707 % which does the magic; we will
708 % shortly give this command to |\AtBeginDocument|, so that it is
709 % switched on at the correct time, when other packages have done
710 % \emph{their} redefinitions of |\foo| (this makes it compatible with
711 % the \Lpackage{hyperref} package, which does its own wholesale redefinitions of
712 % things like |\label|). Below, the locution
713 % |\the\@temptokena| causes the token contents of |\@temptokena| to be
714 % included unexpanded in the definition, despite the |\edef|.
715 %
716 % If the optional |\showlabels| argument is present, then use this as per-command
717 % formatting, so that, for example |\cite| instances may be formatted
718 % distinctively from |\label|.
719 % \begin{macrocode}
720 \def\showlabels{\@ifnextchar[\showlabels@{\showlabels@[]}}
721 \def\showlabels@[#1]#2{%
722 \@temptokena=\expandafter{\csname #2\endcsname}
723 \def\@tempa{#1}%
724 \ifx\@tempa\@empty
725 \expandafter\let\csname SL@fmt@#2\endcsname\relax
726 \else
727 \expandafter\def\csname SL@fmt@#2\endcsname{#1}%
728 \fi
729 \expandafter\edef\csname SL@init@#2\endcsname{%
730 \let\csname SL@orig#2\endcsname\the\@temptokena
731 \let\the\@temptokena\csname SL@#2\endcsname}
732 \AtBeginDocument{\csname SL@init@#2\endcsname}%
733 % \end{macrocode}
734 % \emph{Now} define |\SL@foo| -- it must be undefined when we define
735 % |\SL@initfoo| above, so that it isn't expanded in the |\edef|.
736 % \begin{macrocode}
737 \expandafter\def\csname SL@#2\endcsname{%
738 \expandafter\let\expandafter\SL@fmt@\csname SL@fmt@#2\endcsname
739 \SL@showlabels{#2}}
740 }
741 % \end{macrocode}
742 %
743 % We need a default definition of |\SL@fmt@| for the cases (some
744 % equation formatting) where we don't get to the formatting via this
745 % mechanism.
746 % \begin{macrocode}
747 \let\SL@fmt@\relax
748 % \end{macrocode}
749 % \end{macro}
750 %
751 % \begin{macro}{\SL@showlabels}
752 % Now we get to the command which does the main processing. The
753 % |\SL@showlabels| command calls |\SL@setlabel| to format the label
754 % (putting it in the margin, for example), then calls the original
755 % |\foo| command (namely |\SL@origfoo|) with the original argument.
756 %
757 % The command takes a single argument, namely the name of the command
758 % being wrapped (for example, `label'). We set |\@tempa| to be the
759 % original version of that command (stored in |\SL@orig#1|), and then
760 % take one of two similar paths, depending on whether the command has
761 % an optional argument or not.
762 %
763 % We have to be somewhat careful about the positioning of the
764 % |\@bsphack| and |\@esphack| commands. The |\@esphack| command should
765 % \emph{not} come after the call to |\SL@origfoo|, since that would
766 % confuse things terribly if that command took any other arguments, or
767 % otherwise messed with the token stream (there's actually no problem
768 % in the most common case where we're replacing |\label|, and calling
769 % |\SL@origlabel|, but there are problems when we try to replace
770 % |\begin| or |\ref| in this way). Instead, adapt the contents
771 % of |\@esphack|, but instead of calling |\ignorespaces| when
772 % |\@savsk| is positive, add an |\hskip| of 1~scaled point (equal to
773 % $1/65536\mathrm{pt}=5.363\times10^{-9}\mathrm{m}$). This will be
774 % invisible, but it \emph{is} greater than zero, so that if
775 % |\SL@origfoo| itself uses a |\@bsphack|\dots|\@esphack| pair then
776 % the saved |\@savsk| will be positive, and that future |\@esphack|
777 % will correctly invoke |\ignorespaces|; that pair will also pick up
778 % the |\spacefactor| we restore here. The net result is that the
779 % |\SL@setlabel| is invisible, and |\SL@origfoo| is able to make
780 % itself invisible, too. Command sequence |\SL@setlabel| is what does
781 % the work -- this is |\let| equal to either |\SL@margtext| or
782 % |\SL@inlinetext| below.
783 %
784 % We must declare |\SL@showlabels| to be a robust command, or else we
785 % get confusing expansion problems when, for example, we do
786 % |\showlabels{ref}| and use |\ref| in a caption (see test case t3).
787 % We actually handle three distinct cases here, for |\foo{label}|,
788 % |\foo[opt]{label}| and |\foo*{label}| (the last is to handle the
789 % \Lpackage{hyperref} package's |\ref*{label}| variant; see test case
790 % t14).
791 %
792 % Note that in each case, the |label| is read with sanitised
793 % catcodes. That is, I think, always an acceptable thing to do, in
794 % the sense that I can't think of cases where this breaks anything.
795 %
796 % We open a group in order to call |\@sanitize|; we're able to close
797 % it immediately, within the called macros. We call |\@sanitize| in
798 % order to cope with eg |\index{Poincar\'e}| (see discussion of
799 % |\SL@prlabelname| above). We carefully \emph{avoid} calling
800 % |\@sanitize| before reading an optional argument: this is so that
801 % we read that argument with the existing catcode
802 % assignments, so that eg |\bibitem[P{\'o}lya]{polya54}| works as
803 % expected (see test t20).
804 %
805 % We declare |\showlabeltype| to be the `current' label type. It
806 % would be good to put this inside a group, so that it's only visible
807 % locally, but we would then have to be careful exactly when we closed
808 % the group: if we put it inside the group that's opened for
809 % |\@sanitize|, it would be closed too early to have an effect; if we
810 % open another group for |\showlabeltype|, then we'd have to close it
811 % \emph{after} |\SL@orig@@next|, where we risk colliding with whatever
812 % comes after it (and see above). It might be possible to be cleverer
813 % about this, but it's at least harmless to have the command defined
814 % globally.
815 % \begin{macrocode}
816 \DeclareRobustCommand\SL@showlabels[1]{%
817 \@bsphack
818 \expandafter\let\expandafter\SL@orig@@next\csname SL@orig#1\endcsname
819 \def\showlabeltype{#1}%
820 \begingroup
821 \@ifstar
822 {\@sanitize\SL@showlabelsplainstar}
823 {\@ifnextchar[
824 {\SL@showlabelsopt}
825 {\@sanitize\SL@showlabelsplain}}}
826 \def\SL@showlabelsopt[#1]{% #1 is read before \@sanitize
827 \@sanitize
828 \SL@showlabelsopt@ii{#1}}
829 \def\SL@showlabelsopt@ii#1#2{%
830 \endgroup
831 \SL@setlabel{#2}\relax
832 \ifhmode \spacefactor\@savsf \ifdim\@savsk>\z@ \hskip1sp \fi\fi
833 \SL@orig@@next[#1]{#2}}
834 \def\SL@showlabelsplain#1{%
835 \endgroup
836 \SL@setlabel{#1}\relax
837 \ifhmode \spacefactor\@savsf \ifdim\@savsk>\z@ \hskip1sp \fi\fi
838 \SL@orig@@next{#1}}
839 \def\SL@showlabelsplainstar#1{%
840 \endgroup
841 \SL@setlabel{#1}\relax
842 \ifhmode \spacefactor\@savsf \ifdim\@savsk>\z@ \hskip1sp \fi\fi
843 \SL@orig@@next*{#1}}
844 % \end{macrocode}
845 % \end{macro}
846 %
847 % \begin{macro}{\@makecaption}
848 % The |\@makecaption| command needs special treatment. The
849 % |\SL@margtext| command doesn't work in figure captions, so we need
850 % to force the layout commands to use |\SL@inlinetext| instead, for
851 % all label types, and irrespective of whether we're using the
852 % \Lopt{inline} option. The code here is independent of that in
853 % |\showlabels|, but imitates it, for consistency.
854 % \begin{macrocode}
855 \def\SL@initmakecaption{%
856 \let\SL@origmakecaption\@makecaption
857 \def\@makecaption##1##2{{%
858 \let\SL@setlabel\SL@inlinetext
859 \SL@origmakecaption{##1}{##2}}}}
860 \AtBeginDocument{\SL@initmakecaption}
861 % \end{macrocode}
862 % \end{macro}
863 %
864 % \begin{macro}{\SL@margtext}
865 % This is the central bit of this package, used by |\SL@showlabels|.
866 % The argument is the argument of the |\foo| command which we're
867 % processing (for example, the argument to a |\label| command).
868 %
869 % Depending on the mode, put the
870 % current label name in the margin in one of a variety of ways.
871 % \begin{macrocode}
872 \def\SL@margtext#1{%
873 % \end{macrocode}
874 %
875 % There are three cases here:
876 % \begin{enumerate}
877 % \item We are in maths mode, setting an equation.
878 % We need to distinguish (1a) being in a display, when we \emph{assume}
879 % we're processing a |\label|, and (1b) not, when we should act more like
880 % case~3. Note that case 1a is somewhat heuristic, and will go
881 % wrong if someone uses the |\showlabels{foo}| mechanism to show
882 % some different command within a maths display.
883 % \item We are not in maths mode but we \emph{are} within a display
884 % (this can happen in, for example, the \Lenv{cases} environment from
885 % the \Lpackage{cases} package).
886 % \item We are in text.
887 % \end{enumerate}
888 % There are two outcomes:
889 % \begin{enumerate}
890 % \item we print a label name alongside the equation number
891 % (cases~1a and~2), or
892 % \item we produce a zero-height box in the vertical list (cases~1b
893 % and~3).
894 % \end{enumerate}
895 %
896 % Case 1:
897 % In maths mode, and \emph{if} we're in a display (case~1a), produce a
898 % label name alongside the equation number; if we're not in a display
899 % (case~1b), then act like case~3.
900 % \begin{macrocode}
901 \ifmmode
902 \ifdim\displaywidth>0pt
903 \@tempswatrue
904 \else
905 \@tempswafalse
906 \fi
907 % \end{macrocode}
908 %
909 % Case 2:
910 % Check if we're within a display equation,
911 % and if so act as if we are in maths mode (ie, as above).
912 % Note: most contexts which match case~1 would also be caught by this
913 % test, since |\label| is used almost exclusively within displays,
914 % but it seems clearer to separate the two cases explicitly, as well
915 % as probably dealing better with cases where the package is used for
916 % non-|\label| commands.
917 % \begin{macrocode}
918 \else\ifdim\displaywidth>0pt
919 \@tempswatrue
920 % \end{macrocode}
921 %
922 % Case 3:
923 % Otherwise, create an inter-line zero-height box.
924 % \begin{macrocode}
925 \else
926 \@tempswafalse
927 \fi\fi
928 % \end{macrocode}
929 % Now, |\@tempswa| is true if we are to make a label, and false if
930 % we're to include an interline box.
931 %
932 % True case first:
933 % Save the label name in |\SL@labelname|, so we can use it later
934 % (this is redundant in most \Lpackage{amsmath} contexts, because that
935 % style generally saves this in |\df@label|, but sometimes -- for
936 % example when using the traditional \Lenv{eqnarray} environment
937 % within \Lpackage{amsart} -- |\df@label| can end up unset).
938 % \begin{macrocode}
939 \if@tempswa
940 \xdef\SL@labelname{\SL@prlabelname{#1}}%
941 % \end{macrocode}
942 % Otherwise, create a box with zero height and depth, and the same width
943 % as the page. Put all this in braces, to contain the setting of
944 % |\box\@tempboxa| (which probably shouldn't be necessary). The box
945 % here we set to be the width of |\hsize|. This is \emph{probably}
946 % best, though there's always the worry that |\linewidth| would be the
947 % more \LaTeX-ish thing to do -- using |\columnwidth| is almost
948 % certainly wrong, since |\linewidth| can sometimes be changed without
949 % |\columnwidth| changing with it (for example, in package
950 % \Lpackage{wrapfig}), causing \Lpackage{showlabels} to fail badly.
951 % \begin{macrocode}
952 \else
953 \setbox\@tempboxa=\vbox to 0pt{%
954 \vss
955 \hbox to \hsize{\SL@lrtext{#1}}}%
956 \dp\@tempboxa\z@
957 % \end{macrocode}
958 % Attach this box below the last one, using |\nointerlineskip| if we're in
959 % vertical mode, or |\vadjust| otherwise. We need to save and restore
960 % the value of |\prevdepth| (which has the sentinel value -1000pt if we're
961 % adding this box at the beginning of a vertical list, and
962 % |\nointerlineskip| sets |\prevdepth| to this same value). If we don't
963 % do this, we get extra (`interline') vertical space added in this
964 % case (it might be thought smart to use |\marginpar| here, and so
965 % avoid some of this nonsense, but that's not possible since this
966 % might be called within boxes, which |\marginpar| objects to).
967 %
968 % We don't always get the vertical spacing right here,
969 % but that's perhaps a problem for another day.
970 % \begin{macrocode}
971 \ifvmode
972 \@tempdima=\prevdepth
973 \nointerlineskip\box\@tempboxa\nobreak
974 \prevdepth=\@tempdima
975 \else
976 \vadjust{\box\@tempboxa\nobreak}%
977 \fi
978 \fi
979 }
980 % \end{macrocode}
981 % \end{macro}
982 %
983 % \begin{macro}{\SL@inlinetext}
984 % This is an alternative way of formatting the label, which puts it
985 % inline as much as possible, and avoids straying into the margins.
986 % We just use the same mechanism as for |\SL@margtext|, but do the
987 % inline-or-not testing there.
988 %
989 % If |\df@label| is non-empty, then we are setting an (AMS) equation
990 % label, and the display of the label text has been done in
991 % |\SL@setlabel@ams|, so we mustn't repeat it here.
992 % \iffalse see test t17\fi
993 % \begin{macrocode}
994 \def\SL@inlinetext#1{%
995 \ifx\df@label\@empty
996 \SL@interlinetextright{\SL@prlabelname{#1}}%
997 \fi
998 }
999 % \end{macrocode}
1000 % In vmode, put the label between lines. Set the box depth to zero to
1001 % make sure that descenders don't mess up the spacing.
1002 % \begin{macrocode}
1003 \def\SL@interlinetextleft{\SL@setlefttrue\SL@interlinetext}
1004 \def\SL@interlinetextright{\SL@setleftfalse\SL@interlinetext}
1005 \def\SL@interlinetext#1{%
1006 \setbox\@tempboxa=\hbox{\showlabelsetlabel{\SL@prlabelname{#1}}}\dp\@tempboxa\z@
1007 \ifvmode
1008 \@tempdima=\prevdepth
1009 \nointerlineskip\vbox to 0pt{\vss
1010 \hbox to \hsize{\hss \box\@tempboxa}}\nobreak
1011 \prevdepth=\@tempdima
1012 % \end{macrocode}
1013 % And in horizontal mode, squeeze it between the lines, at the current point,
1014 % carefully taking up no space.
1015 % \begin{macrocode}
1016 \else
1017 \ifSL@setleft
1018 \hbox to 0pt{%
1019 \hss
1020 \vbox to 0pt{\vss
1021 \hbox to 0pt{\hss\box\@tempboxa}%
1022 \showlabelrefline
1023 }}%
1024 \else
1025 \hbox to 0pt{%
1026 \vbox to 0pt{\vss
1027 \box\@tempboxa
1028 \showlabelrefline
1029 }\hss}%
1030 \fi
1031 \penalty10000
1032 \fi
1033 }
1034 % \end{macrocode}
1035 % \end{macro}
1036 %
1037 % \begin{macro}{\showlabelrefline}
1038 % Set a short line which indicates the point where a label is
1039 % attached, when producing inline labels. This additionally positions
1040 % the label up above the line.
1041 % \begin{macrocode}
1042 \def\showlabelrefline{\hrule width 0.05em height 1.5ex depth 0pt }
1043 % \end{macrocode}
1044 % \end{macro}
1045 %
1046 % \begin{macro}{\SL@margintext}
1047 % Set the actual text of the label. Use |\SL@prlabelname| here: without
1048 % this, a label command given outside of an equation or a |\caption|
1049 % will appear wrongly if the label has things like underscores within it.
1050 % \begin{macrocode}
1051 \def\SL@margintext#1{{\showlabelsetlabel{\{\SL@prlabelname{#1}\}}}}
1052 % \end{macrocode}
1053 % \end{macro}
1054 %
1055 % But where is the marginal text actually set? It can be in the left
1056 % margin, the right one, or can alternate. |\SL@lrtext|, used in the
1057 % |\vbox| above, is set, under the control of |\SL@labelposition| below, to
1058 % one of |\SL@lefttext|, |\SL@righttext| or |\SL@alternatetext|.
1059 % \begin{macro}{\SL@righttext}
1060 % \begin{macro}{\SL@lefttext}
1061 % \begin{macrocode}
1062 \def\SL@righttext#1{\hfill\rlap{\quad\SL@margintext{#1}}}
1063 \def\SL@lefttext #1{\llap{\SL@margintext{#1}\quad}\hfill}
1064 % \end{macrocode}
1065 % \end{macro}
1066 % \end{macro}
1067 %
1068 % \begin{macro}{\SL@setLR}
1069 % Define a switch which allows us to state whether we've decided to
1070 % set a particular label to the left or the right, and a macro
1071 % |\SL@setLR| to set it. After |\SL@setLR|, |\ifSL@setleft| is true
1072 % if a label should be set to the left, and is false if it should go
1073 % to the right.
1074 % \begin{macrocode}
1075 \newif\ifSL@setleft
1076 \def\SL@setLR{%
1077 \ifcase\SL@labelposition
1078 % 0=outer margin
1079 \ifodd\c@page
1080 \SL@setleftfalse
1081 \else
1082 \SL@setlefttrue
1083 \fi
1084 \or
1085 % 1=inner margin
1086 \ifodd\c@page
1087 \SL@setlefttrue
1088 \else
1089 \SL@setleftfalse
1090 \fi
1091 \or
1092 % 2=left margin
1093 \SL@setlefttrue
1094 \or
1095 % 3=right margin
1096 \SL@setleftfalse
1097 \else
1098 \SL@canthappen{Impossible labelposition \the\SL@labelposition}
1099 \SL@labelposition=3 % put everything in the right-margin for now
1100 \SL@setleftfalse
1101 \fi
1102 }
1103 % \end{macrocode}
1104 % \end{macro}
1105 %
1106 % The code for |\SL@alternatetext| doesn't work perfectly, as it
1107 % sometimes manages to get things on the wrong side of the text near the
1108 % top of a new page. This is a venial slip, however, as this package
1109 % should never be used in a final version.
1110 % \begin{macro}{\SL@alternatetext}
1111 % \begin{macrocode}
1112 \def\SL@alternatetext{%
1113 \SL@setLR
1114 \ifSL@setleft
1115 \let\SL@next\SL@lefttext
1116 \else
1117 \let\SL@next\SL@righttext
1118 \fi
1119 \SL@next
1120 }
1121 % \end{macrocode}
1122 % \end{macro}
1123 % The case where the \Lopt{twocolumn} option is set is slightly different.
1124 % There we have to switch between placing the note in the left and right
1125 % margins, depending on whether we're setting the first or second column.
1126 % This macro, and |\SL@set@twocoltext| below, uses the switch
1127 % |\if@firstcolumn| to decide whether it's in the first or the second
1128 % column of the text (I suppose it'll get terribly confused if we use
1129 % \file{multicol.sty} along with this). This is defined and maintained in
1130 % the base file \file{ltoutput.dtx}. It's not part of the defined
1131 % interface, however (there doesn't seem to be one, grump), so I don't
1132 % suppose we should really rely on it. There isn't an option, however.
1133 % \begin{macro}{\SL@twocoltext}
1134 % \begin{macrocode}
1135 \def\SL@twocoltext{%
1136 \if@firstcolumn
1137 \let\SL@next\SL@lefttext
1138 \else
1139 \let\SL@next\SL@righttext
1140 \fi
1141 \SL@next}
1142 % \end{macrocode}
1143 % \end{macro}
1144 %
1145 % We have very similar things for equations, except that they are set in
1146 % place, rather than within a zero depth box. This code \emph{assumes} that
1147 % equation numbers are going to be on the right hand side of the page. It
1148 % should probably check for the existence of the \Lopt{leqno} option (how?).
1149 %
1150 % Note that we \emph{do} want this to be |\columnwidth| rather than
1151 % |\hsize|. The \Lpackage{wrapfig} package retains the former as the
1152 % width of the whole column, even though it carefully changes the
1153 % latter to be the width of the \Lenv{wrapfigure} environment. In the
1154 % (unlikely) event we want numbered equations in such an environment
1155 % \emph{and} this label ends up on the left, we do want the
1156 % label right out in the left margin, rather than on the left of the
1157 % \Lenv{wrapfigure} environment.
1158 % \begin{macro}{\SL@set@righttext}
1159 % \begin{macro}{\SL@set@lefttext}
1160 % \begin{macrocode}
1161 \def\SL@set@righttext#1{\rlap{\quad\SL@margintext{#1}}}
1162 \def\SL@set@lefttext #1{\hbox to 0pt{\kern -\columnwidth
1163 \llap{\SL@margintext{#1}\quad}\hss}}
1164 % \end{macrocode}
1165 % \end{macro}
1166 % \end{macro}
1167 % Now do the analogues for the equation numbers, in the case of the
1168 % alternate page selection\dots
1169 % \begin{macro}{\SL@set@alternatetext}
1170 % \begin{macrocode}
1171 \def\SL@set@alternatetext{%
1172 \SL@setLR
1173 \ifSL@setleft
1174 \let\SL@next\SL@set@lefttext
1175 \else
1176 \let\SL@next\SL@set@righttext
1177 \fi
1178 \SL@next
1179 }
1180 % \end{macrocode}
1181 % \end{macro}
1182 % \dots and the twocolumn option
1183 % \begin{macro}{\SL@set@twocoltext}
1184 % \begin{macrocode}
1185 \def\SL@set@twocoltext{%
1186 \if@firstcolumn
1187 \let\SL@next\SL@set@lefttext
1188 \else
1189 \let\SL@next\SL@set@righttext
1190 \fi
1191 \SL@next}
1192 % \end{macrocode}
1193 % \end{macro}
1194 %
1195 % \begin{macro}{\SL@canthappen}
1196 % Issues a |\PackageError| command, and solicits bug reports.
1197 % \begin{macrocode}
1198 \def\SL@canthappen#1{%
1199 \PackageError{showlabels}{#1}
1200 {This shouldn't happen -- the package showlabels has a bug.
1201 \MessageBreak
1202 Please report this, if possible with a sample document which
1203 \MessageBreak
1204 demonstrates the problem, to \filemaintainer. Thanks.}}
1205 % \end{macrocode}
1206 % \end{macro}
1207 %
1208 % To control the positioning of labels, set the |\SL@labelposition|
1209 % switch, which can take values 0, 1, 2, 3, meaning outer, inner,
1210 % left, right margin respectively.
1211 % \begin{macrocode}
1212 \newcount\SL@labelposition
1213 \SL@labelposition=0
1214 % \end{macrocode}
1215 %
1216 % We select between the various possibilities using the \Lopt{outer} and
1217 % \Lopt{inner} options and, implicitly, the \Lopt{twoside} option.
1218 % \begin{macrocode}
1219 \DeclareOption{outer}{\SL@labelposition=0}
1220 \DeclareOption{inner}{\SL@labelposition=1}
1221 \DeclareOption{left}{\SL@labelposition=2}
1222 \DeclareOption{right}{\SL@labelposition=3}
1223 % \end{macrocode}
1224 %
1225 % Labels can be set either in the margins or inline, by switching
1226 % between definitions of |\SL@setlabel|.
1227 % \begin{macrocode}
1228 \newif\ifSL@labelsinline
1229 \SL@labelsinlinefalse
1230 \DeclareOption{marginal}{\SL@labelsinlinefalse}
1231 \DeclareOption{inline}{\SL@labelsinlinetrue}
1232 % \end{macrocode}
1233 % \begin{macro}{\SL@setlabel}
1234 %
1235 % Macro |\SL@setlabel| is where we switch between inline and marginal labels.
1236 % \begin{macrocode}
1237 \def\SL@setlabel{%
1238 \ifSL@labelsinline
1239 \let\@tempa\SL@inlinetext
1240 \else
1241 \let\@tempa\SL@margtext
1242 \fi
1243 \@tempa
1244 }
1245 % \end{macrocode}
1246 % \end{macro}
1247 %
1248 % \begin{macro}{\showlabelsinline}
1249 % It is sometimes convenient (for example when a document encounters a
1250 % situation which this package mishandles) to force inline labels
1251 % temporarily, within a block or environment. Use this macro to do
1252 % that.
1253 % \begin{macrocode}
1254 \def\showlabelsinline{\SL@labelsinlinetrue}
1255 % \end{macrocode}
1256 % \end{macro}
1257 % \begin{macro}{\showlabelsmarginal}
1258 % Add the complementary macro for symmetry, even though this is not
1259 % likely to be useful.
1260 % \begin{macrocode}
1261 \def\showlabelsmarginal{\SL@labelsinlinefalse}
1262 % \end{macrocode}
1263 % \end{macro}
1264 % By default, we run |\showlabels{label}|. The option \Lopt{nolabel}
1265 % turns this off.
1266 % \begin{macrocode}
1267 \newif\ifSL@labellabel
1268 \SL@labellabeltrue
1269 \DeclareOption{nolabel}{\SL@labellabelfalse}
1270 % \end{macrocode}
1271 %
1272 % Define the options \Lopt{final} and \Lopt{draft}. The option
1273 % \Lopt{final} turns off all the functionality of this package by
1274 % disabling the command |\showlabels|, including the implicit
1275 % |\showlabels| command which the package issues as long as the
1276 % \Lopt{nolabel} option has not been given. This is included so that if that
1277 % option is given in the |\documentclass| declaration then this
1278 % package does respect it. \Lopt{draft} does nothing, and therefore
1279 % simply continues the default behaviour of this package; it is here
1280 % purely to partner the \Lopt{final} option.
1281 % \begin{macrocode}
1282 \DeclareOption{final}{\let\showlabels\@gobble}
1283 \DeclareOption{draft}{}
1284 % \end{macrocode}
1285 %
1286 % Process any options that have been set.
1287 % \begin{macrocode}
1288 \ProcessOptions
1289 % \end{macrocode}
1290 % and use the values of |\SL@labelposition| and |if@twoside| which may have
1291 % been set by those options, to set |\SL@lrtext| to be the
1292 % appropriate control sequence. The presence of the \Lopt{twocolumn} option
1293 % means that we ignore the \Lopt{inner} and \Lopt{outer} options.
1294 % \begin{macrocode}
1295 \if@twocolumn
1296 \let\SL@lrtext\SL@twocoltext
1297 \let\SL@set@lrtext\SL@set@twocoltext
1298 \else
1299 \ifcase\SL@labelposition
1300 % 0=outer margin
1301 \if@twoside
1302 \let\SL@lrtext\SL@alternatetext
1303 \let\SL@set@lrtext\SL@set@alternatetext
1304 \else
1305 \let\SL@lrtext\SL@righttext
1306 \let\SL@set@lrtext\SL@set@righttext
1307 \fi
1308 \or
1309 % 1=inner margin
1310 \if@twoside
1311 \let\SL@lrtext\SL@alternatetext
1312 \let\SL@set@lrtext\SL@set@alternatetext
1313 \else
1314 \let\SL@lrtext\SL@lefttext
1315 \let\SL@set@lrtext\SL@set@lefttext
1316 \fi
1317 \or
1318 % 2=left margin
1319 \let\SL@lrtext\SL@lefttext
1320 \let\SL@set@lrtext\SL@set@lefttext
1321 \or
1322 % 3=right margin
1323 \let\SL@lrtext\SL@righttext
1324 \let\SL@set@lrtext\SL@set@righttext
1325 \else
1326 \SL@canthappen{Impossible labelposition \the\SL@labelposition}
1327 \SL@labelposition=3 % put everything in the right-margin for now
1328 \let\SL@lrtext\SL@righttext
1329 \let\SL@set@lrtext\SL@set@righttext
1330 \fi
1331 \fi
1332 % \end{macrocode}
1333 %
1334 % Finally, label all the |\label| commands
1335 % (default behaviour),
1336 % unless this has been suppressed through the \Lopt{nolabel} option.
1337 % \begin{macrocode}
1338 \ifSL@labellabel
1339 \showlabels{label}
1340 \ifSL@AMS
1341 \ifx\showlabels\@gobble
1342 % do nothing -- we're in [final] mode (see test case t13)
1343 \else
1344 \AtBeginDocument{\let\maketag@@@\SL@maketag@@@}
1345 \fi
1346 \fi
1347 \@ifundefined{theIEEEsubequationdis}\relax % and \theequationdis
1348 {\SL@wrap@labeller{theIEEEsubequationdis}
1349 \SL@wrap@labeller{theequationdis}}
1350 \fi
1351 % \end{macrocode}
1352 %
1353 % That's us.
1354 %
1355 % \begin{macrocode}
1356 %</package>
1357 % \end{macrocode}
1358 %
1359 % \Finale
1360 \endinput