027a5da3c827 — Norman Gray 9 months ago
Commands with optional arguments are now handled with the correct catcodes
4 files changed, 67 insertions(+), 21 deletions(-)

M Makefile
M release-notes.xml
M showlabels.dtx.in
A => t/t20.tex
M Makefile +1 -1
@@ 18,7 18,7 @@ 
 #
 # See also the suggestions at <https://ctan.org/help/upload-pkg>.
 
-VERSION=1.10-SNAPSHOT
+VERSION=1.9.1b1
 # RELEASEDATE comes from the repository
 DIST=showlabels-$(VERSION)
 

          
M release-notes.xml +8 -3
@@ 1,10 1,15 @@ 
 <release-notes xmlns='http://ns.nxg.me.uk/release-notes'>
 
   <release>
-    <version>1.10?</version>
-    <date>YYYY-MM-DD</date>
+    <version>1.9.1</version>
+    <date>2021-10-22</date>
     <note>
-      <p>To come...</p>
+      <p>Commands with optional arguments, such as
+      <code>\bibitem[P\'olya]{polya_54}</code> are now handled with the
+      correct catcodes.
+      Fixes <a href='https://todo.sr.ht/~nxg/showlabels/1'>issue 1</a>
+      (new sequencing for issues).
+      Thanks to Michael Levitin for the report here.</p>
     </note>
   </release>
 

          
M showlabels.dtx.in +36 -17
@@ 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}|

          
@@ 529,7 539,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

          
@@ 544,7 555,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}

          
@@ 617,12 628,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

          
@@ 639,31 659,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}
 %

          
A => t/t20.tex +22 -0
@@ 0,0 1,22 @@ 
+%%% Testing: \bibitem with significant catcodes in the optional argument
+% Thanks to Michael Levitin <mr.levitin@googlemail.com> for reporting
+% this, with essentially the following MWE.
+\documentclass{article}
+
+\usepackage{showlabels}
+\showlabels{bibitem}
+\showlabels{cite}
+
+%\usepackage[colorlinks,allcolors=blue]{hyperref}
+\begin{document}
+
+\noindent
+We will use \cite{Pol_54}, and we should see \verb|Pol_54| in the
+margin, and `P\'olya' in the bibliography.
+
+\begin{thebibliography}{999999}
+\bibitem[P{\'o}lya]{Pol_54} G. P\'{o}lya,
+  \emph{Mathematics and plausible reasoning}, in two volumes,
+  Princeton University Press, Princeton, N. J., 1954.
+\end{thebibliography}
+\end{document}