path: root/Master/texmf-dist/source/latex/undolabl/undolabl.dtx

% \iffalse meta-comment
%
% undolabl package
% file version: v1.0d
% file date:          2010/07/15
% documentation date: 2010/07/15
%
% Copyright (C) 2010 H.-Martin M\"{u}nch (Martin dot Muench at Uni-Bonn dot de)
% Portions of code copyrighted by other people as marked.
%
% The main code of this package was invented by
% Ulrich Diez (eu_angelion@web.de) and first published in the
% comp.text.tex newsgroup at Sun, 20 Apr 2008 16:39:26 +0200, with subject:
% Re: How to undefine/overwrite a label? (see e.g.
% http://groups.google.de/group/comp.text.tex/msg/5ba8d4722e5cd326.
% While Ulrich Diez neither wanted to create a package himself yet
% nor have one published under his name, he granted the
% publication of his code. Therefore: Thanks!
%
% This work may be distributed and/or modified under the
% conditions of the LaTeX Project Public License, either
% version 1.3c of this license or (at your option) any later
% version. This version of this license is in
%    http://www.latex-project.org/lppl/lppl-1-3c.txt
% and the latest version of this license is in
%    http://www.latex-project.org/lppl.txt
% and version 1.3c or later is part of all distributions of
% LaTeX version 2005/12/01 or later.
%
% This work has the LPPL maintenance status "maintained".
%
% The Current Maintainer of this work is H.-Martin Muench.
%
% This work consists of the main source file undolabl.dtx
% and the derived files
%    undolabl.sty, undolabl.pdf, undolabl.ins, undolabl.drv,
%    undolabl-example.tex.
%
% Unpacking:
%    (a) If undolabl.ins is present:
%           tex undolabl.ins
%    (b) Without undolabl.ins:
%           tex undolabl.dtx
%    (c) If you insist on using LaTeX
%           latex \let\install=y\input{undolabl.dtx}
%        (quote the arguments according to the demands of your shell)
%
% Documentation:
%    (a) If undolabl.drv is present:
%           (pdf)latex undolabl.drv
%           makeindex -s gind.ist undolabl.idx
%           (pdf)latex undolabl.drv
%           makeindex -s gind.ist undolabl.idx
%           (pdf)latex undolabl.drv
%    (b) Without undolabl.drv:
%           (pdf)latex undolabl.dtx
%           makeindex -s gind.ist undolabl.idx
%           (pdf)latex undolabl.dtx
%           makeindex -s gind.ist undolabl.idx
%           (pdf)latex undolabl.dtx
%
%    The class ltxdoc loads the configuration file ltxdoc.cfg
%    if available. Here you can specify further options, e.g.
%    use DIN A4 as paper format:
%       \PassOptionsToClass{a4paper}{article}
%
%    Programm calls to get the documentation (for example):
%       pdflatex undolabl.dtx
%       makeindex -s gind.ist undolabl.idx
%       % makeindex -s gglo.ist -o undolabl.gls undolabl.glo
%       pdflatex undolabl.dtx
%       makeindex -s gind.ist undolabl.idx
%       % makeindex -s gglo.ist -o undolabl.gls undolabl.glo
%       pdflatex undolabl.dtx
%
% Installation:
%    TDS:tex/latex/muench/undolabl/undolabl.sty
%    TDS:doc/latex/muench/undolabl/undolabl.pdf
%    TDS:doc/latex/muench/undolabl/undolabl-example.tex
%    TDS:source/latex/muench/undolabl/undolabl.dtx
%
%<*ignore>
\begingroup
  \def\x{LaTeX2e}%
\expandafter\endgroup
\ifcase 0\ifx\install y1\fi\expandafter
         \ifx\csname processbatchFile\endcsname\relax\else1\fi
         \ifx\fmtname\x\else 1\fi\relax
\else\csname fi\endcsname
%</ignore>
%<*install>
\input docstrip.tex

\obeyspaces
\Msg{******************************************************}
\Msg{* Installation                                       *}
\Msg{* Package: undolabl v1.0d 2010/07/15 LaTeX2e package *}
\Msg{* Overriding labels (HMM)                            *}
\Msg{******************************************************}

\keepsilent
\askforoverwritefalse

\let\MetaPrefix\relax
\preamble

This is a generated file.

IMPORTANT NOTICE:
The usual disclaimers apply:
If it doesn't work right that's your problem.
(Nevertheless, send an e-mail to the maintainer
 when you find an error in this package.)

This work may be distributed and/or modified under the
conditions of the LaTeX Project Public License, either
version 1.3c of this license or (at your option) any later
version. This version of this license is in
   http://www.latex-project.org/lppl/lppl-1-3c.txt
and the latest version of this license is in
   http://www.latex-project.org/lppl.txt
and version 1.3c or later is part of all distributions of
LaTeX version 2005/12/01 or later.

This work has the LPPL maintenance status "maintained".

The Current Maintainer of this work is H.-Martin Muench
(Martin dot Muench at Uni-Bonn dot de).

The main code of this package was invented by Ulrich Diez
(eu_angelion@web.de) and first published in the comp.text.tex
newsgroup at Sun, 20 Apr 2008 16:39:26 +0200, with subject:
Re: How to undefine/overwrite a label? (see e.g.
http://groups.google.de/group/comp.text.tex/msg/5ba8d4722e5cd326).
While Ulrich Diez neither wanted to create a package himself yet
nor have one published under his name, he granted the
publication of his code. Therefore: Thanks!

This work consists of the main source file undolabl.dtx
and the derived files
   undolabl.sty, undolabl.pdf, undolabl.ins, undolabl.drv,
   undolabl-example.tex.

\endpreamble
\let\MetaPrefix\DoubleperCent

\generate{%
  \file{undolabl.ins}{\from{undolabl.dtx}{install}}%
  \file{undolabl.drv}{\from{undolabl.dtx}{driver}}%
  \file{ltxdoc.cfg}{\from{undolabl.dtx}{ltxdoc}}%
  \usedir{tex/latex/muench/undolabl}%
  \file{undolabl.sty}{\from{undolabl.dtx}{package}}%
  \usedir{doc/latex/muench/undolabl}%
  \file{undolabl-example.tex}{\from{undolabl.dtx}{example}}%
}

\obeyspaces
\Msg{**************************************************************}
\Msg{*                                                            *}
\Msg{* To finish the installation you have to move the following  *}
\Msg{* file into a directory searched by TeX:                     *}
\Msg{*                                                            *}
\Msg{* undolabl.sty                                               *}
\Msg{*                                                            *}
\Msg{* To produce the documentation run the file `undolabl.drv'   *}
\Msg{* through (pdf)LaTeX, e.g.                                   *}
\Msg{*  pdflatex undolabl.dtx                                     *}
\Msg{*  makeindex -s gind.ist undolabl.idx                        *}
\Msg{*  pdflatex undolabl.dtx                                     *}
\Msg{*  makeindex -s gind.ist undolabl.idx                        *}
\Msg{*  pdflatex undolabl.dtx                                     *}
\Msg{*                                                            *}
\Msg{* At least two runs are necessary e. g. to get the           *}
\Msg{*  references right!                                         *}
\Msg{*                                                            *}
\Msg{* Happy TeXing!                                              *}
\Msg{*                                                            *}
\Msg{**************************************************************}

\endbatchfile

%</install>
%<*ignore>
\fi
%</ignore>
%
% \section{The documentation driver file}
%
% The next bit of code contains the documentation driver file for
% \TeX{}, i.\,e., the file that will produce the documentation you
% are currently reading. It will be extracted from this file by the
% \texttt{docstrip} programme. That is, run \LaTeX\ on \texttt{docstrip}
% and specify the \texttt{driver} option when \texttt{docstrip}
% asks for options.
%
%    \begin{macrocode}
%<*driver>
\NeedsTeXFormat{LaTeX2e}[1994/06/01]
\ProvidesFile{undolabl.drv}[2010/07/15 v1.0d%
             Overriding labels (HMM)]%
\documentclass{ltxdoc}[2007/11/11]% v2.0u
\usepackage{holtxdoc}[2010/04/18]% v0.19
%% undolabl may work with earlier versions of LaTeX2e and those
%% class and package, but this was not tested.
%% Please consider updating your LaTeX, class, and package
%% to the most recent version (if they are not already the most
%% recent version).
%% Warning: holtxdoc, 2010/04/24 v0.19, requires the packages
%% hypdoc, 2010/03/26, v1.9
%% hyperref, 2010/03/30, v6.80u (latest: 2010/06/18 v6.81g)
%% pdftexcmds, 2010/04/01, v0.9
%% ltxcmds, 2010/03/09, v1.4 (latest: 2010/04/26, v1.7)
%% hologo, 2010/04/24, v1.2
%% array (latest: 2008/09/09, v2.4c)
%% (or more recent versions) and does neither work with
%% nor check for earlier versions!
\hypersetup{%
 pdfsubject={LaTeX2e package for overriding labels (HMM)},%
 pdfkeywords={LaTeX, undolabl, undolabel, undo label, label, override, Hans-Martin Muench},%
 pdfencoding=auto,%
 pdflang={en},%
 breaklinks=true,%
 linktoc=all,%
 pdfstartview=FitH,%
 pdfpagelayout=OneColumn,%
 bookmarksnumbered=true,%
 bookmarksopen=true,%
 bookmarksopenlevel=2,%
 pdfmenubar=true,%
 pdftoolbar=true,%
 pdfwindowui=true,%
 pdfnewwindow=true%
}
\setlength\hfuzz{1pt} % Ignore slight overfulls.
\CodelineIndex
%\PageIndex           % instead of \CodelineIndex to get the page numbers
\EnableCrossrefs
%\DisableCrossrefs    % Say \DisableCrossrefs if index is ready.
%\RecordChanges       % Gather update information.
%\OnlyDescription     % Comment out for implementation details.
\hyphenation{docu-ment}
\makeatletter
%% Code from tcilatex.tex, Macros for Scientific Word and Scientific WorkPlace 5.5 <06 Oct 2005> %%
%% Copyright (C) 2005 Mackichan Software, Inc.                                                   %%
%% That macro file is NOT proprietary and may be freely copied and distributed.                  %%
  \def\unit#1{\mathord{\thinspace\rm #1}}%
%% End of code from tcilatex.tex                                                                 %%
\makeatother
\begin{document}
  \DocInput{undolabl.dtx}%
\end{document}
%</driver>
%    \end{macrocode}
%
%    \begin{macrocode}
%<*ltxdoc>
\NeedsTeXFormat{LaTeX2e}[1994/06/01]
\ProvidesFile{ltxdoc.cfg}[2010/06/01 v1.0 configuration file for undolabl (HMM)]
  %% Code from original ltxdoc.cfg [2007/01/08 latex-tds: ltxdoc.cls configuration (HO)],  %%
  % copyrighted 2006, 2007 Heiko Oberdiek, part of project `latex-tds'.
  % That file may be distributed and/or modified under the
  % conditions of the LaTeX Project Public License, either version 1.3
  % of this license or (at your option) any later version.
  % The latest version of this license is in
  %   http://www.latex-project.org/lppl.txt
  % and version 1.3c or later is part of all distributions of LaTeX
  % version 2005/12/01 or later.
  % That work has the LPPL maintenance status `maintained'.
  % The Current Maintainer of that work is Heiko Oberdiek.
  %
  \PassOptionsToClass{a4paper}{article}
  \AtEndOfClass{%
    \RequirePackage[numbered]{hypdoc}[2010/03/26]% v1.9
    \pdfstringdefDisableCommands{%
      \let\env\relax % longtable.dtx
      \let\mytt\relax % tabularx.dtx
    }%
    \addtolength{\topmargin}{-10mm}%
    \addtolength{\textheight}{20mm}%
    % Depending on the page style, the head or foot area
    % are put into the text area.
    % Usually the page style is the default "plain".
    % tools/verbatim.dtx uses "myheadings".
    \def\string@plain{plain}%
    \def\string@myheadings{myheadings}%
    \def\current@pagestyle{plain}%
    \let\ltxdoc@cfg@pagestyle\pagestyle
    \def\pagestyle#1{%
      \def\current@pagestyle{#1}%
      \ltxdoc@cfg@pagestyle{#1}%
    }%
    \edef\ltxdoc@cfg@jobname{\jobname}%
    \def\ltxdoc@cfg@longtable{longtable}%
    \@onelevel@sanitize\ltxdoc@cfg@longtable
    \ifx\ltxdoc@cfg@jobname\ltxdoc@cfg@longtable
      \def\current@pagestyle{both}%
    \fi
    \let\ltxdoc@cfg@document\document
    \def\document{%
      \ifx\current@pagestyle\string@plain
        \addtolength{\textheight}{\headheight}%
        \addtolength{\textheight}{\headsep}%
        \setlength{\headheight}{0pt}%
        \setlength{\headsep}{0pt}%
        \global\textheight\textheight
        \global\headheight\headheight
        \global\headsep\headsep
      \fi
      \ifx\current@pagestyle\string@myheadings
        \addtolength{\textheight}{\footskip}%
        \global\textheight\textheight
      \fi
      \ltxdoc@cfg@document
    }%
  %% End of code from original ltxdoc.cfg [2007/01/08 latex-tds: ltxdoc.cls configuration (HO)]  %%
  %% Place additional code here.  %%
  }

%</ltxdoc>
%    \end{macrocode}
%
% \fi
%
% \CheckSum{0}
%
% \CharacterTable
%  {Upper-case    \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
%   Lower-case    \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
%   Digits        \0\1\2\3\4\5\6\7\8\9
%   Exclamation   \!     Double quote  \"     Hash (number) \#
%   Dollar        \$     Percent       \%     Ampersand     \&
%   Acute accent  \'     Left paren    \(     Right paren   \)
%   Asterisk      \*     Plus          \+     Comma         \,
%   Minus         \-     Point         \.     Solidus       \/
%   Colon         \:     Semicolon     \;     Less than     \<
%   Equals        \=     Greater than  \>     Question mark \?
%   Commercial at \@     Left bracket  \[     Backslash    \\
%   Right bracket \]     Circumflex    \^     Underscore    \_
%   Grave accent  \`     Left brace    \{     Vertical bar  \|
%   Right brace   \}     Tilde         \~}
%
% \GetFileInfo{undolabl.drv}
%
% \begingroup
%   \def\x{\#,\$,\^,\_,\~,\ ,\&,\{,\},\%}%
%   \makeatletter
%   \@onelevel@sanitize\x
% \expandafter\endgroup
% \expandafter\DoNotIndex\expandafter{\x}
% \expandafter\DoNotIndex\expandafter{\string\ }
% \begingroup
%   \makeatletter
%     \lccode`9=32\relax
%     \lowercase{%^^A
%       \edef\x{\noexpand\DoNotIndex{\@backslashchar9}}%^^A
%     }%^^A
%   \expandafter\endgroup\x
% \DoNotIndex{\documentclass,\usepackage,\hfuzz,\small,\tt,\begin,\end}
% \DoNotIndex{\NeedsTeXFormat,\filedate,\fileversion,\DoNotIndex}
% \DoNotIndex{\def,\edef,\gdef,\divide,\advance,\multiply}
% \DoNotIndex{\",\-,\,,\\,\hskip,\H,\ldots,\indent,\noindent,\textbackslash}
% \DoNotIndex{\textbf,\textit,\textquotedblleft,\textquotedblright,\textsf,\texttt}
% \DoNotIndex{\ifthenelse,\and,\equal,\whiledo,\if,\ifx,\ifnum,\else,\fi}
% \DoNotIndex{\CodelineIndex,\EnableCrossrefs,\DisableCrossrefs}
% \DoNotIndex{\DocInput,\AltMacroFont}
% \DoNotIndex{\@ne,\tw@,\thr@@}
% \DoNotIndex{\newpage,\pagebreak,\newline,\linebreak,\nolinebreak}
% \DoNotIndex{\lipsum,\MessageBreak,\pageref,\protect}
% \DoNotIndex{\RecordChanges,\OnlyDescription,\ProvidesPackage}
% \DoNotIndex{\smallskip,\medskip,\bigskip,\space,\thinspace}
% \DoNotIndex{\item}
% \DoNotIndex{\plainTeX,\TeX,\LaTeX,\pdfLaTeX}
% \DoNotIndex{\holtxdoc,\hypdoc,\Oberdiek}
% \DoNotIndex{\makeatletter,\makeatother,\footnote,\section}
%
% \title{The \textsf{undolabl} package\footnote{This file%
%        has version number v1.0d, last%
%        revised 2010/07/15, documentation dated 2010/07/15.}}
% \author{H.-Martin M\"{u}nch\\
% (\texttt{Martin dot Muench at Uni-Bonn dot de})}
% \date{2010/07/15}
%
% \maketitle
%
% \begin{abstract}
%  This package allows to override existing labels,
%  especially automatically generated ones.
% \end{abstract}
%
% \noindent \textbf{WARNING}: Since version 1.0d [2010/07/15] the |\undonewlabel|
% command takes only one argument, \texttt{\textbackslash undonewlabel\{<\textit{label name}>\}},
% instead of two, \texttt{\textbackslash undonewlabel\{<\textit{label name}>\}\{\textbackslash on@line\}}.
% Packages or documents, which used older versions of the \textsf{undolabl} package, must be
% updated by removing the second argument of |\undonewlabel|, i.\,e. the |{\on@line}|.\\
%
% \noindent Note: The main code of this package was invented by\\
% \textbf{Ulrich Diez} (\texttt{eu\_angelion@web.de})\\
% and first published in the \Newsgroup{comp.text.tex} newsgroup at\\
% \texttt{Sun,~20~Apr~2008~16:39:26~+0200}, with subject:\\
% \texttt{Re:~How~to~undefine/overwrite~a~label?} (see e.\,g.\\
% \url{http://groups.google.de/group/comp.text.tex/msg/5ba8d4722e5cd326}).\\
% While Ulrich Diez neither wanted to create a package himself yet
% nor have one published under his name, he granted the
% publication of his code. Therefore: Thanks!
% I submitted this package to CTAN (after some updates of the
% documentation, mainly layout, typos and such things.)
%
% \bigskip
%
% \noindent Disclaimer for web links: The author is not responsible for any contents
% referred to in this work unless he has full knowledge of illegal contents.
% If any damage occurs by the use of information presented there, only the
% author of the respective pages might be liable, not the one who has referred
% to these pages.
%
% \bigskip

% \noindent Save per page about $200\unit{ml}$ water,
% $2\unit{g}$ CO$_{2}$ and $2\unit{g}$ wood:
% Therefore please print only if this is really necessary.
%
% \bigskip
%
% \pagebreak
%
% \tableofcontents
%
% \newpage
%
% \section{Introduction\label{sec:Introduction}}
%
% The package's name \texttt{undolabl} is an eight-letter
% abbreviation for the phrases ``undo'' and ``label''.\\
%
%  This package allows to override existing labels,
%  especially automatically generated ones.\\
%
% When an instance of the |\label|-macro occurs in the document\linebreak
% (e.\,g. |\label{foo}|), then a delayed |\write| (a write which is
% performed at shipout-time when the page-number is determined) to
% the |.aux| file is issued and you find in the |.aux| file something
% like:
% \begin{verbatim}
%  \newlabel{foo}{{<page-no>}{<sectional no>}{<probably something else>}}
% \end{verbatim}
% During the beginning of the next \LaTeX -run, the |.aux| file will be
% read and
% \begin{verbatim}
%  \newlabel{foo}{{<page-no>}{<sectional no>}{<probably something else>}}
% \end{verbatim}
% is expanded to
% \begin{verbatim}
%  \@newl@bel r{foo}{{<page-no>}{<sectional no>}{<probably something else>}}
% \end{verbatim}
% which in turn gets expanded to something like (pseudo code):
% \begin{verbatim}
% IF (macro \r@foo is already defined)
% THEN
%   - Issue an error-message,
%   - Make sure that the multiply-defined-labels-warning occurs
%     in the log-file
% ELSE
%  \def\r@foo{{<page-no>}{<sectional no>}{<probably something else>}}
% ENDIF
% \end{verbatim}%
%
% Referencing works as follows:\\
% |\ref{foo}| |->|
% \begin{description}
%   \item[-] expand |\r@foo|: |{<page-no>}{<sectional no>}{<probably something else>}|
%
%   \item[-] grab the second from the resulting arguments: |<sectional no>|
% \end{description}
% |\pageref{foo}| |->|
% \begin{description}
%   \item[-] expand |\r@foo|: |{<page-no>}{<sectional no>}{<probably something else>}|
%
%   \item[-] grab the first from the resulting arguments: |<page-no>|
% \end{description}
% Back to the |\label|-mechanism:
% \begin{description}
%   \item[-] At the beginning of the \LaTeX -run, all the |\r@<label>|-macros
%     get defined from reading the |.aux| file. The |\r@<label>|-macros
%     get used by the referencing-macros (|\ref|, |\pageref|...) during
%     the \LaTeX-run.
%
%   \item[-] During the \LaTeX -run, the |.aux| file gets rewritten.
%
%   \item[-] At the end of the \LaTeX -run, the |.aux| file (which was
%     rewritten/newly created during the \LaTeX -run) is read in order
%     to detect whether references have changed during the current
%     \LaTeX -run.
% \end{description}
% But this time |\@newl@bel| is redefined (|\let equal to \@testdef|)
% and thus this time\\
% \begin{verbatim}
% \@newl@bel r{foo}{{<page-no>}{<sectional no>}{<probably something else>}}
% \end{verbatim}
% expands to something like (pseudo code):
% \begin{verbatim}
%   Compare the (newly written) third argument (that is:
%   {{<page-no>}{<sectional no>}{<probably something else>}} )
%   to the (current/former) definition of \r@foo.
%   If the two are different, then some page- or section-number
%   related to referencing has changed from the last to the current
%   LaTeX-run, thus in this case issue a message in the log-file:
%   "References may have changed. Rerun LaTeX in order to get
%   cross-references right".
% \end{verbatim}
% So what do you need to do in order to override a label:
% \begin{description}
%   \item[-] First you need to write to the |.aux| file to silently undefine
%     the associated |\r@<label>|-macro if it is already defined.
%     That is why |\overridelabel| writes in terms of |\protected@write|
%     to the |.aux| file:
%     \begin{verbatim}
%       \undonewlabel{<label>}
%     \end{verbatim}
%     |\undonewlabel| \textquotedblleft undefines\textquotedblright\ the
%     |\r@<label>|-macro. (How this works will be explained below.)
%
%   \item[-] Then |\overridelabel| can call |\label{<label>}| again
%     and thus produce another |\newlabel{<label>}|-entry to the
%     |.aux| file.
% \end{description}
% In the |.aux| file all this results in a sequence like:
% \begin{verbatim}
%   % from the former \label-call:
%   \newlabel{<label>}{..}
%   |->| \r@<label>-macro gets produced.
%   % from the \overrridelabel-call:
%   % - call to \undonewlabel within \overrridelabel:
%   \undonewlabel{<label>}
%   |->| \r@<label>-macro gets destroyed.
%   % - call to \label within \overrridelabel:
%   \newlabel{<label>}{..}
%   |->| a new \r@<label>-macro but no multiply-label-defined warning
%   gets produced.
% \end{verbatim}
%
% There is another issue left:
% \begin{description}
%   \item[-] It was said that |.aux| file is read at the beginning and at the
%     end of the \LaTeX-run for detecting whether references have changed.
%
%   \item[-] When overriding a |<label>|, there will be several
%     |\newlabel{<label>}|-calls associated to the same label-name in
%     the |.aux| file.
%
%   \item[-] At the beginning of the \LaTeX -run only the last one counts for
%     defining the associated |\r@<label>|-macro.
%
%   \item[-] But at the end, when the new |.aux| file is read, they all count
%     and thus with all these entries but the last one, the
%     above-mentioned |\@testdef|-comparison will yield difference and thus
%     in any case cause a warning-message about references having
%     changed although that might not be a correct statement.
% \end{description}
%
% Ulrich Diez decided to catch this up by his |\undolabl@testdef| command.
% The |\undolabl@testdef|-comparison-mechanism gets enhanced via
% \textquotedblleft replacing\textquotedblright . This works as follows:
% When |.aux| file is read at the beginning of the \LaTeX -run, |\@newl@bel| is
% \underline{not} let equal to |\@testdef|. When |.aux| file is read at the end
% of the \LaTeX -run, |\@newl@bel| \underline{is} let equal to |\@testdef|. Thus
% it is sufficient to write into the beginning of the |.aux| file a direction which
% leads to letting |\@newl@bel| equal to
% \nolinebreak{\textbackslash |my@testdef|} in case its
% definition equals |\@testdef|. That direction is called
% \nolinebreak{\textquotedblleft \textbackslash |reset@newl@bel|\textquotedblright .}
% Also, when the |.aux| file is read at the end of the \LaTeX -run,
% \nolinebreak{\textbackslash |undonwelabel|}-entries therein should
% do nothing, thus
% \nolinebreak{\textbackslash |undonewlabel|} is let equal to |\@gobble|.
%
% \section{Usage}
%
% Load the package placing
% \begin{quote}
%   |\usepackage{undolabl}|
% \end{quote}
% \noindent in the preamble of your \LaTeXe\ source file.\\
%
% When an existing label shall be replaced by a new one, say\\
% |\overridelabel{<label name>}|\\
% (where |<label name>| is the name of the label to be replaced
% by the new one), instead of just |\label{<label name>}|,
% which would produce a\\
% |LaTeX Warning: Label `<label name>' multiply defined.|
%
% \section{Example}
%
%    \begin{macrocode}
%<*example>
\documentclass[british]{article}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\usepackage{undolabl}[2010/07/15]% v1.0d
%% There are no options for the undolabl package. %%
\usepackage{hyperref}[2010/06/18]% v6.81g; if you want to use nameref
\hypersetup{%
 extension=pdf,%
 plainpages=false,%
 pdfpagelabels=true,%
 hyperindex=false,%
 pdflang={en},%
 pdftitle={undolabl package example},%
 pdfauthor={Hans-Martin Muench, after Ulrich Dietz},%
 pdfsubject={Example for the undolabl package},%
 pdfkeywords={LaTeX, undolabl, Ulrich Dietz, Hans-Martin Muench},%
 pdfview=FitH,%
 pdfstartview=FitH,%
 pdfpagelayout=OneColumn,%
 bookmarksopen=true%
}
\makeatletter
%% Code from tcilatex.tex, Macros for Scientific Word and      %%
%% Scientific WorkPlace 5.5 <06 Oct 2005>                      %%
%% Copyright (C) 2005 Mackichan Software, Inc.                 %%
%% That macro file is NOT proprietary and may be freely copied %%
%% and distributed.                                            %%
  \def\unit#1{\mathord{\thinspace\rm #1}}%
%% End of code from tcilatex.tex                               %%
\makeatother
\listfiles
\begin{document}
\pagenumbering{arabic}
\section*{Example for undolabl}

This example demonstrates the use of package\newline
\textsf{undolabl}, v1.0d as of 2010/07/15 (HMM).\newline
For details please see the documentation!\newline

\noindent Save per page about $200\unit{ml}$~water,
$2\unit{g}$~CO$_{2}$ and $2\unit{g}$~wood:\newline
Therefore please print only if this is really necessary.\newline
I do NOT think, that it is necessary to print THIS file, really\newline
(at least not after this page)!

\bigskip

\section{Test}

text \label{testlabel}\\
page-reference: \pageref{testlabel}\\%% -> page 4
sectional-reference: \ref{testlabel}\\%% -> section 4
name-reference: \nameref{testlabel}%% -> Still another test

\newpage

\section{Another test}

text \overridelabel{testlabel}\\
page-reference: \pageref{testlabel}\\%% -> page 4
sectional-reference: \ref{testlabel}\\%% -> section 4
name-reference: \nameref{testlabel}%% -> Still another test

\newpage

\section{Yet another test}

text \overridelabel{testlabel}\\
page-reference: \pageref{testlabel}\\%% -> page 4
sectional-reference: \ref{testlabel}\\%% -> section 4
name-reference: \nameref{testlabel}%% -> Still another test

\newpage

\section{Still another test}

text \overridelabel{testlabel}\\
page-reference: \pageref{testlabel}\\%% -> page 4
sectional-reference: \ref{testlabel}\\%% -> section 4
name-reference: \nameref{testlabel}%% -> Still another test

\end{document}
%</example>
%    \end{macrocode}
%
% \bigskip
%
% \section{The implementation}
%
% For a somewhat longer description see section~\ref{sec:Introduction}.\\

% We start off by checking that we are loading into \LaTeXe\ and
% announcing the name and version of this package.\\
%
%    \begin{macrocode}
%<*package>
%    \end{macrocode}
%
%    \begin{macrocode}
\NeedsTeXFormat{LaTeX2e}[1994/06/01]
\ProvidesPackage{undolabl}[2010/07/15 v1.0d
  Overriding labels (HMM)]

%    \end{macrocode}
%
% \DescribeMacro{\overridelabel}
% In order to override a label, first you need to write to the
% |.aux| file to silently undefine the associated |\r@<label>|-macro
% if it is already defined. That is why |\overridelabel| writes in
% terms of |\protected@write| to the |.aux| file:
% |\undonewlabel{<label>}|,
% \textquotedblleft undefining\textquotedblright\ the |\r@<label>|-macro.
% And a message about this is given.
%
%    \begin{macrocode}
\newcommand\overridelabel[1]{%
  \@bsphack
  \protected@write\@auxout{}{\string\undonewlabel{#1}}%
  \@overriddenmessage s{#1}%
%    \end{macrocode}
%
% Then |\overridelabel| can call |\label{<label>}| again
% and thus produce another |\newlabel{<label>}|-entry to the
% |.aux| file.
%
%    \begin{macrocode}
  \label{#1}%
  \@esphack
  }

%    \end{macrocode}
%
% \DescribeMacro{\undonewlabel}
%
%    \begin{macrocode}
\newcommand\undonewlabel{\@und@newl@bel r}%

%    \end{macrocode}
%
% \DescribeMacro{\@und@newl@bel}
%
% If |\r@<label>| is undefined, give an error message:
%
%    \begin{macrocode}
\newcommand\@und@newl@bel[2]{%
  \@ifundefined{#1@#2}{%
    \PackageError{undolabl}{Label `#2' shall be overridden ^^J
      although it does not yet exist}{%
      A label which does not exist cannot be overridden.}%
  }{%
%    \end{macrocode}
%
% \noindent otherwise:\\
% Undefine |\r@label| via letting it equal to |\relax|:
%
%    \begin{macrocode}
    \expandafter\global
    \expandafter\let
    \csname #1@#2\endcsname\relax
    }%
  }

%    \end{macrocode}
%
% \DescribeMacro{\@overriddenmessage}
%
% Command for the notification of overriding a label:
%
%    \begin{macrocode}
\newcommand\@overriddenmessage[2]{%
  \@ifundefined{#1@#2}{\global\@namedef{#1@#2}{i}}{%
    \expandafter\g@addto@macro\csname #1@#2\endcsname{i}%
    }%
  \PackageWarning{undolabl}{Label `#2' overridden}
  }

%    \end{macrocode}
%
% \DescribeMacro{\undolabl@testdef}
%
%    \begin{macrocode}
\newcommand\undolabl@testdef[3]{%
  \@ifundefined{s@#2}\@secondoftwo\@firstofone{%
    \expandafter\ifx\csname s@#2\endcsname\empty
      \expandafter\@firstofone
    \else
    \expandafter\xdef\csname s@#2\endcsname{%
      \expandafter\expandafter
      \expandafter\@gobble
      \csname s@#2\endcsname
      }%
    \expandafter\@gobble
    \fi
    }%
    {%
    \@testdef{#1}{#2}{#3}%
    }%
  }%

%    \end{macrocode}
%
% \DescribeMacro{\protected@write\\@auxout}
%
%    \begin{macrocode}
\protected@write\@auxout{}{\string\reset@newl@bel}%

%    \end{macrocode}
%
% \DescribeMacro{\reset@newl@bel}
%
%    \begin{macrocode}
\newcommand\reset@newl@bel{%
  \ifx\@newl@bel\@testdef
    \let\@newl@bel\undolabl@testdef
    \let\undonewlabel\@gobble
  \fi
  }%
%    \end{macrocode}
%
%    \begin{macrocode}
%</package>
%    \end{macrocode}
%
% \pagebreak
%
% \section{Installation}
%
% \subsection{Downloads}
%
% Everything should be available on \CTAN{}, \url{ftp://ftp.ctan.org/tex-archive/},
% but may need additional packages themselves.\\
%
% \DescribeMacro{undolabl.dtx}
% For unpacking the |undolabl.dtx| file and constructing the documentation it is required:
% \begin{description}
% \item[-] \TeX Format \LaTeXe, 1994/06/01, v2$\varepsilon $: \CTAN{}
%
% \item[-] document class \textsf{ltxdoc}, 2007/11/11, v2.0u,\\
%           \CTAN{macros/latex/base/ltxdoc.dtx}
%
% \item[-] package \textsf{holtxdoc}, 2010/04/18, v0.18,\\
%           \CTAN{macros/latex/contrib/oberdiek/holtxdoc.dtx}
%
% \item[-] package \textsf{hypdoc}, 2010/03/26, v1.9,\\
%           \CTAN{macros/latex/contrib/oberdiek/hypdoc.dtx}
% \end{description}
%
% \DescribeMacro{undolabl.sty}
% The |undolabl.sty| for \LaTeXe\ (i.\,e. all documents using
% the \textsf{undolabl} package) requires:
% \begin{description}
% \item[-] \TeX Format \LaTeXe, 1994/06/01, v2$\varepsilon $, \CTAN{}
% \end{description}
%
% \DescribeMacro{undolabl-example.tex}
% The |undolabl-example.tex| requires the same files as all
% documents using the \textsf{undolabl} package, and additionally:
% \begin{description}
% \item[-] class \textsf{article}, 2007/10/19, v1.4h, from \textsf{classes.dtx}:\\
%           \CTAN{macros/latex/base/classes.dtx}
%
%  \item[-] package \textsf{hyperref}, 2010/06/18, v6.81g,\\
%            \CTAN{macros/latex/contrib/hyperref/},\\
%            if |nameref| shall be used\\
%            (and when the references shall be hyperlinked, of course)
%
% \item[-] package \textsf{undolabl}, 2010/07/15, v1.0d,\\
%           \CTAN{macros/latex/contrib/undolabl/undolabl.dtx}\\
%   (Well, it is the example file for this package, and because you are reading the
%    documentation for the \textsf{undolabl} package, it can be assumed that you already
%    have some version of it -- is it the current one?)
% \end{description}
%
% \DescribeMacro{Oberdiek}
% \DescribeMacro{holtxdoc}
% \DescribeMacro{hypdoc}
% All packages of Heiko Oberdiek's bundle `oberdiek'
% (especially \textsf{holtxdoc} and \textsf{hypdoc})
% are also available in a TDS compliant ZIP archive:\\
% \CTAN{install/macros/latex/contrib/oberdiek.tds.zip}.\\
% \textbf{Warning}: holtxdoc, 2010/04/24 v0.19, requires the packages
% \begin{description}
% \item[-] hypdoc, 2010/03/26, v1.9
% \item[-] hyperref, 2010/03/30, v6.80u (latest: 2010/06/18, v6.81g)
% \item[-] pdftexcmds, 2010/04/01, v0.9
% \item[-] ltxcmds, 2010/03/09, v1.4 (latest: 2010/04/26, v1.7)
% \item[-] hologo, 2010/04/24, v1.2
% \item[-] array (latest: 2008/09/09, v2.4c)
% \end{description}
% (or more recent versions) and does neither work with
% nor check for earlier versions!\\
% (It is probably best to download\\
% \CTAN{install/macros/latex/contrib/oberdiek.tds.zip}
% and use this, because the packages in there should be both
% recent and compatible.)\\
%
% \pagebreak
%
% \DescribeMacro{M\"{u}nch}
% Packages of mine:\\
% \begin{description}
% \item[undolabl] 2010/07/15, v1.0d, \CTAN{macros/latex/contrib/undolabl.dtx}\\
%  The package described in this very documentation.\\
%  (Code initally by Ulrich Dietz on \Newsgroup{comp.text.tex} at\\
%   \texttt{Mon,~21~Apr~2008~23:04:03~+0200}, see e.\,g.\\
%   \url{http://groups.google.de/group/comp.text.tex/msg/af6cfe93917097da}.)
%
% \item[pagesLTS] 2010/07/15, v1.1d, \CTAN{macros/latex/contrib/pagesLTS.dtx}\\
%  That package allows to refer to the (very) last page, gives the total number of
%  pages, references to special pages, facilitates the use of nearly any pagenumbering
%  you like (e.\,g. negative |Roman| numbers or more than |Z| pages with |Alph| page numbering),
%  and works even with |fnsymbol| page numbers.
%
% \item[papermas] 2010/06/24, v1.0c, \CTAN{macros/latex/contrib/papermas.dtx}\\
%  That package allows to compute the number of sheets of paper needed to
%  print a document as well as the mass of that printed version of the document.
%  Further that package allows to compute \textquotedblleft base to the power of
%  exponent\textquotedblright\ inside \LaTeX.
%
% \item[hrefhide] 2010/06/24, v1.0c, \CTAN{macros/latex/contrib/hrefhide.dtx}\\
%  That package allows to \textquotedblleft hide\textquotedblright\ some (hyperlinked)
%  text when printing the document while keeping the layout.
% \end{description}
%
% \subsection{Package, unpacking TDS}
%
% \paragraph{Package.} This package is available on \CTAN{}:
% \begin{description}
% \item[\CTAN{macros/latex/contrib/undolabl/undolabl.dtx}]\hspace*{0.1cm} \\
%           The source file.
% \item[\CTAN{macros/latex/contrib/undolabl/undolabl.ins}]\hspace*{0.1cm} \\
%           The installation file.
% \item[\CTAN{macros/latex/contrib/undolabl/undolabl.drv}]\hspace*{0.1cm} \\
%           The driver to generate the documentation.
% \item[\CTAN{macros/latex/contrib/undolabl/ltxdoc.cfg}]\hspace*{0.1cm} \\
%           The \LaTeX documentation configuration file, also for generating the documentation.
% \item[\CTAN{macros/latex/contrib/undolabl/undolabl.pdf}]\hspace*{0.1cm} \\
%           The documentation.
% \item[\CTAN{macros/latex/contrib/undolabl/undolabl.sty}]\hspace*{0.1cm} \\
%           The \xfile{sty}le file.
% \item[\CTAN{macros/latex/contrib/undolabl/undolabl-example.tex}]\hspace*{0.1cm} \\
%           The example file.
% \item[\CTAN{macros/latex/contrib/undolabl/undolabl-example.pdf}]\hspace*{0.1cm} \\
%           The compiled example file, as it should look like.
% \item[\CTAN{install/macros/latex/contrib/undolabl.tds.zip}]\hspace*{0.1cm} \\
%       Everything in TDS compliant, compiled format.
% \end{description}
%
% For required other packages, see the preceding subsection.
%
% \paragraph{Unpacking.} The \xext{dtx} file is a self-extracting
% \docstrip\ archive. The files are extracted by running the
% \xext{dtx} through \plainTeX:
% \begin{quote}
%   \verb|tex undolabl.dtx|
% \end{quote}
%
% About generating the documentation see paragraph~\ref{GenDoc} below.\\
%
% \paragraph{TDS.} Now the different files must be moved into
% the different directories in your installation TDS tree
% (also known as \xfile{texmf} tree):
% \begin{quote}
% \def\t{^^A
% \begin{tabular}{@{}>{\ttfamily}l@{ $\rightarrow$ }>{\ttfamily}l@{}}
%   undolabl.sty & tex/latex/muench/undolabl.sty\\
%   undolabl.pdf & doc/latex/muench/undolabl.pdf\\
%   undolabl-example.tex & doc/latex/muench/undolabl-example.tex\\
%   undolabl-example.pdf & doc/latex/muench/undolabl-example.pdf\\
%   undolabl.dtx & source/latex/muench/undolabl.dtx\\
% \end{tabular}^^A
% }^^A
% \sbox0{\t}^^A
% \ifdim\wd0>\linewidth
%   \begingroup
%     \advance\linewidth by\leftmargin
%     \advance\linewidth by\rightmargin
%   \edef\x{\endgroup
%     \def\noexpand\lw{\the\linewidth}^^A
%   }\x
%   \def\lwbox{^^A
%     \leavevmode
%     \hbox to \linewidth{^^A
%       \kern-\leftmargin\relax
%       \hss
%       \usebox0
%       \hss
%       \kern-\rightmargin\relax
%     }^^A
%   }^^A
%   \ifdim\wd0>\lw
%     \sbox0{\small\t}^^A
%     \ifdim\wd0>\linewidth
%       \ifdim\wd0>\lw
%         \sbox0{\footnotesize\t}^^A
%         \ifdim\wd0>\linewidth
%           \ifdim\wd0>\lw
%             \sbox0{\scriptsize\t}^^A
%             \ifdim\wd0>\linewidth
%               \ifdim\wd0>\lw
%                 \sbox0{\tiny\t}^^A
%                 \ifdim\wd0>\linewidth
%                   \lwbox
%                 \else
%                   \usebox0
%                 \fi
%               \else
%                 \lwbox
%               \fi
%             \else
%               \usebox0
%             \fi
%           \else
%             \lwbox
%           \fi
%         \else
%           \usebox0
%         \fi
%       \else
%         \lwbox
%       \fi
%     \else
%       \usebox0
%     \fi
%   \else
%     \lwbox
%   \fi
% \else
%   \usebox0
% \fi
% \end{quote}
% If you have a \xfile{docstrip.cfg} that configures and enables \docstrip's
% TDS installing feature, then some files can already be in the right
% place, see the documentation of \docstrip.
%
% \subsection{Refresh file name databases}
%
% If your \TeX~distribution (\teTeX, \mikTeX,\dots) relies on file name
% databases, you must refresh these. For example, \teTeX\ users run
% \verb|texhash| or \verb|mktexlsr|.
%
% \subsection{Some details for the interested}
%
% \paragraph{Unpacking with \LaTeX.}
% The \xext{dtx} chooses its action depending on the format:
% \begin{description}
% \item[\plainTeX:] Run \docstrip\ and extract the files.
% \item[\LaTeX:] Generate the documentation.
% \end{description}
% If you insist on using \LaTeX\ for \docstrip\ (really,
% \docstrip\ does not need \LaTeX), then inform the autodetect routine
% about your intention:
% \begin{quote}
%   \verb|latex \let\install=y\input{undolabl.dtx}|
% \end{quote}
% Do not forget to quote the argument according to the demands
% of your shell.
%
% \paragraph{Generating the documentation.\label{GenDoc}}
% You can use both the \xext{dtx} or the \xext{drv} to generate
% the documentation. The process can be configured by the
% configuration file \xfile{ltxdoc.cfg}. For instance, put the following
% line into this file, if you want to have A4 as paper format:
% \begin{quote}
%   \verb|\PassOptionsToClass{a4paper}{article}|
% \end{quote}
%
% \noindent An example follows how to generate the
% documentation with \pdfLaTeX :
%
% \begin{quote}
%\begin{verbatim}
%pdflatex undolabl.dtx
%makeindex -s gind.ist undolabl.idx
%pdflatex undolabl.dtx
%makeindex -s gind.ist undolabl.idx
%pdflatex undolabl.dtx
%\end{verbatim}
% \end{quote}
%
% \noindent and with \pdfLaTeX:
% \begin{quote}
%\begin{verbatim}
%pdflatex undolabl.dtx
%makeindex -s gind.ist undolabl.idx
%pdflatex undolabl.dtx
%makeindex -s gind.ist undolabl.idx
%pdflatex undolabl.dtx
%\end{verbatim}
% \end{quote}
%
% \pagebreak
%
% \section{Acknowledgements}
%
% The main code of this package was invented by \textbf{Ulrich Diez}
% (\texttt{eu\_angelion@web.de}) and first published in the \Newsgroup{comp.text.tex}
% newsgroup at\\
% \texttt{Sun,~20~Apr~2008~16:39:26~+0200}, with subject:\\
% \texttt{Re:~How~to~undefine/overwrite~a~label?} (see e.\,g.\\
% \url{http://groups.google.de/group/comp.text.tex/msg/5ba8d4722e5cd326}).\\
% I (H.-Martin M\"{u}nch) would like to thank Ulrich Diez for this as well as
% for his permission to publish it on \CTAN{}.
% I also thank those anonymouse people who had published it somewhere else
% on the internet, where I found it first.
% Further I would like to thank Heiko Oberdiek
% (\texttt{heiko dot oberdiek at googlemail dot com}) for providing
% a~lot~(!) of useful packages (from which I also got everything I
% know about creating a file in \xfile{dtx} format, ok, say it: copying),
% and the \Newsgroup{comp.text.tex} and \Newsgroup{de.comp.text.tex}
% newsgroups for their help in all things \TeX.
%
% \smallskip
%
% \phantomsection
% \begin{History}\label{History}
%   \begin{Version}{2008/04/20 v0.3}
%   \item created by Ulrich Diez
%   \end{Version}
%   \begin{Version}{2010/04/08  v0.3b}
%   \item |.dtx| updated by H.-Martin M\"{u}nch, submitted to \CTAN{}\\
%     (no changes in the style code).
%   \end{Version}
%   \begin{Version}{2010/06/01 v1.0}
%   \item \xfile{.dtx} updated by H.-Martin M\"{u}nch: some minor
%     corrections in the documentation, an internal renaming for possible
%     better compatibility with other packages.
%   \item The main code of this package was invented in 2008 by Ulrich Diez
%     (\texttt{eu\_angelion@web.de}) and published on the internet.
%     Because Ulrich Diez neither wanted to create a package himself yet
%     nor have one published under his name,
%     but granted the publication of his code (Thanks!),
%     I had to change author/maintainer of this package and resubmit it.
%   \end{Version}
%   \begin{Version}{2010/06/03 v1.0b}
%   \item Found an unchanged reference to the package author/maintainer.
%   \item Example adapted to other examples of mine.
%   \item Updated references to other packages.
%   \item TDS locations updated.
%   \item Several changes in the documentation and the Readme file.
%   \end{Version}
%   \begin{Version}{2010/06/24 v1.0c}
%     \item \textsf{holtxdoc} warning in \xfile{drv} updated.
%     \item Corrected the location of the package at CTAN. (TDS still missing due to packaging error.)
%     \item Updated references to other packages: \textsf{hyperref} and \textsf{pagesLTS}.
%     \item Added a list of my other packages.
%   \end{Version}
%   \begin{Version}{2010/07/15 v1.0d}
%     \item There was another update by Ulrich Dietz on \Newsgroup{comp.text.tex} at
%            \texttt{Mon,~21~Apr~2008~23:04:03~+0200}, see e.\,g.\\
%            \url{http://groups.google.de/group/comp.text.tex/msg/af6cfe93917097da},\\
%            which was now included in this package.
%     \item Put more emphasis on \textbf{Ulrich Dietz} writing the initial code.
%     \item Updated references to other packages: \textsf{hyperref} and \textsf{pagesLTS}.
%     \item Corrected the given location of the \textsf{undolabl.tds.zip} file at CTAN.
%   \end{Version}
% \end{History}
%
% % \PrintChanges
%
% \bigskip
%
% When you find a mistake or have a suggestion for an improvement of this package,
% please send an e-mail to the maintainer, thanks! (Please see BUG REPORTS in the README.)
%
% \bigskip
%
% \PrintIndex
%
% \Finale
\endinput