From e55f5510950cf773d024770b0a0d66b13e37dae0 Mon Sep 17 00:00:00 2001 From: Norbert Preining Date: Sun, 10 Oct 2021 03:01:13 +0000 Subject: CTAN sync 202110100301 --- macros/latex/contrib/showlabels/showlabels.dtx | 341 ++++++++++++++++++++++--- 1 file changed, 309 insertions(+), 32 deletions(-) (limited to 'macros/latex/contrib/showlabels/showlabels.dtx') diff --git a/macros/latex/contrib/showlabels/showlabels.dtx b/macros/latex/contrib/showlabels/showlabels.dtx index 3a2c457965..c1a72a27ff 100644 --- a/macros/latex/contrib/showlabels/showlabels.dtx +++ b/macros/latex/contrib/showlabels/showlabels.dtx @@ -2,7 +2,7 @@ % %% This is the showlabels package %% -%%%% Copyright 1999, 2001-09, 2013-16, Norman Gray +%%%% 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 @@ -14,23 +14,18 @@ %% %% This work has the LPPL maintenance status `maintained'. %% -%% The Current Maintainer of this work is Norman Gray +%% The Current Maintainer of this work is Norman Gray %% %% This work consists of the files showlabels.dtx and showlabels.ins, %% and the derived file showlabels.sty. %%%% File: showlabels.dtx -%%%% Source: 95a544e6b41b, 2016-06-09T16:51:03+01:00 +%%%% Source: 5b2959804f35, 2021-10-09T20:59:45+01:00 -\def\filename{showlabels} -\def\fileversion{1.8} -\def\filedate{2016/06/09} -\def\docdate{2016 June 9} -\def\filemaintainer{norman@astro.gla.ac.uk} -% This is revision 95a544e6b41b, 2016-06-09T16:51:03+01:00. +% This is revision 5b2959804f35, 2021-10-09T20:59:45+01:00. %<+package>\NeedsTeXFormat{LaTeX2e} -%<+package>\ProvidesPackage{showlabels}[\filedate\space v\fileversion] -%<+package>\typeout{Package: `showlabels' v\fileversion\space<\filedate>} +%<+package>\ProvidesPackage{showlabels}[2021-10-09\space v1.9] +%<+package>\typeout{Package: `showlabels' v1.9\space<2021-10-09>} % %<*driver> \documentclass{ltxdoc} @@ -67,9 +62,9 @@ % \fi % % -% \title{The \texttt{\filename} package} -% \author{Norman Gray\\|norman@astro.gla.ac.uk|} -% \date{Version \fileversion, \docdate} +% \title{The \texttt{showlabels} package} +% \author{Norman Gray\\|gray@nxg.name|} +% \date{Version 1.9, 2021 October 9} % % \maketitle % @@ -126,6 +121,17 @@ % then give the option \Lopt{nolabel} to the |\usepackage| command: % |\usepackage[nolabel]{showlabels}|. % +% 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}| +% will do this for each of the items that appear in the +% \Lenv{thebibliography} environment, whether it is writen by you or +% by \BibTeX\ (if you use the `biblatex' package, then the +% corresponding command would be +% |\makeatletter\showlabels{blx@bibitem}\makeatother|, but notice that +% this is in principle an undocumented internal of the `biblatex' +% package, so may change). +% % 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 @@ -139,7 +145,7 @@ % temporarily, within a block or environment. Use the % |\showlabelsinline| macro to do that. % -% \subsection*{Formatting} +% \section{Formatting} % % If you want to change the font the labels appear in, redefine the % |\showlabelfont| command, which by default expands to @@ -148,8 +154,8 @@ % \begin{quote} % |\renewcommand{\showlabelfont}{\small\slshape\color{green}}| % \end{quote} -% in the preamble of your document, as long as you have loaded the -% \Lpackage{color} package. +% in the preamble of your document (as long as you have loaded the +% \Lpackage{color} package, of course). % % Alternatively, the |\showlabels| command has an optional argument containing % formatting commands, which allows you to format |\cite| labels, for @@ -157,6 +163,12 @@ % \begin{quote} % |\showlabels[\color{green}]{cite}| % \end{quote} +% The optional formatting command can be either a font-changing +% command, as illustrated here, \emph{or} a command which takes a +% single argument, such as +% \begin{quote} +% |\showlabels[\fbox]{cite}| +% \end{quote} % % If, finally, you want complete control over the labels, you can % instead override |\showlabelsetlabel|, which initially expands to @@ -168,16 +180,28 @@ % \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. -% 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. +% +% The command |\showlabeltype| will expand to the current label type +% (ie, `label' or `cite', etc), so it would be possible for +% |\showlabelsetlabel| to conditionalise on that, if you felt that +% were necessary.\footnote{The support for an one-argument command in +% $\backslash$\texttt{showlabels}, and the presence of the +% $\backslash$\texttt{showlabeltype} macro, were added in version 1.9.} +% +% If instead you want to adjust how inline markings are displayed, you +% can change the definition of the +% |\showlabelrefline| rule from its default. % For example, defining this to be +% \begin{quote} % |\color{red}\hrule width 0.1em height 1.5ex depth 0pt | +% \end{quote} % produces a fattish red line, and defining it to be +% \begin{quote} % |\hrule width 0pt height 1.5ex depth 0pt| +% \end{quote} % suppresses the line but still positions the text between the lines. % -% \subsection*{Compatibility with other packages, and other problems} +% \section{Compatibility with other packages, and other problems} % % The \Lpackage{showlabels} package works by redefining the |\label| % command, along with a few internal \LaTeX\ commands. All the other commands it @@ -252,18 +276,18 @@ % The canonical home page of the package is % \url{http://purl.org/nxg/dist/showlabels}, and it is on CTAN at % \url{https://www.ctan.org/pkg/showlabels}. The source is in -% a repository at Bitbucket: \url{https://bitbucket.org/nxg/showlabels/}. +% a repository online: \url{https://hg.sr.ht/~nxg/showlabels}. % -% \subsection*{Other packages} +% \section{Other packages} % % The \Lpackage{showlabels} package has a large overlap in % functionality with David Carlisle's \Lpackage{showkeys}, although % the latter will only handle |\label| and |\cite| keys. If % \Lpackage{showlabels} fails in some particular situation, you might % want to try using \Lpackage{showkeys}, but please do mention the -% problem, either by email to me, or via the Bitbucket issues list. +% problem, typically by email to me. % -% \subsection*{History and Credits} +% \section{History and Credits} % % I've received bug reports, fixes, or implementable suggestions from many % people, including @@ -303,6 +327,234 @@ % \url{hank@ducvax.auburn.edu}, made the update to NFSS, and % changed the name to `showlabel.sty'. % +% \subsection{Release notes} +% \begingroup +% \iffalse the following are variously unsatisfactory +% \def~{\texttt{\textasciitilde}} +% \def~{$\sim$} +% \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 +% (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 +% 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 +% 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 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 +% (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 +% (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 +% |{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 +% (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 +% (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 +% 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 +% 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 +% 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 +% (such as |\cite| or |\includegraphics|) which +% take an optional argument. +% +% +% +% \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 +% |\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 +% |[right]| options, and fixed a bug which affected +% |\label| commands in captions. +% +% +% +% \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 +% 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 +% package. It corrects all the reported bugs which I could reproduce, +% namely: +% +% \begin{itemize} +% \item 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 +% 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 +% 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 +% 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 +% consequently be glad to be informed of any that appear. Do note that +% the |\usepackage{showlabels}| command \emph{must} appear +% after the |\usepackage{amsmath}| if it is to detect that +% you are using the amsmath package. Note also that, since these +% additions appeared, AMS-LaTeX and the |amstex| package seem +% 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 +% (|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 % % \StopEventually{} % @@ -312,7 +564,7 @@ % \end{macrocode}% % \iffalse % Update history: -% October 94: Norman Gray (norman@astro.gla.ac.uk). Modified to be a +% October 94: Norman Gray (gray@nxg.name). Modified to be a % \LaTeX2e package. % 29-Jan-92 Darrel Hankerson (hank@ducvax.auburn.edu) % Update to NFSS. Change name to `showlabel.sty'. Substitute @@ -462,7 +714,7 @@ % If you want slightly more general control over the labels, you can % instead override |\showlabelsetlabel|. % \begin{macrocode} -\providecommand{\showlabelsetlabel}[1]{{\normalfont\showlabelfont\SL@fmt@ #1}} +\providecommand{\showlabelsetlabel}[1]{{\normalfont\showlabelfont\SL@fmt@{#1}}} % \end{macrocode} % % For the benefit of |\SL@prlabelname|, define |\SL@gobblethree| to do nothing @@ -473,8 +725,14 @@ % % \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. +% abounds!). Use |\r@#1| (defined by |\ref|), rather then just |\#1| +% to avoid defining any new control sequences. +% +% Note that this catcode magic, and the |\@sanitize| in +% |\SL@showlabels| below, are doing much the same job, and indeed are +% almost redundant with each other. But this |\SL@prlabelname| +% doesn't cope with eg |\index{Poincar\'e}|, and the |\@sanitize| +% below doesn't cope with |\section{\label{a_b}Foo}| (see tests t4 and t19). % \begin{macrocode} \def\SL@prlabelname#1{% \expandafter\expandafter\expandafter\SL@gobblethree @@ -579,9 +837,28 @@ % 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). +% +% 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). +% +% 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 +% locally, but we would then have to be careful exactly when we closed +% the group: if we put it inside the group that's opened for +% |\@sanitize|, it would be closed too early to have an effect; if we +% open another group for |\showlabeltype|, then we'd have to close it +% \emph{after} |\SL@orig@@next|, where we risk colliding with whatever +% comes after it (and see above). It might be possible to be cleverer +% about this, but it's at least harmeless to have the command defined +% globally. % \begin{macrocode} \DeclareRobustCommand\SL@showlabels[1]{% + \@bsphack \expandafter\let\expandafter\SL@orig@@next\csname SL@orig#1\endcsname + \def\showlabeltype{#1}% + \begingroup\@sanitize \@ifstar {\SL@showlabelsplainstar} {\@ifnextchar[ @@ -589,19 +866,19 @@ {\SL@showlabelsplain}} } \def\SL@showlabelsopt[#1]#2{% - \@bsphack + \endgroup \SL@setlabel{#2}\relax \ifhmode \spacefactor\@savsf \ifdim\@savsk>\z@ \hskip1sp \fi\fi \SL@orig@@next[#1]{#2}% } \def\SL@showlabelsplain#1{% - \@bsphack + \endgroup \SL@setlabel{#1}\relax \ifhmode \spacefactor\@savsf \ifdim\@savsk>\z@ \hskip1sp \fi\fi \SL@orig@@next{#1}% } \def\SL@showlabelsplainstar#1{% - \@bsphack + \endgroup \SL@setlabel{#1}\relax \ifhmode \spacefactor\@savsf \ifdim\@savsk>\z@ \hskip1sp \fi\fi \SL@orig@@next*{#1}% -- cgit v1.2.3