showlabels (27oct21)

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

2 files changed, 87 insertions, 191 deletions

diff --git a/Master/texmf-dist/source/latex/showlabels/showlabels.drv b/Master/texmf-dist/source/latex/showlabels/showlabels.drv
index 4c70b228be3..cb1d23393ab 100644
--- a/Master/texmf-dist/source/latex/showlabels/showlabels.drv
+++ b/Master/texmf-dist/source/latex/showlabels/showlabels.drv
@@ -11,11 +11,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'.
@@ -26,7 +26,7 @@
 %% 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
 
 \documentclass{ltxdoc}
 \EnableCrossrefs
diff --git a/Master/texmf-dist/source/latex/showlabels/showlabels.dtx b/Master/texmf-dist/source/latex/showlabels/showlabels.dtx
index c1a72a27ff1..ef6f107f608 100644
--- a/Master/texmf-dist/source/latex/showlabels/showlabels.dtx
+++ b/Master/texmf-dist/source/latex/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}
 %