summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/showlabels/showlabels.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/showlabels/showlabels.dtx')
-rw-r--r--macros/latex/contrib/showlabels/showlabels.dtx272
1 files changed, 84 insertions, 188 deletions
diff --git a/macros/latex/contrib/showlabels/showlabels.dtx b/macros/latex/contrib/showlabels/showlabels.dtx
index c1a72a27ff..ef6f107f60 100644
--- a/macros/latex/contrib/showlabels/showlabels.dtx
+++ b/macros/latex/contrib/showlabels/showlabels.dtx
@@ -5,11 +5,11 @@
%%%% Copyright 1999, 2001-09, 2013-21, Norman Gray
%%
%% This work may be distributed and/or modified under the
-%% conditions of the LaTeX Project Public Licence, either version 1.3
+%% conditions of the LaTeX Project Public Licence, either version 1.3c
%% of this licence or (at your option) any later version.
%% The latest version of this licence is in
%% http://www.latex-project.org/lppl.txt
-%% and version 1.3 or later is part of all distributions of LaTeX
+%% and version 1.3c or later is part of all distributions of LaTeX
%% version 2005/12/01 or later.
%%
%% This work has the LPPL maintenance status `maintained'.
@@ -20,12 +20,12 @@
%% and the derived file showlabels.sty.
%%%% File: showlabels.dtx
-%%%% Source: 5b2959804f35, 2021-10-09T20:59:45+01:00
+%%%% Source: 1f8b1fcbe557, 2021-10-27T16:06:03+01:00
-% This is revision 5b2959804f35, 2021-10-09T20:59:45+01:00.
+% This is revision 1f8b1fcbe557, 2021-10-27T16:06:03+01:00.
%<+package>\NeedsTeXFormat{LaTeX2e}
-%<+package>\ProvidesPackage{showlabels}[2021-10-09\space v1.9]
-%<+package>\typeout{Package: `showlabels' v1.9\space<2021-10-09>}
+%<+package>\ProvidesPackage{showlabels}[2021/10/27\space v1.9.1]
+%<+package>\typeout{Package: `showlabels' v1.9.1\space<2021/10/27>}
%
%<*driver>
\documentclass{ltxdoc}
@@ -64,7 +64,7 @@
%
% \title{The \texttt{showlabels} package}
% \author{Norman Gray\\|gray@nxg.name|}
-% \date{Version 1.9, 2021 October 9}
+% \date{Version 1.9.1, 2021 October 27}
%
% \maketitle
%
@@ -113,14 +113,24 @@
% 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}|.
+% If you wish the package to do its magic with another command |\foo|
+% which takes at least one argument (for example |\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}|.
%
+% You can call |\showlabels{foo}| with commands which have starred
+% forms, |\foo*{arg}|, or optional arguments, |\foo[opt]{arg}|. A
+% technical wrinkle is that, in each case, the |{arg}| is read with
+% all of its characters being catcode `other'; I~can't think of a
+% realistic case where this is a problem, since the commands typically
+% given to |\showlabels| will almost certainly do something equivalent
+% to this anyway, but it is a mild change from the default behaviour
+% of the command |\foo|.
+%
% You can do this |\showlabels| step even with commands that you
% invoke only implicitly. If, for example, you want to label each of the
% entries in your bibliography, then |\showlabels{bibitem}|
@@ -268,13 +278,13 @@
% The package might still work with \LaTeX2.09, but that's neither
% supported, nor even still tested.
%
-% This software is copyright, 1999, 2001--09, 2013--16 Norman Gray.
-% It is released under the terms of the LaTeX Project Public Licence.
+% This software is copyright, 1999, 2001-09, 2013-21 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.txt}, 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
+% \url{https://purl.org/nxg/dist/showlabels}, and it is on CTAN at
% \url{https://www.ctan.org/pkg/showlabels}. The source is in
% a repository online: \url{https://hg.sr.ht/~nxg/showlabels}.
%
@@ -335,197 +345,87 @@
% \fi
% \catcode`\~=12
% \iffalse @RELEASENOTES@ \fi
-% \begin{description}
-%
-% \item[1.9, 2021 October 9]\relax
-% \begin{itemize}
-% \item Robustness fix: macros in arguments are now handled, so that
+% \begin{description}\item[1.9.1, 2021 October 27]\relax Commands with optional arguments, such as
+% |\bibitem[P\'olya]{polya_54}| are now handled with the
+% correct catcodes.
+% Fixes issue 1\footnote{\url{https://todo.sr.ht/~nxg/showlabels/1}}
+% (new sequencing for issues).
+% 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
% (after |\showlabel{index}|),
-% |\index{Poincar\'e}| doesn't cause an error.
-% \item The |\showlabel[optarg]{command}| optional argument
-% can now take a one-argument command.
-% \item The macro |\showlabeltype| expands to the current
-% label type, for possible use in |\showlabelsetlabel|.
-% \item The code has moved from Bitbucket to
+% |\index{Poincar\'e}| doesn't cause an error. \P\thinspace The |\showlabel[optarg]{command}| optional argument
+% can now take a one-argument command. \P\thinspace The macro |\showlabeltype| expands to the current
+% label type, for possible use in |\showlabelsetlabel|. \P\thinspace The code has moved from Bitbucket to
% Sourcehut\footnote{\url{https://sourcehut.org}}: the new repository is
% https://hg.sr.ht/~nxg/showlabels\footnote{\url{https://hg.sr.ht/~nxg/showlabels}}.
-% The issues links in the list below are therefore broken.
-% \end{itemize}
-%
-%
-% \item[1.8, 2016 June 9]\relax
-% The |ntheorem| package exposed an apparently
+% The issues links in the list below are therefore broken.\par\item[1.8, 2016 June 9]\relax The |ntheorem| package exposed an apparently
% long-standing incompleteness in the handling of |amsmath|
% documents.
-% Fixes issue 9\footnote{\url{https://bitbucket.org/nxg/showlabels/issues/9/}}.
-%
-%
-%
-% \item[1.7, 2015 December 8]\relax
-% Release v1.7.
-%
-%
-%
-% \item[1.7b2, 2015 December 7]\relax
-% Make the combination of amsmath and [inline] mode work
+% 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
% (fixes issue 8\footnote{\url{https://bitbucket.org/nxg/showlabels/issue/8/}}
% – thanks to A L Dukeman for the report;
-% what is it about showlabels and 6 December?!).
-%
-%
-%
-% \item[1.7b1, 2014 December 6]\relax
-% This is a much-delayed bugfix release (by coincidence
-% \emph{exactly} a year after the previous release!).
-%
-% \begin{itemize}
-% \item Give |\showlabels| an optional formatting argument
+% 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
+% \emph{exactly} a year after the previous release!).\par \P\thinspace Give |\showlabels| an optional formatting argument
% (implements issue 1\footnote{\url{https://bitbucket.org/nxg/showlabels/issue/1/}}
-% – thanks to Francesco Biccari for the suggestion).
-% \item Special-case the IEEEtrantools package
+% – thanks to Francesco Biccari for the suggestion). \P\thinspace Special-case the IEEEtrantools package
% (fixes issue 2\footnote{\url{https://bitbucket.org/nxg/showlabels/issue/2/}}
% – thanks to Boris Kheyfets for the report and test case, and to
-% Ben William Carabelli for additional analysis and a draft fix).
-% \item The |[final]| option now works with the
+% Ben William Carabelli for additional analysis and a draft fix). \P\thinspace The |[final]| option now works with the
% |{amsmath}| package
% (fixes issue 3\footnote{\url{https://bitbucket.org/nxg/showlabels/issue/3/}}
% – thanks to Guillermo Garza and Enno Nagel for the report, and to
-% Guillermo for the test case).
-% \item Handle the hyperref package's |\ref*{label}| variant
+% Guillermo for the test case). \P\thinspace Handle the hyperref package's |\ref*{label}| variant
% (fixes issue 4\footnote{\url{https://bitbucket.org/nxg/showlabels/issue/4/}}
-% – thanks to Alex Watson for the report and test case).
-% \item Handle the case where a label is in a display, but not in maths mode
+% – 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
% (fixes issue 5\footnote{\url{https://bitbucket.org/nxg/showlabels/issue/5/}}
-% – thanks to ‘bartgol’ on Stackexchange for the report and test case).
-% \end{itemize}
-%
-%
-% \item[1.6.6, 2013 December 6]\relax
-% \begin{itemize}
-% \item Add configuration interface |\showlabelrefline| and
+% – 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
% ensure that |\color| works in
-% |\showlabelfont|.
-% \item Various documentation tweaks
-% \item Change licence from GPL to LPPL
-% \item Fix link to repository
-% \end{itemize}
-%
-%
-% \item[1.6.5, 2009 May 27]\relax
-% Fixed a bug in the way that labels including underscores (and
-% other ‘exotic’ characters) were displayed.
-%
-%
-%
-% \item[1.6.4, 2008 October 10]\relax
-% Fixed another poor interaction between eqnarray and amsart. Now
+% |\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
+% other ‘exotic’ characters) were displayed.\par \item[1.6.4, 2008 October 10]\relax Fixed another poor interaction between eqnarray and amsart. Now
% we get equation labels in eqnarray, and we don't get marginal notes
-% about |\eqref| (which is good; might this finally be fixed?).
-%
-%
-%
-% \item[1.6.3, 2008 July 24]\relax
-% Release 1.6.2 broke compatibility with the \emph{rest} of
+% 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
% amsmath (|eqnarray| became the only thing that worked
-% within amsmath)! Fixed. Doh!
-%
-%
-%
-% \item[1.6.2, 2008 June 27]\relax
-% The reimplementation of eqnarray within amsart was such that
-% equation labels disappeared in that case. Fixed.
-%
-%
-%
-% \item[1.6.1, 2007 June 17]\relax
-% Fix an errant test, which mangled equation labels starting
-% with two identical letters.
-%
-%
-%
-% \item[1.6, 2006 May 26]\relax
-% The |\showlabels| command will now work with commands
+% within amsmath)! Fixed. Doh!\par \item[1.6.2, 2008 June 27]\relax The reimplementation of eqnarray within amsart was such that
+% 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
+% with two identical letters.\par \item[1.6, 2006 May 26]\relax The |\showlabels| command will now work with commands
% (such as |\cite| or |\includegraphics|) which
-% take an optional argument.
-%
-%
-%
-% \item[1.5a, 2005 March 17]\relax
-% Defined |\showlabelfont| using
+% take an optional argument.\par \item[1.5a, 2005 March 17]\relax Defined |\showlabelfont| using
% |\ttfamily| rather than |\tt| (I'd
% avoided doing this before to avoid a seemingly pointless
% incompatibility with LaTeX 2.09, but (a) I imagine the
% package is incompatible with that for other reasons, and (b)
-% it's really not worth the hassle...).
-%
-%
-%
-% \item[1.5, 2004 October 8]\relax
-% Added |\showlabelfont| and
+% it's really not worth the hassle...).\par \item[1.5, 2004 October 8]\relax Added |\showlabelfont| and
% |\showlabelsetlabel| commands, allowing
% customisation of the printed labels. Added and documented
% options [final], [draft] (the former makes this package do
-% nothing; the latter is the default behaviour).
-%
-%
-%
-% \item[1.4a, 2003 January 28]\relax
-% Acquired the |[left]| and
+% nothing; the latter is the default behaviour).\par \item[1.4a, 2003 January 28]\relax Acquired the |[left]| and
% |[right]| options, and fixed a bug which affected
-% |\label| commands in captions.
-%
-%
-%
-% \item[1.4, 2001 July 24]\relax
-% Became (more) compatible with the
+% |\label| commands in captions.\par \item[1.4, 2001 July 24]\relax Became (more) compatible with the
% wrapfig package. Also, I added the
% |\showlabels| command, to have the package display
% references to commands other than |\label|
% (|\cite| and |\ref| are obvious ones),
% and an |[inline]| option to have labels (etc.)
% displayed inline where possible, rather than always in the
-% margin.
-%
-%
-%
-% \item[1.3e, 2001 May 30]\relax
-% Became compatible with the hyperref package in
+% margin.\par \item[1.3e, 2001 May 30]\relax Became compatible with the hyperref package in
% particular, and in general with other packages which
% themselves modify the |\label| command. This will
% work, however, only if the showlabels package is loaded after
% other packages which do this. Notwithstanding Sebastian
% Rahtz's excellent general advice on this, showlabels should
-% indeed be loaded after hyperref.
-%
-%
-%
-% \item[1.3e, 2001 May 31]\relax
-% After a long delay, here is an updated version of my showlabels
+% 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
% package. It corrects all the reported bugs which I could reproduce,
-% namely:
-%
-% \begin{itemize}
-% \item The package now formats labels correctly when the
+% namely:\par \P\thinspace The package now formats labels correctly when the
% |\label| command appears outside either an equation or a
-% |\caption| (silly of me).
-%
-% \item A couple of people reported problems in the interaction with the
+% |\caption| (silly of me). \P\thinspace A couple of people reported problems in the interaction with the
% amsmath package. Either these were confined to that package's earlier
% incarnations as AMS-LaTeX or the amstex package, or else there's some
% arcane circumstance I can't reproduce, so I haven't found anything to
% fix on this matter. Note that the
% |\usepackage{showlabels}| command must come \emph{after}
% the |\usepackage{amsmath}| command. Bug-sightings here
-% will be warmly appreciated.
-%
-% \item I haven't worried too much about the precise formatting of the
+% will be warmly appreciated. \P\thinspace I haven't worried too much about the precise formatting of the
% labels – this is, after all, supposed to be a draft-only
-% package.
-% \end{itemize}
-%
-%
-% \item[1.1, 2001 January 1]\relax
-% Modified to conform to the slightly
+% package.\par\item[1.1, 2001 January 1]\relax Modified to conform to the slightly
% different mechanism that |amsmath| uses to produce equation
% numbers. I don't habitually use |amsmath|, so I won't
% discover any bugs or weaknesses with its support here, and I'd
@@ -537,24 +437,11 @@
% to have been declared ‘obsolete’ in favour of the |amsmath|
% package. This package now claims conformance with the
% |amsmath| package alone, though it will probably work with
-% older versions in fact.
-%
-%
-%
-% \item[Updated, 1992 January 29]\relax
-% On 1992 January 29, Darrel Hankerson
+% older versions in fact.\par This is the first version of the package to be distributed under
+% the name |showlabels|.\par \item[Updated, 1992 January 29]\relax On 1992 January 29, Darrel Hankerson
% (|hank@ducvax.auburn.edu|), made the update to NFSS, and
-% changed the name to |showlabel.sty|.
-%
-%
-%
-% \item[Original, 1991 September 21]\relax
-% The package was originally released by me on 1991 September 21, under the name
-% |labels.sty|.
-%
-%
-%
-% \end{description}% \endgroup
+% 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
+% |labels.sty|.\par \end{description}% \endgroup
%
% \StopEventually{}
%
@@ -748,7 +635,8 @@
% normally.
%
% The net result of all this is that a |\showlabels{foo}| command
-% arranges things so that, after |\begin{document}|, |\foo{bar}| expands into
+% arranges things so that, after |\begin{document}|, the original
+% version of |\foo| is saved in |\SL@origfoo|, and |\foo{bar}| expands into
% |\SL@setlabel{bar}\SL@origfoo{bar}|.
%
% First, define a command |\SL@initfoo|, which, when executed, will
@@ -763,7 +651,7 @@
% |\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
+% If the optional |\showlabels| argument is present, then use this as per-command
% formatting, so that, for example |\cite| instances may be formatted
% distinctively from |\label|.
% \begin{macrocode}
@@ -836,12 +724,21 @@
% |\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).
+% \Lpackage{hyperref} package's |\ref*{label}| variant; see test case
+% t14).
+%
+% Note that in each case, the |label| is read with sanitised
+% catcodes. That is, I think, always an acceptable thing to do, in
+% the sense that I can't think of cases where this breaks anything.
%
% We open a group in order to call |\@sanitize|; we're able to close
% it immediately, within the called macros. We call |\@sanitize| in
% order to cope with eg |\index{Poincar\'e}| (see discussion of
-% |\SL@prlabelname| above).
+% |\SL@prlabelname| above). We carefully \emph{avoid} calling
+% |\@sanitize| before reading an optional argument: this is so that
+% we read that argument with the existing catcode
+% assignments, so that eg |\bibitem[P{\'o}lya]{polya54}| works as
+% expected (see test t20).
%
% We declare |\showlabeltype| to be the `current' label type. It
% would be good to put this inside a group, so that it's only visible
@@ -858,31 +755,30 @@
\@bsphack
\expandafter\let\expandafter\SL@orig@@next\csname SL@orig#1\endcsname
\def\showlabeltype{#1}%
- \begingroup\@sanitize
+ \begingroup
\@ifstar
- {\SL@showlabelsplainstar}
+ {\@sanitize\SL@showlabelsplainstar}
{\@ifnextchar[
{\SL@showlabelsopt}
- {\SL@showlabelsplain}}
-}
-\def\SL@showlabelsopt[#1]#2{%
+ {\@sanitize\SL@showlabelsplain}}}
+\def\SL@showlabelsopt[#1]{% #1 is read before \@sanitize
+ \@sanitize
+ \SL@showlabelsopt@ii{#1}}
+\def\SL@showlabelsopt@ii#1#2{%
\endgroup
\SL@setlabel{#2}\relax
\ifhmode \spacefactor\@savsf \ifdim\@savsk>\z@ \hskip1sp \fi\fi
- \SL@orig@@next[#1]{#2}%
-}
+ \SL@orig@@next[#1]{#2}}
\def\SL@showlabelsplain#1{%
\endgroup
\SL@setlabel{#1}\relax
\ifhmode \spacefactor\@savsf \ifdim\@savsk>\z@ \hskip1sp \fi\fi
- \SL@orig@@next{#1}%
-}
+ \SL@orig@@next{#1}}
\def\SL@showlabelsplainstar#1{%
\endgroup
\SL@setlabel{#1}\relax
\ifhmode \spacefactor\@savsf \ifdim\@savsk>\z@ \hskip1sp \fi\fi
- \SL@orig@@next*{#1}%
-}
+ \SL@orig@@next*{#1}}
% \end{macrocode}
% \end{macro}
%