path: root/Master/texmf-dist/source/latex/showlabels/showlabels.dtx

% \iffalse % meta-comment
%
%% This is the showlabels package
%%
%% This software is copyright, 1999, 2001--2007, Norman Gray. 
%% 
%% This program is free software; you can redistribute it and/or
%% modify it under the terms of the GNU General Public License
%% as published by the Free Software Foundation; either version 2
%% of the License, or (at your option) any later version.
%% 
%% This program is distributed in the hope that it will be useful,
%% but WITHOUT ANY WARRANTY; without even the implied warranty of
%% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
%% GNU General Public License for more details.
%% 
%% You should have received a copy of the GNU General Public License
%% along with this program; if not, write to the Free Software
%% Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
%% 
%% Author: Norman Gray, norman@astro.gla.ac.uk.
%% Department of Physics and Astronomy, University of Glasgow, UK
%%
%% See the file LICENCE for a copy of the GPL.
%% You can also find an online copy at http://www.gnu.org/copyleft/gpl.html .
%%
%% $Id: showlabels.dtx,v 1.31 2007/06/17 15:34:32 norman Exp $
%%
%
\def\filename{showlabels}
\def\fileversion{1.6.1}
\def\filedate{2007/06/17}
\def\docdate{2007 June 17}
\def\filemaintainer{norman@astro.gla.ac.uk}
% \changes{v1.4}{2001/07/23}{Avoided defining RCSDate}
%<+package>\NeedsTeXFormat{LaTeX2e}
%<+package>\ProvidesPackage{showlabels}[\filedate\space v\fileversion]
%<+package>\typeout{Package: `showlabels' v\fileversion\space<\filedate>}
%
%<*driver>
\documentclass{ltxdoc}
\EnableCrossrefs
%    \end{macrocode}
%    Some commonly used abbreviations for option names, filenames, 
% counters and packages.
%    \begin{macrocode}
\newcommand\Lopt[1]{\textsf{#1}}		% package options
\newcommand\file[1]{\texttt{#1}}		% filename
%\newcommand\Lcount[1]{\textsl{\small#1}}
\newcommand\pstyle[1]{\textsf{\{#1\}}}		% packages
%% \url macro (url.sty does this better, but we don't want extra dependencies)
\def\setpathdots{\discretionary{.}{}{.}}
\def\setpathslash{\discretionary{/}{}{/}}
{\catcode`\.=\active 
 \catcode`\/=\active 
  \gdef\pathcats{%
    \catcode`\%=12      \catcode`\~=12 
    \catcode`\.=\active  \let.\setpathdots
    \catcode`\/=\active \let/\setpathslash
    \catcode`\#=12      \catcode`\_=12}%
    }
