diff options
author | Karl Berry <karl@freefriends.org> | 2006-01-11 23:57:45 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2006-01-11 23:57:45 +0000 |
commit | 8c437039c00723f9aedc404b620bfbb4316df24c (patch) | |
tree | 2203082bde0899a158b4f662c31b9e469075e937 /Master/texmf-dist | |
parent | 4cdf5027186b67ba5e05c5c7cc6bd7eaa7b1981f (diff) |
trunk/Master/texmf-dist/source/latex/showlabels
git-svn-id: svn://tug.org/texlive/trunk@513 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist')
3 files changed, 976 insertions, 0 deletions
diff --git a/Master/texmf-dist/source/latex/showlabels/showlabels.drv b/Master/texmf-dist/source/latex/showlabels/showlabels.drv new file mode 100644 index 00000000000..9055ed88010 --- /dev/null +++ b/Master/texmf-dist/source/latex/showlabels/showlabels.drv @@ -0,0 +1,66 @@ +%% +%% This is file `showlabels.drv', +%% generated with the docstrip utility. +%% +%% The original source files were: +%% +%% showlabels.dtx (with options: `driver') +%% Showlabels: Style to display labels in the margin +%% This is the showlabels package +%% +%% This software is copyright, 1999, 2001--2005, Norman Gray. +%% +%% This program is free software; you can redistribute it and/or +%% modify it under the terms of the GNU General Public License +%% as published by the Free Software Foundation; either version 2 +%% of the License, or (at your option) any later version. +%% +%% This program is distributed in the hope that it will be useful, +%% but WITHOUT ANY WARRANTY; without even the implied warranty of +%% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +%% GNU General Public License for more details. +%% +%% You should have received a copy of the GNU General Public License +%% along with this program; if not, write to the Free Software +%% Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. +%% +%% Author: Norman Gray, norman@astro.gla.ac.uk. +%% Department of Physics and Astronomy, University of Glasgow, UK +%% +%% See the file LICENCE for a copy of the GPL. +%% You can also find an online copy at http://www.gnu.org/copyleft/gpl.html . +%% +%% $Id: showlabels.dtx,v 1.26 2005/03/17 18:39:35 norman Exp $ +%% +\def\ParseRCSDate$#1: #2 #3 ${\def\SL@Date{#2}} +\ParseRCSDate$Date: 2005/03/17 18:39:35 $ +\def\filename{showlabels} +\def\fileversion{1.5a} +\def\filedate{\SL@Date} +\def\docdate{\SL@Date} +\def\filemaintainer{norman@astro.gla.ac.uk} +\documentclass{ltxdoc} +\EnableCrossrefs +\newcommand\Lopt[1]{\textsf{#1}} % package options +\newcommand\file[1]{\texttt{#1}} % filename +\newcommand\pstyle[1]{\textsf{\{#1\}}} % packages +%% \url macro (url.sty does this better, but we don't want extra dependencies) +\def\setpathdots{\discretionary{.}{}{.}} +\def\setpathslash{\discretionary{/}{}{/}} +{\catcode`\.=\active + \catcode`\/=\active + \gdef\pathcats{% + \catcode`\%=12 \catcode`\~=12 + \catcode`\.=\active \let.\setpathdots + \catcode`\/=\active \let/\setpathslash + \catcode`\#=12 \catcode`\_=12}% + } +\def\setpath#1{\ttfamily <\nobreak #1\nobreak>\endgroup} +\def\url{\begingroup\pathcats\setpath} +\begin{document} +\DocInput{showlabels.dtx} +\PrintIndex +\end{document} +\endinput +%% +%% End of file `showlabels.drv'. diff --git a/Master/texmf-dist/source/latex/showlabels/showlabels.dtx b/Master/texmf-dist/source/latex/showlabels/showlabels.dtx new file mode 100644 index 00000000000..e1a2e9337f9 --- /dev/null +++ b/Master/texmf-dist/source/latex/showlabels/showlabels.dtx @@ -0,0 +1,896 @@ +% \iffalse % meta-comment +% +%% This is the showlabels package +%% +%% This software is copyright, 1999, 2001--2005, Norman Gray. +%% +%% This program is free software; you can redistribute it and/or +%% modify it under the terms of the GNU General Public License +%% as published by the Free Software Foundation; either version 2 +%% of the License, or (at your option) any later version. +%% +%% This program is distributed in the hope that it will be useful, +%% but WITHOUT ANY WARRANTY; without even the implied warranty of +%% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +%% GNU General Public License for more details. +%% +%% You should have received a copy of the GNU General Public License +%% along with this program; if not, write to the Free Software +%% Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. +%% +%% Author: Norman Gray, norman@astro.gla.ac.uk. +%% Department of Physics and Astronomy, University of Glasgow, UK +%% +%% See the file LICENCE for a copy of the GPL. +%% You can also find an online copy at http://www.gnu.org/copyleft/gpl.html . +%% +%% $Id: showlabels.dtx,v 1.26 2005/03/17 18:39:35 norman Exp $ +%% +% +\def\ParseRCSDate$#1: #2 #3 ${\def\SL@Date{#2}} +\ParseRCSDate$Date: 2005/03/17 18:39:35 $ +\def\filename{showlabels} +\def\fileversion{1.5a} +\def\filedate{\SL@Date} +\def\docdate{\SL@Date} +\def\filemaintainer{norman@astro.gla.ac.uk} +% \changes{v1.4}{2001/07/23}{Avoided defining RCSDate} +%<+package>\NeedsTeXFormat{LaTeX2e} +%<+package>\ProvidesPackage{showlabels}[\filedate\space v\fileversion] +%<+package>\typeout{Package: `showlabels' v\fileversion\space<\filedate>} +% +%<*driver> +\documentclass{ltxdoc} +\EnableCrossrefs +% \end{macrocode} +% Some commonly used abbreviations for option names, filenames, +% counters and packages. +% \begin{macrocode} +\newcommand\Lopt[1]{\textsf{#1}} % package options +\newcommand\file[1]{\texttt{#1}} % filename +%\newcommand\Lcount[1]{\textsl{\small#1}} +\newcommand\pstyle[1]{\textsf{\{#1\}}} % packages +%% \url macro (url.sty does this better, but we don't want extra dependencies) +\def\setpathdots{\discretionary{.}{}{.}} +\def\setpathslash{\discretionary{/}{}{/}} +{\catcode`\.=\active + \catcode`\/=\active + \gdef\pathcats{% + \catcode`\%=12 \catcode`\~=12 + \catcode`\.=\active \let.\setpathdots + \catcode`\/=\active \let/\setpathslash + \catcode`\#=12 \catcode`\_=12}% + } +\def\setpath#1{\ttfamily <\nobreak #1\nobreak>\endgroup} +\def\url{\begingroup\pathcats\setpath} +\begin{document} +% \RecordChanges +% \OnlyDescription +\DocInput{showlabels.dtx} +\PrintIndex +% \PrintChanges +\end{document} +%</driver> +% +% \fi +% +% \changes{v1.3b}{1996/06/06}{Clarified copyright and licence conditions, also restructured to make preparing documentation easier.} +% +% \title{The \texttt{\filename} package} +% \author{Norman Gray\\|norman@astro.gla.ac.uk|} +% \date{Version \fileversion, \docdate} +% +% \maketitle +% +% This package helps you keep track of all the labels you define, by +% putting the name of new labels into the margin whenever the +% |\label| command is used. +% +% The package allows you to do the same thing for other commands (see below). +% The only one for which this is \emph{obviously} useful is the +% |\cite| command, but it is also reasonable to do it with, for example, +% the |\ref| or |\begin| commands. +% +% You invoke this package with the command |\usepackage{showlabels}| in +% the preamble, and you may give the following options: +% \begin{quotation} +% \begin{tabular}{lp{25em}} +% \Lopt{outer} & [default] all notes are placed in the text's outer +% margin\\ +% \Lopt{inner} & \dots inner margin\\ +% \Lopt{left} & \dots left margin\\ +% \Lopt{right} & \dots right margin\\ +% \Lopt{marginal} & [default] put notes in the margin\\ +% \Lopt{inline} & put notes inline, as much as possible, and ignore +% any of the margin-placement options above \\ +% \Lopt{nolabel} & do not insert a marginal note for |\label| commands +% (see command |\showlabel| below)\\ +% \Lopt{draft} & [default] does nothing, partner of\dots\\ +% \Lopt{final} & turns off all the package's functionality +% \end{tabular} +% \end{quotation} +% If you don't use the \Lopt{twoside} option, +% then all pages are `right-hand' pages, and the `outer margin' is the +% right hand one. +% +% The package will also work in the presence of the \Lopt{twocolumn} +% option. In this case, the options \Lopt{inner}, \Lopt{outer}, +% \Lopt{left} and \Lopt{right} will be ignored, and the label will be +% placed in the nearer margin. +% +% If you want to change the font the labels appear in, redefine the +% |\showlabelfont| command, which by default expands to +% |\small\ttfamily|. For example, to have labels in a slanted font, you +% could include the definition +% \begin{quote} +% |\renewcommand{\showlabelfont}{\small\slfamily}| +% \end{quote} +% in the preamble of your document. +% If you want still more control over the labels, you can +% instead override |\showlabelsetlabel|, which initially expands to +% just |\showlabelfont #1|. You can use this mechanism to get a +% variety of effects. For example, if you say +% \begin{quote} +% |\usepackage{showlabels,rotating}|\\ +% |\renewcommand{\showlabelsetlabel}[1]|\\ +% \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. +% +% If you wish the package to do its magic with the command |\foo| +% (most typically |\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}|. +% +% By default, the package reprints labels in the margin of the +% document, but as an alternative, labels can be kept inline as much +% as possible. To select this, give the option \Lopt{inline}, +% and to select the default behaviour, use \Lopt{marginal}. +% +% Finally, we have the options \Lopt{final} and \Lopt{draft}. The option +% \Lopt{final} turns off all the functionality of this package. This +% is included so that if that +% option is given globally in the |\documentclass| declaration then this +% package does respect it. \Lopt{draft} does nothing, and therefore +% simply continues the default behaviour of this package; it is here +% to partner the \Lopt{final} option. +% +% \subsection*{Compatibility with other packages, and other problems} +% +% The \pstyle{showlabels} package works by redefining the |\label| +% command, along with the internal \LaTeX\ commands |\@eqnnum|, +% |\@makecaption| and +% |\maketag@@@| (for \pstyle{amsmath}). All the other commands it +% defines are `hidden' by prefixing them with `\texttt{SL@}', with +% the exception of the user commands |\showlabelfont| and +% |\showlabelsetlabel|. Each of +% the three redefined commands carefully includes its previous +% definition. The \pstyle{showlabels} package should therefore come +% \emph{last} of the packages you include using |\usepackage|. +% +% In version 1.1, the package was modified to conform to the slightly +% different mechanism that \texttt{amsmath} uses to produce equation +% numbers. I don't habitually use \texttt{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 +% \pstyle{amsmath} package. Note also that, since these additions +% appeared, AMS-\LaTeX\ and the \texttt{amstex} package seem to have +% been declared `obsolete' in favour of the \texttt{amsmath} package. +% This package now claims conformance with the \texttt{amsmath} +% package alone, though it will probably work with older versions in fact. +% +% In version 1.3e, the program became compatible with the +% \pstyle{hyperref} package in particular, and in general with other +% packages which themselves modify the |\label| command. This will +% work, however, only if the \pstyle{showlabels} package is loaded +% after other packages which do this. Notwithstanding Sebastian +% Rahtz's excellent general advice on this, \pstyle{showlabels} should +% be loaded after \pstyle{hyperref}. +% +% For reasonably obvious reasons, this package will not work at all +% well with the \pstyle{multicol} package, and for possibly less obvious +% reasons, it won't work with the \Lopt{leqno} option either (at some point +% it should be modified to at least recognise and warn of the conflict in +% either case, though it's not obvious to me how to do that). The +% package \emph{should} now work with \pstyle{wrapfig}, though I'm not +% sure that I've exhausted that package's various clevernesses, and +% there might be some spacing and layout bugs which manifest +% themselves in that context. Please report them; in the mean time, +% using option \Lopt{inline} should act as a workaround for any that +% appear. +% +% When labels appear in the margins, they sometimes appear on the +% `wrong' side in \Lopt{twoside} mode. This is a fairly inevitable +% side-effect of the way that \TeX\ builds pages, and a specific +% symptom of the general problem described in +% \url{http://www.tex.ac.uk/cgi-bin/texfaq2html?label=oddpage}. +% As that answer suggests, there are bear-traps involved in the +% standard solutions. Now, showlabels is (a)~permanently teetering +% on the edge of clashing with everything else that messes around with +% labels, and (b)~a draft-only package rather than anything that +% would appear in a final document. (a)~means that I'm rather nervous +% about putting too much cleverness in there, and incidentally shy of +% putting any dependencies on other packages; (b)~means that I feel it +% doesn't really matter enough to be worth removing robustness. So +% I'm afraid I don't plan to change this, and I simply put up with the +% occasional slip. Again the \Lopt{inline} option is a possible +% workaround. +% +% The package might still work with \LaTeX2.09, but that's neither +% supported, nor even still tested. +% +% This software is copyright, 1999, 2001--2003, Norman Gray. It is released under +% the terms of the GNU General Public Licence. See the copyright +% declaration at the top of file \texttt{showlabels.dtx}, and the file +% \texttt{LICENCE} for the licence conditions. You can find an +% online copy of the GPL at \url{http://www.gnu.org/copyleft/gpl.html}. +% +% \subsection*{Other packages} +% +% I know of, but have not yet played with, the package \pstyle{showkeys}, +% by David Carlisle. As far as I know, both packages do roughly the +% same thing. +% +% \subsection*{History and Credits} +% +% Please do let me know if I've omitted anyone from these lists of +% Helpful People. +% +% I received comments and bug reports on version 1.4 from: +% \begin{quotation} +% \begin{tabular}{rl} +% Andreas Balser & \url{balser@mathematik.tu-darmstadt.de}\\ +% Roland Winkler & \url{roland.winkler@physik.uni-erlangen.de}\\ +% Ignacy Sawicki & \url{sawickii@poczta.onet.pl} +% \end{tabular} +% \end{quotation} +% +% I received comments and bug reports on version 1.3 from: +% \begin{quotation} +% \begin{tabular}{rl} +% Andrei Shelankov & \url{Andrei.Shelankov@tp.umu.se}\\ +% Elmar Walhorn & \url{e.walhorn@tu-bs.de}\\ +% \end{tabular} +% \end{quotation} +% +% Prior to version 1.3, I received comments and bug reports from: +% \begin{quotation} +% \begin{tabular}{rl} +% David R. Leal Valmana & \url{david@quijote.uc3m.es}\\ +% Sungmo Park & \url{smp@dingo.etri.re.kr}\\ +% Olivier Michel & \url{Olivier.Michel@lri.fr}\\ +% Jiri Vesely & \url{jvesely@karlin.mff.cuni.cz}\\ +% Patrick Sibille & \url{sibille@amoco.saclay.cea.fr}\\ +% Hagen Kleinert & \url{kleinert@physik.fu-berlin.de}\\ +% Francis M. C. Ching & \url{fmcching@kingcong.uwaterloo.ca}\\ +% Michael Friendly & \url{friendly@hotspur.psych.yorku.ca}\\ +% lester l. helms & \url{l-helms@math.uiuc.edu}\\ +% \end{tabular} +% \end{quotation} +% Many thanks to all. +% +% Back in 29-Jan-92, Darrel Hankerson +% \url{hank@ducvax.auburn.edu}, made the update to NFSS, and +% changed the name to `showlabel.sty'. +% +% The package was originally released by me on 21-Sep-91, under the name +% \texttt{labels.sty}. +% +% +% \StopEventually{} +% +% \section{Implementation} +% \begin{macrocode} +%<*package> +% \end{macrocode}% +% \iffalse +% Update history: +% October 94: Norman Gray (norman@astro.gla.ac.uk). Modified to be a +% \LaTeX2e package. After that, see |\changes|. +% 29-Jan-92 Darrel Hankerson (hank@ducvax.auburn.edu) +% Update to NFSS. Change name to `showlabel.sty'. Substitute +% \nintt -> \small\tt +% \sevit -> \scriptsize\it +% 21-Sep-91 Norman Gray no_gray@vax.acs.open.ac.uk +% Original release of labels.sty +% \fi +% +% Before we do anything else, find out if we're using \pstyle{amsmath}\dots. +% Note that, since these additions appeared, AMS-\LaTeX\ and the +% \texttt{amstex} package seem to have been declared `obsolete'. This +% package now claims conformance with the \texttt{amsmath} package. +% \changes{v1.2}{1996/05/12}{Finally added the AMS-LaTeX variant ifSL@noAMS} +% \changes{v1.3}{1999/02/22}{More rational if it's ifSL@AMS} +% \begin{macrocode} +\newif\ifSL@AMS +\expandafter\ifx\csname maketag@@@\endcsname\relax + \SL@AMSfalse +\else + \SL@AMStrue + \typeout{with amsmath equation tags} +\fi +% \end{macrocode} +% +% \begin{macro}{\@eqnnum} +% This replacement for |\@eqnnum| will produce a note, sticking +% into the margin beside the equation number, showing the equation's label. +% |\SL@labelname| is initialised to |\relax|, redefined within the +% |\label| macro, and reset to |\relax| here. If it's already equal +% to |\relax| here, the equation number hasn't been labelled, and so +% `???' is put in the margin. Don't do this for the \pstyle{amsmath} case +% as it artfully incorporates the |\maketag@@@| mechanism into a +% redefined |\@eqnnum|. +% +% \begin{macrocode} +\ifSL@AMS +% \end{macrocode} +% +% \pstyle{amsmath} uses |\maketag@@@|, to form tags in equations. +% All we have to do is +% hook into the |\maketag@@@| macro, and use |\df@label|, which is +% pre-defined with the current label name. +% \begin{macrocode} + \let\SL@maketag@@@=\maketag@@@ + \def\maketag@@@#1{\SL@maketag@@@{#1}% + \ifx\df@label\@empty +% \SL@eqnlrtext{???}% + \else + \SL@eqnlrtext{\df@label}% + \fi} +\else +% \end{macrocode} +% The `normal' case, without \pstyle{amsmath}. +% \changes{v1.3c}{1999/07/22}{Added expandafter before test -- +% how on earth had this escaped before?!?} +% \changes{v1.3d}{1999/07/23}{Removed ??? when no label exists} +% \begin{macrocode} + \let\SL@eqnnum=\@eqnnum + \def\@eqnnum{\SL@eqnnum + \expandafter\ifx\SL@labelname\relax +% \SL@eqnlrtext{???}% + \else + \SL@eqnlrtext{\SL@labelname}% + \global\def\SL@labelname{\relax}% + \fi} +% \end{macrocode} +% \end{macro} +% And initialise the value of |\labeln@me| to |\relax|, so that +% |\@eqnnum| starts off behaving the right way. +% \begin{macrocode} + \global\def\SL@labelname{\relax} +\fi +% \end{macrocode} +% +% Labels are printed with the font specified by |\showlabelfont|, which +% can be overridden within the document: +% \changes{v1.3}{1999/02/22}{Added showlabelfont} +% Define this using |\ttfamily|, unless we're still using \LaTeX 2.09 +% (surprising it still works!), in which case stick with |\tt|. +% \changes{v1.5a}{2005/03/18}{Use ttfamily instead of tt} +% \begin{macrocode} +\@ifundefined{ttfamily} + {\providecommand{\showlabelfont}{\small\tt}} + {\providecommand{\showlabelfont}{\small\ttfamily}} +% \end{macrocode} +% +% If you want slightly more general control over the labels, you can +% instead override |\showlabelsetlabel|, which is just +% |\newcommand{\showlabelfont}[1]{\normalfont\showlabelfont #1}| by default. +% \begin{macrocode} +\providecommand{\showlabelsetlabel}[1]{\normalfont\showlabelfont #1} +% \end{macrocode} +% +% For the benefit of |\SL@prlabelname|, define |\SL@gobblethree| to do nothing +% other than eat three tokens. +% \begin{macrocode} +\def\SL@gobblethree#1#2#3{} +% \end{macrocode} +% +% \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. +% \begin{macrocode} +\def\SL@prlabelname#1{% +\expandafter\expandafter\expandafter\SL@gobblethree + \expandafter\string\csname r@#1\endcsname} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\showlabels} +% \changes{1.4}{2001/07/23}{Define showlabels command} +% Define the |\showlabels| command which allows us to redefine +% commands which are to have their arguments highlighted. +% That is, |\showlabels{foo}| means that the command |\foo{bar}| will +% write `bar' in the margin, as well as executing whatever |\foo| does +% normally. +% +% The net result of all this is that a |\showlabels{foo}| command +% arranges things so that, after |\begin{document}|, |\foo{bar}| expands into +% |\SL@setlabel{bar}\SL@origfoo{bar}|. +% +% First, define a command |\SL@initfoo|, which, when executed, will +% save the current (at that time) behaviour of the command |\foo|, and +% redefine |\foo| to have the required behaviour; we will +% shortly give this command to |\AtBeginDocument|, so that it is +% switched on at the correct time, when other packages have done +% \emph{their} redefinitions of |\foo| (this makes it compatible with +% the \pstyle{hyperref} package, which does its own wholesale redefinitions of +% things like |\label|). Below, the locution +% |\the\@temptokena| causes the token contents of |\@temptokena| to be +% included unexpanded in the definition, despite the |\edef|. +% \begin{macrocode} +\def\showlabels#1{% + \@temptokena=\expandafter{\csname #1\endcsname} + \expandafter\edef\csname SL@init#1\endcsname{% + \let\csname SL@orig#1\endcsname\the\@temptokena + \let\the\@temptokena\csname SL@#1\endcsname} + \AtBeginDocument{\csname SL@init#1\endcsname}% +% \end{macrocode} +% \emph{Now} define |\SL@foo| -- it must be undefined when we define +% |\SL@initfoo| above, so that it isn't expanded in the |\edef|. +% \begin{macrocode} + \expandafter\def\csname SL@#1\endcsname{\SL@showlabels{#1}} +} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\SL@showlabels} +% Now we get to the command which does the main processing. The +% |\SL@showlabels| command calls |\SL@setlabel| to format the label +% (putting it in the margin, for example), then calls the original +% |\foo| command (namely |\SL@origfoo|) with the original argument. +% +% The first argument is the name of the command which this command is +% replacing, for example `label'. The second is the argument +% originally given to the command. +% +% We have to be somewhat careful about the positioning of the +% |\@bsphack| and |\@esphack| commands. The |\@esphack| command should +% \emph{not} come after the call to |\SL@origfoo|, since that would +% confuse things terribly if that command took any other arguments, or +% otherwise messed with the token stream (there's actually no problem +% in the most common case where we're replacing |\label|, and calling +% |\SL@origlabel|, but there are problems when we try to replace +% |\begin| or |\ref| in this way). Instead, adapt the contents +% of |\@esphack|, but instead of calling |\ignorespaces| when +% |\@savsk| is positive, add an |\hskip| of 1~scaled point (equal to +% $1/65536\mathrm{pt}=5.363\times10^{-9}\mathrm{m}$). This will be +% invisible, but it \emph{is} greater than zero, so that if +% |\SL@origfoo| itself uses a |\@bsphack|\dots|\@esphack| pair then +% the saved |\@savsk| will be positive, and that future |\@esphack| +% will correctly invoke |\ignorespaces|; that pair will also pick up +% the |\spacefactor| we restore here. The net result is that the +% |\SL@setlabel| is invisible, and |\SL@origfoo| is able to make +% itself invisible, too. Command sequence |\SL@setlabel| is what does +% the work -- this is |\let| equal to either |\SL@margtext| or +% |\SL@inlinetext| below. +% \begin{macrocode} +\def\SL@showlabels#1#2{% + \@bsphack + \SL@setlabel{#2}\relax + \ifhmode \spacefactor\@savsf \ifdim\@savsk>\z@ \hskip1sp \fi\fi + \csname SL@orig#1\endcsname{#2}% +} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\@makecaption} +% The |\@makecaption| command needs special treatment. The +% |\SL@margtext| command doesn't work in figure captions, so we need +% to force the layout commands to use |\SL@inlinetext| instead, for +% all label types, and irrespective of whether we're using the +% \Lopt{inline} option. The code here is independent of that in +% |\showlabels|, but imitates it, for consistency. +% \changes{v1.4a}{2003/01/28}{Use SL@inlinetext to display caption label} +% \begin{macrocode} +\def\SL@initmakecaption{% + \let\SL@origmakecaption\@makecaption + \def\@makecaption##1##2{{% + \let\SL@setlabel\SL@inlinetext\SL@origmakecaption{##1}{##2}}}} +\AtBeginDocument{\SL@initmakecaption} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\SL@margtext} +% This is the central bit of this package, used by |\SL@showlabels|. +% The argument is the argument of the |\foo| command which we're +% processing (for example, the argument to a |\label| command). +% +% Depending on the mode, put the +% current label name in the margin in one of a variety of ways. +% \changes{1.4}{2001/07/23}{Define SL@margtext command} +% \begin{macrocode} +\def\SL@margtext#1{% +% \end{macrocode} +% In maths mode, produce a label name alongside the equation number. +% If we're not using \pstyle{amsmath}, then save the label name in +% |\SL@labelname|. If we \emph{are} using \pstyle{amsmath}, then we don't +% have to worry, because it's saved in |\df@label| for us. +% \begin{macrocode} + \ifmmode + \ifSL@AMS\else + \xdef\SL@labelname{\SL@prlabelname{#1}}% + \fi +% \end{macrocode} +% Otherwise, create a box with zero height and depth, and the same width +% as the page. Put all this in braces, to contain the setting of +% |\box\@tempboxa| (which probably shouldn't be necessary). The box +% here we set to be the width of |\hsize|. This is \emph{probably} +% best, though there's always the worry that |\linewidth| would be the +% more \LaTeX-ish thing to do -- using |\columnwidth| is almost +% certainly wrong, since |\linewidth| can sometimes be changed without +% |\columnwidth| changing with it (for example, in package +% \pstyle{wrapfig}), causing \pstyle{showlabels} to fail badly. +% \changes{v1.4}{2002/04/21}{Changed columnwidth to hsize} +% \begin{macrocode} + \else + \setbox\@tempboxa=\vbox to 0pt{\vss + \hbox to \hsize{\SL@lrtext{#1}}}% + \dp\@tempboxa\z@ +% \end{macrocode} +% and attach it below the last one, using |\nointerlineskip| if we're in +% vertical mode, or |\vadjust| otherwise. We need to save and restore +% the value of |\prevdepth| (which has the sentinel value -1000pt if we're +% adding this box at the beginning of a vertical list, and +% |\nointerlineskip| sets |\prevdepth| to this same value). If we don't +% do this, we get extra (`interline') vertical space added in this +% case (it might be thought smart to use |\marginpar| here, and so +% avoid some of this nonsense, but that's not possible since this +% might be called within boxes, which |\marginpar| objects to). +% \begin{macrocode} + \ifvmode + \@tempdima=\prevdepth + \nointerlineskip\box\@tempboxa\nobreak + \prevdepth=\@tempdima + \else + \vadjust{\box\@tempboxa\nobreak}% + \fi +% \end{macrocode} +% That's it. Finish off the |\ifmmode|. +% \begin{macrocode} + \fi +} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\SL@inlinetext} +% This is an alternative way of formatting the label, which puts it +% inline as much as possible, and avoids straying into the margins. +% \changes{1.5}{2002/04/15}{Introduce SL@inlinetext (1.5??)} +% \begin{macrocode} +\def\SL@inlinetext#1{% +% \end{macrocode} +% Maths mode as with |\SL@margtext| +% \begin{macrocode} +\ifmmode + \ifSL@AMS\else + \xdef\SL@labelname{\SL@prlabelname{#1}}% + \fi +\else + \SL@interlinetextright{#1}% +\fi +} +% \end{macrocode} +% In vmode, put the label between lines. Set the box depth to zero to +% make sure that descenders don't mess up the spacing. +% \changes{1.4a}{2002/10/15}{Add SL@interlinetext and friends} +% \begin{macrocode} +\def\SL@interlinetextleft{\SL@setlefttrue\SL@interlinetext} +\def\SL@interlinetextright{\SL@setleftfalse\SL@interlinetext} +\def\SL@interlinetext#1{% + \setbox\@tempboxa=\hbox{\showlabelsetlabel{#1}}\dp\@tempboxa\z@ + \ifvmode + \nointerlineskip\vbox to 0pt{\vss + \hbox to \columnwidth{\hss \box\@tempboxa}}% +% \end{macrocode} +% And in hmode, squeeze it between the lines, at the current point, +% carefully taking up no space. +% \begin{macrocode} + \else + \ifSL@setleft + \hbox to 0pt{% + \hss + \vbox to 0pt{\vss + \hbox to 0pt{\hss\box\@tempboxa}% + \hrule width 0.05em height 1.5ex depth 0pt + }}% + \else + \hbox to 0pt{% + \vbox to 0pt{\vss + \box\@tempboxa + \hrule width 0.05em height 1.5ex depth 0pt + }\hss}% + \fi + \penalty10000 + \fi +} +% \end{macrocode} +% \end{macro} +% +% +% \begin{macro}{\SL@margintext} +% Set the actual text of the label. Use |\SL@prlabelname| here: without +% this, a label command given outside of an equation or a |\caption| +% will appear wrongly if the label has things like underscores within it. +% \changes{v1.3}{1999/02/22}{Use prlabelname within SL@margintext} +% \begin{macrocode} +\def\SL@margintext#1{{\showlabelsetlabel{\{\SL@prlabelname{#1}\}}}} +% \end{macrocode} +% \end{macro} +% +% But where is the marginal text actually set? It can be in the left +% margin, the right one, or can alternate. |\SL@lrtext|, used in the +% |\vbox| above, is set, under the control of |\SL@labelposition| below, to +% one of |\SL@lefttext|, |\SL@righttext| or |\SL@alternatetext|. +% \begin{macro}{\SL@righttext} +% \begin{macro}{\SL@lefttext} +% \begin{macrocode} +\def\SL@righttext#1{\hfill\rlap{\quad\SL@margintext{#1}}} +\def\SL@lefttext #1{\llap{\SL@margintext{#1}\quad}\hfill} +% \end{macrocode} +% \end{macro} +% \end{macro} +% +% \begin{macro}{\SL@setLR} +% Define a switch which allows us to state whether we've decided to +% set a particular label to the left or the right, and a macro +% |\SL@setLR| to set it. After |\SL@setLR|, |\ifSL@setleft| is true +% if a label should be set to the left, and is false if it should go +% to the right. +% \begin{macrocode} +\newif\ifSL@setleft +\def\SL@setLR{% + \ifcase\SL@labelposition + % 0=outer margin + \ifodd\c@page + \SL@setleftfalse + \else + \SL@setlefttrue + \fi + \or + % 1=inner margin + \ifodd\c@page + \SL@setlefttrue + \else + \SL@setleftfalse + \fi + \or + % 2=left margin + \SL@setlefttrue + \or + % 3=right margin + \SL@setleftfalse + \else + \SL@canthappen{Impossible labelposition \the\SL@labelposition} + \SL@labelposition=3 % put everything in the right-margin for now + \SL@setleftfalse + \fi +} +% \end{macrocode} +% \end{macro} +% +% The code for |\SL@alternatetext| doesn't work perfectly, as it +% sometimes manages to get things on the wrong side of the text near the +% top of a new page. This is a venial slip, however, as this package +% should never be used in a final version. +% \begin{macro}{\SL@alternatetext} +% \begin{macrocode} +\def\SL@alternatetext{% + \SL@setLR + \ifSL@setleft + \let\SL@next\SL@lefttext + \else + \let\SL@next\SL@righttext + \fi + \SL@next +} +% \end{macrocode} +% \end{macro} +% The case where the \Lopt{twocolumn} option is set is slightly different. +% There we have to switch between placing the note in the left and right +% margins, depending on whether we're setting the first or second column. +% This macro, and |\SL@eqntwocoltext| below, uses the switch +% |\if@firstcolumn| to decide whether it's in the first or the second +% column of the text (I suppose it'll get terribly confused if we use +% \file{multicol.sty} along with this). This is defined and maintained in +% the base file \file{ltoutput.dtx}. It's not part of the defined +% interface, however (there doesn't seem to be one, grump), so I don't +% suppose we should really rely on it. There isn't an option, however. +% \begin{macro}{\SL@twocoltext} +% \changes{v1.1}{1995/02/06}{Added the twocoltext alternatives} +% \begin{macrocode} +\def\SL@twocoltext{% + \if@firstcolumn + \let\SL@next\SL@lefttext + \else + \let\SL@next\SL@righttext + \fi + \SL@next} +% \end{macrocode} +% \end{macro} +% +% We have very similar things for equations, except that they are set in +% place, rather than within a zero depth box. This code ASSUMES that +% equation numbers are going to be on the right hand side of the page. It +% should probably check for the existence of the \Lopt{leqno} option (how?). +% \begin{macro}{\SL@eqnrighttext} +% \begin{macro}{\SL@eqnlefttext} +% \begin{macrocode} +\def\SL@eqnrighttext#1{\rlap{\quad\SL@margintext{#1}}} +\def\SL@eqnlefttext #1{\hbox to 0pt{\kern -\columnwidth + \llap{\SL@margintext{#1}\quad}\hss}} +% \end{macrocode} +% \end{macro} +% \end{macro} +% Now do the analogues for the equation numbers, in the case of the +% alternate page selection\dots +% \begin{macro}{\SL@eqnalternatetext} +% \begin{macrocode} +\def\SL@eqnalternatetext{% + \SL@setLR + \ifSL@setleft + \let\SL@next\SL@eqnlefttext + \else + \let\SL@next\SL@eqnrighttext + \fi + \SL@next +} +% \end{macrocode} +% \end{macro} +% \dots and the twocolumn option +% \begin{macro}{\SL@eqntwocoltext} +% \begin{macrocode} +\def\SL@eqntwocoltext{% + \if@firstcolumn + \let\SL@next\SL@eqnlefttext + \else + \let\SL@next\SL@eqnrighttext + \fi + \SL@next} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\SL@canthappen} +% Issues a |\PackageError| command, and solicits bug reports. +% \begin{macrocode} +\def\SL@canthappen#1{% + \PackageError{showlabels}{#1} + {This shouldn't happen -- the package showlabels has a bug. + \MessageBreak + Please report this, if possible with a sample document which + \MessageBreak + demonstrates the problem, to \filemaintainer. Thanks.}} +% \end{macrocode} +% \end{macro} +% +% To control the positioning of labels, set the |\SL@labelposition| +% switch, which can take values 0, 1, 2, 3, meaning outer, inner, +% left, right margin respectively. +% \changes{v1.4a}{2003/01/28}{Added left/right options} +% \begin{macrocode} +\newcount\SL@labelposition +\SL@labelposition=0 +% \end{macrocode} +% +% We select between the various possibilities using the \Lopt{outer} and +% \Lopt{inner} options and, implicitly, the \Lopt{twoside} option. +% \begin{macrocode} +\DeclareOption{outer}{\SL@labelposition=0} +\DeclareOption{inner}{\SL@labelposition=1} +\DeclareOption{left}{\SL@labelposition=2} +\DeclareOption{right}{\SL@labelposition=3} +% \end{macrocode} +% +% \begin{macro}{\SL@setlabel} +% Labels can be set either in the margins or inline, by switching +% between definitions of |\SL@setlabel|. +% \begin{macrocode} +\DeclareOption{marginal}{\let\SL@setlabel\SL@margtext} +\DeclareOption{inline}{\let\SL@setlabel\SL@inlinetext} +\let\SL@setlabel\SL@margtext +% \end{macrocode} +% \end{macro} +% +% By default, we run |\showlabels{label}|. The option \Lopt{nolabel} +% turns this off. +% \begin{macrocode} +\newif\if@showlabellabel +\@showlabellabeltrue +\DeclareOption{nolabel}{\@showlabellabelfalse} +% \end{macrocode} +% +% Define the options \Lopt{final} and \Lopt{draft}. The option +% \Lopt{final} turns off all the functionality of this package by +% disabling the command |\showlabels|, including the implicit +% |\showlabels| command which the package issues as long as the +% \Lopt{nolabel} option has not been given. This is included so that if that +% option is given in the |\documentclass| declaration then this +% package does respect it. \Lopt{draft} does nothing, and therefore +% simply continues the default behaviour of this package; it is here +% purely to partner the \Lopt{final} option. +% \begin{macrocode} +\DeclareOption{final}{\let\showlabels\@gobble} +\DeclareOption{draft}{} +% \end{macrocode} +% +% Process any options that have been set. +% \begin{macrocode} +\ProcessOptions +% \end{macrocode} +% and use the values of |\SL@labelposition| and |if@twoside| which may have +% been set by those options, to set |\SL@lrtext| to be the +% appropriate control sequence. The presence of the \Lopt{twocolumn} option +% means that we ignore the \Lopt{inner} and \Lopt{outer} options. +% \begin{macrocode} +\if@twocolumn + \let\SL@lrtext\SL@twocoltext + \let\SL@eqnlrtext\SL@eqntwocoltext +\else + \ifcase\SL@labelposition + % 0=outer margin + \if@twoside + \let\SL@lrtext\SL@alternatetext + \let\SL@eqnlrtext\SL@eqnalternatetext + \else + \let\SL@lrtext\SL@righttext + \let\SL@eqnlrtext\SL@eqnrighttext + \fi + \or + % 1=inner margin + \if@twoside + \let\SL@lrtext\SL@alternatetext + \let\SL@eqnlrtext\SL@eqnalternatetext + \else + \let\SL@lrtext\SL@lefttext + \let\SL@eqnlrtext\SL@eqnlefttext + \fi + \or + % 2=left margin + \let\SL@lrtext\SL@lefttext + \let\SL@eqnlrtext\SL@eqnlefttext + \or + % 3=right margin + \let\SL@lrtext\SL@righttext + \let\SL@eqnlrtext\SL@eqnrighttext + \else + \SL@canthappen{Impossible labelposition \the\SL@labelposition} + \SL@labelposition=3 % put everything in the right-margin for now + \let\SL@lrtext\SL@righttext + \let\SL@eqnlrtext\SL@eqnrighttext + \fi +\fi +% \end{macrocode} +% +% If we have selected the \Lopt{inline} option, however (which we can +% detect because |\SL@setlabel| will have been set to +% |\SL@inlinetext|, then put equation numbers inline, too. +% \changes{1.4a}{2002/10/15}{Equation numbers inline, too} +% \begin{macrocode} +\ifx\SL@setlabel\SL@inlinetext + \let\SL@eqnlrtext\SL@interlinetextleft +\fi +% \end{macrocode} +% +% Finally, label all the |\label| commands (default, and previous, +% behaviour), unless this has been suppressed through the +% \Lopt{nolabel} option. +% \begin{macrocode} +\if@showlabellabel + \showlabels{label} +\fi +% \end{macrocode} +% +% That's us. +% +% \begin{macrocode} +%</package> +% \end{macrocode} +% +% \Finale +\endinput diff --git a/Master/texmf-dist/source/latex/showlabels/showlabels.ins b/Master/texmf-dist/source/latex/showlabels/showlabels.ins new file mode 100644 index 00000000000..fde5edb09ff --- /dev/null +++ b/Master/texmf-dist/source/latex/showlabels/showlabels.ins @@ -0,0 +1,14 @@ +\input docstrip +\preamble + Showlabels: Style to display labels in the margin +\endpreamble +\keepsilent +\askforoverwritefalse + +\generate{\file{showlabels.drv}{\from{showlabels.dtx}{driver}} + \file{showlabels.sty}{\from{showlabels.dtx}{package}} + } + +\endbatchfile + +%% $Id: showlabels.ins,v 1.2 2001/04/19 15:18:00 norman Exp $ |