Le package showkeys^{∗}

David Carlisle

Traduction française par Jean-Pierre Drucbert^{†}

1997/06/12

1 Introduction

sec+intro

Le package showkeys modifie les commandes \label, \ref, \pageref, \cite et \bibitem pour que la clé « interne » soit imprimée. Ce package fait de grands efforts pour placer ces labels de façon que la mise en page du reste de votre document reste inchangée. \label et \bibitem font que le label apparaîtra dans une boîte soit dans la marge, soit dans une boîte TEX de largeur nulle, qui peut éventuellement se surcharger à du texte. Les commandes \ref, \pageref et \cite impriment leurs arguments en petits caractères, juste au dessus de la ligne, comme

ceci : ^{\underline{sec+intro}} 1.

Ce package fonctionne aussi avec l’option de classe fleqn, les packages qui font partie d’AMSL^{A}TEX, et avec les packages varioref, natbib et harvard.

2 Options du package

options

Certaines personnes ont dit que l’impression des clés \ref et \cite était moins utile que celle des clés \label et donc maintenant le package showkeys accepte deux options pouvant être données dans la commande \usepackage : notref pour empêcher la redéfinition de \ref et \pageref, et des commandes

associées du package varioref. notcite pour empêcher la redéfinition de la commande \cite et des commandes

associées dans les packages harvard et natbib.

Donc si ce package est chargé par \usepackage[notref]{showkeys}, alors \ref

aura sa définition standard, mais \label imprimera la clé donnée en argument (habituellement dans la marge).

Si vous estimez que l’impression des clés vous distrait, mais ne voulez pas utiliser les options ci-dessus pour la supprimer, vous pouvez aussi utiliser : color Imprime les clés dans une couleur distincte. La couleur par défaut est un

gris pâle. Les couleurs peuvent être modifiées en redéfinissant les deux couleurs suivantes après chargement du package : refkey (également utilisée pour \cite) et labelkey (également utilisée pour \bibitem). Les valeurs par défaut sont :

∗Ce fichier a le numéro de version v3.12, révisé le 1997/06/12.

†Dernière mise à jour le 20/01/2000

  \definecolor{refkey}{gray}{.75}
  \definecolor{labelkey}{gray}{.75}

Si cette option est utilisée, le package color sera automatiquement chargé. showkeys accepte deux autres options.

final pour supprimer l’action de ce package, pour la version « finale » du docu-

ment. draft pour un comportement normal de ce package. Il est clair qu’il est sans intérêt de donner directement l’option final dans la commande \usepackage, car le fait de simplement ne pas charger le package aurait le même effet, et s’exécuterait plus rapidement ; cependant l’option final peut être utile si elle est utilisée une fois pour toutes dans la commande \documentclass afin d’affecter tous les packages qui seront chargés. L’option draft ne fait rien du tout, mais elle est là pour honorer une convention informelle qui veut que les packages aient ces options par paires.

3 Plus d’exemples

examples

Le seul autre package similaire que j’ai pu trouver dans l’index des commandes, \underline{DMJ+mi} [3], était showlabels.sty, ^{\underline{GN+sl}} [1]. Après avoir écrit la première épreuve de package, j’ai trouvé ^{\underline{anon+sk}} [2] dans mon installation locale ! Je pense que mon package est plus robuste que ^{\underline{anon+sk}} [2], mais comme j’ai trouvé que showkeys était plutôt un bon nom, je l’ai volé pour ce package.

e^1 1. Cet item a une commande \label immédiatement derrière \item.

2. Celui-ci a la commande \label à la fin.

e^2

     Une minipage :-

À l’intérieur d’environnements tels que cette minipage, nous ne pouvous pas utiliser de notes marginales (\marginpar^{1}), donc l’aspect est légèrement différent. Voici de nouveau cet environne-

                     ment enumerate :

e^10 1. Cet item a une commande \label immédia-

tement derrière \item.

2. Celui-ci a la commande \label à la fin.

                 e^20