\def\setpath#1{\ttfamily <\nobreak #1\nobreak>\endgroup}
\def\url{\begingroup\pathcats\setpath}
\begin{document}
% \RecordChanges
% \OnlyDescription
\DocInput{showlabels.dtx}
\PrintIndex
% \PrintChanges
\end{document}
%</driver>
%
% \fi
%
% \changes{v1.3b}{1996/06/06}{Clarified copyright and licence conditions, also restructured to make preparing documentation easier.}
%
% \title{The \texttt{\filename} package}
% \author{Norman Gray\\|norman@astro.gla.ac.uk|}
% \date{Version \fileversion, \docdate}
%
% \maketitle
%
% This package helps you keep track of all the labels you define, by
% putting the name of new labels into the margin whenever the
% |\label| command is used.
%
% You can do the same thing for other commands (see below).
% The only one for which this is \emph{obviously} useful is the
% |\cite| command, but it is also reasonable to do it with, for example,
% the |\ref| or |\begin| commands.
%
% Invoke this package with the command |\usepackage{showlabels}| in
% the preamble, and you may give the following options:
% \begin{quotation}
% \begin{tabular}{lp{25em}}
%    \Lopt{outer}    & [default] all notes are placed in the text's outer
%                      margin\\
%    \Lopt{inner}    & \dots inner margin\\
%    \Lopt{left}     & \dots left margin\\
%    \Lopt{right}    & \dots right margin\\
%    \Lopt{marginal} & [default] put notes in the margin\\
%    \Lopt{inline}   & put notes inline, as much as possible, and ignore 
%                      any of the margin-placement options above \\
%    \Lopt{nolabel}  & do not insert a marginal note for |\label| commands
%                      (see command |\showlabels| below)\\
%    \Lopt{draft}    & [default] does nothing, partner of\dots\\
%    \Lopt{final}    & turns off all the package's functionality
% \end{tabular}
% \end{quotation}
% If you don't use the \Lopt{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 \Lopt{twocolumn} 
% option.  In this case, the options \Lopt{inner}, \Lopt{outer},
% \Lopt{left} and \Lopt{right} will be ignored, and the label will be
% placed in the nearer margin.
%
% If you want to change the font the labels appear in, redefine the
% |\showlabelfont| command, which by default expands to
% |\small\ttfamily|.  For example, to have labels in a slanted font, you
% could include the definition
% \begin{quote}
% |\renewcommand{\showlabelfont}{\small\slfamily}|
% \end{quote}
% in the preamble of your document.
% If you want still more control over the labels, you can
% instead override |\showlabelsetlabel|, which initially expands to
% just |\showlabelfont #1|.  You can use this mechanism to get a
% variety of effects.  For example, if you say
% \begin{quote}
% |\usepackage{showlabels,rotating}|\\
% |\renewcommand{\showlabelsetlabel}[1]|\\
% \null\qquad |{\begin{turn}{60}\showlabelfont #1\end{turn}}|
% \end{quote}
% then you end up with your labels at a jaunty angle in the margin.
%
% If you wish the package to do its magic with the command |\foo|
% (most typically |\cite|), then give the command |\showlabels{foo}|.
% The default behaviour of the package is to give the command
% |\showlabels{label}| internally; if you don't want this to happen --
% perhaps because you \emph{only} want |\cite| commands highlighted --
% then give the option \Lopt{nolabel} to the |\usepackage| command:
% |\usepackage[nolabel]{showlabels}|.
%
% By default, the package displays labels in the margin of the
% document, but as an alternative, labels can be kept inline as much
% as possible; this is much more legible when there are multiple
% labels on a single line.  To select this, give the option
% \Lopt{inline}, and to select the default behaviour, use
% \Lopt{marginal}.
%
% Finally, we have the options \Lopt{final} and \Lopt{draft}.  The option
% \Lopt{final} turns off all the functionality of this package.  This
% is included so that if that
% option is given globally in the |\documentclass| declaration then this
% package does respect it.  \Lopt{draft} does nothing, and therefore
% simply continues the default behaviour of this package; it is here
% to partner the \Lopt{final} option.
%
% \subsection*{Compatibility with other packages, and other problems}
%
% The \pstyle{showlabels} package works by redefining the |\label|
% command, along with the internal \LaTeX\ commands |\@eqnnum|,
% |\@makecaption| and
% |\maketag@@@| (for \pstyle{amsmath}).  All the other commands it
% defines are `hidden' by prefixing them with `\texttt{SL@}', with
% the exception of the user commands |\showlabelfont| and
% |\showlabelsetlabel|.  Each of
% the three redefined commands carefully includes its previous
% definition.  The \pstyle{showlabels} package should therefore come
% \emph{last} of the packages you include using |\usepackage|.
%
% In version 1.1, the package was modified to conform to the slightly
% different mechanism that \texttt{amsmath} uses to produce equation
% numbers.  Do note that the
% |\usepackage{showlabels}| command \emph{must} appear after the
% |\usepackage{amsmath}| if it is to detect that you are using the
% \pstyle{amsmath} package\footnote{Note that AMS-\LaTeX\ and the
% \texttt{amstex} package have been declared `obsolete' in favour of
% the \texttt{amsmath} package.  This package now claims conformance
% with the \texttt{amsmath} package alone, though it will probably
% work with older versions in fact.}.
%
% In version 1.3e, the program became compatible with the
% \pstyle{hyperref} package in particular, and in general with other
% packages which themselves modify the |\label| command.  This will
% work, however, only if the \pstyle{showlabels} package is loaded
% after other packages which do this.  Notwithstanding Sebastian
% Rahtz's excellent general advice on this, \pstyle{showlabels} should
% be loaded after \pstyle{hyperref}.
%
% For reasonably obvious reasons, this package will not work at all 
% well with the \pstyle{multicol} package, and for possibly less obvious 
% reasons, it won't work with the \Lopt{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 \emph{should} now work with \pstyle{wrapfig}, though I'm not
% sure that I've exhausted that package's various clevernesses, and
% there might be some spacing and layout bugs which manifest
% themselves in that context.  Please report them; in the mean time,
% using option \Lopt{inline} should act as a workaround for any that
% appear.
%
% When labels appear in the margins, they sometimes appear on the
% `wrong' side in \Lopt{twoside} mode.  This is a fairly inevitable
% side-effect of the way that \TeX\ builds pages, and a specific
% symptom of the general problem described in
% \url{http://www.tex.ac.uk/cgi-bin/texfaq2html?label=oddpage}.
% As that answer suggests, there are bear-traps involved in the
% standard solutions.  Now, showlabels is (a)~permanently teetering
% on the edge of clashing with everything else that messes around with
% labels, and (b)~a draft-only package rather than anything that
% would appear in a final document.  (a)~means that I'm rather nervous
% about putting too much cleverness in there, and incidentally shy of
% putting any dependencies on other packages; (b)~means that I feel it
% doesn't really matter enough to be worth removing robustness.  So
% I'm afraid I don't plan to change this, and I simply put up with the
% occasional slip.  Again the \Lopt{inline} option is a possible
% workaround.
%
% The package might still work with \LaTeX2.09, but that's neither
% supported, nor even still tested.
%
% This software is copyright, 1999, 2001--2007, Norman Gray.
% It is released under
% the terms of the GNU General Public Licence.  See the copyright
% declaration at the top of file \texttt{showlabels.dtx}, and the file
% \texttt{LICENCE} for the licence conditions.  You can find an
% online copy of the GPL at
% \url{http://www.gnu.org/copyleft/gpl.html}.
%
% The canonical home page of the package is
% \url{http://purl.org/nxg/dist/showlabels}, and it is on CTAN at
% \url{/macros/latex/contrib/supported/showlabels/}.
%
% \subsection*{Other packages}
%
% I know of, but have not yet played with, the package \pstyle{showkeys},
% by David Carlisle.  As far as I know, both packages do roughly the
% same thing.
%
% \subsection*{History and Credits}
%
% I've received bug reports, fixes, or implementable suggestions from many
% people, including
%   Andreas Balser,
%   Francis M. C. Ching,
%   Michael Friendly,
%   Tino G\"ortem\"oller,
%   Lester L. Helms,
%   Hagen Kleinert,
%   Olivier Michel,
%   Sungmo Park,
%   Ignacy Sawicki,
%   Andrei Shelankov,
%   Patrick Sibille,
%   David R. Leal Valmana,
%   Ji\v ri Vesely,
%   Elmar Walhorn,
%   Roland Winkler.
% Many thanks to all.  If I've missed your name out of this list,
% please accept my apologies, and do let me know.
%
% Back in 29-Jan-92, Darrel Hankerson
% \url{hank@ducvax.auburn.edu}, made the update to NFSS, and
% changed the name to `showlabel.sty'.
%
% The package was originally released by me on 21-Sep-91, under the name
% \texttt{labels.sty}.
%
%
% \StopEventually{}
%
% \section{Implementation}
%    \begin{macrocode}
%<*package>
%    \end{macrocode}%
% \iffalse
% Update history:
% October 94: Norman Gray (norman@astro.gla.ac.uk). Modified to be a 
% \LaTeX2e package.  After that, see |\changes|.
% 29-Jan-92 Darrel Hankerson (hank@ducvax.auburn.edu)
%  Update to NFSS. Change name to `showlabel.sty'. Substitute
%  	\nintt -> \small\tt
%	\sevit -> \scriptsize\it
% 21-Sep-91 Norman Gray  no_gray@vax.acs.open.ac.uk 
%  Original release of labels.sty
% \fi
%
% Before we do anything else, find out if we're using \pstyle{amsmath}\dots.
% Note that, since these additions appeared, AMS-\LaTeX\ and the
% \texttt{amstex} package seem to have been declared `obsolete'.  This
% package now claims conformance with the \texttt{amsmath} package.
% \changes{v1.2}{1996/05/12}{Finally added the AMS-LaTeX variant ifSL@noAMS}
% \changes{v1.3}{1999/02/22}{More rational if it's ifSL@AMS}
%    \begin{macrocode}
\newif\ifSL@AMS
\expandafter\ifx\csname maketag@@@\endcsname\relax
  \SL@AMSfalse
\else
  \SL@AMStrue
  \typeout{with amsmath equation tags}
\fi
%    \end{macrocode}
%
% \begin{macro}{\@eqnnum}
% This replacement for |\@eqnnum| will produce a note, sticking
% into the margin beside the equation number, showing the equation's label.
% |\SL@labelname| 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 \pstyle{amsmath} case
% as it artfully incorporates the |\maketag@@@| mechanism into a
% redefined |\@eqnnum|.
%
%    \begin{macrocode}
\ifSL@AMS
%    \end{macrocode}
%
% \pstyle{amsmath} uses |\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.
%    \begin{macrocode}
  \let\SL@maketag@@@=\maketag@@@
  \def\maketag@@@#1{%
    \SL@maketag@@@{#1}%
    \ifx\df@label\@empty
%    \SL@eqnlrtext{???}%
    \else
      \SL@eqnlrtext{\df@label}%
    \fi
  }
\else
%    \end{macrocode}
% The `normal' case, without \pstyle{amsmath}.
% \changes{v1.3c}{1999/07/22}{Added expandafter before test -- 
%       how on earth had this escaped before?!?}
% \changes{v1.3d}{1999/07/23}{Removed ??? when no label exists}
% \changes{v1.6.1}{2007/06/17}{Fix test again.}
% The test here must be |\ifx\SL@labelname\relax| with
% |\global\let\SL@labelname\relax|, not |\expandafter\ifx\SL@...| and
% |\global\def\SL@labelname{\relax}| (as it once was), since the
% latter evaluates to true when |\SL@...| is |\relax| \emph{and} when
% |\SL@...| starts with two identical characters, which is wrong (it
% took embarrassingly many goes to get this right).
%    \begin{macrocode}
  \let\SL@eqnnum=\@eqnnum
  \def\@eqnnum{%
    \SL@eqnnum
    \ifx\SL@labelname\relax
%    \SL@eqnlrtext{???}%
    \else
      \SL@eqnlrtext{\SL@labelname}%
      \global\let\SL@labelname\relax
    \fi
  }
%    \end{macrocode}
% \end{macro}
% And initialise the value of |\SL@labelname| to |\relax|, so that 
% |\@eqnnum| starts off behaving the right way. 
%    \begin{macrocode}
  \global\let\SL@labelname\relax
\fi
%    \end{macrocode}
%
% Labels are printed with the font specified by |\showlabelfont|, which
% can be overridden within the document:
% \changes{v1.3}{1999/02/22}{Added showlabelfont}
% Define this using |\ttfamily|, unless we're still using \LaTeX 2.09
% (surprising it still works!), in which case stick with |\tt|.
% \changes{v1.5a}{2005/03/18}{Use ttfamily instead of tt}
%    \begin{macrocode}
\@ifundefined{ttfamily}
  {\providecommand{\showlabelfont}{\small\tt}}
  {\providecommand{\showlabelfont}{\small\ttfamily}}
%    \end{macrocode}
%
% If you want slightly more general control over the labels, you can
% instead override |\showlabelsetlabel|, which is just
% |\newcommand{\showlabelfont}[1]{\normalfont\showlabelfont #1}| by default.
%    \begin{macrocode}
\providecommand{\showlabelsetlabel}[1]{\normalfont\showlabelfont #1}
%    \end{macrocode}
%
% For the benefit of |\SL@prlabelname|, define |\SL@gobblethree| to do nothing 
% other than eat three tokens.
%    \begin{macrocode}
\def\SL@gobblethree#1#2#3{}
%    \end{macrocode}
%
% \begin{macro}{\SL@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.
%    \begin{macrocode}
\def\SL@prlabelname#1{%
\expandafter\expandafter\expandafter\SL@gobblethree
    \expandafter\string\csname r@#1\endcsname}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\showlabels}
% \changes{1.4}{2001/07/23}{Define showlabels command}
% Define the |\showlabels| command which allows us to redefine
% commands which are to have their arguments highlighted.
% That is, |\showlabels{foo}| means that the command |\foo{bar}| will
% write `bar' in the margin, as well as executing whatever |\foo| does
% normally.
%
% The net result of all this is that a |\showlabels{foo}| command
% arranges things so that, after |\begin{document}|,  |\foo{bar}| expands into
% |\SL@setlabel{bar}\SL@origfoo{bar}|.
%
% First, define a command |\SL@initfoo|, which, when executed, will
% save the current (at that time) behaviour of the command |\foo| as
% |\@SL@origfoo|, and then set |\foo| to be equivalent to |\SL@foo|,
% which does the magic; we will 
% shortly give this command to |\AtBeginDocument|, so that it is
% switched on at the correct time, when other packages have done
% \emph{their} redefinitions of |\foo| (this makes it compatible with
% the \pstyle{hyperref} package, which does its own wholesale redefinitions of
% things like |\label|).  Below, the locution
% |\the\@temptokena| causes the token contents of |\@temptokena| to be
% included unexpanded in the definition, despite the |\edef|.
%    \begin{macrocode}
\def\showlabels#1{%
  \@temptokena=\expandafter{\csname #1\endcsname}
  \expandafter\edef\csname SL@init#1\endcsname{%
    \let\csname SL@orig#1\endcsname\the\@temptokena
    \let\the\@temptokena\csname SL@#1\endcsname}
  \AtBeginDocument{\csname SL@init#1\endcsname}%
%    \end{macrocode}
% \emph{Now} define |\SL@foo| -- it must be undefined when we define
% |\SL@initfoo| above, so that it isn't expanded in the |\edef|.
%    \begin{macrocode}
  \expandafter\def\csname SL@#1\endcsname{\SL@showlabels{#1}}
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\SL@showlabels}
% Now we get to the command which does the main processing.  The
% |\SL@showlabels| command calls |\SL@setlabel| to format the label
% (putting it in the margin, for example), then calls the original
% |\foo| command (namely |\SL@origfoo|) with the original argument.
%
% The command takes a single argument, namely the name of the command
% being wrapped (for example, `label').  We set |\@tempa| to be the
% original version of that command (stored in |\SL@orig#1|), and then
% take one of two similar paths, depending on whether the command has
% an optional argument or not.
%
% We have to be somewhat careful about the positioning of the
% |\@bsphack| and |\@esphack| commands.  The |\@esphack| command should
% \emph{not} come after the call to |\SL@origfoo|, since that would
% confuse things terribly if that command took any other arguments, or
% otherwise messed with the token stream (there's actually no problem
% in the most common case where we're replacing |\label|, and calling
% |\SL@origlabel|, but there are problems when we try to replace
% |\begin| or |\ref| in this way).  Instead, adapt the contents 
% of |\@esphack|, but instead of calling |\ignorespaces| when
% |\@savsk| is positive, add an |\hskip| of 1~scaled point (equal to
% $1/65536\mathrm{pt}=5.363\times10^{-9}\mathrm{m}$).  This will be
% invisible, but it \emph{is} greater than zero, so that if
% |\SL@origfoo| itself uses a |\@bsphack|\dots|\@esphack| pair then
% the saved |\@savsk| will be positive, and that future |\@esphack|
% will correctly invoke |\ignorespaces|; that pair will also pick up
% the |\spacefactor| we restore here.  The net result is that the
% |\SL@setlabel| is invisible, and |\SL@origfoo| is able to make
% itself invisible, too.  Command sequence |\SL@setlabel| is what does
% the work -- this is |\let| equal to either |\SL@margtext| or
% |\SL@inlinetext| below.
%    \begin{macrocode}
\def\SL@showlabels#1{%
  \def\@tempa{\csname SL@orig#1\endcsname}
  \@ifnextchar[\SL@showlabelsopt\SL@showlabelsplain
}
\def\SL@showlabelsopt[#1]#2{%
  \@bsphack
  \SL@setlabel{#2}\relax
  \ifhmode \spacefactor\@savsf \ifdim\@savsk>\z@ \hskip1sp \fi\fi
  \@tempa[#1]{#2}%
}
\def\SL@showlabelsplain#1{%
  \@bsphack
  \SL@setlabel{#1}\relax
  \ifhmode \spacefactor\@savsf \ifdim\@savsk>\z@ \hskip1sp \fi\fi
  \@tempa{#1}%
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@makecaption}
% The |\@makecaption| command needs special treatment.  The
% |\SL@margtext| command doesn't work in figure captions, so we need
% to force the layout commands to use |\SL@inlinetext| instead, for
% all label types, and irrespective of whether we're using the
% \Lopt{inline} option.  The code here is independent of that in
% |\showlabels|, but imitates it, for consistency.
% \changes{v1.4a}{2003/01/28}{Use SL@inlinetext to display caption label}
%    \begin{macrocode}
\def\SL@initmakecaption{%
  \let\SL@origmakecaption\@makecaption
  \def\@makecaption##1##2{{%
    \let\SL@setlabel\SL@inlinetext\SL@origmakecaption{##1}{##2}}}}
\AtBeginDocument{\SL@initmakecaption}   
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\SL@margtext}
% This is the central bit of this package, used by |\SL@showlabels|.
% The argument is the argument of the |\foo| command which we're
% processing (for example, the argument to a |\label| command).
%
% Depending on the mode, put the 
% current label name in the margin in one of a variety of ways.
% \changes{1.4}{2001/07/23}{Define SL@margtext command}
%    \begin{macrocode}
\def\SL@margtext#1{%
%    \end{macrocode}
% In maths mode, produce a label name alongside the equation number.
% If we're not using \pstyle{amsmath}, then save the label name in
% |\SL@labelname|.  If we \emph{are} using \pstyle{amsmath}, then we don't
% have to worry, because it's saved in |\df@label| for us.
%    \begin{macrocode}
  \ifmmode
    \ifSL@AMS\else
      \xdef\SL@labelname{\SL@prlabelname{#1}}%
    \fi
%    \end{macrocode}
% 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
% |\box\@tempboxa| (which probably shouldn't be necessary).  The box
% here we set to be the width of |\hsize|.  This is \emph{probably}
% best, though there's always the worry that |\linewidth| would be the
% more \LaTeX-ish thing to do -- using |\columnwidth| is almost
% certainly wrong, since |\linewidth| can sometimes be changed without
% |\columnwidth| changing with it (for example, in package
% \pstyle{wrapfig}), causing \pstyle{showlabels} to fail badly.
% \changes{v1.4}{2002/04/21}{Changed columnwidth to hsize}
%    \begin{macrocode}
  \else
    \setbox\@tempboxa=\vbox to 0pt{\vss
      \hbox to \hsize{\SL@lrtext{#1}}}%
    \dp\@tempboxa\z@
%    \end{macrocode}
% and attach it below the last one, using |\nointerlineskip| if we're in 
% vertical mode, or |\vadjust| otherwise.  We need to save and restore
% the value of |\prevdepth| (which has the sentinel value -1000pt if we're
% adding this box at the beginning of a vertical list, and
% |\nointerlineskip| sets |\prevdepth| to this same value).  If we don't
% do this, we get extra (`interline') vertical space added in this
% case (it might be thought smart to use |\marginpar| here, and so
% avoid some of this nonsense, but that's not possible since this
% might be called within boxes, which |\marginpar| objects to). 
%    \begin{macrocode}
    \ifvmode
      \@tempdima=\prevdepth
      \nointerlineskip\box\@tempboxa\nobreak
      \prevdepth=\@tempdima
    \else
      \vadjust{\box\@tempboxa\nobreak}%
    \fi
%    \end{macrocode}
% That's it.  Finish off the |\ifmmode|.
%    \begin{macrocode}
  \fi
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\SL@inlinetext}
% This is an alternative way of formatting the label, which puts it
% inline as much as possible, and avoids straying into the margins.
% \changes{1.5}{2002/04/15}{Introduce SL@inlinetext (1.5??)}
%    \begin{macrocode}
\def\SL@inlinetext#1{%
%    \end{macrocode}
% Maths mode as with |\SL@margtext|
%    \begin{macrocode}
\ifmmode
  \ifSL@AMS\else
    \xdef\SL@labelname{\SL@prlabelname{#1}}%
  \fi
\else
  \SL@interlinetextright{#1}%
\fi
}
%    \end{macrocode}
% In vmode, put the label between lines.  Set the box depth to zero to
% make sure that descenders don't mess up the spacing.
% \changes{1.4a}{2002/10/15}{Add SL@interlinetext and friends}
%    \begin{macrocode}
\def\SL@interlinetextleft{\SL@setlefttrue\SL@interlinetext}
\def\SL@interlinetextright{\SL@setleftfalse\SL@interlinetext}
\def\SL@interlinetext#1{%
  \setbox\@tempboxa=\hbox{\showlabelsetlabel{#1}}\dp\@tempboxa\z@
  \ifvmode
    \nointerlineskip\vbox to 0pt{\vss
      \hbox to \columnwidth{\hss \box\@tempboxa}}%
%    \end{macrocode}
% And in hmode, squeeze it between the lines, at the current point,
% carefully taking up no space.
%    \begin{macrocode}
  \else
    \ifSL@setleft
      \hbox to 0pt{%
	\hss
	\vbox to 0pt{\vss
	  \hbox to 0pt{\hss\box\@tempboxa}%
	  \hrule width 0.05em height 1.5ex depth 0pt
	}}%
    \else
      \hbox to 0pt{%
	\vbox to 0pt{\vss
	  \box\@tempboxa
	  \hrule width 0.05em height 1.5ex depth 0pt
	}\hss}%
    \fi
    \penalty10000 
  \fi
}
%    \end{macrocode}
% \end{macro}
%
%
% \begin{macro}{\SL@margintext}
% Set the actual text of the label.  Use |\SL@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.
% \changes{v1.3}{1999/02/22}{Use prlabelname within SL@margintext}
%    \begin{macrocode}
\def\SL@margintext#1{{\showlabelsetlabel{\{\SL@prlabelname{#1}\}}}}
%    \end{macrocode}
% \end{macro}
%
% 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 |\SL@labelposition| below, to 
% one of |\SL@lefttext|, |\SL@righttext| or |\SL@alternatetext|.
% \begin{macro}{\SL@righttext}
% \begin{macro}{\SL@lefttext}
%    \begin{macrocode}
\def\SL@righttext#1{\hfill\rlap{\quad\SL@margintext{#1}}}
\def\SL@lefttext #1{\llap{\SL@margintext{#1}\quad}\hfill}
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
% \begin{macro}{\SL@setLR}
% Define a switch which allows us to state whether we've decided to
% set a particular label to the left or the right, and a macro
% |\SL@setLR| to set it.  After |\SL@setLR|, |\ifSL@setleft| is true
% if a label should be set to the left, and is false if it should go
% to the right.
%    \begin{macrocode}
\newif\ifSL@setleft
\def\SL@setLR{%
  \ifcase\SL@labelposition
    % 0=outer margin
    \ifodd\c@page
      \SL@setleftfalse
    \else
      \SL@setlefttrue
    \fi
  \or
    % 1=inner margin
    \ifodd\c@page
      \SL@setlefttrue
    \else
      \SL@setleftfalse
    \fi
  \or
    % 2=left margin
    \SL@setlefttrue
  \or
    % 3=right margin
    \SL@setleftfalse
  \else
    \SL@canthappen{Impossible labelposition \the\SL@labelposition}
    \SL@labelposition=3 % put everything in the right-margin for now
    \SL@setleftfalse
  \fi
}
%    \end{macrocode}
% \end{macro}
%
% 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.
% \begin{macro}{\SL@alternatetext}
%    \begin{macrocode}
\def\SL@alternatetext{%
  \SL@setLR
  \ifSL@setleft
    \let\SL@next\SL@lefttext
  \else
    \let\SL@next\SL@righttext
  \fi
  \SL@next
}
%    \end{macrocode}
% \end{macro}
% The case where the \Lopt{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 
% \file{multicol.sty} along with this).  This is defined and maintained in 
% the base file \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.
% \begin{macro}{\SL@twocoltext}
% \changes{v1.1}{1995/02/06}{Added the twocoltext alternatives}
%    \begin{macrocode}
\def\SL@twocoltext{%
  \if@firstcolumn
    \let\SL@next\SL@lefttext
  \else
    \let\SL@next\SL@righttext
  \fi
  \SL@next}
%    \end{macrocode}
% \end{macro}
%
% 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 \Lopt{leqno} option (how?).
% \begin{macro}{\SL@eqnrighttext}
% \begin{macro}{\SL@eqnlefttext}
%    \begin{macrocode}
\def\SL@eqnrighttext#1{\rlap{\quad\SL@margintext{#1}}}
\def\SL@eqnlefttext #1{\hbox to 0pt{\kern -\columnwidth
	\llap{\SL@margintext{#1}\quad}\hss}}
%    \end{macrocode}
% \end{macro}
% \end{macro}
% Now do the analogues for the equation numbers, in the case of the 
% alternate page selection\dots
% \begin{macro}{\SL@eqnalternatetext}
%    \begin{macrocode}
\def\SL@eqnalternatetext{%
  \SL@setLR
  \ifSL@setleft
    \let\SL@next\SL@eqnlefttext
  \else
    \let\SL@next\SL@eqnrighttext
  \fi
  \SL@next
}
%    \end{macrocode}
% \end{macro}
% \dots and the twocolumn option
% \begin{macro}{\SL@eqntwocoltext}
%    \begin{macrocode}
\def\SL@eqntwocoltext{%
  \if@firstcolumn
    \let\SL@next\SL@eqnlefttext
  \else
    \let\SL@next\SL@eqnrighttext
  \fi
  \SL@next}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\SL@canthappen}
% Issues a |\PackageError| command, and solicits bug reports.
%    \begin{macrocode}
\def\SL@canthappen#1{%
    \PackageError{showlabels}{#1}
        {This shouldn't happen -- the package showlabels has a bug.
        \MessageBreak
        Please report this, if possible with a sample document which
        \MessageBreak
        demonstrates the problem, to \filemaintainer.  Thanks.}}
%    \end{macrocode}
% \end{macro}
%
% To control the positioning of labels, set the |\SL@labelposition|
% switch, which can take values 0, 1, 2, 3, meaning outer, inner,
% left, right margin respectively.
% \changes{v1.4a}{2003/01/28}{Added left/right options}
%    \begin{macrocode}
\newcount\SL@labelposition
\SL@labelposition=0
%    \end{macrocode}
%
% We select between the various possibilities using the \Lopt{outer} and 
% \Lopt{inner} options and, implicitly, the \Lopt{twoside} option.
%    \begin{macrocode}
\DeclareOption{outer}{\SL@labelposition=0}
\DeclareOption{inner}{\SL@labelposition=1}
\DeclareOption{left}{\SL@labelposition=2}
\DeclareOption{right}{\SL@labelposition=3}
%    \end{macrocode}
%
% \begin{macro}{\SL@setlabel}
% Labels can be set either in the margins or inline, by switching
% between definitions of |\SL@setlabel|.
%    \begin{macrocode}
\DeclareOption{marginal}{\let\SL@setlabel\SL@margtext}
\DeclareOption{inline}{\let\SL@setlabel\SL@inlinetext}
\let\SL@setlabel\SL@margtext
%    \end{macrocode}
% \end{macro}
%
% By default, we run |\showlabels{label}|.  The option \Lopt{nolabel}
% turns this off.
%    \begin{macrocode}
\newif\if@showlabellabel
\@showlabellabeltrue
\DeclareOption{nolabel}{\@showlabellabelfalse}
%    \end{macrocode}
%
% Define the options \Lopt{final} and \Lopt{draft}.  The option
% \Lopt{final} turns off all the functionality of this package by
% disabling the command |\showlabels|, including the implicit
% |\showlabels| command which the package issues as long as the
% \Lopt{nolabel} option has not been given.  This is included so that if that
% option is given in the |\documentclass| declaration then this
% package does respect it.  \Lopt{draft} does nothing, and therefore
% simply continues the default behaviour of this package; it is here
% purely to partner the \Lopt{final} option.
%    \begin{macrocode}
\DeclareOption{final}{\let\showlabels\@gobble}
\DeclareOption{draft}{}
%    \end{macrocode}
%
% Process any options that have been set.
%    \begin{macrocode}
\ProcessOptions
%    \end{macrocode}
% and use the values of |\SL@labelposition| 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 \Lopt{twocolumn} option 
% means that we ignore the \Lopt{inner} and \Lopt{outer} options.
%    \begin{macrocode}
\if@twocolumn
  \let\SL@lrtext\SL@twocoltext
  \let\SL@eqnlrtext\SL@eqntwocoltext
\else
  \ifcase\SL@labelposition
    % 0=outer margin
    \if@twoside
      \let\SL@lrtext\SL@alternatetext
      \let\SL@eqnlrtext\SL@eqnalternatetext
    \else
      \let\SL@lrtext\SL@righttext
      \let\SL@eqnlrtext\SL@eqnrighttext
    \fi
  \or
    % 1=inner margin
    \if@twoside
      \let\SL@lrtext\SL@alternatetext
      \let\SL@eqnlrtext\SL@eqnalternatetext
    \else
      \let\SL@lrtext\SL@lefttext
      \let\SL@eqnlrtext\SL@eqnlefttext
    \fi
  \or
    % 2=left margin
    \let\SL@lrtext\SL@lefttext
    \let\SL@eqnlrtext\SL@eqnlefttext
  \or
    % 3=right margin
    \let\SL@lrtext\SL@righttext
    \let\SL@eqnlrtext\SL@eqnrighttext
  \else
    \SL@canthappen{Impossible labelposition \the\SL@labelposition}
    \SL@labelposition=3 % put everything in the right-margin for now
    \let\SL@lrtext\SL@righttext
    \let\SL@eqnlrtext\SL@eqnrighttext
  \fi
\fi
%    \end{macrocode}
%
% If we have selected the \Lopt{inline} option, however (which we can
% detect because |\SL@setlabel| will have been set to
% |\SL@inlinetext|, then put equation numbers inline, too.
% \changes{1.4a}{2002/10/15}{Equation numbers inline, too}
%    \begin{macrocode}
\ifx\SL@setlabel\SL@inlinetext
  \let\SL@eqnlrtext\SL@interlinetextleft
\fi
%    \end{macrocode}
%
% Finally, label all the |\label| commands (default, and previous,
% behaviour), unless this has been suppressed through the
% \Lopt{nolabel} option.
%    \begin{macrocode}
\if@showlabellabel
  \showlabels{label}
\fi
%    \end{macrocode}
%
% That's us.  
%
%    \begin{macrocode}
%</package>
%    \end{macrocode}
%
% \Finale
\endinput