% \iffalse % meta-comment
%
% This is the showlabels package option
% \fi
%
\def\filename{showlabels}
\def\fileversion{v1.2}
\def\filedate{1996/05/12}
\def\docdate{1996/05/12}
%  \CheckSum{302}
%
% \title{The \texttt{\filename} package\thanks{This file has version 
% number \fileversion, last revised \filedate, documentation dated \docdate}}
% \author{Norman Gray\\|norman@astro.gla.ac.uk|}
%
% \maketitle
%
% This is the showlabels class option.
%
% This class option introduces no new commands, it just helps you keep track 
% of all the labels by putting the name of the new label into the margin 
% whenever either the |\label| command is used, or an equation is 
% automatically numbered (by replacing the internal |\@eqnnum| command).  
% There are therefore no usage instructions.  You invoke this package with 
% the command |\usepackage{showlabels}| in the preamble, and you may give the 
% options \Lopt{inner} or \Lopt{outer} (the default) to have the labels placed in 
% the inner or outer margin of the text.
%
% The package will also work in the presence of the \Lopt{twocolumn} 
% option.  In this case, the options \Lopt{inner} and \Lopt{outer} will be 
% ignored, and the label will be placed in the nearer margin.
%
% The package has (finally) been modified to deal with the slightly
% different mechanism that AMS-\LaTeX\ uses to produce equation
% numbers.  I don't habitually use AMS-\LaTeX, 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.  The
% |\usepackage{showlabels}| must appear \emph{after} any AMS stuff is
% loaded.
%
% For reasonably obvious reasons, this package will \emph{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).
%
% \StopEventually{}
%
% \section{The driver file}
% Nothing fancy.
%    \begin{macrocode}
%<*driver>
\documentclass{ltxdoc}
\EnableCrossrefs
%    \end{macrocode}
%    Some commonly used abbreviations for option names, filenames, 
% counters and packages.
%    \begin{macrocode}
\newcommand\Lopt[1]{\textsf {#1}}
\newcommand\file[1]{\texttt {#1}}
\newcommand\Lcount[1]{\textsl {\small#1}}
\newcommand\pstyle[1]{\textsl {#1}}
\date{\docdate}
%    \end{macrocode}
% The body of the style.  Include all the details.
%    \begin{macrocode}
\begin{document}
% \OnlyDescription %uncomment to suppress the source listing
\DocInput{showlabels.dtx}
\PrintIndex
\PrintChanges
\end{document}
%</driver>
%    \end{macrocode}
%
% \section{The package}
%    \begin{macrocode}
%<*package>
%    \end{macrocode}
%
%    \begin{macrocode}
\NeedsTeXFormat{LaTeX2e}
\ProvidesPackage{showlabels}[\filedate\space\fileversion]
\typeout{Package: `showlabels' \fileversion\space<\filedate>}
\wlog{Documentation}
%    \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 AMS-\LaTeX\dots
% \changes{v1.2}{1996/05/12}{Finally added the AMS-LaTeX variant ifSL@noAMS}
%    \begin{macrocode}
\newif\ifSL@noAMS
\expandafter\ifx\csname maketag@@@\endcsname\relax
  \SL@noAMStrue
\else
  \SL@noAMSfalse
  \typeout{with AMS-LaTeX 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@labeln@me| 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 AMS-\LaTeX\ case
% as it artfully incorporates the |\maketag@@@| mechanism into a
% redefined |\@eqnnum|.
%
%    \begin{macrocode}
\ifSL@noAMS
  \let\@@eqnnum=\@eqnnum
  \def\@eqnnum{\@@eqnnum
  \ifx\SL@labeln@me\relax
    \SL@eqnlrtext{???}%
  \else
    \SL@eqnlrtext{\SL@labeln@me}%
    \global\def\SL@labeln@me{\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@labeln@me{\relax}
%    \end{macrocode}
%
% Otherwise do a similar thing for AMS-\LaTeX's |\maketag@@@|, which
% is what it uses 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}
\else
  \let\@maketag@@@=\maketag@@@
  \def\maketag@@@#1{\@maketag@@@{#1}%
  \ifx\df@label\@empty
%    \SL@eqnlrtext{???}%
  \else
    \SL@eqnlrtext{\df@label}%
  \fi}
\fi
%    \end{macrocode}
%
% For the benefit of |\prlabelname|, define |\SL@gobblethree| to do nothing 
% other than eat three tokens.
%    \begin{macrocode}
\def\SL@gobblethree#1#2#3{}
%    \end{macrocode}
%
% \begin{macro}{\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\prlabelname#1{%
\expandafter\expandafter\expandafter\SL@gobblethree
    \expandafter\string\csname r@#1\endcsname}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@makecaption}
% Simple replacement for the |\@makecaption| command.  This simply issues 
% the original |\@makecaption| command after redefining |\label|.  This 
% does not put the label name in the margin (that's too complicated 
% for the moment), but instead inserts it as part of the caption.
%    \begin{macrocode}
\let\@@makecaption\@makecaption
\long\def\@makecaption#1#2{{\def\label##1{{\small\tt
	\{\prlabelname{##1}\}\space}\SL@label{##1}}%
%    \end{macrocode}
% \dots and follows it with the original, saved, |\@makecaption|.
%    \begin{macrocode}
	\@@makecaption{#1}{#2}}}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\label}
% This is the central bit of this package.  Depending on the mode, put the 
% current label name in the margin in one of a variety of ways.
% First of all, issue the saved |\SL@label| command.
%    \begin{macrocode} 
\let\SL@label\label
\def\label#1{\@bsphack\SL@label{#1}%
%    \end{macrocode}
% In maths mode, produce a label name alongside the equation number.
% If we're not using AMS-\LaTeX, then save the label name in
% |\SL@labelname|.  If we \emph{are} using AMS-\LaTeX, then we don't
% have to worry, because it's saved in |\df@label| for us.
%    \begin{macrocode}
  \ifmmode
    \ifSL@noAMS
      \xdef\SL@labeln@me{\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 |\box0| 
% (which probably shouldn't be necessary).
%    \begin{macrocode}
  \else
    {\setbox0=\vbox to 0pt{\vss
      \hbox to \columnwidth{\SL@lrtext{#1}}}%
    \dp0=0pt
%    \end{macrocode}
% and attach it below the last one, using |\nointerlineskip| if we're in 
% vertical mode, or |\vadjust| otherwise.
%    \begin{macrocode}
    \ifvmode
      \nointerlineskip\box0\nobreak
    \else
      \vadjust{\box0\nobreak}%
    \fi}%
%    \end{macrocode}
% That's it.  Finish off the |\ifmmode| and give the partner to |\@bsphack|.
%    \begin{macrocode}
  \fi
  \@esphack}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\margintext}
% Set the actual text of the label.
%    \begin{macrocode}
\def\SL@margintext#1{{\small\sl\{#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 |\if@outerlabels| 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}
% The code for |\SK@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{%
  \if@outerlabels
    \ifodd\c@page
      \let\SL@next\SL@righttext\else
      \let\SL@next\SL@lefttext\fi
  \else
    \ifodd\c@page
      \let\SL@next\SL@lefttext\else
      \let\SL@next\SL@righttext\fi
  \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{%
  \if@outerlabels
    \ifodd\c@page
      \let\SL@next\SL@eqnrighttext\else
      \let\SL@next\SL@eqnlefttext\fi
  \else
    \ifodd\c@page
      \let\SL@next\SL@eqnlefttext\else
      \let\SL@next\SL@eqnrighttext\fi
  \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}
%
% To keep track of things, declare the |\if@outerlabels| switch, and set 
% it true by default.
%    \begin{macrocode}
\newif\if@outerlabels
\@outerlabelstrue
%    \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}{\@outerlabelstrue}
\DeclareOption{inner}{\@outerlabelsfalse}
%    \end{macrocode}
%
% Process any options that have been set.
%    \begin{macrocode}
\ProcessOptions
%    \end{macrocode}
% and use the values of |\if@outerlabels| 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
  \if@outerlabels
    \if@twoside
	  \let\SL@lrtext\SL@alternatetext
	  \let\SL@eqnlrtext\SL@eqnalternatetext
    \else
      \let\SL@lrtext\SL@righttext
      \let\SL@eqnlrtext\SL@eqnrighttext
    \fi
  \else
    \if@twoside
	  \let\SL@lrtext\SL@alternatetext
	  \let\SL@eqnlrtext\SL@eqnalternatetext
    \else
      \let\SL@lrtext\SL@lefttext
      \let\SL@eqnlrtext\SL@eqnlefttext
    \fi
  \fi
\fi
%    \end{macrocode}
%
% That's us.  
%
%    \begin{macrocode}
%</package>
%    \end{macrocode}
%
% \Finale
\endinput