Mathématiques en hors-texte (sans compteur equation).

                                0 = 0 disp

Du texte faisant référence à la page ^{\underline{disp}} 2, et à l’item ^{\underline{e^1}} 1.

Si showkeys pense que l’environnement courant va produire un « numéro d’équation », alors il ne montre pas le label là où se trouve la commande \label, mais essaie de le placer dans la marge, comme cela se voit pour l’équation ^{\underline{eq+xx}} 1. Le package « connaît » les environnements standard equation et eqnarray, et connaît aussi tous les environnements d’alignement numérotés offerts par le package AMSL^{A}TEX, amsmath.

1En réalité, \marginpar n’est actuellement plus utilisé dans ce package.

1 = 1  (1) eq+xx

                              2 = 2  (2) eqnar+a

3 = 3

                              4 = 4  (3) eqnar+b

À l’intérieur d’un environnement figure ou table, le \label ne doit pas être placé avant la commande \caption. Si vous placez \label à l’intérieur de l’argument de \caption, le label aura cet aspect :

Fig. 1 – À l’intérieur de l’argument de la légende. cap+a

Si vous placez \label immédiatement après la commande \caption, il sera montré comme ceci :

Fig. 2 – Immédiatement après l’argument de la légende.  cap+b

Si vous placez la commande \label n’importe où après la commande \caption, il pourra être montré comme ceci :

Fig. 3 – En mode vertical pas immédiatement derrière une boîte.

cap+c

Références

GN+sl [1] Gil Neiger, showlabels.sty, Un package, sans date, similaire à celui-ci, mais

montrant les labels en ligne, ce qui affecte la mise en page du document.

anon+sk [2] Anonyme, showkeys.sty, Paquetage, daté du 14 mai 1988. Très similaire à celui-

ci, utilise aussi \marginpar en mode vertical externe.

DMJ+mi [3] David M. Jones, TEX Macro Index, Un catalogue de macros TEX, comprenant des fichiers de packages L^{A}TEX, disponible sur toutes les bonnes archives TEX.

4 The Macros

1 ⟨∗package⟩

First we handle the options. Normally all related comands are defined to show their ‘keys’. But since v3.03 one can specify:

notref to stop the redefinition of \ref (and \pageref, and related commands from varioref package),

notcite to stop the redefinition of \cite and related commands from the harvard and natbib packages.

 2 \DeclareOption{notref}{\let\SK@ref\@empty}
 3 \DeclareOption{notcite}{\let\SK@cite\@empty}

\SK@refcolor \SK@labelcolor Colour commands. Normally no-op.

 4 \let\SK@refcolor\relax
 5 \let\SK@labelcolor\relax

color option loads the color package and defines the colours. Delayed to the end of the package as package loading not allowed in this option section.

 6 \DeclareOption{color}{\AtEndOfPackage{%
 7 \RequirePackage{color}%
 8 \definecolor{refkey}{gray}{.75}%
 9 \definecolor{labelkey}{gray}{.75}%
10 \def\SK@refcolor{\color{refkey}}%
11 \def\SK@labelcolor{\color{labelkey}}}}

Allow final to be specified in the document class options to supress the loading of this package.

12 \DeclareOption{final}{\endinput}
13 \DeclareOption{draft}{}
14 \ProcessOptions
\SK@label \SK@bibitem \SK@lbibitem The saved original definitions
15 \let\SK@label\label
16 \let\SK@bibitem\@bibitem
17 \let\SK@lbibitem\@lbibitem

\label The new definition, print the argument, and then do the old definition.

