% \iffalse
%% File: showkeys.dtx Copyright (C) 1992-1995 David Carlisle
%
%<*dtx>
          \ProvidesFile{showkeys.dtx}
%</dtx>
%<package>\NeedsTeXFormat{LaTeX2e}
%<package>\ProvidesPackage{showkeys}
%<driver> \ProvidesFile{showkeys.drv}
% \fi
%         \ProvidesFile{showkeys.dtx}
          [1995/04/25 v3.03 Show cite and label keys (DPC)]
%
% \iffalse
%<*driver>
\documentclass{ltxdoc}
\usepackage
%     [notcite,notref]
            {showkeys}
\setlength{\belowcaptionskip}{\baselineskip}
\setlength{\abovecaptionskip}{0pt}
\begin{document}
\DocInput{showkeys.dtx}
\end{document}
%</driver>
% \fi
%
% \GetFileInfo{showkeys.dtx}
% \title{The \textsf{showkeys} package\thanks{This file
%         has version number \fileversion, last
%         revised \filedate.}}
% \author{David Carlisle}
% \date{\filedate}
% \maketitle
%
% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
% \CheckSum{401}
%
%
% \changes{v1.01}{1992/08/25}{Initial version}
% \changes{v1.02}{1994/01/05}
%         {Fix incorrect initialisation (FGBDA19@CC1.KULEUVEN.AC.BE)}
% \changes{v2.00}{1994/01/31}{new version for LaTeX2e}
% \changes{v2.01}{1994/06/30}{Fix \cs{ProvidesPackage} usage.}
% \changes{v3.00}{1994/09/07}
%         {Support harvard, varioref and natbib packages,}
% \changes{v3.02}{1995/03/17}
%         {Support new AMS files}
%
% \section{Introduction}\label{sec:intro}
%
% |showkeys.sty| modifies the |\label|, |\ref|, |\pageref|, |\cite|, and
% |\bibitem| commands 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: \ref{sec:intro}.
% This package works with the \textsf{fleqn} package, and the packages
% in the AMS-\LaTeX\ collection.
% \changes{v2.00}{1992/01/31}
%         {leqno or ams* may now be loaded after showkeys}
%
% \section{Package Options}\label{options}
% Some people have commented that the printing of the |\ref| and
% |\cite| keys is less useful than the printing of the |\label| keys
% and so \textsf{showkeys} now supports two options that can be given
% in the |\usepackage| command.:
% \begin{description}
% \item[notref] to stop the redefinition of |\ref| and |\pageref|,
% and related commands from the \textsf{varioref} package.
% \item[notcite] to stop the redefinition of |\cite| and related
% commands from the \textsf{harvard} and \textsf{natbib} packages.
% \end{description}
%
% 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).
%
% \section{More Examples}\label{examples}
% The only other similar package that I could find in the macro index,
% \cite{DMJ:mi}, was |showlabels.sty|, \cite{GN:sl}. After the first
% draft of this package was written, I found \cite{anon:sk} on my local
% installation! I think the current package is more robust than
% \cite{anon:sk}, but I thought that |showkeys| was rather a good name,
% so I have stolen it for this file.
%
% \begin{enumerate}
% \item \label{e^1}This has |\label| immediately after |\item|.
% \item This has the |\label| at the end.\label{e^2}
% \end{enumerate}
%
% \[
% \mbox{A minipage :- }\left\{
% \begin{minipage}{3in}
% Within environments like this |minipage|, We can not use
% |\marginpar|\footnotemark,
% so the appearance is slightly different. Here is that |enumerate|
% environment again:
%
% \begin{enumerate}
% \item \label{m&e^1}This has |\label| immediately after |\item|.
% \item This has the |\label| at the end.\label{m&e^2}
% \end{enumerate}
% \end{minipage}
% \right.
% \]
%
% Displayed math (without |equation| counter).
% \[0=0\label{disp}\]
%
% Some text refering to the maths on page~\pageref{disp},  and the
% item~\ref{e^1}.\footnotetext{Actually \texttt{\string\marginpar} is
% not used at all in this package now.}
%
% 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~\ref{eq:xx}.
% The package `knows' about the standard |equation| and |eqnarray|
% environments, and also all the numbered alignment environments offered
% by the AMS\LaTeX\ package, |amsmath|.
%
% ^^A (|amstex.sty| must be loaded before |showkeys.sty|
% ^^A for this to work.)
% \changes{v2.00}{1992/01/31}
%         {leqno or ams* may now be loaded after showkeys}
%
% \begin{equation}
% 1=1\label{eq:xx}
% \end{equation}
%
% \begin{eqnarray}
% 2&=&2\label{eqnar:a}\\
% 3&=&3\nonumber\\
% 4&=&4\label{eqnar:b}
% \end{eqnarray}
%
%
% \begin{figure}[h]
% 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:
%
% \caption{Within the caption argument.\label{cap:a}}
%
% If you place |\label| immediately after the |\caption| command it will
% be shown like this:
%
% \caption{Immediately after the caption argument.}\label{cap:b}
%
% If you place the |\label| command at some random point after the
% |\caption| command, it may be shown like:
%
% \caption{In vertical mode not immediately after a box.}
% \vspace{2pt}
%
% \label{cap:c}
% \end{figure}
%
%
% \begin{thebibliography}{9}
%
% \bibitem{GN:sl}
% Gil Neiger, {\em showlabels.sty},
% Undated package, similar to this one, but shows labels
% inline, affecting the formating of the document.
%
% \bibitem{anon:sk}
% Annonymous, {\em showkeys.sty},
% Package, dated 14 May 1988. Very similar to this one,
% also uses |\marginpar| in outer vertical mode.
%
% \bibitem{DMJ:mi}
% David M. Jones, {\em \TeX\ Macro Index},
% A catalogue of \TeX\ macros, including \LaTeX\ packages,
% available from all good \TeX\ archives.
%
% \end{thebibliography}
%
% \StopEventually{}
%
% \section{The Macros}
%
%    \begin{macrocode}
%<*package>
%    \end{macrocode}
%
%
% First we handle the options. Normally all related comands are
% defined to show there `keys'. But since v3.03 one can specify:
%
% \texttt{notref} to stop the redefinition of |\ref| (and |\pageref|,
% and related commands from \textsf{varioref} package) 
%
% \texttt{notcite} to stop the redefinition of |\cite| and related
% commands from the \textsf{harvard} and \textsf{natbib} packages.
%
% \changes{v3.03}{1995/04/25}
%      {Add option handling.}
%    \begin{macrocode}
\DeclareOption{notref}{\let\SK@ref\@empty}
\DeclareOption{notcite}{\let\SK@cite\@empty}
\ProcessOptions
%    \end{macrocode}
%
% \changes{v2.00}{1992/01/31}
%         {\cmd{reset@font} is now standard}
%
% \begin{macro}{\SK@label}
% \begin{macro}{\SK@bibitem}
% \begin{macro}{\SK@lbibitem}
% The saved original definitions
%    \begin{macrocode}
\let\SK@label\label
\let\SK@bibitem\@bibitem
\let\SK@lbibitem\@lbibitem
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
%
%
% \begin{macro}{\label}
% The new definition, print the argument, and then do the old
% definition.
%    \begin{macrocode}
\def\label#1{\@bsphack\SK@\SK@@label{#1}\SK@label{#1}\@esphack}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@bibitem}
% \begin{macro}{\@lbibitem}
% \changes{v3.02}{1995/03/17}
%         {New label code.}
% For |\bibitem|, position the \textsf{showkeys} code as for a standard
% list with |\item| and |\label|.
%    \begin{macrocode}
\def\@bibitem#1{%
  \SK@bibitem{#1}\SK@\SK@@label{#1}\ignorespaces}
\def\@lbibitem[#1]#2{%
  \SK@lbibitem[#1]{#2}\SK@\SK@@label{#2}\ignorespaces}
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
% \begin{macro}{\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|.
%    \begin{macrocode}
\def\SK@#1#2{\def\@tempa{#2}\expandafter#1\meaning\@tempa\SK@}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\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.
%    \begin{macrocode}
\def\SK@@label#1>#2\SK@{%
%    \end{macrocode}
% 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.
%    \begin{macrocode}
  \gdef\SK@lab{\smash{\fbox{\reset@font\small\ttfamily#2}}}%
  \ifvmode
    \if@inlabel
%    \end{macrocode}
% \changes{v3.02}{1995/03/17}
%         {New code for `in label' case.}
% 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.
%    \begin{macrocode}
      \global\setbox\@labels\hbox{%
        \llap{\SK@lab\SK@lab@relax
              \kern\@totalleftmargin\kern\marginparsep}%
        \box\@labels}%
%    \end{macrocode}
% 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.
%    \begin{macrocode}
    \else
      \ifinner
        \skip@=\lastskip\unskip
%    \end{macrocode}
% 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.)
% \changes{v3.00}{1994/09/07}
%      {Back up over a previous skip because of the new 
%       \cs{belowcaptionskip}}
%    \begin{macrocode}
        \skip@\lastskip\unskip
        \setbox\z@\lastbox
        \ifvoid\z@
          \nointerlineskip\SK@labx
        \else
          \hbox{\box\z@\SK@labx}%
        \fi
        \vskip\skip@
      \else
%    \end{macrocode}
% In outer vertical mode, use a |\vadjust| at the start of the next
% paragraph (previously used |\marginpar|).
% \changes{v3.02}{1995/03/17}
%         {Use \cs{vadjust} instead of \cs{marginpar}}
%    \begin{macrocode}
        \everypar\expandafter{\the\everypar
          \vadjust{\llap{\SK@lab\kern\marginparsep}}\SK@lab@relax}%
      \fi
    \fi
  \else
%    \end{macrocode}
% 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.
% \changes{v3.02}{1995/03/17}
%         {Add \cs{ifmmode} test}
%    \begin{macrocode}
    \csname SK@\@currenvir\endcsname
    \ifSK@equation\else
      \ifmmode
        \SK@labx
      \else
%    \end{macrocode}
% Inner horizontal mode. Not much we can do, just stick it here.
% \changes{v3.03}{1995/04/25}
%         {Fix inner horizontal mode case (broken in 3.02)}
%    \begin{macrocode}
        \ifinner
          \rlap\SK@lab
      \else
%    \end{macrocode}
% In outer horizontal mode use |\vadjust| to get to the margin.
% \changes{v3.02}{1995/03/17}
%         {Use \cs{vadjust} in horizontal mode}
%    \begin{macrocode}
          \vadjust{\llap{\SK@lab\kern\marginparsep}}%
        \fi
        \SK@lab@relax
      \fi  
    \fi  
  \fi}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\iftagsleft@}
% Make sure that this AMS\LaTeX\ command really is an |\if..|
% \changes{v2.00}{1992/01/31}
%         {Defer tests to begin document}
%    \begin{macrocode}
\AtBeginDocument{%
  \let\SK@eqnnum\@eqnnum
  \def\@tempa{\let\iftagsleft@\iffalse}%
  \ifx\iftagsleft@\undefined\@tempa\fi%
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\tag@form@}
% \changes{v3.02}{1995/03/17}
%         {Support new AMS files}
% \begin{macro}{\eqnnum}
% Perhaps if |leqno| is operative, I should define |\@eqnnum| with the
% `left' version, but it does not really matter.
%    \begin{macrocode}
  \let\SK@tagform@\tagform@
  \iftagsleft@
    \def\tagform@#1{%
      \ifx\df@label\@empty
        \SK@lab@relax
      \else
        \expandafter\SK@@label\meaning\df@label\SK@
      \fi
      \llap{\SK@lab\kern\marginparsep}%
      \SK@lab@relax\SK@tagform@{#1}}%
    \def\@eqnnum{%
      \llap{\SK@lab\kern\displaywidth\kern\marginparsep}%
      \SK@lab@relax\SK@eqnnum}%
%    \end{macrocode}
%
%    \begin{macrocode}
  \else
    \def\tagform@#1{%
      \ifx\df@label\@empty
        \SK@lab@relax
      \else
        \expandafter\SK@@label\meaning\df@label\SK@
      \fi
      \SK@tagform@{#1}
      \rlap{\kern\marginparsep\SK@lab}\SK@lab@relax}%
    \def\@eqnnum{\SK@eqnnum\rlap{\kern\marginparsep\SK@lab}%
                     \SK@lab@relax}%
  \fi}
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
% \begin{macro}{\SK@labx}
% Print the label, and then globally reset the print command to
% |\relax|.
%    \begin{macrocode}
\def\SK@labx{\rlap\SK@lab\global\let\SK@lab\relax}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\SK@lab@relax}
% Clear the label.
% \changes{v1.02}{1994/01/05}{Execute to initialise correctly}
%    \begin{macrocode}
\def\SK@lab@relax{\global\let\SK@lab\relax}\SK@lab@relax
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\SK@equation}
% \begin{macro}{\SK@eqnaray}
% \begin{macro}{\SK@align}
% \begin{macro}{\SK@alignat}
% \begin{macro}{\SK@xalignat}
% \begin{macro}{\SK@xxalignat}
% \begin{macro}{\SK@gather}
% \begin{macro}{\SK@multline}
% \begin{macro}{\SK@flalign}
% \changes{v3.02}{1995/03/17}
%         {Add \cs{SK@flalign}}
% 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\ldots
%    \begin{macrocode}
\newif\ifSK@equation
\let\SK@equation\SK@equationtrue
\let\SK@eqnarray\SK@equationtrue
\let\SK@align\SK@equationtrue
\let\SK@alignat\SK@equationtrue
\let\SK@xalignat\SK@equationtrue
\let\SK@xxalignat\SK@equationtrue
\let\SK@gather\SK@equationtrue
\let\SK@multline\SK@equationtrue
\let\SK@flalign\SK@equationtrue
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
%
%
% The next section redefines |\ref| and |\pageref| (unless the
% \texttt{notref} otption was given).
%    \begin{macrocode}
\ifx\SK@ref\@empty\else
%    \end{macrocode}
%
% \begin{macro}{\ref}
% \begin{macro}{\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.
% \changes{v3.00}{1994/09/07}
%      {Delay \cs{ref} redefinition.}
% \changes{v3.03}{1995/04/25}
%      {Make redefinition conditional on notref option}
%    \begin{macrocode}
\AtBeginDocument{%
  \let\SK@ref\ref
  \let\SK@pageref\pageref
  \DeclareRobustCommand\ref[1]{\SK@\SK@@ref{#1}\SK@ref{#1}}%
  \DeclareRobustCommand\pageref[1]{\SK@\SK@@ref{#1}\SK@pageref{#1}}%
  \ifx\vpageref\@undefined\else
%    \end{macrocode}
% varioref support.
%    \begin{macrocode}
    \let\SK@@@vpageref\@@vpageref
    \def\@@vpageref#1[#2]#3{{%
      \let\label\SK@label\let\ref\SK@ref\let\pageref\SK@pageref
      \leavevmode\unskip\SK@\SK@@ref{#3}\SK@@@vpageref#1[#2]{#3}}}%
    \DeclareRobustCommand\vref[1]{%
      \unskip~\ref{#1}%
      {\let\label\SK@label\let\ref\SK@ref\let\pageref\SK@pageref
       \SK@@@vpageref\unskip[\unskip\space]{#1}}}%
  \fi}
%    \end{macrocode}
%
%    \begin{macrocode}
\fi
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
% Now redefine |\cite| unless \texttt{notcite} option given.   
%    \begin{macrocode}
\ifx\SK@cite\@empty\else
%    \end{macrocode}
%
% \begin{macro}{\cite}
% \changes{v3.00}{1994/09/07}
%      {Delay \cs{cite} redefinition.}
% \changes{v3.03}{1995/04/25}
%      {Make redefinition conditional on notcite option}
%    \begin{macrocode}
\AtBeginDocument{%
  \ifx\HAR@checkdef\@undefined
%    \end{macrocode}
% Standard (non-harvard) support, including extra cite commands from
% natbib.
% \changes{v3.01}{1994/09/09}
%         {Add \cs{citefullauthor}}
%    \begin{macrocode}
    \let\SK@cite\cite
    \def\cite#1#{\SK@citea{#1}}%
    \let\SK@citeauthor\citeauthor
    \def\citeauthor#1{\SK@\SK@@ref{#1}\SK@citeauthor{#1}}%
    \let\SK@citefullauthor\citefullauthor
    \def\citefullauthor#1{\SK@\SK@@ref{#1}\SK@citefullauthor{#1}}%
    \let\SK@citeyear\citeyear
    \def\citeyear#1{\SK@\SK@@ref{#1}\SK@citeyear{#1}}%
  \else
%    \end{macrocode}
% In the harvard style do \emph{not} redefine individual cite commands.
% Just redefine one internal command that is used in all the citation
% forms.
%    \begin{macrocode}
    \let\SK@HAR@checkdef\HAR@checkdef
    \def\HAR@checkdef#1#2{%
      \expandafter\SK@\expandafter\SK@@ref\expandafter{#1}%
      \SK@HAR@checkdef{#1}{#2}}%
      \expandafter\let\expandafter
         \SK@HAR@bi\csname\string\harvarditem\endcsname
      \expandafter\def\csname\string\harvarditem\endcsname[#1]#2#3#4{%
        \SK@\SK@@label{#4}\SK@HAR@bi[#1]{#2}{#3}{#4}}%
  \fi}
%    \end{macrocode}
%
%    \begin{macrocode}
\def\SK@citea#1#2{%
  \SK@\SK@@ref{#2}\SK@cite#1{#2}}
%    \end{macrocode}
%
%    \begin{macrocode}
\fi
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\SK@@ref}
% This is much simpler than the printing of the label, as we know that
% we can be in horizontal mode.
%    \begin{macrocode}
\def\SK@@ref#1>#2\SK@{%
  \leavevmode\vbox to \z@{\vss
    \rlap{\vrule\raise .75em
       \hbox{\underbar{\reset@font\footnotesize\ttfamily#2}}}}}
%    \end{macrocode}
% \end{macro}
%
%    \begin{macrocode}
%</package>
%    \end{macrocode}
%
% \Finale
%
