The showkeys package^{∗}

David Carlisle

1996/05/17

1 Introduction

showkeys.sty modifies the \label, \ref, \pageref, \cite, and \bibitem com-
sec:intro

mands so that the ‘internal’ key is printed. The package tries hard to position these labels so that the formatting of the rest of the document is unchanged. \label and \bibitem cause the key to appear in a box either in the margin, or in a TEX box of zero width, which may possibly over-print other text. The \ref, \pageref and \cite commands print their arguments in small type, raised just above the line, like this: ^{\underline{sec:intro}} 1. This package works with the fleqn option, the packages in the AMS-L^{A}TEX collection, and the varioref, natbib and harvard packages.

2 Package Options

Some people have commented that the printing of the \ref and \cite keys is less

options

useful than the printing of the \label keys and so showkeys now supports two options that can be given in the \usepackage command.:

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

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

So if the package is loaded with \usepackage[notref]{showkeys} then \ref will have its standard definition, but \label will print its key argument (usually in the margin).

The package accepts two further options.

final to supress the action of this package, for ‘final’ versions.

draft the normal behaviour of this package.

Clearly there is not much point in entering the final option directly in the \usepackage command, as just not loading this package would have the same effect, and execute more quickly, however the final option may be useful as it may be used once in the documentclass command to affect any number of packages that may be loaded. The draft option does not do anything, but is there to honour an informal convention that packages have these options in pairs.

∗This file has version number v3.07, last revised 1996/05/17.

3 More Examples

The only other similar package that I could find in the macro index, ^{\underline{DMJ:mi}} [3], was

examples

showlabels.sty, ^{\underline{GN:sl}} [1]. After the first draft of this package was written, I found ^{\underline{anon:sk}} [2] on my local installation! I think the current package is more robust than ^{\underline{anon:sk}} [2], but I thought that showkeys was rather a good name, so I have stolen it for this file.

e^1 1. This has \label immediately after \item.

2. This has the \label at the end.

e^2

A minipage :- Within environments like this minipage, We can not use \marginpar^{1}, so the appearance is slightly different. Here is that enumerate environment again:

m&e^1 1. This has \label immediately after \item.

2. This has the \label at the end.

              m&e^2

Displayed math (without equation counter).

                                0 = 0 disp

Some text refering to the maths on page ^{\underline{disp}} 2, and the item ^{\underline{e^1}} 1.

If showkeys thinks that the current environment is going to produce an “equation number”, then it does not show the label where the \label command occurs, but tries to put it in the margin, as shown with equation ^{\underline{eq:xx}} 1. The package ‘knows’ about the standard equation and eqnarray environments, and also all the numbered alignment environments offered by the AMSL^{A}TEX package, amsmath.

1 = 1  (1) eq:xx

                              2 = 2  (2) eqnar:a

3 = 3

                              4 = 4  (3) eqnar:b

References

GN:sl [1] Gil Neiger, showlabels.sty, Undated package, similar to this one, but shows labels inline, affecting the formating of the document.

anon:sk [2] Annonymous, showkeys.sty, Package, dated 14 May 1988. Very similar to this one, also uses \marginpar in outer vertical mode.

DMJ:mi [3] David M. Jones, TEX Macro Index, A catalogue of TEX macros, including L^{A}TEX packages, available from all good TEX archives.

1Actually \marginpar is not used at all in this package now.

Within a figure environment, the \label must not come before the \caption command. If you place \label inside the argument of \caption the label will be shown like this:

Figure 1: Within the caption argument. cap:a

If you place \label immediately after the \caption command it will be shown like this:

Figure 2: Immediately after the caption argument.  cap:b

If you place the \label command at some random point after the \caption command, it may be shown like:

Figure 3: In vertical mode not immediately after a box.

 cap:c