showlabels (11dec15)

git-svn-id: svn://tug.org/texlive/trunk@39083 c570f23f-e606-0410-a88d-b1316a301751

2 files changed, 326 insertions, 212 deletions

diff --git a/Master/texmf-dist/source/latex/showlabels/showlabels.drv b/Master/texmf-dist/source/latex/showlabels/showlabels.drv
index c33c3dcb259..6baee82ff31 100644
--- a/Master/texmf-dist/source/latex/showlabels/showlabels.drv
+++ b/Master/texmf-dist/source/latex/showlabels/showlabels.drv
@@ -8,7 +8,7 @@
 %% Showlabels: Style to display labels in the margin
 %% This is the showlabels package
 %%
-%%%% Copyright 2005--2013, Norman Gray
+%%%% Copyright 1999, 2001--09, 2013--15, Norman Gray
 %%
 %% This work may be distributed and/or modified under the
 %% conditions of the LaTeX Project Public License, either version 1.3
@@ -25,16 +25,16 @@
 %% This work consists of the files showlabels.dtx and showlabels.ins,
 %% and the derived file showlabels.cls.
 \def\filename{showlabels}
-\def\fileversion{1.6.6}
-\def\filedate{2013/12/06}
-\def\docdate{2013 December 6}
+\def\fileversion{1.7}
+\def\filedate{2015/12/08}
+\def\docdate{2015 December 8}
 \def\filemaintainer{norman@astro.gla.ac.uk}
 \documentclass{ltxdoc}
 \EnableCrossrefs
 \newcommand\Lopt[1]{\textsf{#1}} % package options
 \newcommand\file[1]{\texttt{#1}} % filename
 \newcommand\Lenv[1]{\textsl{\{#1\}}}
-\newcommand\pstyle[1]{\textsf{\{#1\}}} % packages
+\newcommand\Lpackage[1]{\textsf{\{#1\}}} % packages
 %% \url macro (url.sty does this better, but we don't want extra dependencies)
 \def\setpathdots{\discretionary{.}{}{.}}
 \def\setpathslash{\discretionary{/}{}{/}}
diff --git a/Master/texmf-dist/source/latex/showlabels/showlabels.dtx b/Master/texmf-dist/source/latex/showlabels/showlabels.dtx
index 5e87a0a65d0..ec9053b780e 100644
--- a/Master/texmf-dist/source/latex/showlabels/showlabels.dtx
+++ b/Master/texmf-dist/source/latex/showlabels/showlabels.dtx
@@ -2,7 +2,7 @@
 %
 %% This is the showlabels package
 %%
-%%%% Copyright 2005--2013, Norman Gray
+%%%% Copyright 1999, 2001--09, 2013--15, Norman Gray
 %%
 %% This work may be distributed and/or modified under the
 %% conditions of the LaTeX Project Public License, either version 1.3
@@ -13,18 +13,18 @@
 %% version 2005/12/01 or later.
 %%
 %% This work has the LPPL maintenance status `maintained'.
-%% 
+%%
 %% The Current Maintainer of this work is Norman Gray <http://nxg.me.uk>
 %%
 %% This work consists of the files showlabels.dtx and showlabels.ins,
 %% and the derived file showlabels.cls.
 %
 \def\filename{showlabels}
-\def\fileversion{1.6.6}
-\def\filedate{2013/12/06}
-\def\docdate{2013 December 6}
+\def\fileversion{1.7}
+\def\filedate{2015/12/08}
+\def\docdate{2015 December 8}
 \def\filemaintainer{norman@astro.gla.ac.uk}
-% \changes{v1.4}{2001/07/23}{Avoided defining RCSDate}
+% This is revision aa6f5b4db751, 2015-12-08.
 %<+package>\NeedsTeXFormat{LaTeX2e}
 %<+package>\ProvidesPackage{showlabels}[\filedate\space v\fileversion]
 %<+package>\typeout{Package: `showlabels' v\fileversion\space<\filedate>}
@@ -33,21 +33,21 @@
 \documentclass{ltxdoc}
 \EnableCrossrefs
 %    \end{macrocode}
-%    Some commonly used abbreviations for option names, filenames, 
+%    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\Lenv[1]{\textsl{\{#1\}}}
-\newcommand\pstyle[1]{\textsf{\{#1\}}}		% packages
+\newcommand\Lpackage[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 
+{\catcode`\.=\active
+ \catcode`\/=\active
   \gdef\pathcats{%
-    \catcode`\%=12      \catcode`\~=12 
+    \catcode`\%=12      \catcode`\~=12
     \catcode`\.=\active  \let.\setpathdots
     \catcode`\/=\active \let/\setpathslash
     \catcode`\#=12      \catcode`\_=12}%
@@ -55,17 +55,14 @@
 \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|}
@@ -92,7 +89,7 @@
 %    \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 
+%    \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)\\
@@ -102,13 +99,45 @@
 % \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. 
+% right hand one.
 %
-% The package will also work in the presence of the \Lopt{twocolumn} 
+% 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.
 %
+% 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.  The \Lopt{draft} option does nothing, and therefore
+% simply continues the default behaviour of this package; it is here
+% to partner the \Lopt{final} option.
+%
+% \DescribeMacro{\showlabels}
+% 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}.
+%
+% \DescribeMacro{\showlabelsinline}
+% It is sometimes convenient (for example when a document encounters a
+% situation which this package mishandles) to force inline labels
+% temporarily, within a block or environment.  Use the
+% |\showlabelsinline| macro to do that.
+%
+% \subsection*{Formatting}
+%
 % 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,
@@ -117,8 +146,16 @@
 % |\renewcommand{\showlabelfont}{\small\slshape\color{green}}|
 % \end{quote}
 % in the preamble of your document, as long as you have loaded the
-% \pstyle{color} package.
-% If you want still more control over the labels, you can
+% \Lpackage{color} package.
+%
+% Alternatively, the |\showlabels| command has an optional argument containing
+% formatting commands, which allows you to format |\cite| labels, for
+% example, differently from |\label|.  Thus:
+% \begin{quote}
+% |\showlabels[\color{green}]{cite}|
+% \end{quote}
+%
+% If, finally, you want complete 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
@@ -127,7 +164,7 @@
 % |\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.  
+% then you end up with your labels at a jaunty angle in the margin.
 % Finally, you can change the definition of the
 % |\showlabelrefline| rule from its default,
 % in order to change how the inline rule (see below) is displayed.
@@ -137,40 +174,17 @@
 % |\hrule width 0pt height 1.5ex depth 0pt|
 % suppresses the line but still positions the text between the lines.
 %
-% 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.  The \Lopt{draft} option 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|
+% The \Lpackage{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
+% |\maketag@@@| (for \Lpackage{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
+% definition.  The \Lpackage{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
@@ -178,26 +192,31 @@
 % 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
+% \Lpackage{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
+% In version 1.3e, the package became compatible with the
+% \Lpackage{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
+% work, however, only if the \Lpackage{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 
+% Rahtz's excellent general advice on this, \Lpackage{showlabels} should
+% be loaded after \Lpackage{hyperref}.
+%
+% In version 1.7, the package became compatible with the
+% equation-numbering mechanism of the \Lpackage{IEEEtrantools}
+% package.  As with \Lpackage{amsmath}, this involves a certain amount
+% of special-casing.
+%
+% For reasonably obvious reasons, this package will not work at all
+% well with the \Lpackage{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
+% package \emph{should} now work with \Lpackage{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,
@@ -224,15 +243,10 @@
 % The package might still work with \LaTeX2.09, but that's neither
 % supported, nor even still tested.
 %
-% This software is copyright, 1999, 2001--2009, 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}.  If the licence is a
-% problem for some reason, please get in touch -- I'm probably fairly
-% easily persuadable to change it.
+% This software is copyright, 1999, 2001--09, 2013--15 Norman Gray.
+% It is released under the terms of the LaTeX Project Public Licence.
+% See the copyright declaration at the top of file \texttt{showlabels.dtx},
+% and the file \texttt{lppl}, for the licence conditions.
 %
 % The canonical home page of the package is
 % \url{http://purl.org/nxg/dist/showlabels}, and it is on CTAN at
@@ -240,7 +254,7 @@
 %
 % \subsection*{Other packages}
 %
-% David Carlisle's \pstyle{showkeys} does roughly the same thing, but
+% David Carlisle's \Lpackage{showkeys} does roughly the same thing, but
 % it will only handle |\label| and |\cite| keys.
 %
 % \subsection*{History and Credits}
@@ -248,15 +262,20 @@
 % I've received bug reports, fixes, or implementable suggestions from many
 % people, including
 %   Andreas Balser,
+%   bartgol (on Stackexchange),
 %   Francesco Biccari,
 %   Francis M. C. Ching,
 %   Sven de Vries,
+%   A L Dukeman,
 %   Michael Friendly,
+%   Guillermo Garza,
 %   Tino G\"ortem\"oller,
 %   Lester L. Helms,
+%   Boris Kheyfets,
 %   Hagen Kleinert,
 %   David R. Leal Valmana,
 %   Olivier Michel,
+%   Enno Nagel,
 %   Sungmo Park,
 %   Ignacy Sawicki,
 %   Andrei Shelankov,
@@ -264,6 +283,8 @@
 %   Mariano Su\'arez-Alvarez,
 %   Ji\v ri Vesely,
 %   Elmar Walhorn,
+%   Alex Watson,
+%   Ben William Carabelli,
 %   Roland Winkler.
 % Many thanks to all.  If I've missed your name out of this list
 % (or indeed if I've alphabetised you incorrectly),
@@ -284,30 +305,53 @@
 %    \end{macrocode}%
 % \iffalse
 % Update history:
-% October 94: Norman Gray (norman@astro.gla.ac.uk). Modified to be a 
-% \LaTeX2e package.  After that, see |\changes|.
+% October 94: Norman Gray (norman@astro.gla.ac.uk). Modified to be a
+% \LaTeX2e package.
 % 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 
+% 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.
+% Before we do anything else, find out if we're using \Lpackage{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
+\@ifundefined{maketag@@@}
   \SL@AMSfalse
-\else
-  \SL@AMStrue
-  \typeout{with amsmath equation tags}
-\fi
+  {\SL@AMStrue\typeout{with amsmath equation tags}}
+%    \end{macrocode}
+%
+% The command which sets equationn text is |\SL@eqntext|, which tests
+% whether the content should be inline or not.
+%    \begin{macrocode}
+\def\SL@eqntext{%
+  \ifSL@labelsinline
+    \let\@tempa\SL@interlinetextleft
+  \else
+    \let\@tempa\SL@eqnlrtext
+  \fi
+  \@tempa
+}
+%    \end{macrocode}
+%
+% The |\SL@wrap@labeller| macro wraps the given macro in such a way
+% that we display the label.
+%    \begin{macrocode}
+\def\SL@wrap@labeller#1{%
+  \expandafter\let\csname SL@orig@#1\expandafter\endcsname\csname #1\endcsname
+  \expandafter\def\csname #1\endcsname{%
+    \csname SL@orig@#1\endcsname
+    \ifx\SL@labelname\relax
+      % do nothing
+    \else
+      \SL@eqntext{\SL@labelname}%
+    \fi
+    \global\let\SL@labelname\relax}}
 %    \end{macrocode}
 %
 % \begin{macro}{\@eqnnum}
@@ -316,19 +360,21 @@
 % |\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
-% we avoid putting anything in the margin.  In the \pstyle{amsmath} case
+% we avoid putting anything in the margin.  In the \Lpackage{amsmath} case
 % we instead redefine |\maketag@@@|.
 %
+% First, deal with the case where the document uses the
+% \Lpackage{amsmath} macros.
 %    \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.  If the |\df@label| is
+% \Lpackage{amsmath} redefines |\label| to set the macro |\df@label|,
+% and then uses |\maketag@@@{\df@label}|, to form tags (ie, equation
+% labels) in equations.  So we hook into the |\maketag@@@| macro.
+% If the |\df@label| is
 % empty (almost certainly because the user has used the
-% \Lenv{eqnarray} environment within \pstyle{amsmath}), then fall back
+% \Lenv{eqnarray} environment within \Lpackage{amsmath}), then fall back
 % on the |\SL@labelname| contents instead.
 % \iffalse See tests t2 and t11\fi
 % We must make sure to leave |\SL@labelname| equal to |\relax| at the
@@ -341,56 +387,57 @@
 % |\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).
+% took embarrassingly many goes to get this right). The following is
+% similar to the effect of |\SL@wrap@labeller|, but not quite,
+% because (a) |\maketag@@@| takes an argument, and (b) we also have to
+% check |\df@label|.
 %    \begin{macrocode}
-  \let\SL@maketag@@@=\maketag@@@
-  \def\maketag@@@#1{%
-    \SL@maketag@@@{#1}%
-    %\message{maketag@@@: df@label=\df@label, SL@labelname=\SL@labelname, env=\@currenvir}%
+  \let\SL@orig@maketag@@@=\maketag@@@
+  \def\SL@maketag@@@#1{%
+    \SL@orig@maketag@@@{#1}%
     \ifx\df@label\@empty
       \ifx\SL@labelname\relax
         % do nothing
       \else
-        \SL@eqnlrtext{\SL@labelname}%
+        \SL@eqntext{\SL@labelname}%
       \fi
     \else
-      \SL@eqnlrtext{\df@label}%
+      \SL@eqntext{\df@label}%
     \fi
     \global\let\SL@labelname\relax
   }
 \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.}
+%
+% Next, deal with the `normal' case, without \Lpackage{amsmath}.
+% Package \Lpackage{amsmath} redefines |\@eqnnum| in terms of
+% |\maketag@@@|, so we should avoid doing this in the
+% non-\Lpackage{amsmath} case.
 %    \begin{macrocode}
-  \let\SL@eqnnum=\@eqnnum
-  \def\@eqnnum{%
-    \SL@eqnnum
-    \ifx\SL@labelname\relax
-      % do nothing
-    \else
-      \SL@eqnlrtext{\SL@labelname}%
-    \fi
-    \global\let\SL@labelname\relax
-  }
+  %% \let\SL@eqnnum=\@eqnnum
+  %% \def\@eqnnum{%
+  %%   \SL@eqnnum
+  %%   \ifx\SL@labelname\relax
+  %%     % do nothing
+  %%   \else
+  %%     \SL@eqntext{\SL@labelname}%
+  %%   \fi
+  %%   \global\let\SL@labelname\relax
+  %% }
+  \SL@wrap@labeller{@eqnnum}
 \fi
 %    \end{macrocode}
 % \end{macro}
-% And initialise the value of |\SL@labelname| to |\relax|, so that 
-% |\@eqnnum| starts off behaving the right way. 
+% 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
 %    \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}}
@@ -400,18 +447,18 @@
 % If you want slightly more general control over the labels, you can
 % instead override |\showlabelsetlabel|.
 %    \begin{macrocode}
-\providecommand{\showlabelsetlabel}[1]{{\normalfont\showlabelfont #1}}
+\providecommand{\showlabelsetlabel}[1]{{\normalfont\showlabelfont\SL@fmt@ #1}}
 %    \end{macrocode}
 %
-% For the benefit of |\SL@prlabelname|, define |\SL@gobblethree| to do nothing 
+% 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 
+% 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{%
@@ -421,7 +468,6 @@
 % \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
@@ -435,28 +481,48 @@
 % 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 
+% 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
+% the \Lpackage{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|.
+%
+% If the optional argument is present, then use this as per-command
+% formatting, so that, for example |\cite| instances may be formatted
+% distinctively from |\label|.
 %    \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}%
+\def\showlabels{\@ifnextchar[\showlabels@{\showlabels@[]}}
+\def\showlabels@[#1]#2{%
+  \@temptokena=\expandafter{\csname #2\endcsname}
+  \def\@tempa{#1}%
+  \ifx\@tempa\@empty
+    \expandafter\let\csname SL@fmt@#2\endcsname\relax
+  \else
+    \expandafter\def\csname SL@fmt@#2\endcsname{#1}%
+  \fi
+  \expandafter\edef\csname SL@init@#2\endcsname{%
+    \let\csname SL@orig#2\endcsname\the\@temptokena
+    \let\the\@temptokena\csname SL@#2\endcsname}
+  \AtBeginDocument{\csname SL@init@#2\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}}
+  \expandafter\def\csname SL@#2\endcsname{%
+    \expandafter\let\expandafter\SL@fmt@\csname SL@fmt@#2\endcsname
+    \SL@showlabels{#2}}
 }
 %    \end{macrocode}
+%
+% We need a default definition of |\SL@fmt@| for the cases (some
+% equation formatting) where we don't get to the formatting via this
+% mechanism.
+%    \begin{macrocode}
+\let\SL@fmt@\relax
+%    \end{macrocode}
 % \end{macro}
 %
 % \begin{macro}{\SL@showlabels}
@@ -478,7 +544,7 @@
 % 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 
+% |\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
@@ -492,25 +558,38 @@
 % the work -- this is |\let| equal to either |\SL@margtext| or
 % |\SL@inlinetext| below.
 %
-% We must declare |\SL@showlabels| to be a robust command, or else we 
+% We must declare |\SL@showlabels| to be a robust command, or else we
 % get confusing expansion problems when, for example, we do
 % |\showlabels{ref}| and use |\ref| in a caption (see test case t3).
+% We actually handle three distinct cases here, for |\foo{label}|,
+% |\foo[opt]{label}| and |\foo*{label}| (the last is to handle the
+% \Lpackage{hyperref} package's |\ref*{label}| variant; see test case t14).
 %    \begin{macrocode}
 \DeclareRobustCommand\SL@showlabels[1]{%
-  \def\@tempa{\csname SL@orig#1\endcsname}%
-  \@ifnextchar[\SL@showlabelsopt\SL@showlabelsplain
+  \expandafter\let\expandafter\SL@orig@@next\csname SL@orig#1\endcsname
+  \@ifstar
+    {\SL@showlabelsplainstar}
+    {\@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}%
+  \SL@orig@@next[#1]{#2}%
 }
 \def\SL@showlabelsplain#1{%
   \@bsphack
   \SL@setlabel{#1}\relax
   \ifhmode \spacefactor\@savsf \ifdim\@savsk>\z@ \hskip1sp \fi\fi
-  \@tempa{#1}%
+  \SL@orig@@next{#1}%
+}
+\def\SL@showlabelsplainstar#1{%
+  \@bsphack
+  \SL@setlabel{#1}\relax
+  \ifhmode \spacefactor\@savsf \ifdim\@savsk>\z@ \hskip1sp \fi\fi
+  \SL@orig@@next*{#1}%
 }
 %    \end{macrocode}
 % \end{macro}
@@ -522,13 +601,13 @@
 % 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}   
+    \let\SL@setlabel\SL@inlinetext
+    \SL@origmakecaption{##1}{##2}}}}
+\AtBeginDocument{\SL@initmakecaption}
 %    \end{macrocode}
 % \end{macro}
 %
@@ -537,23 +616,48 @@
 % 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 
+% 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}
+%
+% There are three cases here:
+% \begin{enumerate}
+% \item We are in maths mode, setting an equation.
+% \item We are not in maths mode but we \emph{are} within a display
+% (this can happen in, for example, the \Lenv{cases} environment from
+% the \Lpackage{cases} package).
+% \item We are in text.
+% \end{enumerate}
+%
+% Case 1:
 % In maths mode, produce a label name alongside the equation number.
 % Save the label name in |\SL@labelname|, so we can use it later
-% (this is redundant in most \pstyle{amsmath} contexts, because that
+% (this is redundant in most \Lpackage{amsmath} contexts, because that
 % style generally saves this in |\df@label|, but sometimes -- for
 % example when using the traditional \Lenv{eqnarray} environment
-% within \pstyle{amsart} -- |\df@label| can end up unset).
+% within \Lpackage{amsart} -- |\df@label| can end up unset).
 %    \begin{macrocode}
   \ifmmode
     \xdef\SL@labelname{\SL@prlabelname{#1}}%
 %    \end{macrocode}
-% Otherwise, create a box with zero height and depth, and the same width 
+%
+% Case 2:
+% Check if we're within a display equation,
+% and if so act as if we are in maths mode (ie, as above).
+% Note: most contexts which match case~1 would also be caught by this
+% test, since |\label| is used almost exclusively within displays,
+% but it seems clearer to separate the two cases explicitly, as well
+% as probably dealing better with cases where the package is used for
+% non-|\label| commands.
+%    \begin{macrocode}
+  \else\ifdim\displaywidth>0pt
+    \xdef\SL@labelname{\SL@prlabelname{#1}}%
+%    \end{macrocode}
+%
+% Case 3:
+% 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}
@@ -561,15 +665,15 @@
 % 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}
+% \Lpackage{wrapfig}), causing \Lpackage{showlabels} to fail badly.
 %    \begin{macrocode}
   \else
-    \setbox\@tempboxa=\vbox to 0pt{\vss
+    \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 
+% Attach this box 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
@@ -577,7 +681,7 @@
 % 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). 
+% might be called within boxes, which |\marginpar| objects to).
 %    \begin{macrocode}
     \ifvmode
       \@tempdima=\prevdepth
@@ -587,9 +691,9 @@
       \vadjust{\box\@tempboxa\nobreak}%
     \fi
 %    \end{macrocode}
-% That's it.  Finish off the |\ifmmode|.
+% That's it.  Finish off the sequence of cases.
 %    \begin{macrocode}
-  \fi
+  \fi\fi
 }
 %    \end{macrocode}
 % \end{macro}
@@ -597,34 +701,25 @@
 % \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??)}
+% We just use the same mechanism as for |\SL@margtext|, but do the
+% inline-or-not testing there.
 %    \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{\SL@prlabelname{#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@
+  \setbox\@tempboxa=\hbox{\showlabelsetlabel{\SL@prlabelname{#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,
+% And in horizontal mode, squeeze it between the lines, at the current point,
 % carefully taking up no space.
 %    \begin{macrocode}
   \else
@@ -634,15 +729,15 @@
  	\vbox to 0pt{\vss
  	  \hbox to 0pt{\hss\box\@tempboxa}%
  	  \showlabelrefline
- 	}}%
+        }}%
     \else
       \hbox to 0pt{%
  	\vbox to 0pt{\vss
  	  \box\@tempboxa
  	  \showlabelrefline
- 	}\hss}%
+        }\hss}%
     \fi
-    \penalty10000 
+    \penalty10000
   \fi
 }
 %    \end{macrocode}
@@ -661,15 +756,14 @@
 % 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 
+% 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}
@@ -718,9 +812,9 @@
 %    \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 
+% 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}
@@ -735,18 +829,17 @@
 }
 %    \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 
+% 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 
+% 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
@@ -759,8 +852,8 @@
 % \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 
+% place, rather than within a zero depth box.  This code \emph{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}
@@ -771,7 +864,7 @@
 %    \end{macrocode}
 % \end{macro}
 % \end{macro}
-% Now do the analogues for the equation numbers, in the case of the 
+% Now do the analogues for the equation numbers, in the case of the
 % alternate page selection\dots
 % \begin{macro}{\SL@eqnalternatetext}
 %    \begin{macrocode}
@@ -815,13 +908,12 @@
 % 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 
+% 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}
@@ -830,22 +922,44 @@
 \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
+\newif\ifSL@labelsinline
+\SL@labelsinlinefalse
+\DeclareOption{marginal}{\SL@labelsinlinefalse}
+\DeclareOption{inline}{\SL@labelsinlinetrue}
+%    \end{macrocode}
+% \begin{macro}{\SL@setlabel}
+%
+% Macro |\SL@setlabel| is where we switch between inline and marginal labels.
+%    \begin{macrocode}
+\def\SL@setlabel{%
+  \ifSL@labelsinline
+    \let\@tempa\SL@inlinetext
+  \else
+    \let\@tempa\SL@margtext
+  \fi
+  \@tempa
+}
 %    \end{macrocode}
 % \end{macro}
 %
+% \begin{macro}{\showlabelsinline}
+% It is sometimes convenient (for example when a document encounters a
+% situation which this package mishandles) to force inline labels
+% temporarily, within a block or environment.  Use this macro to do
+% that.
+%    \begin{macrocode}
+\def\showlabelsinline{\SL@labelsinlinetrue}
+%    \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}
+\newif\ifSL@labellabel
+\SL@labellabeltrue
+\DeclareOption{nolabel}{\SL@labellabelfalse}
 %    \end{macrocode}
 %
 % Define the options \Lopt{final} and \Lopt{draft}.  The option
@@ -867,8 +981,8 @@
 \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 
+% 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
@@ -910,26 +1024,26 @@
 \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}
+% Finally, label all the |\label| commands
+% (default behaviour),
+% unless this has been suppressed through the \Lopt{nolabel} option.
 %    \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
+\ifSL@labellabel
   \showlabels{label}
+  \ifSL@AMS
+    \ifx\showlabels\@gobble
+      % do nothing -- we're in [final] mode (see test case t13)
+    \else
+      \let\maketag@@@\SL@maketag@@@
+    \fi
+  \fi
+  \@ifundefined{theIEEEsubequationdis}\relax % and \theequationdis
+    {\SL@wrap@labeller{theIEEEsubequationdis}
+     \SL@wrap@labeller{theequationdis}}
 \fi
 %    \end{macrocode}
 %
-% That's us.  
+% That's us.
 %
 %    \begin{macrocode}
 %</package>