% \iffalse % meta-comment
%
% This is the showlabels package option
%
%% This software is copyright, 1999, 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 .
%
%<+package|driver>%% RCS Info $Id: showlabels.dtx,v 1.4 1999/07/22 17:28:21 norman Exp $
%<+package>\NeedsTeXFormat{LaTeX2e}
%<+package>\ProvidesPackage{showlabels}[1999/07/22 v1.3c]
%<+package>\typeout{Package: `showlabels' v1.3c\space<1999/07/22>}
\def\filename{showlabels}
\def\fileversion{v1.3c}
\def\filedate{1999/07/22}
\def\docdate{1999/07/22}
%
%<*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}
%% \url macro (url.sty does this better)
\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
%
% \CheckSum{274}
% \changes{v1.2a}{1996/10/04}{Corrected the checksum!}
% \changes{v1.3b}{1996/06/06}{Clarified copyright and licence conditions, also restructured to make preparing documentation easier.}
%
% \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 package 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.
% 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} and \Lopt{outer} will be 
% ignored, and the label will be placed in the nearer margin.
%
% 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 must appear \emph{after} the
% |\usepackage{amsmath}|. 
% 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.
%
% If you want to change the font the labels appear in, use something
% along the lines of |\renewcommand{\showlabelsfont}{\small\slfamily}|.
%
% 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 might still work with \LaTeX2.09, but that's neither
% supported, nor even tested.
%
% This software is copyright, 1999, 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}.
%
% \section{History and Credits}
%
% For version 1.3, I received comments and bug reports from:
%   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}.
% 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'.
%
% Originally released 21-Sep-91 by me, under the name 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 AMS-\LaTeX\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 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@AMS
%    \end{macrocode}
%
% AMS-\LaTeX 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\@maketag@@@=\maketag@@@
  \def\maketag@@@#1{\@maketag@@@{#1}%
  \ifx\df@label\@empty
%    \SL@eqnlrtext{???}%
  \else
    \SL@eqnlrtext{\df@label}%
  \fi}
\else
%    \end{macrocode}
% The `normal' case, without AMS-LaTeX
% \changes{v1.3c}{1999/07/22}{Added expandafter before test -- 
%       how on earth had this escaped before?!?}
%    \begin{macrocode}
  \let\@@eqnnum=\@eqnnum
  \def\@eqnnum{\@@eqnnum
  \expandafter\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}
\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}
%    \begin{macrocode}
\def\showlabelfont{\small\tt}
%    \end{macrocode}
% Leave this as |\small\tt|, to avoid a pointless incompatibility with
% \LaTeX 2.09.
%
% 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.
% \changes{v1.3a}{1999/03/04}{Changed private @@makecaption to SL@makecaption}
%    \begin{macrocode}
\let\SL@makecaption\@makecaption
\long\def\@makecaption#1#2{{\def\label##1{{\showlabelfont
	\{\prlabelname{##1}\}\space}\SL@label{##1}}%
%    \end{macrocode}
% \dots and follows it with the original, saved, |\@makecaption|.
%    \begin{macrocode}
	\SL@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@AMS\else
      \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.  Use |\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{{\showlabelfont\{\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 |\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 |\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{%
  \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