18 \def\label#1{%
19 \@bsphack
20 \SK@\SK@@label{#1}%
21 \begingroup
22  \SK@label{#1}%
23 \endgroup
24 \@esphack}

\@bibitem \@lbibitem For \bibitem, position the showkeys code as for a standard list with \item and

\label.
25 \def\@bibitem#1{%
26 \SK@bibitem{#1}\SK@\SK@@label{#1}\ignorespaces}
27 \def\@lbibitem[#1]#2{%
28 \SK@lbibitem[#1]{#2}\SK@\SK@@label{#2}\ignorespaces}

\SK@ Grab hold of #2 via \meaning so characters like & and ^do not cause problems later, and pass the result on to the command #1.

29 \def\SK@#1#2{%
30 \protected@edef\@tempa{#2}%
31 \expandafter#1\meaning\@tempa\SK@}

\SK@@label Strip off the initial segment of the \meaning output, and then put the rest either in a \marginpar or in a box of size 0pt, hopefully not disturbing the surrounding text.

32 \def\SK@@label#1>#2\SK@{%

Need to work globally as in some cases like alignments, and fleqn, the counter will be printed in a different group to the \label command.

33 \gdef\SK@lab{\smash{\SK@labelcolor\fbox{%
34  \normalfont\small\ttfamily#2}}}%
35 \ifvmode
36  \if@inlabel

If the \label is straight after \item (\bibitem is handled by this case as well) then the item label has not been added to the page yet. It is hanging around in the box \@labels waiting for the paragraph to start. So just need to attatch the label to this box.

37  \global\setbox\@labels\hbox{%
38  \llap{\SK@lab\SK@lab@relax
39  \kern\@totalleftmargin\kern\marginparsep}%
40  \box\@labels}%
41  \else

If we insert a box into the main vertical list, do not want to change \prevdepth as that would afect vertical spacing in the document. (The box itself should not cause any difference in break points as there is a node there anyway coming from the \write to the aux file.

42  \dimen@\prevdepth
43  \nointerlineskip

The inner vertical mode cases are mainly designed to do the right thing with float captions, but seem to work OK in other cases as well.

44  \ifinner
45  \skip@\lastskip\unskip

In inner vertical mode, attach the label to the right of the immediately preceding box, if it is a box before the current point. Otherwise just put it in a box of zero dimensions, with no interline skip. (This may slightly move the surrounding text (but perhaps not now that \prevdepth is restored.)

46  \advance\skip@\lastskip\unskip
47  \setbox\z@\lastbox
48  \ifvoid\z@
49  \llap{\SK@lab\SK@lab@relax\kern\marginparsep}%
50  \else
51  \hbox{\box\z@\kern\marginparsep\SK@labx}%
52  \fi
53  \vskip\skip@
54  \else

In outer vertical mode, previously used a \vadjust at the start of the next paragraph (and before that used \marginpar). These methods sometimes cause extra space, eg if paragraph starts with a math display, so now just insert the box directly, taking care not to change \prevdepth.

55  \llap{\SK@lab\SK@lab@relax\kern\marginparsep}%
56  \fi
Restore \prevdepth.
57  \prevdepth\dimen@
58  \fi
59 \else

If we are in an numbered equation-style environment, do nothing as the code to print the number will also print the label, otherwise just stick the label at the current point, in a box of zero dimensions.

60  \csname SK@\@currenvir\endcsname
61  \ifSK@equation\else

62  \ifmmode
63  \SK@labx
64  \else

Inner horizontal mode. Not much we can do, just stick it here.

65  \ifinner
66  \rlap\SK@lab
67  \else

In outer horizontal mode use \vadjust to get to the margin.

68  \vadjust{\llap{\SK@lab\kern\marginparsep}}%
69  \fi
70  \SK@lab@relax
71  \fi
72  \fi
73 \fi}

\iftagsleft@ Make sure that this AMSL^{A}TEX command really is an \if..

74 \AtBeginDocument{%
75 \let\SK@eqnnum\@eqnnum
76 \def\@tempa{\let\iftagsleft@\iffalse}%
77 \ifx\iftagsleft@\undefined\@tempa\fi%

\tag@form@ \eqnnum Perhaps if leqno is operative, I should define \@eqnnum with the ‘left’ version, but it does not really matter.

78 \let\SK@tagform@\tagform@
79 \iftagsleft@
80  \def\tagform@#1{%
81  \ifx\df@label\@empty
82  \SK@lab@relax
83  \else
84  \expandafter\SK@@label\meaning\df@label\SK@
85  \fi
86  \llap{\SK@lab\kern\marginparsep}%
87  \SK@lab@relax\SK@tagform@{#1}}%
88  \def\@eqnnum{%
89  \llap{\SK@lab\kern\displaywidth\kern\marginparsep}%
90  \SK@lab@relax\SK@eqnnum}%
91 \else
92  \def\tagform@#1{%
93  \ifx\df@label\@empty
94  \SK@lab@relax
95  \else
96  \expandafter\SK@@label\meaning\df@label\SK@
97  \fi
98  \SK@tagform@{#1}%
99  \rlap{\kern\marginparsep\SK@lab}\SK@lab@relax}%
100  \def\@eqnnum{\SK@eqnnum\rlap{\kern\marginparsep\SK@lab}%
101  \SK@lab@relax}%
102 \fi}

\SK@labx Print the label, and then globally reset the print command to \relax.

103 \def\SK@labx{\rlap\SK@lab\global\let\SK@lab\relax}

\SK@lab@relax Clear the label.

104 \def\SK@lab@relax{\global\let\SK@lab\relax}\SK@lab@relax

\SK@equation \SK@eqnarray The following environments print an equation number, so \label should not print its argument at the point where it appears. Note this will fail to show the label if you are in an eqnarray environment, and use \label together with \nonumber This might just about make sense if you are going to use \pageref, but that is too bad…

105 \newif\ifSK@equation
106 \let\SK@equation\SK@equationtrue
107 \let\SK@eqnarray\SK@equationtrue

\eqnarray When the AMS packages are loaded showkeys assumes environments work ‘The AMS way’ However eqnarray (unlike equation) is not redefined, so here we need to remove some of the AMS hacks.

108 \toks@\expandafter{\eqnarray}
109 \edef\eqnarray{\let\noexpand\tagform@\noexpand\SK@tagform@\the\toks@}
\SK@align \SK@alignat \SK@xalignat \SK@xxalignat \SK@gather \SK@multline \SK@flalign The AMS environments
110 \let\SK@align\SK@equationtrue
111 \let\SK@alignat\SK@equationtrue
112 \let\SK@xalignat\SK@equationtrue
113 \let\SK@xxalignat\SK@equationtrue
114 \let\SK@gather\SK@equationtrue
115 \let\SK@multline\SK@equationtrue
116 \let\SK@flalign\SK@equationtrue

\SK@def This macro redefines a command #1. The new definition can make use of the old definition as \SK@old name. If #1 is really a \protect’ed command with the real definition in a ‘space’ command then the ‘space’ version is used as the old definition. Need to test this for each command as some package may have changed the status of a command to being ‘protected’. The new definition is made as if with \DeclareRobustCommand, but with \def syntax for the argument specification.

117 \def\SK@def#1{%
118 \edef\@tempa{\expandafter\@gobble\string#1}%
119 \@ifundefined{\@tempa\space}%
120  {\expandafter\let\csname SK@\@tempa\endcsname#1}%
121  {\expandafter\let\csname SK@\@tempa\expandafter\endcsname
122  \csname\@tempa\space\endcsname}%
123 \expandafter\def\expandafter#1\expandafter{%
124  \expandafter\protect\csname\@tempa\space\endcsname}%
125 \expandafter\def\csname\@tempa\space\endcsname}

The next section redefines \ref and \pageref (unless the notref option was given).

126 \ifx\SK@ref\@empty

Even if notref option is used, need to fudge the varioref commands as they use \label internally.

127 \AtBeginDocument{%
128 \ifx\vpageref\@undefined\else
129  \SK@def\@@vpageref#1[#2]#3{{%

130  \let\label\SK@label
131  \SK@@@vpageref#1[#2]{#3}}}%
132  \DeclareRobustCommand\vref[1]{%
133  \unskip~\ref{#1}%
134  {\let\label\SK@label
135  \SK@@@vpageref\unskip[\unskip\space]{#1}}}%
136 \fi}
137 \else

\ref \pageref Save the redefinition to \begin{document} so that this package can work with packages that redefine \cite. Tested with harvard and natbib packages. Also add code at this point to support varioref.

138 \AtBeginDocument{%
139 \SK@def\ref#1{\SK@\SK@@ref{#1}\SK@ref{#1}}%
140 \SK@def\pageref#1{\SK@\SK@@ref{#1}\SK@pageref{#1}}%
141 \ifx\vpageref\@undefined\else

varioref support.

142  \SK@def\@@vpageref#1[#2]#3{{%
143  \let\label\SK@label\let\ref\SK@ref\let\pageref\SK@pageref
144  \leavevmode\unskip\SK@\SK@@ref{#3}\SK@@@vpageref#1[#2]{#3}}}%
145  \DeclareRobustCommand\vref[1]{%
146  \unskip~\ref{#1}%
147  {\let\label\SK@label\let\ref\SK@ref\let\pageref\SK@pageref
148  \SK@@@vpageref\unskip[\unskip\space]{#1}}}%
149 \fi}
150 \fi

Now redefine \cite unless notcite option given.

151 \ifx\SK@cite\@empty
152 \AtBeginDocument{%
153 \ifx\HAR@checkdef\@undefined\else
154  \expandafter\let\expandafter
155  \SK@HAR@bi\csname\string\harvarditem\endcsname
156  \expandafter\def\csname\string\harvarditem\endcsname[#1]#2#3#4{%
157  \SK@HAR@bi[#1]{#2}{#3}{#4}\SK@\SK@@label{#4}}%
158 \fi}
159 \else
\cite
160 \AtBeginDocument{%
161 \ifx\HAR@checkdef\@undefined

Standard (non-harvard) support, including extra cite commands from natbib and cite.

If cite or overcite is being used, redefine \citen rather than \cite so as not to spoil the space and punctuation calculations done by those packages.

162  \ifx\citen\@undefined
163  \SK@def\cite#1#{\SK@citea{#1}}%
164  \else
165  \SK@def\citen#1{\SK@\SK@@ref{#1}\SK@citen{#1}}%
166  \fi
167  \SK@def\citeauthor#1{\SK@\SK@@ref{#1}\SK@citeauthor{#1}}%

168  \SK@def\citefullauthor#1{\SK@\SK@@ref{#1}\SK@citefullauthor{#1}}%
169  \SK@def\citeyear#1{\SK@\SK@@ref{#1}\SK@citeyear{#1}}%
170 \else

In the harvard style do not redefine individual cite commands. Just redefine one internal command that is used in all the citation forms.

171  \SK@def\HAR@checkdef#1#2{%
172  \expandafter\SK@\expandafter\SK@@ref\expandafter{#1}%
173  \SK@HAR@checkdef{#1}{#2}}%
174  \expandafter\let\expandafter
175  \SK@HAR@bi\csname\string\harvarditem\endcsname
176  \expandafter\def\csname\string\harvarditem\endcsname[#1]#2#3#4{%
177  \SK@HAR@bi[#1]{#2}{#3}{#4}\SK@\SK@@label{#4}}%
178 \fi}
179 \def\SK@citea#1#2{%
180 \SK@\SK@@ref{#2}\SK@cite#1{#2}}
181 \fi

\SK@@ref This is much simpler than the printing of the label, as we know that we can be in horizontal mode.

182 \def\SK@@ref#1>#2\SK@{%
183 \leavevmode\vbox to\z@{%
184  \vss
185  \SK@refcolor
186  \rlap{\vrule\raise .75em%
187  \hbox{\underbar{\normalfont\footnotesize\ttfamily#2}}}}}

188 ⟨/package⟩