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.dtx341
1 files changed, 309 insertions, 32 deletions
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 <http://nxg.me.uk>
+%% The Current Maintainer of this work is Norman Gray <https://nxg.me.uk>
%%
%% 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}%