summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/tools
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2006-01-11 23:58:32 +0000
committerKarl Berry <karl@freefriends.org>2006-01-11 23:58:32 +0000
commit8eb89f2adefbbdc3005c34350665a94992d4b300 (patch)
tree80bb4be1dd47d7481bf4e8d94309477ec3cf22d2 /Master/texmf-dist/source/latex/tools
parent173c95c204f01e6bb18cc852925c9a1cef535740 (diff)
trunk/Master/texmf-dist/source/latex/tools
git-svn-id: svn://tug.org/texlive/trunk@559 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/latex/tools')
-rw-r--r--Master/texmf-dist/source/latex/tools/afterpage.dtx384
-rw-r--r--Master/texmf-dist/source/latex/tools/array.dtx2820
-rw-r--r--Master/texmf-dist/source/latex/tools/bm.dtx1636
-rw-r--r--Master/texmf-dist/source/latex/tools/calc.dtx950
-rw-r--r--Master/texmf-dist/source/latex/tools/dcolumn.dtx360
-rw-r--r--Master/texmf-dist/source/latex/tools/delarray.dtx205
-rw-r--r--Master/texmf-dist/source/latex/tools/enumerate.dtx335
-rw-r--r--Master/texmf-dist/source/latex/tools/fileerr.dtx137
-rw-r--r--Master/texmf-dist/source/latex/tools/fontsmpl.dtx352
-rw-r--r--Master/texmf-dist/source/latex/tools/ftnright.dtx995
-rw-r--r--Master/texmf-dist/source/latex/tools/hhline.dtx321
-rw-r--r--Master/texmf-dist/source/latex/tools/indentfirst.dtx75
-rw-r--r--Master/texmf-dist/source/latex/tools/layout.dtx1024
-rw-r--r--Master/texmf-dist/source/latex/tools/longtable.dtx2146
-rw-r--r--Master/texmf-dist/source/latex/tools/multicol.dtx3472
-rw-r--r--Master/texmf-dist/source/latex/tools/rawfonts.dtx218
-rw-r--r--Master/texmf-dist/source/latex/tools/showkeys.dtx796
-rw-r--r--Master/texmf-dist/source/latex/tools/somedefs.dtx171
-rw-r--r--Master/texmf-dist/source/latex/tools/tabularx.dtx896
-rw-r--r--Master/texmf-dist/source/latex/tools/theorem.dtx1163
-rw-r--r--Master/texmf-dist/source/latex/tools/tools.ins208
-rw-r--r--Master/texmf-dist/source/latex/tools/trace.dtx708
-rw-r--r--Master/texmf-dist/source/latex/tools/varioref.dtx1903
-rw-r--r--Master/texmf-dist/source/latex/tools/verbatim.dtx1881
-rw-r--r--Master/texmf-dist/source/latex/tools/xr.dtx172
-rw-r--r--Master/texmf-dist/source/latex/tools/xspace.dtx144
26 files changed, 23472 insertions, 0 deletions
diff --git a/Master/texmf-dist/source/latex/tools/afterpage.dtx b/Master/texmf-dist/source/latex/tools/afterpage.dtx
new file mode 100644
index 00000000000..4c4d67b8c60
--- /dev/null
+++ b/Master/texmf-dist/source/latex/tools/afterpage.dtx
@@ -0,0 +1,384 @@
+% \iffalse meta-comment
+%
+% Copyright 1993 1994 1995 1996 1997 1998 1999 2000 2001 2002 2003
+% The LaTeX3 Project and any individual authors listed elsewhere
+% in this file.
+%
+% This file is part of the Standard LaTeX `Tools Bundle'.
+% -------------------------------------------------------
+%
+% It 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.3 or later is part of all distributions of LaTeX
+% version 2003/12/01 or later.
+%
+% The list of all files belonging to the LaTeX `Tools Bundle' is
+% given in the file `manifest.txt'.
+%
+% \fi
+% \iffalse
+%% File: afterpage.dtx Copyright (C) 1994 1994 1995 David Carlisle
+%
+%<package>\NeedsTeXFormat{LaTeX2e}
+%<package>\ProvidesPackage{afterpage}
+%<package> [1995/10/27 v1.08 After-Page Package (DPC)]
+%
+%<*driver>
+\documentclass{ltxdoc}
+\usepackage{afterpage}
+\GetFileInfo{afterpage.sty}
+\begin{document}
+\title{The \textsf{afterpage} package\thanks{This file
+ has version number \fileversion, last
+ revised \filedate.}}
+\author{David Carlisle\\carlisle@cs.man.ac.uk}
+\date{\filedate}
+\maketitle
+\DocInput{afterpage.dtx}
+\end{document}
+%</driver>
+% \fi
+%
+% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%
+% \changes{v1.00}{1993/01/25}{Initial version}
+% \changes{v1.05}{1993/07/14}{First public version}
+% \changes{v1.06}{1994/02/01}{Update for LaTeX2e}
+% \changes{v1.07}{1994/05/23}{Documentation Changes}
+% \changes{v1.08}{1995/10/27}
+% {Use \cs{par} not \cs{endgraf}, for tools/1579}
+% \changes{v1.08}{1995/10/27}
+% {Try and do something sensible with nested \cs{clearpage},
+% for tools/1880}
+% \changes{v1.08}{1995/10/27}
+% {Try and do something sensible with footnotes, for tools/1884}
+%
+% \CheckSum{269}
+%
+% This package implements a command, |\afterpage|, that causes the
+% commands specified in its argument to be expanded after the curent
+% page is output.\footnote{This is really a pre-release, to see whether
+% people like the idea of a command like this. This implementation is
+% \emph{not} particularly robust. This implementation does not work in
+% two column mode, and can get `confused' by \LaTeX's floating
+% environments.}
+%
+% \begin{enumerate}
+% \item Sometimes \LaTeX's float positioning mechanism gets overloaded,
+% and all floating |figure|s and |table|s drift to the end of the
+% document. One may flush out all the unprocessed floats by issuing a
+% |\clearpage| command, but this has the effect of making the current
+% page end prematurely. Now you can issue |\afterpage{\clearpage}| and
+% the current page will be filled up with text as usual, but then a
+% |\clearpage| command will flush out all the floats before the next
+% text page begins.
+% \item An earlier mechanism to help with float placement was the
+% optional argument |[H]| (meaning {\bf HERE!}) which was originally
+% added to the standard floating environments by |here.sty|, and is now
+% provided by |float.sty|. However some |[H]| users have commented that
+% they did not really mean `Here!' They actually wanted `Somewhere
+% close'. This can now be achieved by\\
+% |\afterpage{\clearpage\begin{figure}[H] |\ldots
+% |\end{figure}}|\\
+% This ensures that the figure is at the top of the next page. (The
+% |\clearpage| stops any other figures drifting past the |[H]| figure.)
+% \item Floating longtables. |longtable.sty| provides the |longtable|
+% environment, a multi-page version of |tabular|. Many |longtable| users
+% have told me that it is difficult to set the text surrounding the long
+% table, and that they wanted a `floating' version. As, presumably,
+% |longtable|s are long, they are probably too large to hold in memory,
+% and float in the way that the |table| environment is floated, however
+% if the table is in a separate file, say |ltfile.tex|, you can now
+% use one of:\\
+% |\afterpage{\clearpage\input{ltfile}}|\\
+% |\afterpage{\clearpage\input{ltfile}\clearpage}|.\\
+% The first form lets text apear on the same page as the end of the
+% longtable, the second ensures that the surrounding text starts again
+% on a new page.
+% \end{enumerate}
+%
+% \StopEventually{}
+%
+% \begin{macrocode}
+%<*package>
+% \end{macrocode}
+%
+% \begin{macro}{\afterpage}
+% The token register used to save the old output routine.
+% \begin{macrocode}
+\newtoks\AP@output
+\global\AP@output\expandafter{\the\output}
+% \end{macrocode}
+%
+% A box register used to save any part of the next page which has
+% already been processed.
+% \begin{macrocode}
+\newbox\AP@partial
+% \end{macrocode}
+%
+% A box register used to save any footnote texts that are `tied' to
+% the text that gets saved in |\AP@partial|.
+% \begin{macrocode}
+\newbox\AP@footins
+% \end{macrocode}
+%
+% The following macro attempts to get safely into vertical mode, and
+% then invokes a special output routine to grab the current page into
+% |\AP@partial|.
+% \begin{macrocode}
+\def\AP@savetop{%
+% \end{macrocode}
+% Now begins a test to see what state we are in. |\AP@noindent| will
+% be defined so as to return to this state (well, almost!) after
+% afterpage has finished.
+% \begin{macrocode}
+ \ifvmode
+% \end{macrocode}
+% Vertical mode. This is the simplest case, do nothing.
+% \begin{macrocode}
+ \let\AP@noindent\empty
+ \else\ifhmode
+% \end{macrocode}
+% Horizontal mode.
+% `Back out' into vertical mode, removing the indentation box as we go.
+% If in fact there was no indentation box, the output routine was
+% invoked by |\noindent| (what bad luck!) so we have to remember to
+% re-insert the |\noindent| before the paragraph is seen again.
+% |\everypar| tokens have already been inserted, so don't insert them
+% again.
+% \begin{macrocode}
+ \setbox\z@\lastbox
+ \edef\AP@noindent
+ {{\everypar{}\ifvoid\z@\noindent\else\indent\fi}}%
+ \par
+ \else
+% \end{macrocode}
+% The remaining (even worse) possibility that the ouput routine
+% was triggered by the start of displaymath within a paragraph.
+%
+% Come out of displaymath with |$$|, then adjust the spacing (getting
+% into vmode at the same time). |\AP@noindent| will restart display math
+% later. |\everydisplay| tokens have already been inserted (they apply
+% to the math list that will be started by |\AP@noindent|, even though
+% they were triggered by the display math that was closed by the lines
+% below!). Save the values |\prevgraf| and |\predisplaysize| for use in
+% the re-started math list.
+% \begin{macrocode}
+ \abovedisplayshortskip\z@\abovedisplayskip\z@
+ \belowdisplayshortskip\z@\belowdisplayskip\z@
+ \xdef\AP@disp{%
+ \predisplaysize\the\predisplaysize
+ \prevgraf\the\prevgraf\relax}%
+ $$\vskip-\baselineskip\vskip-\parskip
+ \edef\AP@noindent{%
+% \end{macrocode}
+% Do not insert |\everydisplay| tokens again.
+% \begin{macrocode}
+ \toks@{\the\everydisplay}\everydisplay{}%
+% \end{macrocode}
+% Start displaymath mode with no spurious paragraph line above it.
+% Restore |\prevgraf| and |\predisplaysize|. Use |\aftergroup| to
+% restore the correct setting for |\everydisplay| after this display
+% has finished.
+% \begin{macrocode}
+ {\everypar{}\noindent}$$\AP@disp\aftergroup\noexpand\AP@ed}%
+ \fi\fi
+% \end{macrocode}
+% Now switch the output routine and remove everything from the current
+% page into the box |\AP@partial|.
+% \begin{macrocode}
+ \begingroup
+ \nointerlineskip\null
+ \output{%
+ \global\setbox\AP@partial\vbox{%
+ \unvbox\@cclv
+ \global\setbox\@ne\lastbox}%
+% \end{macrocode}
+% If the text that is saved in |\AP@partial| had footnotes, we'd
+% better grab them as well otherwise they may come out on a page
+% with the `afterpage' text, before the page that has the
+% footnote mark! (Added at v1.08.)
+% \begin{macrocode}
+ \global\setbox\AP@footins\box\footins}%
+% \end{macrocode}
+% Having defined the output routine, trigger it\ldots
+% \begin{macrocode}
+ \eject
+ \endgroup}
+% \end{macrocode}
+%
+% |\AP@| stores all the commands that must be executed after the page
+% break.
+% \begin{macrocode}
+\let\AP@\relax
+% \end{macrocode}
+%
+% Restore the |\everydisplay| register. |\ignorespaces| prevents a space
+% or newline after |$$| creating rogue a indentation or paragraph.
+% \begin{macrocode}
+\def\AP@ed{\everydisplay\expandafter{\the\toks@}\ignorespaces}
+% \end{macrocode}
+%
+% Remove the current vertical list, insert the commands |\AP@|
+% at the top of the page, and then re-insert the saved text.
+% \begin{macrocode}
+\def\AP@@{%
+ \AP@savetop
+ \global\expandafter\let\expandafter\AP@\expandafter\relax\AP@
+ \par
+% \end{macrocode}
+% The text originally at the top of this page is now stored in the box
+% |\AP@partial|, including |\topskip| glue. Now we want to unbox
+% |\AP@partial|, placing the baseline of the first row |\baselineskip|
+% below the baseline of the last line coming from the afterpage text.
+% If we assumed nothing has too much height or depth (and |\topskip| is
+% rigid), it would be fairly trivial to position the contents of
+% |\AP@partial| so that the baseline of the first row was
+% |\baselineskip| below the last row just added.
+%
+% In this version, I thought it might be fun to try to exactly achieve
+% the |\baselineskip|--or--|\lineskip| calculation that \TeX\ normally
+% does internally. The call to |\addboxcontents| does the right thing
+% (I hope).
+% \begin{macrocode}
+ \addboxcontents\AP@partial
+% \end{macrocode}
+% Now re-insert any footnote text. This may not be quite the right
+% place, as the text that has just been unboxed may break over a page
+% in its new position. Also it may not be the right number if the text
+% from |\afterpage| itself contains footnotes. Too bad!
+% \begin{macrocode}
+ \ifvoid\AP@footins\else
+ \insert\footins{\unvbox\AP@footins}\fi
+% \end{macrocode}
+% Now repair things if we started off in horizontal mode.
+% \begin{macrocode}
+ \AP@noindent}
+% \end{macrocode}
+%
+% If |\AP@| is not |\relax| then the current page already has some
+% `afterpage' commands, so just add the new commands to the end of the
+% list. Otherwise save the commands in |\AP@|. (within a local group),
+% and switch the output routine. (The new output routine just calls the
+% old one if it is invoked by a \LaTeX{} float.
+% \begin{macrocode}
+\long\def\afterpage#1{%
+ \ifx\AP@\relax
+ \gdef\AP@{{#1\par}}%
+ \global\output{%
+ \the\AP@output
+ \ifnum\outputpenalty>-\@Mi
+ \global\output\expandafter{\the\AP@output}%
+ \aftergroup\AP@@
+ \fi}%
+ \else
+ \expandafter\gdef\expandafter\AP@\expandafter{\AP@{#1\par}}%
+ \fi}
+% \end{macrocode}
+%
+% If we have got to the end of the document or clearpage
+% just put the stuff out without any trickery.
+% \begin{macrocode}
+\let\AP@clearpage\clearpage
+\def\clearpage{%
+ \ifx\AP@\relax
+ \AP@clearpage
+ \else
+ \global\output\expandafter{\the\AP@output}%
+ \AP@clearpage
+% \end{macrocode}
+% At this point (since v1.08) Need to clear |\AP@| \emph{before}
+% using its expansion, as otherwise hit an infinite loop. Sigh.
+% \begin{macrocode}
+ \global\expandafter\let\expandafter\AP@\expandafter\relax
+ \expandafter\expandafter\AP@
+ \fi}
+\let\AP@enddocument\enddocument
+\def\enddocument{%
+ \ifx\AP@\relax\else
+ \global\output\expandafter{\the\AP@output}%
+ \AP@clearpage
+ \global\expandafter\let\expandafter\AP@\expandafter\relax
+ \expandafter\expandafter\AP@
+ \fi
+ \AP@enddocument}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\addboxcontents}
+% Given a vbox |#1|, add to the current vertical list such that the end
+% result is equivalent to the list that \TeX\ would have built had the
+% contents of |#1| (apart from any initial glue) been added individually
+% to the current list.
+
+% So essentially, the problem is that of unboxing |#1|, but replacing
+% the glue at the top of |#1| with (something equivalent to) the
+% |\baselineskip| or |\lineskip| glue that \TeX\ would normally have
+% placed before the first box in |#1|. Also |\prevdepth| must be set at
+% the end.
+% \begin{macrocode}
+\def\addboxcontents#1{{%
+% \end{macrocode}
+% Perhaps I shouldnt use grouping here, as I probably don't really want
+% to save |#1|. If it is removed, |\splittopskip| and |\splitmaxdepth|
+% would need to be restored by hand.
+%
+% First replace any glue at the top by |\vskip 0pt|.
+% \begin{macrocode}
+ \splittopskip\z@
+ \splitmaxdepth\maxdimen
+ \setbox#1\vbox{\break\unvbox#1}%
+ \setbox\z@\vsplit#1to\z@
+% \end{macrocode}
+% Put the breakpoint back.
+% \begin{macrocode}
+ \setbox#1\vbox{\break\unvbox#1}%
+% \end{macrocode}
+% Set |\skip@| to be height of |#1| (without top glue)
+% \begin{macrocode}
+ \skip@\ht#1%
+% \end{macrocode}
+% Now make the first baseline of the first row be |\vsize| from the top.
+% (This assumes that the first row has height less than |\vsize|.)
+% \begin{macrocode}
+ \splittopskip\vsize
+ \setbox\z@\vsplit#1to\z@
+% \end{macrocode}
+% Subtract the new height of |#1| from |\skip@|, and add back on
+% |\splittopskip|, so |\skip@| is now the height of the first row of
+% |#1| This may still be 0pt if (eg) a mark or whatsit is between the
+% top glue and the first box. Save (this height${}-{}$|\splittopskip|)
+% in |\skip\tw@|.
+% \begin{macrocode}
+ \advance\skip@-\ht#1%
+ \skip\tw@\skip@
+ \advance\skip@\splittopskip
+% \end{macrocode}
+% Now fake \TeX's |\baselineskip| calculation.
+% \begin{macrocode}
+ \advance\skip@\prevdepth
+ \advance\skip@-\baselineskip
+ \advance\skip\tw@\ifdim-\skip@<\lineskiplimit\lineskip\else-\skip@\fi
+% \end{macrocode}
+% Finally add the glue.
+% \begin{macrocode}
+ \vskip\skip\tw@
+% \end{macrocode}
+% Now unbox the box, setting |\prevdepth| by hand, as |\unvbox| (unlike
+% |\box|) does not automatically set it.
+% \begin{macrocode}
+ \global\dimen@i\dp#1%
+ \unvbox#1}%
+ \prevdepth\dimen@i}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macrocode}
+%</package>
+% \end{macrocode}
+%
+% \Finale
+%
diff --git a/Master/texmf-dist/source/latex/tools/array.dtx b/Master/texmf-dist/source/latex/tools/array.dtx
new file mode 100644
index 00000000000..b6641457103
--- /dev/null
+++ b/Master/texmf-dist/source/latex/tools/array.dtx
@@ -0,0 +1,2820 @@
+% \iffalse meta-comment
+%
+% Copyright 1993 1994 1995 1996 1997 1998 1999 2000 2001 2002 2003
+% The LaTeX3 Project and any individual authors listed elsewhere
+% in this file.
+%
+% This file is part of the Standard LaTeX `Tools Bundle'.
+% -------------------------------------------------------
+%
+% It 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.3 or later is part of all distributions of LaTeX
+% version 2003/12/01 or later.
+%
+% The list of all files belonging to the LaTeX `Tools Bundle' is
+% given in the file `manifest.txt'.
+%
+% \fi
+%\iffalse % this is a METACOMMENT !
+%
+%% Package `array' to use with LaTeX 2e
+%% Copyright (C) 1989-1998 Frank Mittelbach, all rights reserved.
+%<+package>\NeedsTeXFormat{LaTeX2e}[1995/06/01]
+%<+package>\ProvidesPackage{array}
+%<+package> [2003/12/17 v2.4a Tabular extension package (FMi)]
+%
+% \fi
+%
+% \CheckSum{1114}
+%% \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 \~}
+%%
+%
+%
+% \changes{v2.3c}{1995/11/02}{(DPC) minor doc changes}
+%
+% \changes{v2.3a}{1994/10/16}{Added code for \cs{firsthline} and
+% friends}
+%
+% \changes{v2.2c}{1994/03/14}{removed check for \cs{@tfor} bug}
+%
+% \changes{v1.0b}{1987/06/04}{`@classi (faster),
+% `@classvi (new) A in preamble means
+% \&\& in `halign.}
+%
+% \changes{v1.1a}{1987/07/05}{New concept:
+% preamblechar: c,l,r,C,L,R,A,p,t,{\tt !|},@,!!}
+% \changes{v1.1b}{1987/09/21}{Again p like original \LaTeX{} and z for
+% centered `parbox.}
+%
+% \changes{v1.2a}{1987/09/27}{Completely new implementation.}
+% \changes{v1.2b}{1987/10/06}{{\tt !|} does no longer generate space at
+% start or end of the preamble. Otherwise `hline
+% is too long.}
+% \changes{v1.2b}{1987/10/06}{Enlarged `@arstrutbox by 1pt (Test-Impl)
+% with dimen `@strutheight.}
+% \changes{v1.2c}{1987/10/22}{New dimen parameter `extrarowheight
+% (default: 0pt).}
+% \changes{v1.2c}{1987/10/22}{Enlarged `@arstrutbox by `extrarowheight.
+% Thus you may avoid large characters to
+% overprint a `hline.}
+% \changes{v1.2c}{1987/10/22}{Introduced `m@th in `@array to allow
+% non-zero values of `mathsurround.}
+% \changes{v1.2d}{1987/11/02}{Completed the documentation.}
+% \changes{v1.2e}{1987/11/03}{Bug fixed: A at start of preamble resulted
+% in an error since `@mkpream generated
+% `@arstrut \& ... as a preamble.}
+% \changes{v1.2f}{1987/11/09}{`@testpach documented.}
+%
+% \changes{v1.3a}{1987/11/11}{Again a new implementation, with a new
+% concept (cf. the documentation).}
+% \changes{v1.3b}{1988/03/17}{`@decl expands now into `@empty, i.e., it
+% disappears when the preamble is generated,
+% except when the user specifies A\{\} or
+% B\{\}.}
+%
+% \changes{v1.4a}{1988/03/18}{Test implementation of use of token
+% registers in order to do without `protect.}
+% \changes{v1.4b}{1988/03/19}{Changed erroneous class numbers:
+% 5 -!> 6
+% 6 -!> 7
+% 7 -!> 5
+% Corresponding changes in the macros.}
+% \changes{v1.4c}{1988/03/19}{Everything except p,z now works with token
+% registers.}
+%
+% \changes{v1.9a}{1988/03/20}{Last (so I hope) major change: 1) Options
+% B,A now called !>,<. These options now point
+% to the column they modify.}
+% \changes{v1.9a}{1988/03/20}{2) `protect is no longer necessary. But
+% still the macro `@expast needs top be
+% modified. `multicolumn still does not work.}
+% \changes{v1.9b}{1988/04/29}{inserted missing `fi in `@testpach.
+% Corrected \LaTeX bug in `@tfor.}
+% \changes{v1.9c}{1988/05/07}{Re-introduced `@endpbox.
+% `multicolumn now works!! Version number still
+% 1.9 since the documentation is still not
+% finished.}
+% \changes{v1.9c}{1988/05/07}{1) `def `the@toks \{`the ...\} remaining
+% only in `@mkpream. 2) Removed `@classiii and
+% replaced by `save@decl.}
+% \changes{v1.9c}{1988/05/07}{3) `insert@column contains only `@tempcnta
+% and `count@ counters. 4) `@@startpbox and
+% `@@endpbox now totally obsolete.}
+% \changes{v1.9d}{1988/05/10}{Replaced `number by `the where the `toks
+% registers' contents are used.}
+% \changes{v1.9e}{1988/05/11}{Re-introduced `@xargarraycr and
+% `@yargarraycr, since `endtemplate seems to
+% be `outer.}
+% \changes{v1.9f}{1988/05/20}{Small changes finally carried out:
+% 1) `par!=`@empty.
+% 2) \{..ifnum0!=!`\}... $\to$ `bgroup and
+% analoguously `egroup.}
+% \changes{v1.9g}{1988/02/24}{Inserted again \{..ifnum0!=!`\}..,
+% c.f. Appendix D of the \protect\TeX{}book.}
+% \changes{v1.9h}{1988/06/28}{No longer necessary to read in the file
+% twice.}
+% \changes{v1.9i}{1988/06/28}{Corrected typo in german version.}
+% \changes{v1.9j}{1988/11/23}{In a `r' column an extra `kern`z@ is
+% needed.}
+% \changes{v1.9j}{1988/11/23}{Otherwise the `hfil on the left side
+% will be removed by the `unskip in
+% `insert@column if the entry is empty.}
+% \changes{v1.9k}{1988/06/28}{Corrected typo in german version.}
+% \changes{v1.9k}{1989/01/16}{`begin{Macro} changed to `begin{macro} in
+% documentation.}
+%
+% \changes{v2.0a}{1989/05/12}{{\tt\textbackslash @thetoks} changed to
+% {\tt\textbackslash the@toks}.}
+% \changes{v2.0a}{1989/05/12}{source changed to reflect new doc.sty
+% conventions.}
+% \changes{v2.0a}{1989/05/12}{t option renamed to p to be compatible to
+% the original.}
+% \changes{v2.0a}{1989/05/12}{File renamed from arraye.sty to
+% array.sty.}
+% \changes{v2.0b}{1989/05/17}{Three forgotten end macro added.}
+% \changes{v2.0b}{1989/05/17}{All lines shortened to 72 or less.}
+% \changes{v2.2a}{1994/02/03}{Upgrade to \LaTeXe}
+%
+% \DoNotIndex{\@depth,\@ehc,\@fortmp,\@height,\@ifnextchar,\@ifstar}
+% \DoNotIndex{\@ifundefined,\@ne,\@nil,\@tempa,\@tempb}
+% \DoNotIndex{\@tempcnta,\@tempd,\@tempdima,\@whilenum,\@width,\\}
+% \DoNotIndex{\@tforloop}
+% \DoNotIndex{\advance}
+% \DoNotIndex{\baselineskip,\begingroup,\bgroup}
+% \DoNotIndex{\cr,\crcr,\csname}
+% \DoNotIndex{\def,\do,\docdate,\dp}
+% \DoNotIndex{\edef,\egroup,\else,\endcsname,\endinput,\expandafter}
+% \DoNotIndex{\fi,\filedate,\fileversion}
+% \DoNotIndex{\gdef}
+% \DoNotIndex{\hbox,\hfil,\hsize,\hskip,\ht}
+% \DoNotIndex{\if,\ifcase,\ifdim,\ifnum,\ifx,\ignorespaces}
+% \DoNotIndex{\kern}
+% \DoNotIndex{\leavevmode,\let,\lineskip}
+% \DoNotIndex{\m@ne,\multispan}
+% \DoNotIndex{\newcount,\newdimen,\noalign}
+% \DoNotIndex{\or}
+% \DoNotIndex{\relax}
+% \DoNotIndex{\setbox,\space,\strutbox}
+% \DoNotIndex{\tabskip,\thr@@,\the,\toks,\toks@,\tw@,\typeout}
+% \DoNotIndex{\unhcopy,\unskip}
+% \DoNotIndex{\vbox,\vcenter,\vline,\vrule,\vtop,\vskip}
+% \DoNotIndex{\xdef}
+% \DoNotIndex{\z@}
+%
+% \GetFileInfo{array.sty}
+%
+% \title{A new implementation of \LaTeX's \textsf{tabular}
+% and \textsf{array} environment\thanks{This file
+% has version number \fileversion, last
+% revised \filedate.}}
+% \author{Frank Mittelbach
+% \and
+% David Carlisle\thanks{David kindly agreed on the inclusion
+% of the \texttt{\textbackslash{}newcolumntype} implementation,
+% formerly in
+% \texttt{newarray.sty} into this package }}
+%
+% \date{Printed \today}
+%
+% \maketitle
+%
+% \MakeShortVerb{\=}
+%
+% \begin{abstract}
+% This article describes an extended implementation of the \LaTeX\
+% \textsf{array}-- and \textsf{tabular}--environments. The special
+% merits of this implementation are further options to format columns
+% and the fact that fragile \LaTeX--commands don't have to be
+% =\protect='ed any more within those environments.
+%
+% The major part of the code for this package dates back to 1988---so
+% does some of its documentation.
+% \end{abstract}
+%
+%
+%
+% \section{Introduction}
+%
+% This new implementation of the \textsf{array}-- and
+% \textsf{tabular}--environments is part of a larger project in which
+% we are trying to improve the \LaTeX\--code in some aspects and to
+% make \LaTeX\ even easier to handle.
+%
+% The reader should be familiar with the general structure of the
+% environments
+% mentioned above. Further information can be found in
+% \cite{bk:lamport} and \cite{bk:GMS94}.
+% The additional options which can be used in the
+% preamble as well as those which now have a slightly different meaning
+% are described in table~\ref{tab:opt}.
+%
+% \DescribeMacro\extrarowheight
+% Additionally we introduce a new
+% parameter called =\extrarowheight=. If it takes a positive
+% length, the value of the parameter is added to the normal height of
+% every row of the table, while
+% the depth will remain the same. This is important for tables
+% with horizontal lines because those lines normally touch the
+% capital letters.
+% For example, we used =\setlength{\extrarowheight}{1pt}=
+% in table~\ref{tab:opt}.
+%
+% \begin{table}[t]
+% \begin{center}
+% \setlength{\extrarowheight}{1pt}
+% \begin{tabular}{|>{\tt}c|m{9cm}|}
+% \hline
+% \multicolumn{2}{|c|}{Unchanged options}\\
+% \hline
+% l & Left adjusted column. \\
+% c & Centered adjusted column. \\
+% r & Right adjusted column. \\
+% p\{width\} & Equivalent to =\parbox[t]{width}=. \\
+% @\{decl.\} & Suppresses inter-column space and inserts
+% \texttt{decl.}\ instead. \\
+% \hline
+% \multicolumn{2}{|c|}{New options}\\
+% \hline
+% m\{width\} & Defines a column of width \texttt{width}.
+% Every entry will be centered in proportion to
+% the rest of the line. It is somewhat like
+% =\parbox{width}=. \\
+% \hline
+% b\{width\} & Coincides with =\parbox[b]{width}=. \\
+% \hline
+% >\{decl.\} & Can be used before an \texttt{l}, \texttt{r},
+% \texttt{c}, \texttt{p}, \texttt{m} or a
+% \texttt{b} option. It inserts \texttt{decl.}\
+% directly in front of the entry of the column.
+% \\
+% \hline
+% <\{decl.\} & Can be used after an \texttt{l}, \texttt{r},
+% \texttt{c}, =p{..}=, =m{..}= or a =b{..}=
+% option. It inserts \texttt{decl.}\ right
+% after the entry of the column. \\
+% \hline
+% | & Inserts a vertical line. The distance between
+% two columns will be enlarged by the width of
+% the line
+% in contrast to the original definition of
+% \LaTeX. \\
+% \hline
+% !\{decl.\} & Can be used anywhere and corresponds with the
+% \texttt{|} option. The difference is that
+% \texttt{decl.} is inserted instead of a
+% vertical line, so this option doesn't
+% suppress the normally inserted space between
+% columns in contrast to =@{...}=.\\
+% \hline
+% \end{tabular}
+% \end{center}
+% \caption{The preamble options.} \label{tab:opt}
+% \end{table}
+%
+%
+% We will discuss a few examples using the new preamble options before
+% dealing with the implementation.
+% \begin{itemize}
+% \item
+% If you want to use a special font (for example =\bfseries=) in a
+% flushed left column, this can be done with =>{\bfseries}l=. You
+% do not have to begin every entry of the column with =\bfseries=
+% any more.
+% \item
+% In columns which have been generated with \texttt{p}, \texttt{m}
+% or \texttt{b}, the default value of =\parindent= is
+% \textsf{0pt}.
+% This can be changed with \\
+% =>{\setlength{\parindent}{1cm}}p=.
+% \item
+% The \texttt{>}-- and \texttt{<}--options were originally
+% developed for the following application:
+% =>{$}c<{$}= generates a column in math
+% mode in a \textsf{tabular}--environment. If you use this type
+% of a preamble in an \textsf{array}--environment, you get a
+% column in LR mode because the additional \$'s cancel the
+% existing \$'s.
+% \item
+% One can also think of more complex applications. A problem
+% which has
+% been mentioned several times in \TeX{}hax can be solved with
+% =>{\centerdots}c=\linebreak[0]=<{\endcenterdots}=.
+% To center decimals at their
+% decimal points you (only?) have to define the following macros:
+% \begin{verbatim}
+%{\catcode`\.\active\gdef.{\egroup\setbox2\hbox\bgroup}}
+%\def\centerdots{\catcode`\.\active\setbox0\hbox\bgroup}
+%\def\endcenterdots{\egroup\ifvoid2 \setbox2\hbox{0}\fi
+% \ifdim \wd0>\wd2 \setbox2\hbox to\wd0{\unhbox2\hfill}\else
+% \setbox0\hbox to\wd2{\hfill\unhbox0}\fi
+% \catcode`\.12 \box0.\box2}
+%\end{verbatim}
+% Warning: The code is bad, it doesn't work with more than one
+% dot in a cell and doesn't work when the tabular is used in the
+% argument of some other command. A much better version is
+% provided in the \texttt{dcolumn.sty} by David Carlisle.
+% \item
+% Using =c!{\hspace{1cm}}c= you get space between two
+% columns which is enlarged by one centimeter, while
+% =c@{\hspace{1cm}}c= gives you exactly one centimeter
+% space between two columns.
+% \end{itemize}
+%
+% \subsection{Defining new column specifiers}
+%
+% \DeleteShortVerb{\=}
+% \MakeShortVerb{\"}
+% \DescribeMacro{\newcolumntype}
+% Whilst it is handy to be able to type
+% \begin{quote}
+% ">{"\meta{some declarations}"}{c}<{"\meta{some more
+% declarations}"}"
+% \end{quote}
+% if you have a one-off column in a table, it is rather inconvenient
+% if you often use columns of this form. The new version allows you
+% to define a new column specifier, say \texttt{x}, which will expand to
+% the primitives column specifiers.\footnote{This command was named
+% \texttt{\textbackslash{}newcolumn} in the \texttt{newarray.sty}.
+% At the moment \texttt{\textbackslash{}newcolumn} is still supported
+% (but gives a warning). In later releases it will vanish.} Thus we
+% may define
+% \begin{quote}
+% "\newcolumntype{x}{>{"\meta{some declarations}"}{c}<{"\meta{some
+% more declarations}"}}"\hspace*{-3cm} ^^A no overfull from this line
+% \end{quote}
+% One can then use the \texttt{x} column specifier in the preamble
+% arguments of all \texttt{array} or \texttt{tabular} environments in
+% which you want columns of this form.
+%
+% It is common to need math-mode and LR-mode columns in the same
+% alignment. If we define:
+% \begin{quote}
+% "\newcolumntype{C}{>{$}c<{$}}" \\
+% "\newcolumntype{L}{>{$}l<{$}}" \\
+% "\newcolumntype{R}{>{$}r<{$}}"
+% \end{quote}
+% Then we can use \texttt{C} to get centred LR-mode in an
+% \texttt{array}, or centred math-mode in a \texttt{tabular}.
+%
+% The example given above for `centred decimal points' could be
+% assigned to a \texttt{d} specifier with the following command.
+% \begin{quote}
+% "\newcolumntype{d}{>{\centerdots}c<{\endcenterdots}}"
+% \end{quote}
+%
+% The above solution always centres the dot in the
+% column. This does not look too good if the column consists of large
+% numbers, but to only a few decimal places. An alternative definition
+% of a \texttt{d} column is
+% \begin{quote}
+% "\newcolumntype{d}[1]{>{\rightdots{#1}}r<{\endrightdots}}"
+% \end{quote}
+% where the appropriate macros in this case are:\footnote{The package
+% \texttt{dcolumn.sty} contains more robust macros based on these
+% ideas.}
+% \begin{verbatim}
+% \def\coldot{.}% Or if you prefer, \def\coldot{\cdot}
+% {\catcode`\.=\active
+% \gdef.{$\egroup\setbox2=\hbox to \dimen0 \bgroup$\coldot}}
+% \def\rightdots#1{%
+% \setbox0=\hbox{$1$}\dimen0=#1\wd0
+% \setbox0=\hbox{$\coldot$}\advance\dimen0 \wd0
+% \setbox2=\hbox to \dimen0 {}%
+% \setbox0=\hbox\bgroup\mathcode`\.="8000 $}
+% \def\endrightdots{$\hfil\egroup\box0\box2}
+%\end{verbatim}
+% Note that "\newcolumntype" takes the same optional argument as
+% "\newcommand" which declares the number of arguments of the column
+% specifier being defined. Now we can specify "d{2}" in our preamble
+% for a column of figures to at most two decimal places.
+%
+% A rather different use of the "\newcolumntype" system takes
+% advantage of the fact that the replacement text in the
+% "\newcolumntype" command may refer to more than one column. Suppose
+% that a document contains a lot of \texttt{tabular} environments that
+% require the same preamble, but you wish to experiment with different
+% preambles. Lamport's original definition allowed you to do the
+% following (although it was probably a mis-use of the system).
+% \begin{quote}
+% "\newcommand{\X}{clr}"\\
+% "\begin{tabular}{\X}" \ldots
+% \end{quote}
+% \texttt{array.sty} takes great care \textbf{not} to expand the
+% preamble, and so the above does not work with the new scheme. With
+% the new version this functionality is returned:
+% \begin{quote}
+% "\newcolumntype{X}{clr}"\\
+% "\begin{tabular}{X}" \ldots
+% \end{quote}
+%
+% The replacement text in a "\newcolumntype" command may refer to any of
+% the primitives of \texttt{array.sty} see table \ref{tab:opt} on page
+% \pageref{tab:opt}, or to any new letters defined in other
+% "\newcolumntype" commands.
+%
+%
+% \DescribeMacro{\showcols}A list of all the currently active
+% "\newcolumntype" definitions is sent to the terminal and log file if
+% the "\showcols" command is given.
+%
+%
+% \subsection{Special variations of \texttt{\textbackslash hline}}
+%
+% The family of \texttt{tabular} environments allows
+% vertical positioning with respect to the baseline of
+% the text in which the environment appears. By default the
+% environment appears centered, but this can be changed to
+% align with the first or last line in the environment by
+% supplying a \texttt{t} or \texttt{b} value to the
+% optional position argument. However, this does not work
+% when the first or last element in the environment is a
+% "\hline" command---in that case the environment is
+% aligned at the horizontal rule.
+%
+% \pagebreak[3]
+%
+% Here is an example:
+% \begin{center}
+% \begin{minipage}[t]{.4\linewidth}
+% Tables
+% \begin{tabular}[t]{l}
+% with no\\ hline \\ commands \\ used
+% \end{tabular} versus \\ tables
+% \begin{tabular}[t]{|l|}
+% \hline
+% with some \\ hline \\ commands \\
+% \hline
+% \end{tabular} used.
+% \end{minipage}
+% \begin{minipage}[t]{.5\linewidth}
+% \begin{verbatim}
+% Tables
+% \begin{tabular}[t]{l}
+% with no\\ hline \\ commands \\ used
+% \end{tabular} versus tables
+% \begin{tabular}[t]{|l|}
+% \hline
+% with some \\ hline \\ commands \\
+% \hline
+% \end{tabular} used.
+% \end{verbatim}
+% \end{minipage}
+% \end{center}
+%
+% \DescribeMacro\firsthline
+% \DescribeMacro\lasthline
+% Using "\firsthline" and "\lasthline" will
+% cure the problem, and the tables will align properly as long
+% as their first or last line does not contain extremely large
+% objects.
+% \begin{center}
+% \begin{minipage}[t]{.4\linewidth}
+% Tables
+% \begin{tabular}[t]{l}
+% with no\\ line \\ commands \\ used
+% \end{tabular} versus \\ tables
+% \begin{tabular}[t]{|l|}
+% \firsthline
+% with some \\ line \\ commands \\
+% \lasthline
+% \end{tabular} used.
+% \end{minipage}
+% \begin{minipage}[t]{.5\linewidth}
+% \begin{verbatim}
+% Tables
+% \begin{tabular}[t]{l}
+% with no\\ line \\ commands \\ used
+% \end{tabular} versus tables
+% \begin{tabular}[t]{|l|}
+% \firsthline
+% with some \\ line \\ commands \\
+% \lasthline
+% \end{tabular} used.
+% \end{verbatim}
+% \end{minipage}
+% \end{center}
+% \DescribeMacro\extratabsurround
+% The implementation of these two commands contains an extra
+% dimension, which is called "\extratabsurround", to add some
+% additional space at the top and the bottom of such an environment.
+% This is useful if such tables are nested.
+%
+% \section{Final Comments}
+%
+% \subsection{Handling of rules}
+%
+% There are two possible approaches to the handling of horizontal and
+% vertical rules in tables:
+% \begin{enumerate}
+% \item rules can be placed into the available space without
+% enlarging the table, or
+% \item rules can be placed between columns or rows thereby enlarging
+% the table.
+% \end{enumerate}
+% \texttt{array.sty} implements the second possibility while the
+% default implementation in the \LaTeX{} kernel implements the first
+% concept. Both concepts have their merrits but one has to be aware of
+% the individual implications.
+% \begin{itemize}
+% \item
+% With standard \LaTeX{} adding rules to a table will not affect the
+% width or height of the table (unless double rules are used), e.g.,
+% changing a preamble from \verb=lll= to \verb=l|l|l= does not
+% affect the document other than adding rules to the table. In
+% contrast, with \texttt{array.sty} a table that just fit the
+% \verb=\textwidth= might now produce an overfull box.
+% \item
+% With standard \LaTeX{} modifying the width of rules could result
+% in ugly looking tables because without adjusting the
+% \verb=\tabcolsep=, etc.\ the space between rule and column could
+% get too small (or too large). In fact even overprinting of text is
+% possible. In contrast, with \texttt{array.sty} modifying any such
+% length usually works well as the actual visual white space (from
+% \verb=\tabcolsep=, etc.) does not depend on the width of the
+% rules.
+% \item
+% With standard \LaTeX{} boxed tabulars actually have strange
+% corners because the horizontal rules end in the middle of the
+% vertical ones. This looks very unpleasant when a large
+% \verb=\arrayrulewidth= is chosen. In that case a simple table like
+%\begin{verbatim}
+%\setlength{\arrayrulewidth}{5pt}
+%\begin{tabular}{|l|}
+% \hline A \\ \hline
+%\end{tabular}
+%\end{verbatim}
+% will produce something like
+% \begin{center}
+%\setlength{\arrayrulewidth}{5pt}
+%\begin{tabular}{@{}l@{}}
+% \hline \null\hskip-.5\arrayrulewidth\vline
+% \hskip\tabcolsep
+% A\hskip\tabcolsep
+% \vline\hskip-.5\arrayrulewidth\null \\ \hline
+%\end{tabular}
+% \quad
+% instead of
+% \quad
+%\begin{tabular}{|l|}
+% \hline A \\ \hline
+%\end{tabular}
+% \end{center}
+% \end{itemize}
+%
+% \subsection{Comparisons with older versions of \texttt{array.sty}}
+%
+% There are some differences in the way version 2.1 treats incorrect
+% input, even if the source file does not appear to use any of the
+% extra features of the new version.
+% \begin{itemize}
+% \item A preamble of the form "{wx*{0}{abc}yz}" was treated by
+% versions prior to 2.1 as "{wx}". Version 2.1 treats it as "{wxyz}"
+% \item An incorrect positional argument such as \texttt{[Q]} was
+% treated as \texttt{[c]} by \texttt{array.sty}, but is now treated as
+% \texttt{[t]}.
+% \item A preamble such as "{cc*{2}}" with an error in
+% a $*$-form will generate different errors in the new version. In
+% both cases the error message is not particularly helpful to the
+% casual user.
+% \item Repeated \texttt{<} or \texttt{>} constructions
+% generated an error in earlier versions, but are now allowed in
+% this package. ">{"\meta{decs1}"}>{"\meta{decs2}"}" is treated the
+% same as ">{"\meta{decs2}\meta{decs1}"}".
+% \item The "\extracolsep"
+% command does not work with the old versions of \texttt{array.sty},
+% see the comments in \texttt{array.bug}. With version 2.1
+% "\extracolsep" may again be used in \texttt{@}-expressions as in
+% standard \LaTeX, and also in \texttt{!}-expressions (but see the
+% note below).
+% \end{itemize}
+%
+%
+% \subsection{Bugs and Features}
+%
+% \begin{itemize}
+% \item Error messages generated when parsing the column specification
+% refer to the preamble argument \textbf{after} it has been re-written
+% by the "\newcolumntype" system, not to the preamble entered by the
+% user. This seems inevitable with any system based on
+% pre-processing and so is classed as a \textbf{feature}.
+%
+% \item The treatment of multiple \texttt{<} or \texttt{>}
+% declarations may seem strange at first. Earlier implementations
+% treated ">{"\meta{decs1}"}>{"\meta{decs2}"}" the same as
+% ">{"\meta{decs1}\meta{decs2}"}". However this did not give the
+% user the opportunity of overriding the settings of a
+% "\newcolumntype" defined using these declarations. For example,
+% suppose in an \texttt{array} environment we use a \texttt{C}
+% column defined as above. The \texttt{C} specifies a centred text
+% column, however ">{\bfseries}C", which re-writes to
+% ">{\bfseries}>{$}c<{$}" would not specify a bold column as might
+% be expected, as the preamble would essentially expand to
+% "\hfil$\bfseries$#$ $\hfil" and so the column entry would not be in the
+% scope of the "\bfseries"\,! The present version switches the order
+% of repeated declarations, and so the above example now produces a
+% preamble of the form "\hfil$" "$\bfseries#$" "$\hfil", and the
+% dollars cancel each other out without limiting the scope of the
+% "\bfseries".
+%
+% \item The use of "\extracolsep" has been subject to the following
+% two restrictions. There must be at most one "\extracolsep"
+% command per "@", or "!" expression and the command must be
+% directly entered into the "@" expression, not as part of a macro
+% definition. Thus "\newcommand{\ef}{\extracolsep{\fill}}" \ldots
+% "@{\ef}" does not work with this package. However you can use
+% something like
+% "\newcolumntype{e}{@{\extracolsep{\fill}}" instead.
+%
+% \item As noted by the \LaTeX{} book, for the purpose of
+% "\multicolumn" each column with the exception of the first one
+% consists of the entry and the \emph{following} inter-column
+% material. This means that in a tabular with the preamble
+% "|l|l|l|l|" input such as "\multicolumn{2}{|c|}" in
+% anything other than the first column is incorrect.
+
+% In the standard array/tabular implementation this error is not so
+% noticeable as that version contains negative spacing so that each
+% "|" takes up no horizontal space. But since in this package the
+% vertical lines take up their natural width one sees two lines if
+% two are specified.
+%
+% \end{itemize}
+%
+%
+%
+% \changes{v2.2b}{1994/02/04}{Removed interactive prompt}
+%
+% \StopEventually{
+%
+%
+% \begin{thebibliography}{1}
+% \bibitem{bk:GMS94} \textsc{M.~Goossens}, \textsc{F.~Mittelbach}
+% and \textsc{A.~Samarin}.
+% \newblock The \LaTeX{} Companion.
+% \newblock
+% Addison-Wesley, Reading, Massachusetts, 1994.
+% \bibitem{bk:knuth} \textsc{D. E. Knuth}.
+% \newblock The \TeX{}book (Computers \& Typesetting Volume A).
+% \newblock
+% Addison-Wesley, Reading, Massachusetts, 1986.
+% \bibitem{bk:lamport} \textsc{L. Lamport}.
+% \newblock
+% \LaTeX\ --- A Document Preparation System.
+% \newblock
+% Addison-Wesley, Reading, Massachusetts, 1986.
+% \end{thebibliography}
+%
+% } ^^A end of \StopEventually
+%
+%
+%
+%
+% \section{The documentation driver file}
+%
+% The first 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} program.
+% \begin{macrocode}
+%<*driver>
+\NeedsTeXFormat{LaTeX2e}[1995/12/01]
+\documentclass{ltxdoc}
+
+\AtBeginDocument{\DeleteShortVerb{\|}} % undo the default is not used
+
+ \usepackage{array}
+
+ % Allow large table at bottom
+ \renewcommand{\bottomfraction}{0.7}
+
+\EnableCrossrefs
+ %\DisableCrossrefs % Say \DisableCrossrefs if index is ready
+
+\RecordChanges % Gather update information
+
+\CodelineIndex % Index code by line number
+
+ %\OnlyDescription % comment out for implementation details
+ %\OldMakeindex % use if your MakeIndex is pre-v2.9
+\begin{document}
+ \DocInput{array.dtx}
+\end{document}
+%</driver>
+% \end{macrocode}
+%
+%
+% \section{The construction of the preamble}
+%
+% \DeleteShortVerb{\"}
+% \MakeShortVerb{\=}
+%
+% It is obvious that those environments will consist mainly of an
+% =\halign=, because \TeX\ typesets tables using this primitive.
+% That is why we will now take a look at the algorithm which determines
+% a preamble for a =\halign= starting with a given user preamble
+% using the options mentioned above.
+%
+%
+% The current version is defined at the top of the file looking
+% something like this
+% \begin{macrocode}
+%<*package>
+%\NeedsTeXFormat{LaTeX2e}[1994/05/13]
+%\ProvidesPackage{array}[\filedate\space version\fileversion]
+% \end{macrocode}
+%
+% The most interesting macros of this implementation are without doubt
+% those which are responsible for the construction of the preamble for
+% the =\halign=. The underlying algorithm was developed by
+% \textsc{Lamport} (resp.\ \textsc{Knuth}, see texhax V87\#??), and it
+% has been extended and improved.
+%
+% The user preamble will be read \textsf{token} by \textsf{token}. A
+% \textsf{token} is a single character like \texttt{c} or a block
+% enclosed in ={...}=. For example the preamble of
+% =\begin{tabular}=\linebreak[0]={lc||c@{\hspace{1cm}}}= consists of
+% the \textsf{token} \texttt{l}, \texttt{c}, \texttt{|}, \texttt{|},
+% \texttt{@} and =\hspace{1cm}=.
+%
+% The currently used \textsf{token} and the one, used before, are needed
+% to decide on how the construction of the preamble has to be
+% continued.
+% In the example mentioned above the \texttt{l} causes the preamble
+% to begin with =\hskip\tabcolsep=. Furthermore
+% =# \hfil= would be appended to define a flush left column.
+% The next \textsf{token} is a \texttt{c}. Because it was preceded by an
+% \texttt{l} it generates a new column. This is done with
+% =\hskip \tabcolsep & \hskip \tabcolsep=. The column which is to
+% be centered will be appended with =\hfil # \hfil=.
+% The \textsf{token} \texttt{|} would then add a space of
+% =\hskip \tabcolsep=
+% and a vertical line because the last
+% \textsf{tokens} was a \texttt{c}.
+% The following \textsf{token} \texttt{|} would only add a space
+% =\hskip \doublerulesep= because it was preceded by the
+% \textsf{token} \texttt{|}. We will not discuss our example further but
+% rather take a look at the general case of constructing preambles.
+%
+% The example shows that the desired preamble for the
+% =\halign= can be constructed as soon as the action of all
+% combinations
+% of the preamble \textsf{tokens} are specified. There are 18 such
+% \textsf{tokens}
+% so we have $19 \cdot 18 \string= 342$ combinations if we count the
+% beginning of
+% the preamble as a special \textsf{token}. Fortunately, there are many
+% combinations which generate the same spaces, so we can define
+% \textsf{token} classes. We will identify a
+% \textsf{token} within a class with a number, so we can insert the
+% formatting (for example of a column).
+% Table~\ref{tab:Klassen} lists all \textsf{token} classes and
+% their corresponding numbers.
+% \begin{table}[ht]
+% \begin{center}
+% \begin{tabular}[t]{>{\ttfamily}ccc}
+% \textsf{token} & =\@chclass= & =\@chnum= \\[2mm]
+% c & 0 & 0 \\
+% l & 0 & 1 \\
+% r & 0 & 2 \\
+% p-arg & 0 & 3 \\
+% t-arg & 0 & 4 \\
+% b-arg & 0 & 5 \\
+% | & 1 & 0 \\
+% !-arg & 1 & 1 \\
+% <-arg & 2 & --- \\
+% >-arg & 3 & ---
+% \end{tabular}
+% \kern3mm \vrule \kern3mm%
+% \begin{tabular}[t]{>{\ttfamily}ccc}
+% \textsf{token} & =\@chclass= & =\@chnum= \\[2mm]
+% Start & 4 & --- \\
+% @-arg & 5 & --- \\
+% ! & 6 & --- \\
+% @ & 7 & --- \\
+% < & 8 & --- \\
+% > & 9 & --- \\
+% p & 10 & 3 \\
+% t & 10 & 4 \\
+% b & 10 & 5
+% \end{tabular}
+% \end{center}
+% \caption{Classes of preamble \textsf{tokens}}
+% \label{tab:Klassen}
+% \end{table}
+%
+%
+% \begin{macro}{\@chclass}
+% \begin{macro}{\@chnum}
+% \begin{macro}{\@lastchclass}
+% The class and the number of the current \textsf{token} are saved in
+% the
+% \textsf{count} registers =\@chclass=
+% and =\@chnum=, while the class of the previous
+% \textsf{token} is stored in the
+% \textsf{count} register =\@lastchclass=.
+% All of the mentioned registers are already allocated in
+% \texttt{latex.tex},
+% which is the reason why the following three lines of code are
+% commented out.
+% Later throughout the text I will not mention it again explicitely
+% whenever I use a =%= sign. These parts are already defined in
+% \texttt{latex.tex}.
+% \begin{macrocode}
+% \newcount \@chclass
+% \newcount \@chnum
+% \newcount \@lastchclass
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+%
+%
+% \begin{macro}{\@addtopreamble}
+% We will save the already constructed preamble for
+% the =\halign=
+% in the global macro =\@preamble=. This will then be
+% enlarged with
+% the command =\@addtopreamble=.
+% \begin{macrocode}
+\def\@addtopreamble#1{\xdef\@preamble{\@preamble #1}}
+% \end{macrocode}
+% \end{macro}
+%
+%
+%
+%
+%
+% \subsection{The character class of a \textsf{token}}
+%
+% \begin{macro}{\@testpach}
+% \changes{v2.0a}{1989/05/12}{p option renamed to m (middle).}
+% \changes{v2.0a}{1989/05/12}{t option renamed to p to be compatible to
+% the original.}
+% With the help of =\@lastchclass= we can now define a macro
+% which determines the class and the number of a given preamble
+% \textsf{token}
+% and assigns them to the registers
+% =\@chclass= and =\@chnum=.
+% \changes{v2.0f}{1992/02/29}{Argument removed since implicitly known}
+% \begin{macrocode}
+\def\@testpach{\@chclass
+% \end{macrocode}
+% First we deal with the cases in which the \textsf{token}
+% (=#1=) is the argument of \texttt{!}, \texttt{@}, \texttt{<} or
+% \texttt{>}. We can see this from the value of =\@lastchclass=:
+% \begin{macrocode}
+ \ifnum \@lastchclass=6 \@ne \@chnum \@ne \else
+ \ifnum \@lastchclass=7 5 \else
+ \ifnum \@lastchclass=8 \tw@ \else
+ \ifnum \@lastchclass=9 \thr@@
+% \end{macrocode}
+% Otherwise we will assume that the \textsf{token} belongs to the
+% class $0$
+% and assign the corresponding number to =\@chnum= if our
+% assumption is correct.
+% \begin{macrocode}
+ \else \z@
+% \end{macrocode}
+% If the last \textsf{token} was a \texttt{p}, \texttt{m} or a
+% \texttt{b}, =\@chnum= already has the right value. This is the
+% reason for the somewhat curious choice of the \textsf{token}
+% numbers in class $10$.
+% \begin{macrocode}
+ \ifnum \@lastchclass = 10 \else
+% \end{macrocode}
+% Otherwise we will check if =\@nextchar= is either a \texttt{c},
+% \texttt{l} or an \texttt{r}. Some applications change the
+% catcodes of certain characters like ``\texttt{@}'' in
+% \texttt{amstex.sty}. As a result the tests below would fail since
+% they assume non-active character tokens. Therefore we evaluate
+% =\@nextchar= once thereby turning the first token of its
+% replacement text into a char. At this point here this should have
+% been the only char present in =\@nextchar= which put into via a
+% =\def=.
+% \changes{v2.0f}{1992/02/29}{Ensure to test a char which is not active}
+% \begin{macrocode}
+ \edef\@nextchar{\expandafter\string\@nextchar}%
+ \@chnum
+ \if \@nextchar c\z@ \else
+ \if \@nextchar l\@ne \else
+ \if \@nextchar r\tw@ \else
+% \end{macrocode}
+% If it is a different \textsf{token}, we know that the class was
+% not $0$. We assign the value $0$ to =\@chnum= because this value
+% is needed for the \texttt{|}--\textsf{token}. Now we must check
+% the remaining classes. Note that the value of =\@chnum= is
+% insignificant here for most classes.
+% \begin{macrocode}
+ \z@ \@chclass
+ \if\@nextchar |\@ne \else
+ \if \@nextchar !6 \else
+ \if \@nextchar @7 \else
+ \if \@nextchar <8 \else
+ \if \@nextchar >9 \else
+% \end{macrocode}
+% The remaining permitted \textsf{tokens} are \texttt{p},
+% \texttt{m} and \texttt{b} (class $10$).
+% \begin{macrocode}
+ 10
+ \@chnum
+ \if \@nextchar m\thr@@\else
+ \if \@nextchar p4 \else
+ \if \@nextchar b5 \else
+% \end{macrocode}
+% Now the only remaining possibility is a forbidden \textsf{token},
+% so we choose class $0$ and number $0$ and give an error message.
+% Then we finish the macro by closing all =\if='s.
+% \begin{macrocode}
+ \z@ \@chclass \z@ \@preamerr \z@ \fi \fi \fi \fi
+ \fi \fi \fi \fi \fi \fi \fi \fi \fi \fi \fi \fi}
+% \end{macrocode}
+% \end{macro}
+%
+%
+%
+%
+%
+% \subsection{Multiple columns ($*$--form)}
+%
+% \begin{macro}{\@xexpast}
+% \begin{macro}{\the@toks}
+% \begin{macro}{\the@toksz}
+% \label{@xexpast} Now we discuss the macro that deletes all forms
+% of type =*{=\textit{N\/}=}{=\textit{String\/}=}= from a user
+% preamble and replaces them with \textit{N} copies of
+% \textit{String}. Nested $*$--expressions are dealt with
+% correctly, that means $*$--expressions are not substituted if
+% they are in explicit braces, as in =@{*}=.
+%
+% This macro is called via
+% =\@xexpast=\meta{preamble}=*0x\@@=.
+% The $*$--expression =*0x= is being used to terminate the
+% recursion,
+% as we shall see later, and =\@@= serves as an argument
+% delimiter. =\@xexpast= has four arguments. The first
+% one is the part of the
+% user preamble before the first $*$--expression while the second
+% and third ones are the arguments of the first $*$--expression
+% (that is \textit{N} and \textit{String} in the notation mentioned
+% above).
+% The fourth argument is the rest of the preamble.
+% \begin{macrocode}
+\def\@xexpast#1*#2#3#4\@@{%
+% \end{macrocode}
+% The number of copies of \textit{String} (=#2=) that are to be
+% produced will be saved in a \textsf{count} register.
+% \begin{macrocode}
+ \@tempcnta #2
+% \end{macrocode}
+% We save the part of the preamble which does not
+% contain a $*$--form (=#1=)
+% in a \PlainTeX\ \textsf{token} register.
+% We also save \textit{String} (=#3=) using a \LaTeX\
+% \textsf{token} register.
+% \begin{macrocode}
+ \toks@={#1}\@temptokena={#3}%
+% \end{macrocode}
+% Now we have to use a little trick to produce \textit{N} copies of
+% \textit{String}.
+% We could try =\def\@tempa{#1}= and then
+% \textit{N} times =\edef\@tempa{\@tempa#3}=. This would have the
+% undesired effect that all macros within =#1= and =#3=
+% would be expanded, although, for example, constructions like
+% =@{..}= are not supposed to be changed.
+% That is why we =\let= two control sequences to
+% be equivalent to =\relax=.
+% \begin{macrocode}
+ \let\the@toksz\relax \let\the@toks\relax
+% \end{macrocode}
+% Then we ensure that =\@tempa= contains
+% ={\the@toksz\the@toks...\the@toks}= (the macro
+% =\the@toks= exactly \textit{N\/} times) as substitution text.
+% \begin{macrocode}
+ \def\@tempa{\the@toksz}%
+ \ifnum\@tempcnta >0 \@whilenum\@tempcnta >0\do
+ {\edef\@tempa{\@tempa\the@toks}\advance \@tempcnta \m@ne}%
+% \end{macrocode}
+% If \textit{N\/} was greater than zero we prepare for another call
+% of =\@xexpast=. Otherwise we assume we have reached the end of
+% the user preamble, because we had appended =*0x\@@= when we first
+% called =\@xexpast=. In other words: if the user inserts
+% =*{0}{..}= in his preamble, \LaTeX\ ignores the rest of it.
+% \begin{macrocode}
+ \let \@tempb \@xexpast \else
+ \let \@tempb \@xexnoop \fi
+% \end{macrocode}
+% Now we will make sure that the part of the user preamble, which
+% was already dealt with, will be saved again in =\@tempa=.
+% \begin{macrocode}
+ \def\the@toksz{\the\toks@}\def\the@toks{\the\@temptokena}%
+ \edef\@tempa{\@tempa}%
+% \end{macrocode}
+% We have now evaluated the first $*$--expression, and the user
+% preamble up to this point
+% is saved in =\@tempa=. We will put the contents of
+% =\@tempa= and the rest of the user preamble together and work
+% on the result with =\@tempb=. This macro either corresponds
+% to =\@xexpast=, so that the next
+% $*$--expression is handled, or to the macro =\@xexnoop=,
+% which only ends the recursion by deleting its argument.
+% \begin{macrocode}
+ \expandafter \@tempb \@tempa #4\@@}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\@xexnoop}
+% So the first big problem is solved. Now it is easy to
+% specify =\@xexnoop=.
+% Its argument is delimited by =\@@= and it simply expands to
+% nothing.
+% \begin{macrocode}
+% \def\@xexnoop#1\@@{}
+% \end{macrocode}
+% \end{macro}
+%
+%
+%
+%
+% \section{The insertion of declarations
+% (\texttt{>}, \texttt{<}, \texttt{!}, \texttt{@})}
+%
+%
+% The preamble will be enlarged with the help of =\xdef=, but the
+% arguments of \texttt{>}, \texttt{<},~\texttt{!}\ and \texttt{@} are
+% not supposed to be expanded during the construction (we want an
+% implementation that doesn't need a =\protect=). So we have to find a
+% way to inhibit the expansion of those arguments.
+%
+% We will solve this problem with \textsf{token} registers. We need
+% one register for every \texttt{!}\ and \texttt{@}, while we need two
+% for every \texttt{c}, \texttt{l}, \texttt{r}, \texttt{m}, \texttt{p}
+% or \texttt{b}. This limits the number of columns of a table because
+% there are only 256 \textsf{token} registers. But then, who needs
+% tables with more than 100 columns?
+%
+% One could also find a solution which only needs two or three
+% \textsf{token} registers by proceeding similarly as in the macro
+% =\@xexpast= (see page \pageref{@xexpast}). The advantage of our
+% approach is the fact that we avoid some of the problems that arise
+% with the other method\footnote{Maybe there are also historical
+% reasons.}.
+%
+% So how do we proceed? Let us assume that we had =!{foo}= in the
+% user preamble and say we saved \texttt{foo} in
+% \textsf{token} register $5$. Then we call
+% =\@addtopreamble{\the@toks5}= where
+% =\the@toks= is defined in a way that it does not expand
+% (for example it could be equivalent to =\relax=). Every
+% following call
+% of =\@addtopreamble= leaves =\the@toks5= unchanged in
+% =\@preamble=. If the construction of the preamble is completed
+% we change the definition of =\the@toks= to
+% =\the\toks= and expand =\@preamble= for the last time.
+% During this process all parts of the form
+% =\the@toks=\meta{Number}
+% will be substituted by the contents of the respective \textsf{token}
+% registers.
+%
+% As we can see from this informal discussion the construction of the
+% preamble has to take place within a group, so that the
+% \textsf{token} registers we use will be freed later on. For that
+% reason we keep all assignments to =\@preamble= global; therefore the
+% replacement text of this macro will remain the same after we leave
+% the group.
+%
+% \begin{macro}{\count@}
+% We further need a \textsf{count} register to remember which
+% \textsf{token} register is to be used next. This will be
+% initialized with $-1$ if we want to begin with the \textsf{token}
+% register $0$. We use the \PlainTeX\ scratch register =\count@=
+% because everything takes place locally. All we have to do is
+% insert =\the@toks= =\the= =\count@= into the preamble.
+% =\the@toks= will remain unchanged and =\the\count@= expands into
+% the saved number.
+% \end{macro}
+%
+% \begin{macro}{\prepnext@tok}
+% The macro =\prepnext@tok= is in charge of preparing the next
+% \textsf{token} register. For that purpose we increase
+% =\count@= by $1$:
+% \begin{macrocode}
+\def\prepnext@tok{\advance \count@ \@ne
+% \end{macrocode}
+% Then we locally delete any contents the
+% \textsf{token} register might have.
+% \begin{macrocode}
+ \toks\count@{}}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\save@decl}
+% During the construction of the preamble the current
+% \textsf{token} is always saved in the macro =\@nextchar= (see the
+% definition of =\@mkpream= on page \pageref{@mkpream}). The macro
+% =\save@decl= saves it into the next free \textsf{token} register,
+% i.e.\ in =\toks\count@=.
+% \changes{v2.0c}{1990/08/14}{\cs{relax} removed and added elsewhere.}
+% \begin{macrocode}
+\def\save@decl{\toks\count@ \expandafter{\@nextchar}}
+% \end{macrocode}
+% The reason for the use of =\relax= is the following
+% hypothetical situation in the preamble:
+% \quad =..\the\toks1\the\toks2..= \quad \TeX\ expands
+% =\the\toks2= first in order to find out if the digit =1=
+% is followed by other digits. E.g.\ a =5= saved in the
+% \textsf{token} register $2$ would lead \TeX\ to insert the contents
+% of \textsf{token} register $15$ instead of $1$ later on.
+%
+% The example above referred to an older version of =\save@decl= which
+% inserted a =\relex= inside the token register. This is now moved to
+% the places where the actual token registers are inserted (look for
+% =\the@toks=) because the old version would still make =@=
+% expressions to moving arguments since after expanding the second
+% register while looking for the end of the number the contents of the
+% token register is added so that later on the whole register will be
+% expanded. This serious bug was found after nearly two years
+% international use of this package by Johannes Braams.
+% \end{macro}
+%
+%
+%
+% How does the situation look like, if we want to add another column
+% to the preamble, i.e.\ if we have found a \texttt{c}, \texttt{l},
+% \texttt{r}, \texttt{p}, \texttt{m} or \texttt{b} in the user
+% preamble? In this case we have the problem of the \textsf{token}
+% register from =>{..}= and =<{..}= having to be inserted at this
+% moment because formating instructions like =\hfil= have to be set
+% around them. On the other hand it is not known yet, if any =<{..}=
+% instruction will appear in the user preamble at all.
+%
+% We solve this problem by adding two \textsf{token} registers at a
+% time. This explains, why we have freed the \textsf{token} registers
+% in =\prepnext@tok=.
+%
+% \begin{macro}{\insert@column}
+% \begin{macro}{\@sharp}
+% We now define the macro =\insert@column= which will do
+% this work for us.
+% \begin{macrocode}
+\def\insert@column{%
+% \end{macrocode}
+% Here, we assume that the \textsf{count} register
+% =\@tempcnta= has saved the value $=\count@= - 1$.
+% \begin{macrocode}
+ \the@toks \the \@tempcnta
+% \end{macrocode}
+% Next follows the =#= sign which specifies the place
+% where the text of the column shall be inserted. To avoid
+% errors during the expansions in
+% =\@addtopreamble= we hide this sign in the command
+% =\@sharp= which is temporarily occupied with
+% =\relax= during the build-up of the preamble.
+% To remove unwanted spaces before and after the column text, we set
+% an =\ignorespaces= in front and a =\unskip= afterwards.
+% \changes{v2.0e}{1991/02/07}{Added \{\} around \cs{@sharp} for new ftsel}
+% \changes{v2.0h}{1992/06/22}{Removed \{\} again in favour of
+% \cs{d@llarbegin}}
+% \begin{macrocode}
+ \ignorespaces \@sharp \unskip
+% \end{macrocode}
+% Then the second \textsf{token} register follows whose number should
+% be saved in =\count@=.
+% We make sure that there will be no further expansion after reading
+% the number, by finishing with =\relax=. The case above is not
+% critical since it is ended by =\ignorespaces=.
+% \changes{v2.0c}{1990/08/14}{\cs{relax} added to avoid problem
+% \cs{the}\cs{toks0}\cs{the}\cs{toks1}.}
+% \begin{macrocode}
+ \the@toks \the \count@ \relax}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+%
+%
+%
+% \subsection{The separation of columns}
+%
+% \begin{macro}{\@addamp}
+% In the preamble a =&= has to be inserted between any two columns;
+% before the first column there should not be a =&=. As the user
+% preamble may start with a \texttt{|} we have to remember somehow
+% if we have already inserted a =#= (i.e.\ a column). This is done
+% with the boolean variable =\if@firstamp= that we test in
+% =\@addamp=, the macro that inserts the =&=.
+% \begin{macrocode}
+% \newif \@iffirstamp
+% \def\@addamp{\if@firstamp \@firstampfalse
+% \else \@addtopreamble &\fi}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\@acol}
+% \begin{macro}{\@acolampacol}
+% \begin{macro}{\col@sep}
+% We will now define some abbreviations for the extensions,
+% appearing most often in the preamble build-up.
+% Here =\col@sep= is a \textsf{dimen} register which is set
+% equivalent to =\arraycolsep= in an \textsf{array}--environment,
+% otherwise it is set equivalent to =\tabcolsep=.
+% \begin{macrocode}
+\newdimen\col@sep
+\def\@acol{\@addtopreamble{\hskip\col@sep}}
+% \def\@acolampacol{\@acol\@addamp\@acol}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+%
+% \subsection{The macro \texttt{\textbackslash @mkpream}}
+%
+% \begin{macro}{\@mkpream}
+% \begin{macro}{\the@toks}
+% \label{@mkpream}
+% Now we can define the macro which builds up the preamble for the
+% =\halign=.
+% First we initialize =\@preamble=, =\@lastchclass=
+% and the boolean variable =\if@firstamp=.
+% \begin{macrocode}
+\def\@mkpream#1{\gdef\@preamble{}\@lastchclass 4 \@firstamptrue
+% \end{macrocode}
+% During the build-up of the preamble we cannot directly use the
+% =#= sign; this would lead to an error message in the next
+% =\@addtopreamble= call.
+% Instead, we use the command =\@sharp= at places where later
+% a =#= will be.
+% This command is at first given the meaning =\relax=;
+% therefore it will not be expanded when the preamble
+% is extended.
+% In the macro =\@array=, shortly before the =\halign=
+% is carried out, =\@sharp= is given its final meaning.
+%
+% In a similar way,
+% we deal with the commands =\@startpbox= and
+% =\@endpbox=, although the reason is different here: these
+% macros expand in many \textsf{tokens} which would delay the
+% build-up of the preamble.
+% \begin{macrocode}
+ \let\@sharp\relax \let\@startpbox\relax \let\@endpbox\relax
+% \end{macrocode}
+% Now we remove possible $*$-forms in the user preamble with the
+% command =\@xexpast=. As we already know, this command saves
+% its result in the macro =\@tempa=.
+% \begin{macrocode}
+ \@xexpast #1*0x\@@
+% \end{macrocode}
+% Afterwards we initialize all registers and macros, that we need
+% for the build-up of the preamble.
+% Since we want to start with the \textsf{token} register $0$,
+% =\count@= has to contain the value $-1$.
+% \begin{macrocode}
+ \count@\m@ne
+ \let\the@toks\relax
+% \end{macrocode}
+% Then we call up =\prepnext@tok= in order to prepare the
+% \textsf{token} register $0$ for use.
+% \begin{macrocode}
+ \prepnext@tok
+% \end{macrocode}
+% To evaluate the user preamble (without stars) saved in
+% =\@tempa= we use the \LaTeX--macro =\@tfor=.
+% The strange appearing construction with =\expandafter= is
+% based on the fact that we have to put the replacement text of
+% =\@tempa= and not the macro =\@tempa= to this
+% \LaTeX--macro.
+% \begin{macrocode}
+ \expandafter \@tfor \expandafter \@nextchar
+ \expandafter :\expandafter =\@tempa \do
+% \end{macrocode}
+% The body of this loop (the group after the =\do=)
+% is executed for one \textsf{token} at a time, whereas
+% the current \textsf{token} is saved in =\@nextchar=.
+% At first we evaluate the current \textsf{token} with the already
+% defined macro =\@testpach=, i.e.\ we assign to
+% =\@chclass= the character class and to =\@chnum=
+% the character number of this \textsf{token}.
+% \changes{v2.0f}{1992/02/29}{\cs{@testpach} now without arg}
+% \begin{macrocode}
+ {\@testpach
+% \end{macrocode}
+% Then we branch out depending on the value of =\@chclass= into
+% different macros that extend the preamble respectively.
+% \begin{macrocode}
+ \ifcase \@chclass \@classz \or \@classi \or \@classii
+ \or \save@decl \or \or \@classv \or \@classvi
+ \or \@classvii \or \@classviii \or \@classix
+ \or \@classx \fi
+% \end{macrocode}
+% Two cases deserve our special attention: Since the current
+% \textsf{token} cannot have the character class $4$ (start) we
+% have skipped this possibility. If the character class is $3$,
+% only the content of =\@nextchar= has to be saved into the current
+% \textsf{token} register; therefore we call up =\save@decl=
+% directly and save a macro name. After the preamble has been
+% extended we assign the value of =\@chclass= to the counter
+% =\@lastchclass= to assure that this information will be available
+% during the next run of the loop.
+% \begin{macrocode}
+ \@lastchclass\@chclass}%
+% \end{macrocode}
+% After the loop has been finished space must still be added to
+% the created preamble, depending on the last \textsf{token}.
+% Depending on the value of =\@lastchclass= we perform
+% the necessary operations.
+% \begin{macrocode}
+ \ifcase\@lastchclass
+% \end{macrocode}
+% If the last class equals $0$ we add a
+% =\hskip \col@sep=.
+% \begin{macrocode}
+ \@acol \or
+% \end{macrocode}
+% If it equals $1$ we do not add any additional space so that the
+% horizontal lines do not exceed the vertical ones.
+% \begin{macrocode}
+ \or
+% \end{macrocode}
+% Class $2$ is treated like class $0$ because a =<{...}= can
+% only directly follow after class $0$.
+% \begin{macrocode}
+ \@acol \or
+% \end{macrocode}
+% Most of the other possibilities can only appear if the user
+% preamble was defective. Class $3$ is not allowed since after a
+% =>{..}= there must always follow a \texttt{c}, \texttt{l},
+% \texttt{r}, \texttt{p},\texttt{m} or \texttt{b}. We report an
+% error and ignore the declaration given by ={..}=.
+% \begin{macrocode}
+ \@preamerr \thr@@ \or
+% \end{macrocode}
+% If =\@lastchclass= is $4$ the user preamble has been empty.
+% To continue, we insert a =#= in the preamble.
+% \begin{macrocode}
+ \@preamerr \tw@ \@addtopreamble\@sharp \or
+% \end{macrocode}
+% Class $5$ is allowed again. In this case
+% (the user preamble ends with =@{..}=) we need not
+% do anything.
+% \begin{macrocode}
+ \or
+% \end{macrocode}
+% Any other case means that the arguments to =@=, \texttt{!},
+% \texttt{<}, \texttt{>}, \texttt{p}, \texttt{m} or \texttt{b} have
+% been forgotten. So we report an error and ignore the last
+% \textsf{token}.
+% \begin{macrocode}
+ \else \@preamerr \@ne \fi
+% \end{macrocode}
+% Now that the build-up of the preamble is almost finished we can
+% insert the \textsf{token} registers and therefore redefine
+% =\the@toks=. The actual insertion, though, is performed
+% later.
+% \begin{macrocode}
+ \def\the@toks{\the\toks}}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+%
+%
+% \section{The macros \texttt{\textbackslash @classz}
+% to \texttt{\textbackslash @classx}}
+%
+% The preamble is extended by the macros =\@classz= to
+% =\@classx= which are called by =\@mkpream=
+% depending on =\@lastchclass=
+% (i.e. the character class of the last \textsf{token}).
+% \begin{macro}{\@classx}
+% First we define =\@classx= because of its important r\^ole.
+% When it is called we find that the current
+% \textsf{token} is \texttt{p}, \texttt{m} or \texttt{b}.
+% That means that a new column has to start.
+% \begin{macrocode}
+\def\@classx{%
+% \end{macrocode}
+% Depending on the value of =\@lastchclass= different actions
+% must take place:
+% \begin{macrocode}
+ \ifcase \@lastchclass
+% \end{macrocode}
+% If the last character class was $0$ we separate the columns by
+% =\hskip\col@sep= followed by =&= and another
+% =\hskip\col@sep=.
+% \begin{macrocode}
+ \@acolampacol \or
+% \end{macrocode}
+% If the last class was class $1$ --- that means that a vertical
+% line was
+% drawn, --- before this line a =\hskip\col@sep= was inserted.
+% Therefore there has to be only a =&= followed by
+% =\hskip\col@sep=. But this =&= may be inserted only
+% if this is not the first column. This process is controlled
+% by =\if@firstamp= in the macro =\addamp=.
+% \begin{macrocode}
+ \@addamp \@acol \or
+% \end{macrocode}
+% Class $2$ is treated like class $0$ because =<{...}= can only
+% follow after class $0$.
+% \begin{macrocode}
+ \@acolampacol \or
+% \end{macrocode}
+% Class $3$ requires no actions because all things necessary have
+% been done by the preamble \textsf{token} \texttt{>}.
+% \begin{macrocode}
+ \or
+% \end{macrocode}
+% Class $4$ means that we are at the beginning of the preamble.
+% Therefore we start the preamble with =\hskip\col@sep= and
+% then call =\@firstampfalse=. This makes sure that a later
+% =\@addamp= inserts the character
+% =&= into the preamble.
+% \begin{macrocode}
+ \@acol \@firstampfalse \or
+% \end{macrocode}
+% For class $5$ \textsf{tokens} only the character =&= is inserted
+% as a column separator. Therefore we call =\@addamp=.
+% \begin{macrocode}
+ \@addamp
+% \end{macrocode}
+% Other cases are impossible. For an example
+% $=\@lastchclass= \string= 6$---as it might appear in a
+% preamble of the form =...!p...=---\texttt{p} would have
+% been taken as an argument of \texttt{!}\ by =\@testpach=.
+% \begin{macrocode}
+ \fi}
+% \end{macrocode}
+% \end{macro}
+%
+%
+% \begin{macro}{\@classz}
+% If the character class of the last \textsf{token} is $0$ we have
+% \texttt{c}, \texttt{l}, \texttt{r} or an argument of \texttt{m},
+% \texttt{b} or\ \texttt{p}. In the first three cases the preamble
+% must be extended the same way as if we had class $10$. The
+% remaining two cases do not require any action because the space
+% needed was generated by the last \textsf{token} (i.e.\
+% \texttt{m}, \texttt{b} or \texttt{p}). Since =\@lastchclass= has
+% the value $10$ at this point nothing happens when =\@classx= is
+% called. So the macro =\@chlassz= may start like this:
+% \begin{macrocode}
+\def\@classz{\@classx
+% \end{macrocode}
+% According to the definition of =\insert@column= we must store
+% the number of the \textsf{token} register in which a preceding
+% =>{..}= might have stored its argument into
+% =\@tempcnta=.
+% \begin{macrocode}
+ \@tempcnta \count@
+% \end{macrocode}
+% To have $=\count@= \string= =\@tmpcnta= + 1$ we prepare
+% the next \textsf{token} register.
+% \begin{macrocode}
+ \prepnext@tok
+% \end{macrocode}
+% Now the preamble must be extended with the column whose format
+% can be determinated by =\@chnum=.
+% \begin{macrocode}
+ \@addtopreamble{\ifcase \@chnum
+% \end{macrocode}
+% If =\@chnum= has the value $0$ a centered column has to be
+% generated.
+% So we begin with stretchable space.
+% \begin{macrocode}
+ \hfil
+% \end{macrocode}
+% The command =\d@llarbegin= follows expanding into =\begingroup=
+% (in the \textsf{tabular}--environment) or into =$=. Doing this
+% (provided an appropriate setting of =\d@llarbegin=) we achieve
+% that the contents of the columns of an \textsf{array}--environment
+% are set in math mode while those of a \textsf{tabular}--environment
+% are set in LR mode.
+% \begin{macrocode}
+ \d@llarbegin
+% \end{macrocode}
+% Now we insert the contents of the two \textsf{token} registers
+% and the symbol
+% for the column entry (i.e.\ =#= or
+% more precise =\@sharp=) using =\insert@column=.
+% \begin{macrocode}
+ \insert@column
+% \end{macrocode}
+% We end this case with =\d@llarend= and =\hfil= where =\d@llarend=
+% again is either =$= or =\endgroup=.
+% \begin{macrocode}
+ \d@llarend \hfil \or
+% \end{macrocode}
+% The templates for \texttt{l} and \texttt{r} (i.e.\ =\@chnum= $1$
+% or $2$) are generated the same way. Since one =\hfil= is
+% missing the text is moved to the relevant side.
+% The =\kern\z@= is needed in case of an empty column
+% entry. Otherwise
+% the =\unskip= in =\insert@column= removes the
+% =\hfil=. Changed to =\hskip1sp= so that it interacts better with
+% =\@bsphack=.
+% \changes{v2.3f}{1996/04/22}
+% {(DPC) Extra \cs{kern} keeps tabcolsep in empty l columns
+% internal/2122}
+% \changes{v2.3i}{1996/06/14}
+% {Change both \cs{kern}\cs{z@} to \cs{hskip}1sp for latex/2160}
+% \begin{macrocode}
+ \hskip1sp\d@llarbegin \insert@column \d@llarend \hfil \or
+ \hfil\hskip1sp\d@llarbegin \insert@column \d@llarend \or
+% \end{macrocode}
+% The templates for \texttt{p}, \texttt{m} and \texttt{b} mainly
+% consist of a \textsf{box}. In case of \texttt{m} it is generated
+% by =\vcenter=. This command is allowed only in math
+% mode. Therefore we start with a~=$=.
+% \begin{macrocode}
+ $\vcenter
+% \end{macrocode}
+% The part of the templates which is the same in all three cases
+% (\texttt{p}, \texttt{m} and \texttt{b})
+% is built by the macros =\@startpbox= and
+% =\@endpbox=. =\@startpbox= has an argument:
+% the width of the column which is stored in the current
+% \textsf{token} (i.e.\ =\@nextchar=).
+% Between these two macros we find the well known
+% =\insert@column=.
+% \begin{macrocode}
+ \@startpbox{\@nextchar}\insert@column \@endpbox $\or
+% \end{macrocode}
+% The templates for \texttt{p} and \texttt{b} are generated in the
+% same way though we do not need the =$= characters because we use
+% =\vtop= or =\vbox=.
+% \begin{macrocode}
+ \vtop \@startpbox{\@nextchar}\insert@column \@endpbox \or
+ \vbox \@startpbox{\@nextchar}\insert@column \@endpbox
+% \end{macrocode}
+% Other values for =\@chnum= are impossible. Therefore we
+% end the arguments to =\@addtopreamble= and =\ifcase=.
+% Before we come to the end of =\@classz= we have to
+% prepare the next \textsf{token} register.
+% \begin{macrocode}
+ \fi}\prepnext@tok}
+% \end{macrocode}
+% \end{macro}
+%
+%
+% \begin{macro}{\@classix}
+% In case of class $9$ (\texttt{>}--\textsf{token}) we first check
+% if the character class of the last
+% \textsf{token} was $3$. In this case we have a
+% user preamble of the form =..>{...}>{...}..= which
+% is not allowed. We only give an error message and continue.
+% So the declarations defined by the first =>{...}=
+% are ignored.
+% \begin{macrocode}
+\def\@classix{\ifnum \@lastchclass = \thr@@
+ \@preamerr \thr@@ \fi
+% \end{macrocode}
+% Furthermore, we call up =\@class10= because afterwards always a
+% new column is started by \texttt{c}, \texttt{l}, \texttt{r},
+% \texttt{p}, \texttt{m} or \texttt{b}.
+% \begin{macrocode}
+ \@classx}
+% \end{macrocode}
+% \end{macro}
+%
+%
+%
+% \begin{macro}{\@classviii}
+% If the current \textsf{token} is a \texttt{<} the last character
+% class must be $0$. In this case it is not necessary to extend the
+% preamble. Otherwise we output an error message, set =\@chclass=
+% to $6$ and call =\@classvi=. By doing this we achieve that
+% \texttt{<} is treated like \texttt{!}.
+% \begin{macrocode}
+\def\@classviii{\ifnum \@lastchclass >\z@
+ \@preamerr 4\@chclass 6 \@classvi \fi}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\@arrayrule}
+% There is only one incompatibility with the original definition:
+% the definition of =\@arrayrule=. In the original a line without
+% width\footnote{So the space between \texttt{cc} and \texttt{c|c}
+% is equal.} is created by multiple insertions of
+% =\hskip .5\arrayrulewidth=.
+% We only insert a vertical line into the
+% preamble. This is done to prevent problems with \TeX's main
+% memory when generating tables with many vertical lines in them
+% (especially in the case of \textsf{floats}).
+% \begin{macrocode}
+\def\@arrayrule{\@addtopreamble \vline}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\@classvii}
+% As a consequence it follows that in case of class $7$
+% (=@= \textsf{token}) the preamble need not to be extended.
+% In the original definition $=\@lastchclass= \string= 1$
+% is treated by inserting =\hskip .5\arrayrulewidth=.
+% We only check if the last \textsf{token} was of class $3$ which is
+% forbidden.
+% \begin{macrocode}
+\def\@classvii{\ifnum \@lastchclass = \thr@@
+% \end{macrocode}
+% If this is true we output an error message and
+% ignore the declarations stored
+% by the last =>{...}=, because these are overwritten
+% by the argument of \texttt{@}.
+% \begin{macrocode}
+ \@preamerr \thr@@ \fi}
+% \end{macrocode}
+% \end{macro}
+%
+%
+% \begin{macro}{\@classvi}
+% If the current \textsf{token} is a regular \texttt{!}\ and the
+% last class was $0$ or $2$ we extend the preamble with
+% =\hskip\col@sep=. If the last \textsf{token} was of class $1$
+% (for instance \texttt{|}) we extend with =\hskip \doublerulesep=
+% because the construction =!{...}= has to be treated like
+% \texttt{|}.
+% \begin{macrocode}
+\def\@classvi{\ifcase \@lastchclass
+ \@acol \or
+ \@addtopreamble{\hskip \doublerulesep}\or
+ \@acol \or
+% \end{macrocode}
+% Now =\@preamerr...= should follow because a
+% user preamble of the form =..>{..}!.= is not allowed.
+% To save memory we call =\@classvii= instead which also
+% does what we want.
+% \begin{macrocode}
+ \@classvii
+% \end{macrocode}
+% If =\@lastchclass= is $4$ or $5$ nothing has to be done.
+% Class $6$ to $10$ are not possible.
+% So we finish the macro.
+% \begin{macrocode}
+ \fi}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\@classii}
+% \begin{macro}{\@classiii}
+% In the case of character classes $2$ and $3$ (i.e.\ the argument
+% of \texttt{<} or \texttt{>}) we only have to store the current
+% \textsf{token} (=\@nextchar=) into the corresponding
+% \textsf{token} register since the preparation and
+% insertion of these registers
+% are done by the macro =\@classz=.
+% This is equivalent to calling =\save@decl= in the case of
+% class $3$. To save command identifiers we do this call up
+% in the macro =\@mkpream=.
+%
+% Class $2$ exhibits a more complicated situation: the
+% \textsf{token} registers have already been inserted by
+% =\@classz=. So the value of =\count@= is too high
+% by one. Therefore we decrease =\count@= by $1$.
+% \begin{macrocode}
+\def\@classii{\advance \count@ \m@ne
+% \end{macrocode}
+% Next we store the current \textsf{token} into the correct
+% \textsf{token} register by calling =\save@decl= and then
+% increase the value of =\count@= again. At this point we
+% can save memory once more (at the cost of time) if we use the
+% macro =\prepnext@tok=.
+% \begin{macrocode}
+ \save@decl\prepnext@tok}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+%
+% \begin{macro}{\@classv}
+% If the current \textsf{token} is of class $5$ then it is an
+% argument of a \texttt{@} \textsf{token}. It must be stored into a
+% \textsf{token} register.
+% \begin{macrocode}
+\def\@classv{\save@decl
+% \end{macrocode}
+% We extend the preamble with a command which inserts this
+% \textsf{token} register into the preamble when its construction
+% is finished. The user expects that this argument is worked out in
+% math mode if it was used in an
+% \textsf{array}--environment. Therefore we surround it with
+% =\d@llar...='s.
+% \changes{v2.0c}{1990/08/14}{\cs{relax} added to avoid problem
+% `the`toks0`the`toks1.}
+% \begin{macrocode}
+ \@addtopreamble{\d@llarbegin\the@toks\the\count@\relax\d@llarend}%
+% \end{macrocode}
+% Finally we must prepare the next \textsf{token} register.
+% \begin{macrocode}
+ \prepnext@tok}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\@classi}
+% In the case of class $0$ we were able to generate the necessary
+% space between columns by using the macro =\@classx=.
+% Analogously the macro =\@classvi= can be used for class $1$.
+% \begin{macrocode}
+\def\@classi{\@classvi
+% \end{macrocode}
+% Depending on =\@chnum= a vertical line
+% \begin{macrocode}
+ \ifcase \@chnum \@arrayrule \or
+% \end{macrocode}
+% or (in case of =!{...}=) the current \textsf{token} --- stored
+% in =\@nextchar= --- has to be inserted into the preamble.
+% This corresponds to calling =\@classv=.
+% \begin{macrocode}
+ \@classv \fi}
+% \end{macrocode}
+% \end{macro}
+%
+%
+%
+% \begin{macro}{\@startpbox}
+% In =\@classz= the macro =\@startpbox= is used.
+% The width of the \textsf{parbox} is passed as an argument.
+% =\vcenter=, =\vtop= or =\vbox= are already in the
+% preamble. So we start with the braces for the wanted box.
+% \begin{macrocode}
+\def\@startpbox#1{\bgroup
+% \end{macrocode}
+% The argument is the width of the box. This information has to be
+% assigned to =\hsize=.
+% Then we assain default values to several parameters used in a
+% \textsf{parbox}.
+% \changes{v2.3k}{1998/05/12}{Use \cs{setlength} to set \cs{hsize},
+% so that the calc package can be applied here (pr/2793)}
+% \begin{macrocode}
+ \setlength\hsize{#1}\@arrayparboxrestore
+% \end{macrocode}
+% Our main problem is to obtain the same distance between succeeding
+% lines of the \textsf{parbox}.
+% We have to remember that the distance between two \textsf{parboxes}
+% should be defined by =\@arstrut=. That means that it can be
+% greater than the distance in a \textsf{parbox}.
+% Therefore it is not enough to set a =\@arstrut= at the
+% beginning and at the end of the \textsf{parbox}. This would
+% dimension the distance
+% between first and second line and the distance between the two
+% last lines of the \textsf{parbox} wrongly.
+% To prevent this we set an invisible rule of height
+% =\@arstrutbox=
+% at the beginning of the \textsf{parbox}. This has no effect on the
+% depth of the first line. At the end of the \textsf{parbox} we set
+% analogously another invisible rule which only affects the depth
+% of the last line. It is necessary to wait inserting this strut
+% until the paragraph actually starts to allow for things like
+% =\parindent= changes via =>{...}=.
+% \changes{v2.1c}{1992/12/14}{Use `everypar to insert strut}
+% \begin{macrocode}
+ \everypar{%
+ \vrule \@height \ht\@arstrutbox \@width \z@
+ \everypar{}}%
+ }
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\@endpbox}
+% If there are any declarations defined by =>{...}=
+% and =<{...}=
+% they now follow in the macro =\@classz= --- the contents
+% of the column in between.
+% So the macro =\@endpbox= must insert the \textsf{specialstrut}
+% mentioned earlier and then close the group opened by
+% =\@startpbox=.
+% \changes{v2.2d}{1994/05/16}{Use \LaTeXe \cs{@finalstrut}}
+% \changes{v2.3g}{1996/05/07}{Add \cs{hfil} for tools/2120}
+% \begin{macrocode}
+\def\@endpbox{\@finalstrut\@arstrutbox \egroup\hfil}
+% \end{macrocode}
+% \end{macro}
+%
+%
+% \section{Building and calling \texttt{\textbackslash halign}}
+%
+% \begin{macro}{\@array}
+% After we have discussed the macros needed for the evaluation
+% of the user preamble we can define the macro =\@array=
+% which uses these macros to create a =\halign=.
+% It has two arguments. The first one is a position argument
+% which can be \texttt{t}, \texttt{b} or \texttt{c}; the
+% second one describes the wanted preamble,
+% e.g.\ it has the form =|c|c|c|=.
+% \begin{macrocode}
+\def\@array[#1]#2{%
+% \end{macrocode}
+% First we define a \textsf{strut} whose size basically corresponds
+% to a normal \textsf{strut} multiplied by the factor
+% =\arraystretch=.
+% This \textsf{strut} is then inserted into every row and enforces
+% a minimal distance between two rows.
+% Nevertheless, when using horizontal lines, large letters
+% (like accented capital letters) still collide with such lines.
+% Therefore at first we add to the height of a normal \textsf{strut}
+% the value of the parameter =\extrarowheight=.
+% \begin{macrocode}
+ \@tempdima \ht \strutbox
+ \advance \@tempdima by\extrarowheight
+ \setbox \@arstrutbox \hbox{\vrule
+ \@height \arraystretch \@tempdima
+ \@depth \arraystretch \dp \strutbox
+ \@width \z@}%
+% \end{macrocode}
+% Then we open a group, in which the user preamble is evaluated by
+% the macro =\@mkpream=. As we know this must happen locally.
+% This macro creates a preamble for a =\halign= and saves
+% its result globally in the control sequence =\@preamble=.
+% \begin{macrocode}
+ \begingroup
+ \@mkpream{#2}%
+% \end{macrocode}
+% We again redefine =\@preamble= so that a call up of =\@preamble=
+% now starts the =\halign=. Thus also the arguments of \texttt{>},
+% \texttt{<}, \texttt{@} and \texttt{!}, saved in the
+% \textsf{token} registers are inserted into the preamble. The
+% =\tabskip= at the beginning and end of the preamble is set to
+% \textsf{0pt} (in the beginning by the use of =\ialign=). Also the
+% command =\@arstrut= is build in, which inserts the
+% =\@arstrutbox=, defined above. Of course, the opening brace after
+% =\ialign= has to be implicit as it will be closed in =\endarray=
+% or another macro.
+% \changes{v2.3m}{1998/12/31}{Added \cs{noexpand} in front of \cs{ialign}
+% to guard against interesting :-) changes to \cs{halign} done to support
+% text glyphs in math}
+%
+% The =\noexpand= in front of =\ialign= does no harm in standard \LaTeX{}
+% and was added since some experimental support for using text glyphs in math
+% redefines =\halign= with the result that is becomes expandable with
+% disastrous results in cases like this.
+% In the kernel definition for this macro the problem does
+% not surface because there =\protect= is set (which is not necessary in this
+% implementation as there is no arbitrary user input that can get expanded) and
+% the experimental code made the redefinition robust. Whether this is the right
+% approach is open to question; consider the =\noexpand= a curtesy to allow an
+% unsupported redefinition of a \TeX{} primitive for the moment (as people rely
+% on that experimental code).
+% \begin{macrocode}
+ \xdef\@preamble{\noexpand \ialign \@halignto
+ \bgroup \@arstrut \@preamble
+ \tabskip \z@ \cr}%
+% \end{macrocode}
+% What we have not explained yet is the macro =\@halignto=
+% that was just used. Depending on its replacement text the
+% =\halign= becomes a =\halign= \texttt{to} \meta{dimen}.
+% Now we close the group again. Thus
+% =\@startpbox= and =\@endpbox= as well as all
+% \textsf{token} registers get their former meaning back.
+% \begin{macrocode}
+ \endgroup
+% \end{macrocode}
+% To support the \texttt{delarray.sty} package we include a hook
+% into this part of the code which is a no-op in the main package.
+% \changes{v2.1a}{1992/07/03}{Hook for delarray added}
+% \begin{macrocode}
+ \@arrayleft
+% \end{macrocode}
+% Now we decide depending on the position argument in which
+% \textsf{box} the =\halign= is to be put. (=\vcenter= may be used
+% because we are in math mode.)
+% \changes{v2.1a}{1992/07/03}{Wrong spec is now equiv to [t]}
+% \begin{macrocode}
+ \if #1t\vtop \else \if#1b\vbox \else \vcenter \fi \fi
+% \end{macrocode}
+% Now another implicit opening brace appears; then definitions
+% which shall stay local follow. While constructing the
+% =\@preamble= in =\@mkpream= the =#= sign must be
+% hidden in the macro =\@sharp= which is =\let= to
+% =\relax= at that moment (see definition of =\@mkpream=
+% on page~\pageref{@mkpream}).
+% All these now get their actual meaning.
+% \begin{macrocode}
+ \bgroup
+ \let \@sharp ##\let \protect \relax
+% \end{macrocode}
+% With the above defined \textsf{struts} we fix down the distance
+% between rows by setting =\lineskip= and =\baselineskip=
+% to \textsf{0pt}. Since there have to be set =$='s
+% around every column in the \textsf{array}--environment
+% the parameter =\mathsurround= should
+% also be set to \textsf{0pt}. This prevents additional space between
+% the rows. The
+% \PlainTeX--macro =\m@th= does this.
+% \begin{macrocode}
+ \lineskip \z@
+ \baselineskip \z@
+ \m@th
+% \end{macrocode}
+% Beside, we have to assign a special meaning (which we still have
+% to specify) to the line separator =\\=. We also have to
+% redefine the command =\par= in such a way that empty lines in
+% =\halign= cannot do any damage. We succeed in doing so
+% by choosing something that will disappear when expanding.
+% After that we only have to call up =\@preamble= to
+% start the wanted =\halign=.
+% \changes{1994/12/08}{v2.3b}{add \cs{tabularnewline}}
+% \begin{macrocode}
+ \let\\\@arraycr \let\tabularnewline\\\let\par\@empty \@preamble}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\arraybackslash}
+% \changes{v2.4a}{2003/12/17}{(DPC) Macro added (from tabularx)}
+% Restore |\\| for use in array and tabular environment (after
+% |\raggedright| etc.).
+% \begin{macrocode}
+\def\arraybackslash{\let\\\tabularnewline}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\extrarowheight}
+% The \textsf{dimen} parameter used above also needs to be
+% allocated. As a default value we use \textsf{0pt}, to ensure
+% compatibility with standard \LaTeX.
+% \begin{macrocode}
+\newdimen \extrarowheight
+\extrarowheight=0pt
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\@arstrut}
+% Now the insertion of =\@arstrutbox= through =\@arstut=
+% is easy since we know exactly in which mode \TeX\ is while working
+% on the =\halign= preamble.
+% \begin{macrocode}
+\def\@arstrut{\unhcopy\@arstrutbox}
+% \end{macrocode}
+% \end{macro}
+%
+%
+% \section{The line separator \texttt{\textbackslash\textbackslash}}
+%
+% \begin{macro}{\@arraycr}
+% In the macro =\@array= the line separator =\\= is
+% =\let= to the command =\@arraycr=.
+% Its definition starts with a special brace which I have directly
+% copied from the original definition. It is
+% necessary, because the =\futurlet= in =\@ifnextchar=
+% might
+% expand a following =&= \textsf{token} in a construction like
+% =\\ &=. This would otherwise end the alignment template at a
+% wrong time. On the other hand we have to be careful to avoid
+% producing a real group, i.e.\ ={}=, because the command will also
+% be used for the array environment, i.e.\ in math mode. In that
+% case an extra ={}= would produce an ord atom which could mess up
+% the spacing. For this reason we use a combination that does not
+% really produce a group at all but modifies the master counter so
+% that a =&= will not be considered belonging to the current
+% =\halign= while we are looking for a =*= or =[=.
+% For further information see
+% \cite[Appendix D]{bk:knuth}.
+% \changes{v2.3c}{1995/04/23}{Avoid adding an ord atom in math}
+% \begin{macrocode}
+\def\@arraycr{\relax\iffalse{\fi\ifnum 0=`}\fi
+% \end{macrocode}
+% Then we test whether the user is using the star form and ignore
+% a possible star (I also disagree with this procedure, because a
+% star does not make any sense here).
+% \begin{macrocode}
+ \@ifstar \@xarraycr \@xarraycr}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\@xarraycr}
+% In the command =\@xarraycr= we test if an optional argument
+% exists.
+% \begin{macrocode}
+\def\@xarraycr{\@ifnextchar [%
+% \end{macrocode}
+% If it does, we branch out into the macro =\@argarraycr= if
+% not we close the special brace (mentioned above) and end the row
+% of the =\halign= with a =\cr=.
+% \changes{v2.3c}{1995/04/23}{Avoid adding an ord atom in math}
+% \begin{macrocode}
+ \@argarraycr {\ifnum 0=`{}\fi\cr}}
+% \end{macrocode}
+% \end{macro}
+%
+%
+% \begin{macro}{\@argarraycr}
+% If additional space is requested by the user this case is treated
+% in the macro =\@argarraycr=. First we close the special brace
+% and then we test if the additional space is positive.
+% \changes{v2.3c}{1995/04/23}{Avoid adding an ord atom in math}
+% \begin{macrocode}
+\def\@argarraycr[#1]{\ifnum0=`{}\fi\ifdim #1>\z@
+% \end{macrocode}
+% If this is the case we create an invisible vertical rule with
+% depth =\dp\@arstutbox=${}+{}$\meta{wanted\ space}.
+% Thus we achieve that all vertical lines specified
+% in the user preamble by a \texttt{|} are now
+% generally drawn.
+% Then the row ends with a =\cr=.
+%
+% If the space is negative we end the row at once with a =\cr=
+% and move back up with a =\vskip=.
+%
+% While testing these macros I found out that the
+% =\endtemplate=
+% created by =\cr= and =&= is something like an
+% =\outer= primitive and therefore it should not appear in
+% incomplete =\if= statements. Thus the following solution was
+% chosen which hides the =\cr= in other macros when \TeX\
+% is skipping conditional text.
+% \changes{v2.3c}{1995/04/23}{Use \cs{expandafter}'s in conditional}
+% \begin{macrocode}
+ \expandafter\@xargarraycr\else
+ \expandafter\@yargarraycr\fi{#1}}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\@xargarraycr}
+% \begin{macro}{\@yargarraycr}
+% The following macros were already explained above.
+% \begin{macrocode}
+\def\@xargarraycr#1{\unskip
+ \@tempdima #1\advance\@tempdima \dp\@arstrutbox
+ \vrule \@depth\@tempdima \@width\z@ \cr}
+\def\@yargarraycr#1{\cr\noalign{\vskip #1}}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+%
+%
+%
+% \section{Spanning several columns}
+%
+% \begin{macro}{\multicolumn}
+% If several columns should be held together with a special format
+% the command =\multicolumn= must be used. It has three
+% arguments: the number of columns to be covered; the format for
+% the result column and the actual column entry.
+% \changes{v2.3j}{1998/01/29}{Command made \cs{long} to match
+% kernel change for pr/2180}
+% \begin{macrocode}
+\long\def\multicolumn#1#2#3{%
+% \end{macrocode}
+% First we combine the given number of columns into a single one;
+% then we start a new block so that the following definition is kept
+% local.
+% \begin{macrocode}
+ \multispan{#1}\begingroup
+% \end{macrocode}
+% Since a =\multicolumn= should only describe the format of a
+% result column, we redefine =\@addamp= in such a way that one gets
+% an error message if one uses more than one \texttt{c},
+% \texttt{l}, \texttt{r}, \texttt{p}, \texttt{m} or \texttt{b} in
+% the second argument. One should consider that this definition is
+% local to the build-up of the preamble; an \textsf{array}-- or
+% \textsf{tabular}--environment in the third argument of the
+% =\multicolumn= is therefore worked through correctly as well.
+% \begin{macrocode}
+ \def\@addamp{\if@firstamp \@firstampfalse \else
+ \@preamerr 5\fi}%
+% \end{macrocode}
+% Then we evaluate the second argument with the help of
+% =\@mkpream=.
+% Now we still have to insert the contents of the \textsf{token}
+% register into the =\@preamble=, i.e.\ we have to say
+% =\xdef\@preamble{\@preamble}=. This is achieved shorter by
+% writing:
+% \begin{macrocode}
+ \@mkpream{#2}\@addtopreamble\@empty
+% \end{macrocode}
+% After the =\@preamble= is created we forget all local
+% definitions and occupations of the \textsf{token} registers.
+% \begin{macrocode}
+ \endgroup
+% \end{macrocode}
+% In the special situation of =\multicolumn= =\@preamble=
+% is not needed as preamble for a =\halign= but it is directly
+% inserted into our table. Thus instead of =\sharp=
+% there has to be the column entry (=#3=) wanted by the user.
+% \begin{macrocode}
+ \def\@sharp{#3}%
+% \end{macrocode}
+% Now we can pass the =\@preamble= to \TeX\ . For safety
+% we start with an =\@arstrut=. This should usually be in the
+% template for the first column however we do not know if this
+% template was overwritten by our =\multicolumn=.
+% We also add a =\null= at the right end to prevent any following
+% =\unskip= (for example from =\\[..]=) to remove the =\tabcolsep=.
+% \changes{v2.2e}{1994/06/01}{Added \cs{null}}
+% \begin{macrocode}
+ \@arstrut \@preamble
+ \null
+ \ignorespaces}
+% \end{macrocode}
+% \end{macro}
+%
+%
+%
+% \section{The Environment Definitions}
+%
+% After these preparations we are able to define the environments. They
+% only differ in the initialisations of =\d@llar...=, =\col@sep=
+% and =\@halignto=.
+%
+% \begin{macro}{\@halignto}
+% \begin{macro}{\d@llarbegin}
+% \begin{macro}{\d@llarend}
+% In order to relieve the \textsf{save stack} we assign the
+% replacement texts for =\@halignto= globally. =\d@llar= has to be
+% local since otherwise nested \textsf{tabular} and \textsf{array}
+% environments (via =\multicolumn=) are impossible.
+% \changes{v2.0g}{1992/06/18}{`d@llarbegin defined on toplevel.}
+% When the new font selection scheme is in force we have to
+% we surround all =\halign= entries
+% with braces. See remarks in TUGboat 10\#2. Actually we are going
+% to use =\begingroup= and =\endgroup=. However, this is only
+% necessary when we are in text mode. In math the surrounding
+% dollar signs will already serve as the necessary extra grouping
+% level. Therefore we switch the settings of =\d@llarbegin= and
+% =\d@llarend= between groups and dollar signs.
+% \begin{macrocode}
+\let\d@llarbegin\begingroup
+\let\d@llarend\endgroup
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+%
+% \begin{macro}{\array}
+% Our new definition of =\array= then reads:
+% \changes{v2.0d}{1990/08/20}{`d@llar local to preamble.}
+% \begin{macrocode}
+\def\array{\col@sep\arraycolsep
+ \def\d@llarbegin{$}\let\d@llarend\d@llarbegin\gdef\@halignto{}%
+% \end{macrocode}
+% Since there might be an optional argument we call another
+% macro which is also used by the other environments.
+% \begin{macrocode}
+ \@tabarray}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\@tabarray}
+% This macro tests for a optional bracket and then calls up
+% =\@array= or =\@array[c]= (as default).
+% \begin{macrocode}
+\def\@tabarray{\@ifnextchar[{\@array}{\@array[c]}}
+% \end{macrocode}
+% \end{macro}
+%
+%
+% \begin{macro}{\tabular}
+% \begin{macro}{\tabular*}
+% The environments \textsf{tabular} and \textsf{tabular$*$} differ
+% only in the initialisation of the command =\@halignto=. Therefore
+% we define
+% \begin{macrocode}
+\def\tabular{\gdef\@halignto{}\@tabular}
+% \end{macrocode}
+% and analoguesly for the star form. We evalute the argument first
+% using =\setlength= so that users of the \texttt{calc} package can
+% write code like\\ =\begin{tabular*}{(\columnwidth-1cm)/2}...=
+% \changes{v2.3l}{1998/05/13}{Use \cs{setlength} evaluate arg
+% so that the calc package can be applied here (pr/2793)}
+% \begin{macrocode}
+\expandafter\def\csname tabular*\endcsname#1{%
+ \setlength\dimen@{#1}%
+ \xdef\@halignto{to\the\dimen@}\@tabular}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\@tabular}
+% The rest of the job is carried out by the =\@tabular= macro:
+% \begin{macrocode}
+\def\@tabular{%
+% \end{macrocode}
+% First of all we have to make sure that we start out in
+% \textsf{hmode}. Otherwise we might find our table dangling by
+% itself on a line.
+% \begin{macrocode}
+ \leavevmode
+% \end{macrocode}
+% It should be taken into consideration that the macro =\@array=
+% must be called in math mode. Therefore we open a \textsf{box},
+% insert a =$= and then assign the correct values to =\col@sep= and
+% =\d@llar...=.
+% \changes{v2.0d}{1990/08/20}{`d@llar local to preamble.}
+% \begin{macrocode}
+ \hbox \bgroup $\col@sep\tabcolsep \let\d@llarbegin\begingroup
+ \let\d@llarend\endgroup
+% \end{macrocode}
+% Now everything \textsf{tabular} specific is done and we are able to
+% call the =\@tabarray= macro.
+% \begin{macrocode}
+ \@tabarray}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\endarray}
+% When the processing of \textsf{array} is finished we have to
+% close the =\halign=
+% and afterwards the surrounding \textsf{box} selected by
+% =\@array=. To save \textsf{token} space we then redefine
+% =\@preamble=
+% because its replacement text isn't longer needed.
+% \begin{macrocode}
+\def\endarray{\crcr \egroup \egroup \gdef\@preamble{}}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\endtabular}
+% \begin{macro}{\endtabular*}
+% To end a \textsf{tabular} or \textsf{tabular$*$} environment we
+% call up =\endarray=, close the math mode and then the surrounding
+% =\hbox=.
+% \begin{macrocode}
+\def\endtabular{\endarray $\egroup}
+\expandafter\let\csname endtabular*\endcsname=\endtabular
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+%
+%
+% \section{Last minute definitions}
+%
+%
+% If this file is used as a package file we should =\let= all macros
+% to =\relax= that were used in the original but are no longer
+% necessary.
+% \begin{macrocode}
+\let\@ampacol=\relax \let\@expast=\relax
+\let\@arrayclassiv=\relax \let\@arrayclassz=\relax
+\let\@tabclassiv=\relax \let\@tabclassz=\relax
+\let\@arrayacol=\relax \let\@tabacol=\relax
+\let\@tabularcr=\relax \let\@@endpbox=\relax
+\let\@argtabularcr=\relax \let\@xtabularcr=\relax
+% \end{macrocode}
+%
+% \begin{macro}{\@preamerr}
+% We also have to redefine the error routine =\@preamerr= since
+% new kind of errors are possible.
+% The code for this macro is not perfect yet;
+% it still needs too much memory.
+% \begin{macrocode}
+\def\@preamerr#1{\def\@tempd{{..} at wrong position: }%
+ \PackageError{array}{%
+ \ifcase #1 Illegal pream-token (\@nextchar): `c' used\or %0
+ Missing arg: token ignored\or %1
+ Empty preamble: `l' used\or %2
+ >\@tempd token ignored\or %3
+ <\@tempd changed to !{..}\or %4
+ Only one column-spec. allowed.\fi}\@ehc} %5
+% \end{macrocode}
+% \end{macro}
+%
+%
+%
+% \section
+% [Defining your own column specifiers]
+% {Defining your own column specifiers\footnotemark}
+%
+% \footnotetext{The code and the documentation in this section was
+% written by David. So far only the code from newarray was plugged
+% into array so that some parts of the documentation still claim
+% that this is newarray and even worse, some parts of the code are
+% unnecessarily doubled. This will go away in a future release. For
+% the moment we thought it would be more important to bring both
+% packages together.}
+% \changes{v2.1a}{1992/07/03}{Newcolumn stuff added}
+%
+% \DeleteShortVerb{\=}
+% \MakeShortVerb{\"}
+%
+% \begin{macro}{\newcolumn}
+% In \texttt{newarray.sty} the macro for specifying new columns was
+% named "\newcolumn". When the functionality was added to
+% \texttt{array.sty} the command was renamed "\newcolumntype".
+% Initially both names were supported, but now (In versions of this
+% package distributed for \LaTeXe) the old name is not defined.
+% \changes{v2.2a}{1994/02/03}{Now made `newcolumn an error}
+% \changes{v2.2a}{1994/02/04}{Removed `newcolumn}
+% \begin{macrocode}
+%<*ncols>
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\newcolumntype}
+% \changes{v2.1b}{1992/06/07}{Macro renamed from `newcolumn} As
+% described above, the "\newcolumntype" macro gives users the chance
+% to define letters, to be used in the same way as the primitive
+% column specifiers, `c' `p' etc.
+% \begin{macrocode}
+\def\newcolumntype#1{%
+% \end{macrocode}
+% "\NC@char" was added in V2.01 so that active characters, like "@" in
+% AMS\LaTeX\ may be used. This trick was stolen from \texttt{array.sty}
+% 2.0h. Note that we need to use the possibly active token,
+% "#1", in several places, as that is the token that actually
+% appears in the preamble argument.
+% \begin{macrocode}
+ \edef\NC@char{\string#1}%
+% \end{macrocode}
+% First we check whether there is already a definition for this column.
+% Unlike "\newcommand" we give a warning rather than an error if it is
+% defined. If it is a new column, add "\NC@do" \meta{column} to
+% the list "\NC@list".
+% \begin{macrocode}
+ \@ifundefined{NC@find@\NC@char}%
+ {\@tfor\next:=<>clrmbp@!|\do{\if\noexpand\next\NC@char
+ \PackageWarning{array}%
+ {Redefining primitive column \NC@char}\fi}%
+ \NC@list\expandafter{\the\NC@list\NC@do#1}}%
+ {\PackageWarning{array}{Column \NC@char\space is already defined}}%
+% \end{macrocode}
+% Now we define a macro with an argument delimited by the new column
+% specifier, this is used to find occurences of this specifier in the
+% user preamble.
+% \begin{macrocode}
+ \@namedef{NC@find@\NC@char}##1#1{\NC@{##1}}%
+% \end{macrocode}
+% If an optional argument was not given, give a default argument of 0.
+% \begin{macrocode}
+ \@ifnextchar[{\newcol@{\NC@char}}{\newcol@{\NC@char}[0]}}
+% \end{macrocode}
+% \end{macro}
+% \begin{macro}{\newcol@}
+% We can now define the macro which does the rewriting,
+% "\@reargdef" takes the same arguments as "\newcommand", but
+% does not check that the command is new. For a column, say `D' with
+% one argument, define a command "\NC@rewrite@D" with one
+% argument, which recursively calls "\NC@find" on the user preamble
+% after replacing the first token or group with the replacement text
+% specified in the "\newcolumntype" command. "\NC@find" will find the
+% next occurrence of `D' as it will be "\let" equal to
+% "\NC@find@D" by "\NC@do".
+% \begin{macrocode}
+\def\newcol@#1[#2]#3{\expandafter\@reargdef
+ \csname NC@rewrite@#1\endcsname[#2]{\NC@find#3}}
+% \end{macrocode}
+% \end{macro}
+% \begin{macro}{\NC@}
+% Having found an occurence of the new column, save the preamble
+% before the column in "\@temptokena", then check to see if we
+% are at the end of the preamble. (A dummy occurrence of the column
+% specifier will be placed at the end of the preamble by "\NC@do".
+% \begin{macrocode}
+\def\NC@#1{%
+ \@temptokena\expandafter{\the\@temptokena#1}\futurelet\next\NC@ifend}
+% \end{macrocode}
+% \end{macro}
+% \begin{macro}{\NC@ifend}
+% We can tell that we are at the end as "\NC@do" will place a "\relax"
+% after the dummy column.
+% \begin{macrocode}
+\def\NC@ifend{%
+% \end{macrocode}
+% If we are at the end, do nothing. (The whole preamble will now be in
+% "\@temptokena".)
+% \begin{macrocode}
+ \ifx\next\relax
+% \end{macrocode}
+% Otherwise set the flag "\if@tempswa", and rewrite the column.
+% "\expandafter" introduced 1n V2.01
+% \begin{macrocode}
+ \else\@tempswatrue\expandafter\NC@rewrite\fi}
+% \end{macrocode}
+% \end{macro}
+% \begin{macro}{\NC@do}
+% If the user has specified `C' and `L' as new columns, the list of
+% rewrites (in the token register "\NC@list") will look like
+% "\NC@do *" "\NC@do C" "\NC@do L".
+% So we need to define "\NC@do" as a one argument macro which
+% initialises the rewriting of the specified column. Let us assume that
+% `C' is the argument.
+% \begin{macrocode}
+\def\NC@do#1{%
+% \end{macrocode}
+% First we let "\NC@rewrite" and "\NC@find" be
+% "\NC@rewrite@C" and "\NC@find@C" respectively.
+% \begin{macrocode}
+ \expandafter\let\expandafter\NC@rewrite
+ \csname NC@rewrite@\string#1\endcsname
+ \expandafter\let\expandafter\NC@find
+ \csname NC@find@\string#1\endcsname
+% \end{macrocode}
+% Clear the token register "\@temptokena" after putting the present
+% contents of the register in front of the token "\NC@find". At the
+% end we place the tokens `"C\relax"' which "\NC@ifend" will use
+% to detect the end of the user preamble.
+% \begin{macrocode}
+ \expandafter\@temptokena\expandafter{\expandafter}%
+ \expandafter\NC@find\the\@temptokena#1\relax}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\showcols}
+% This macro is useful for debugging "\newcolumntype" specifications,
+% it is the equivalent of the primitive "\show" command for macro
+% definitions. All we need to do is locally redefine "\NC@do" to take
+% its argument (say `C') and then "\show" the (slightly modified)
+% definition of "\NC@rewrite@C". Actually as the the list always
+% starts off with "\NC@do *" and we do not want to print the
+% definition of the $*$-form, define "\NC@do" to throw away the first
+% item in the list, and then redefine itsef to print the rest of the
+% definitions.
+% \begin{macrocode}
+\def\showcols{{\def\NC@do##1{\let\NC@do\NC@show}\the\NC@list}}
+% \end{macrocode}
+% \end{macro}
+% \begin{macro}{\NC@show}
+% If the column `C' is defined as above, then
+% "\show\NC@rewrite@C" would output\\
+% "\long macro: ->\NC@find >{$}c<{$}".
+% We want to strip the "long macro: ->" and the "\NC@find". So first we
+% use "\meaning" and then apply the macro "\NC@strip" to the tokens so
+% produced and then "\typeout" the required string.
+% \begin{macrocode}
+\def\NC@show#1{%
+ \typeout{Column #1\expandafter\expandafter\expandafter\NC@strip
+ \expandafter\meaning\csname NC@rewrite@#1\endcsname\@@}}
+% \end{macrocode}
+% \end{macro}
+% \begin{macro}{\NC@strip}
+% Delimit the arguments to "\NC@strip" with `\texttt{:}', `\texttt{->}',
+% a space, and "\@@" to pull out the required parts of the output from
+% "\meaning".
+% \begin{macrocode}
+\def\NC@strip#1:#2->#3 #4\@@{#2 -> #4}
+% \end{macrocode}
+% \end{macro}
+% \begin{macro}{\NC@list}
+% Allocate the token register used for the rewrite list.
+% \begin{macrocode}
+\newtoks\NC@list
+% \end{macrocode}
+% \end{macro}
+%
+% \subsection{The $*$--form}
+% We view the $*$-form as a slight generalisation of the system
+% described in the previous subsection. The idea is to define a $*$
+% column by a command of the form:
+% \begin{verbatim}
+% \newcolumntype{*}[2]{%
+% \count@=#1\ifnum\count@>0
+% \advance\count@ by -1 #2*{\count@}{#2}\fi}
+% \end{verbatim}
+% \begin{macro}{\NC@rewrite@*}\label{NC@rewrite@*}
+% This does not work however as "\newcolumntype" takes great care not
+% to expand anything in the preamble, and so the "\if" is never
+% expanded. "\newcolumntype" sets up various other parts of the
+% rewrite correctly though so we can define:
+% \begin{macrocode}
+\newcolumntype{*}[2]{}
+% \end{macrocode}
+% Now we must correct the definition of "\NC@rewrite@*". The
+% following is probably more efficient than a direct translation of
+% the idea sketched above, we do not need to put a $*$ in the preamble
+% and call the rewrite recursively, we can just put "#1" copies of
+% "#2" into "\@temptokena". (Nested $*$ forms will be expanded
+% when the whole rewrite list is expanded again, see "\@mkpream")
+% \begin{macrocode}
+\long\@namedef{NC@rewrite@*}#1#2{%
+% \end{macrocode}
+% Store the number.
+% \begin{macrocode}
+ \count@#1
+% \end{macrocode}
+% Put "#1" copies of "#2" in the token register.
+% \begin{macrocode}
+ \loop
+ \ifnum\count@>\z@
+ \advance\count@\m@ne
+ \@temptokena\expandafter{\the\@temptokena#2}%
+ \repeat
+% \end{macrocode}
+% "\NC@do" will ensure that "\NC@find" is "\let" equal
+% to "\NC@find@*".
+% \begin{macrocode}
+ \NC@find}
+% \end{macrocode}
+% \end{macro}
+%
+% \subsection{Modifications to internal macros of \texttt{array.sty}}
+%
+% \begin{macro}{\@xexpast}
+% \begin{macro}{\@xexnoop}
+% These macros are used to expand $*$-forms in
+% \texttt{array.sty}. "\let" them to "\relax" to save space.
+% \begin{macrocode}
+\let\@xexpast\relax
+\let\@xexnoop\relax
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\save@decl}
+% We do not assume that the token register is free, we add the new
+% declarations to the front of the register. This is to allow user
+% preambles of the form, ">{foo}>{bar}..". Users are not encouraged to
+% enter such expressions directly, but they may result from the
+% rewriting of "\newcolumntype"'s.
+% \begin{macrocode}
+\def\save@decl{\toks \count@ = \expandafter\expandafter\expandafter
+ {\expandafter\@nextchar\the\toks\count@}}
+% \end{macrocode}
+% \end{macro}
+% \begin{macro}{\@mkpream}
+% The main modification to "\@mkpream" is to replace the call to
+% "\@xexpast" (which expanded $*$-forms) by a loop which expands
+% all "\newcolumntype" specifiers.
+% \begin{macrocode}
+\def\@mkpream#1{\gdef\@preamble{}\@lastchclass 4 \@firstamptrue
+ \let\@sharp\relax \let\@startpbox\relax \let\@endpbox\relax
+% \end{macrocode}
+% Now we remove possible $*$-forms and user-defined column
+% specifiers in the user preamble by repeatedly executing the list
+% "\NC@list" until the re-writes have no more effect. The
+% expanded preamble will then be in the token register
+% "\@temptokena". Actually we need to know at this point that
+% this is not "\toks0".
+% \begin{macrocode}
+ \@temptokena{#1}\@tempswatrue
+ \@whilesw\if@tempswa\fi{\@tempswafalse\the\NC@list}%
+% \end{macrocode}
+% Afterwards we initialize all registers and macros, that we need
+% for the build-up of the preamble.
+% \begin{macrocode}
+ \count@\m@ne
+ \let\the@toks\relax
+ \prepnext@tok
+% \end{macrocode}
+% Having expanded all tokens defined using "\newcolumntype" (including
+% "*"), we evaluate the remaining tokens, which are saved in
+% "\@temptokena". We use the \LaTeX--macro "\@tfor" to inspect each
+% token in turn.
+% \begin{macrocode}
+ \expandafter \@tfor \expandafter \@nextchar
+ \expandafter :\expandafter =\the\@temptokena \do
+% \end{macrocode}
+% "\@testpatch" does not take an argument since \texttt{array.sty} 2.0h.
+% \begin{macrocode}
+ {\@testpach
+ \ifcase \@chclass \@classz \or \@classi \or \@classii
+ \or \save@decl \or \or \@classv \or \@classvi
+ \or \@classvii \or \@classviii
+% \end{macrocode}
+% In \texttt{newarray.sty} class 9 is equivalent to class 10.
+% \begin{macrocode}
+ \or \@classx
+ \or \@classx \fi
+ \@lastchclass\@chclass}%
+ \ifcase\@lastchclass
+ \@acol \or
+ \or
+ \@acol \or
+ \@preamerr \thr@@ \or
+ \@preamerr \tw@ \@addtopreamble\@sharp \or
+ \or
+ \else \@preamerr \@ne \fi
+ \def\the@toks{\the\toks}}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\@classix}
+% \texttt{array.sty} does not allow repeated \texttt{>}
+% declarations for the same column. This is allowed in
+% \texttt{newarray.sty} as documented in the introduction. Removing
+% the test for this case makes class 9 equivalent to class 10, and
+% so this macro is redundant. It is "\let" to "\relax" to save
+% space.
+% \begin{macrocode}
+\let\@classix\relax
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\@classviii}
+% In \texttt{newarray.sty} explicitly allow class 2, as repeated
+% \texttt{<} expressions are accepted by this package.
+% \begin{macrocode}
+\def\@classviii{\ifnum \@lastchclass >\z@\ifnum\@lastchclass=\tw@\else
+ \@preamerr 4\@chclass 6 \@classvi \fi\fi}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\@classv}
+% Class 5 is \texttt{@}-expressions (and is also called by class 1)
+% This macro was incorrect in Version~1. Now we do not expand the
+% "@"-expression, but instead explicitly replace an
+% "\extracolsep" command by an assignment to "\tabskip" by a
+% method similar to the "\newcolumntype" system described above.
+% "\d@llarbegin" "\d@llarend" were introduced in V2.01 to match
+% \texttt{array.sty} 2.0h.
+% \begin{macrocode}
+\def\@classv{\save@decl
+ \expandafter\NC@ecs\@nextchar\extracolsep{}\extracolsep\@@@
+ \@addtopreamble{\d@llarbegin\the@toks\the\count@\relax\d@llarend}%
+ \prepnext@tok}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\NC@ecs}
+% Rewrite the first occurrence of "\extracolsep{1in}" to
+% "\tabskip1in\relax". As a side effect discard any tokens after a
+% second "\extracolsep", there is no point in the user entering two of
+% these commands anyway, so this is not really a restriction.
+% \begin{macrocode}
+\def\NC@ecs#1\extracolsep#2#3\extracolsep#4\@@@{\def\@tempa{#2}%
+ \ifx\@tempa\@empty\else\toks\count@={#1\tabskip#2\relax#3}\fi}
+%</ncols>
+% \end{macrocode}
+% \end{macro}
+%
+%
+% \subsection{Support for the \texttt{delarray.sty}}
+%
+% The \texttt{delarray.sty} package extends the array syntax by
+% supporting the notation of delimiters. To this end we extend the
+% array parsing mechanism to include a hook which can be used by this
+% (or another) package to do some additional parsing.
+%
+% \begin{macro}{\@tabarray}
+% This macro tests for an optional bracket and then calls up
+% "\@@array" or "\@@array[c]" (as default).
+% \begin{macrocode}
+%<*package>
+\def\@tabarray{\@ifnextchar[{\@@array}{\@@array[c]}}
+% \end{macrocode}
+% \end{macro}
+% \begin{macro}{\@@array}
+% This macro tests could then test an optional delimiter before the
+% left brace of the main preamble argument. Here in the main package
+% it simply is let to be "\@array".
+% \begin{macrocode}
+\let\@@array\@array
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\endarray}
+% \begin{macro}{\@arrayright}
+% We have to declare the hook we put into "\@array" above.
+% A similar hook `"\@arrayright"' will be inserted into the
+% "\endarray" to gain control. Both defaults to empty.
+% \begin{macrocode}
+\def\endarray{\crcr \egroup \egroup \@arrayright \gdef\@preamble{}}
+\let\@arrayleft\@empty
+\let\@arrayright\@empty
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+% \subsection{Support for \texttt{\textbackslash firsthline} and
+% \texttt{\textbackslash lasthline}}
+%
+% The Companion~\cite[p.137]{bk:GMS94} suggests two additional
+% commands to control the allignments in case of tabulars with
+% horizontal lines. They are now added to this package.
+%
+% \begin{macro}{\extratabsurround}
+% The extra space around a table when "\firsthline" or "\lasthline"
+% are used.
+% \begin{macrocode}
+\newlength{\extratabsurround}
+\setlength{\extratabsurround}{2pt}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\backup@length}
+% This register will be used internally by "\firsthline" and
+% "\lasthline".
+% \begin{macrocode}
+\newlength{\backup@length}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\firsthline}
+% \changes{v2.3h}{1996/05/25}{Complete reimplementation}
+% This code can probably be improved but for the moment it should
+% serve.
+%
+% We start by producing a single tabular row without any visible
+% content that will produce the external reference point in case
+% "[t]" is used.
+% \begin{macrocode}
+\newcommand{\firsthline}{%
+ \multicolumn1c{%
+% \end{macrocode}
+% Within this row we calculate "\backup@length" to be the height
+% plus depth of a standard line. In addition we have to add the
+% width of the "\hline", something that was forgotten in the
+% original definition.
+% \begin{macrocode}
+ \global\backup@length\ht\@arstrutbox
+ \global\advance\backup@length\dp\@arstrutbox
+ \global\advance\backup@length\arrayrulewidth
+% \end{macrocode}
+% Finally we do want to make the height of this first line be a bit
+% larger than usual, for this we place the standard array strut
+% into it but raised by "\extratabsurround"
+% \begin{macrocode}
+ \raise\extratabsurround\copy\@arstrutbox
+% \end{macrocode}
+% Having done all this we end the line and back up by the value of
+% "\backup@length" and then finally place our "\hline". This should
+% place the line exactly at the right place but keep the reference
+% point of the whole tabular at the baseline of the first row.
+% \begin{macrocode}
+ }\\[-\backup@length]\hline
+}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\lasthline}
+% \changes{v2.3h}{1996/05/25}{Complete reimplementation}
+% For "\lasthline" the situation is even worse and I got it
+% completely wrong initially.
+%
+% The problem in this case is that if the optional argument "[b]"
+% is used we do want the reference point of the tabular be at the
+% baseline of the last row but at the same time do want the the
+% depth of this last line increased by "\extratabsurround" without
+% changing the placement "\hline".
+%
+% We start by placing the rule followed by an invisible row.
+% \begin{macrocode}
+\newcommand{\lasthline}{\hline\multicolumn1c{%
+% \end{macrocode}
+% We now calculate "\backup@length" to be the height and depth of
+% two lines plus the width of the rule.
+% \begin{macrocode}
+ \global\backup@length2\ht\@arstrutbox
+ \global\advance\backup@length2\dp\@arstrutbox
+ \global\advance\backup@length\arrayrulewidth
+% \end{macrocode}
+% This will bring us back to the baseline of the second last row:
+% \begin{macrocode}
+ }\\[-\backup@length]%
+% \end{macrocode}
+% Thus if we now add another invisible row the reference point of
+% that row will be at the baseline of the last row (and will be the
+% reference for the whole tabular). Since this row is invisible we
+% can enlarge its depth by the desired amount.
+% \begin{macrocode}
+ \multicolumn1c{%
+ \lower\extratabsurround\copy\@arstrutbox
+ }%
+}
+% \end{macrocode}
+% \end{macro}
+%
+%
+% \subsection{Getting the spacing around rules right}
+%
+% Beside a larger functionality \texttt{array.sty} has one
+% important difference to the standard \texttt{tabular} and
+% \texttt{array} environments: horizontal and vertical rules make a
+% table larger or wider, e.g., \verb=\doublerulesep= really denotes
+% the space between two rules and isn't measured from the middle of
+% the rules.
+%
+% \begin{macro}{\@xhline}
+% For vertical rules this is implemented by the definitions above,
+% for horizontal rules we have to take out the backspace.
+% \changes{v2.3d}{1995/11/19}{fix space between double rules pr/1945}
+% \begin{macrocode}
+\CheckCommand*\@xhline{\ifx\reserved@a\hline
+ \vskip\doublerulesep
+ \vskip-\arrayrulewidth
+ \fi
+ \ifnum0=`{\fi}}
+\renewcommand*\@xhline{\ifx\reserved@a\hline
+ \vskip\doublerulesep
+ \fi
+ \ifnum0=`{\fi}}
+%</package>
+% \end{macrocode}
+% \end{macro}
+%
+% \PrintIndex
+% \PrintChanges
+%
+% \Finale
+%
+\endinput
+
diff --git a/Master/texmf-dist/source/latex/tools/bm.dtx b/Master/texmf-dist/source/latex/tools/bm.dtx
new file mode 100644
index 00000000000..41eb25c8a79
--- /dev/null
+++ b/Master/texmf-dist/source/latex/tools/bm.dtx
@@ -0,0 +1,1636 @@
+% \iffalse meta-comment
+%
+% Copyright 1993 1994 1995 1996 1997 1998 1999 2000 2001 2002 2003
+% The LaTeX3 Project and any individual authors listed elsewhere
+% in this file.
+%
+% This file is part of the Standard LaTeX `Tools Bundle'.
+% -------------------------------------------------------
+%
+% It 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.3 or later is part of all distributions of LaTeX
+% version 2003/12/01 or later.
+%
+% The list of all files belonging to the LaTeX `Tools Bundle' is
+% given in the file `manifest.txt'.
+%
+% \fi
+%
+% \iffalse
+%% Copyright 1996 1997 1998 1999 2002 2003 2004 David Carlisle Frank Mittelbach
+%%
+%% Development of this package was commissioned by Y&Y Inc.
+%% http://www.yandy.com
+%
+%
+%<*dtx>
+ \ProvidesFile{bm.dtx}
+%</dtx>
+%<package>\NeedsTeXFormat{LaTeX2e}
+%<package>\ProvidesPackage{bm}
+%<driver>\ProvidesFile{bm.drv}
+% \fi
+% \ProvidesFile{bm.dtx}
+ [2004/02/26 v1.1c Bold Symbol Support (DPC/FMi)]
+%
+% \iffalse
+%<*driver>
+\documentclass{ltxdoc}
+\usepackage{bm}
+\begin{document}
+\DocInput{bm.dtx}
+\end{document}
+%</driver>
+% \fi
+%
+% \CheckSum{944}
+%
+% \GetFileInfo{bm.dtx}
+%
+% \title{The \textsf{bm} package\thanks{This file
+% has version number \fileversion, last
+% revised \filedate.}\ \thanks{Development of this package
+% was commissioned by Y\&Y.}}
+%
+% \date{\filedate}
+% \author{David Carlisle with support by Frank Mittelbach}
+% \maketitle
+%
+% \section{Introduction}
+%
+% This package defines commands to access bold math
+% symbols. The basic command is |\bm| which may be used to make the
+% math expression in its argument be typeset using bold fonts.
+%
+% The syntax of |\bm| is:\\
+% |\bm|\marg{math expression}\\
+% So |$\alpha \not= \bm{\alpha}$| produces $\alpha \not= \bm{\alpha}$.
+%
+% |\bm| goes to some trouble to preserve the spacing, so that for
+% instance |\bm<| is a bold $\bm<$ but with the correct |\mathrel|
+% spacing that \TeX\ gives to $<$. The calculations that \TeX\ needs to
+% do for |\bm| can be quite involved and so a definition form is
+% provided.
+%
+% |\DeclareBoldMathCommand|%^^A
+% \oarg{math version}\marg{cmd}\marg{math expression}
+%
+% Defines |\cmd| to be the bold form of the math expression.
+% The \meta{math version} defaults to `bold' (i.e., |\boldmath|).
+%
+% For relatively simple expressions, the resulting definitions are very
+% efficient, for instance after:\\
+% |\DeclareBoldMathCommand\balpha{\alpha}|\\
+% |\balpha| is a single `mathchardef' token producing a bold alpha,
+% and so is just as fast to execute as |\alpha|.
+%
+% The above command is mainly intended for use in packages.
+% For occasional use in \LaTeX\ documents, and for compatibility
+% with the plain \TeX\ support for the mathtime fonts, a `user-level'
+% version, |\bmdefine| is provided that is equivalent to:\\
+% |\DeclareBoldMathCommand[bold]|.
+%
+% If there is a `heavy' math version defined (usually accessed by a
+% user-command |\heavymath|) then a similar command |\hm|
+% is defined which access these `ultra bold' fonts. Currently this is
+% probably only useful with the `mathtime plus' font collection.
+% Definitions of commands that use these fonts may be made by
+% specifying the optional argument `heavy' to |\DeclareBoldMathCommand|.
+% Again an abbreviation, |\hmdefine|, is provided, equivalent to:\\
+% |\DeclareBoldMathCommand[heavy]|.
+%
+% The command names (but not the implementation) are taken from Michael
+% Spivak's macros to support the mathtime fonts for plain \TeX. In those
+% original macros, the syntax for |\bmdefine| was
+% |\bmdefine\balpha{\bm\alpha}| (with a nested |\bm|). This syntax also
+% works with this package.
+%
+% \section{Font allocation}
+% In order to access bold fonts in the simplest and quickest possible
+% manner, the package normally allocates symbol fonts for bold
+% (and possibly heavy) fonts into the `normal' math version.
+% By default it allocates at most four fonts for |\bm| and at most
+% three fonts for |\hm|. This means that if the mathtime plus font set
+% is being used, seven additional symbol fonts will be used, in addition
+% to the basic four that \LaTeX\ already declares. The mathtime
+% package also declares an extra symbol font, bringing the total to
+% twelve. The maximum number of symbol \emph{and} math alphabet fonts
+% that can be used in a math version is sixteen. So the above allocation
+% scheme does not leave room for many extra math symbols (such as the
+% AMS symbols) or math alphabets (such as |\mathit|).
+%
+% Before loading the \textsf{bm} package you may define |\bmmax|
+% and |\hmmax| to be suitable values, for instance you may want
+% to set |\newcommand\hmmax{0}| if you will not be using |\hm|
+% much, but you do have a heavy math version defined.
+%
+% Even if |\bmmax| is set to zero, |\bm| will still access the correct
+% bold fonts (by accessing the fonts via |\boldmath|) but this method
+% is slower, and does not work with delimiters. Delimiters can only be
+% made bold if the bold font has been allocated.
+%
+% Conversely if you have a non standard font set that makes available
+% extra math delimiters and accents in bold and medium weights you may
+% want to \emph{increase} |\bmmax| so that fonts are allocated for
+% your font set.
+%
+% \section{Features}
+% In most cases this package should work in a fairly self explanatory
+% way, but there are some things that might not be obvious.
+%
+% \subsection{Interaction with Math Alphabet Commands}
+%
+% As mentioned above, |\bm| goes to some trouble to try to make a
+% command that is just like its argument, but using a bold font.
+% This does not always produce the effect that you might expect.
+%\begin{verbatim}
+% $1 g \bm{g}$
+% $2 \mathrm{g \bm{g}}$
+% $3 {g} \bm{{g}}$
+% $4 \mathrm{{g} \bm{{g}}}$
+% $5 \mathrm{g} \bm{\mathrm{g}}$
+%\end{verbatim}
+% produces the following:
+% \begin{flushleft}
+% $1 g \bm{g}$
+% $2 \mathrm{g \bm{g}}$
+% $3 {g} \bm{{g}}$
+% $4 \mathrm{{g} \bm{{g}}}$
+% $5 \mathrm{g} \bm{\mathrm{g}}$
+% \end{flushleft}
+% In math mode `g' is effectively a command that produces the letter `g'
+% from the `letters' alphabet, unless a Math Alphabet command is in
+% effect, in which case the `g' comes from the specified alphabet.
+% |\bm{g}| makes an equivalent command, but which defaults to a bold
+% letter alphabet. So in the first example |\bm{g}| is bold math italic,
+% but in the second example the |\mathrm| applies to both |g| and
+% |\bm{g}| in the same way, and so they are both roman.
+%
+% |\bm| only inspects the `top level' definition of a command, for more
+% complicated expressions, and anything inside a |{ }| group, |\bm|
+% forces bold fonts by essentially the same (slow) technique used by the
+% AMS |\boldsymbol| command (but |\bm| still takes more care of the
+% spacing). So the third example produces identical output to the first
+% (but \TeX\ takes more time producing it).
+%
+% In the fourth example the |\mathrm{\bm{g}}| is essentially
+% equivalent to |\mathrm{\mbox{\boldmath$g$}}|. Currently math alphabet
+% settings are not passed down to `nested' math lists, and so in this
+% example, the |\mathrm| has no effect, and a bold math italic $\bm g$
+% is obtained.
+%
+% Similarly the last example is equivalent to
+% |$\mbox{\boldmath$\mathrm{g}$}}| and so in this case, one obtains a
+% bold roman \textbf{g}.
+%
+% \subsection{Delimiters}
+% \TeX\ can treat character tokens in two\footnote
+% {Well more than two really.}
+% ways. If there is a preceding
+% |\left| or |\right| it can treat them as a delimiter, otherwise it can
+% treat them as a standard character. For example |\left<\right>|
+% produces $\left<\right>$, which is totally different from |<>|, which
+% produces $<>$.
+%
+% \TeX\ can only do this for character tokens. Commands such as
+% |\langle| do not act in this way. This means that |\bm| has to decide
+% whether to treat a character as a delimiter or not. The rule it uses
+% is, it makes a delimiter command for a character if the previous
+% token in the argument was |\left| or |\right|. So |\left\bm{<}| does
+% not work, but |\bm{\left<}| does.
+%
+% \subsection{Command Arguments}
+%
+% Normally if a command takes arguments the full command, including
+% any arguments, should be included in |\bm|.
+%
+% So |\bm{\overbrace{abc}}| (producing \smash{$\bm{\overbrace{abc}}$})
+% not
+% |\bm{\overbrace}{abc}|. If you do not include all the arguments you
+% will typically get the error message:\\
+% |Runaway argument?|\\
+% |! Forbidden control sequence found while scanning use of|
+% \texttt{\ldots}
+%
+% However commands defined in terms of the \TeX\ accent and
+% radical primitives \emph{may} be used without their arguments.
+% So |\bm{\hat}{a}| produces $\bm{\hat}{a}$, a bold accent over a
+% non-bold $a$ (compare $\hat{a}$)
+% whereas |\bm{\hat{a}}| makes both the $a$ and the accent bold,
+% $\bm{\hat{a}}$.
+% Similarly, although the \LaTeX\ command |\sqrt| must be used with its
+% arguments, |\sqrtsign| may be used as in |\bm\sqrtsign{abc}| to
+% produce $\bm\sqrtsign{abc}$ rather than $\sqrtsign{abc}$ or
+% $\bm{\sqrtsign{abc}}$
+%
+% If you really need to make a command with arguments use bold fonts
+% without making all of the arguments bold, you can explicitly
+% reset the math version in the argument, eg:\\
+% $\begin{array}{ccc}
+% |\sqrt{xyz}|&|\bm{\sqrt{xyz}}|&|\bm{\sqrt{\mbox{\unboldmath$xyz$}}}|\\
+% \sqrt{xyz}& \bm{\sqrt{xyz}}& \bm{\sqrt{\mbox{\unboldmath$xyz$}}}
+% \end{array}$
+%
+% \subsection{Bold fonts}
+% This package interrogates the font allocations of the bold and heavy
+% math versions, to determine which bold fonts are available.
+% This means that it is best to load the package \emph{after}
+% any packages that define new symbol fonts, or (like the
+% \textsf{mathtime} package) completely change the symbol font
+% allocations.
+%
+% If no bold font appears to be available for a particular symbol,
+% |\bm| will use `poor man's bold' that is, overprinting the same
+% character in slightly offset
+% positions to give an appearance of boldness.
+%
+% In the standard Computer Modern font set, there is no bold
+% `large symbols' font. In the `mathptm' and (standard) mathtime
+% font sets there are no bold math fonts. In the `mathtime plus'
+% font set there are suitable fonts for bold and heavy math setting,
+% and so |\bm| and |\hm| work well. Similarly in the basic Lucida
+% New Math font set there are no bold math fonts, so |\bm| will
+% use `poor man's bold. However if the Lucida Expert set is used,
+% Then |\bm| will detect, and use the bold math fonts that are
+% available.
+%
+% As discussed above, one may set |\bmmax| higher or lower than its
+% default value of four to control the font allocation system. Finer
+% control may be gained by explicitly declaring bold symbol fonts.
+% Suppose you have a symbol font `xyz' that is available in medium and
+% bold weights, then you would declare this to \LaTeX\ via:\\
+% |\DeclareSymbolFont{extras} {OMS}{xyz}{m}{n}|\\
+% |\SetSymbolFont{extras}{bold}{OMS}{xyz}{bx}{n}|\\
+% At this point the symbols wil be available in the normal math
+% version, and their bold variants in |\boldmath|. If you also
+% declare:\\
+% |\DeclareSymbolFont{boldextras}{OMS}{xyz}{bx}{n}|\\
+% That is, declare a symbol font whose name is formed by prefixing
+% `bold' (or `heavy') to an existing symbol font, then |\bm| (or
+% |\hm|) will use this font directly, rather then accessing the
+% `extras' symbol font via |\boldmath|.
+%
+% \subsection{Strange failures}
+% In order to get the correct spacing, |\bm| has to `investigate' the
+% definition of the commands in its argument. It is possible that
+% some strange constructions could `confuse' this investigation.
+% If this happens then \LaTeX\ will almost certainly stop with a strange
+% error. This should not happen with any of the math symbols
+% defined in the base \LaTeX\ or AMS distributions, or any commands
+% defined in terms of those symbols using normal \LaTeX\ math
+% constructs. However if some command does fail to work inside |\bm|
+% you should always be able to surround it with an extra set of braces
+% |\bm{{\cmd}}| rather than |\bm{\cmd}|. |\bm| will not then attempt
+% to set the correct spacing, so you may need to set it explicitly,
+% for instance, for a relation, |\bm{\mathrel{\cmd}}|.
+%
+% \subsection{AMS package \textsf{amsbsy}}
+% The |\bm| command shares some functionailty with the |\boldsymbol|
+% command from the AMS \LaTeX\ collection. To aid in moving documents
+% between these two packages, this package defines |\boldsymbol| and
+% |\heavysymbol| as alternative names for |\bm| and |\hm|.
+%
+% \StopEventually{}
+%
+% \section{Implementation}
+%
+% \changes{v0.01}{1996/12/01}
+% {Initial DPC attempt,
+% remove all assumptions about mathtime encoding}
+% \changes{v0.02}{1996/12/02}
+% {Add \cs{mathchoice} stuff}
+% \changes{v0.03}{1996/12/12}
+% {Completely reimplement (again). Add \cs{bmdefine}.}
+% \changes{v0.04}{1996/12/12}
+% {Add \cs{hm} and support for special active mathcode.}
+% \changes{v0.05}{1996/12/12}
+% {Assorted fixes}
+% \changes{v0.99}{1997/01/16}
+% {First public version}
+% \changes{v1.0a}{1997/02/14}
+% {First ctan version (same as 0.99b)}
+% \changes{v1.0b}{1997/04/14}
+% {Add to tools bundle.}
+% \changes{v1.0g}{1999/07/05}
+% {minor doc changes latex/3058}
+%
+%
+%
+% The commands |\bm| and |\hm| work by defining a number of additional
+% symbol fonts corresponding to the standard ones
+% `operators', `letters', `symbols', and `largesymbols'.
+% The names for these symbols fonts are produced by prefixing the usual
+% name with `bold' or `heavy'.
+%
+% For maximum flexibility we get the font definitions by looking in the
+% corresponding math versions, i.e., into |\mv@bold| and if defined into
+% |\mv@heavy|.
+%
+% \begin{macrocode}
+%<*package>
+% \end{macrocode}
+% \changes{v0.09}{1996/12/19}
+% {Always define \cs{bm} even if no bold math}
+%
+% \begin{macro}{\bm@table}
+% \changes{v0.10}{1997/01/04}
+% {Macro added}
+% \changes{v0.12}{1997/01/10}
+% {Ensure do not allocate too many math group slots.}
+% \changes{v0.99a}{1997/01/17}
+% {Let \cs{hm} use font allocated for \cs{bm}}
+% \changes{v0.99b}{1997/01/19}
+% {Restore NFSS internals}
+% \begin{macro}{\bm@boldtable}
+% \begin{macro}{\bm@heavytable}
+% The table, |\bm@table|, (which is locally |\let| to either the bold
+% or heavy version) defines, for each \meta{math group} (\meta{fam}),
+% the `offset' to the bold version of the specified symbol font.
+% If there is no bold symbol font defined, the offset will be
+% set to zero if there is a bold font assigned to this slot in the
+% bold math version, or $-1$ if the font in the bold math version
+% is the same as the one in the normal math version. In this case
+% a `poor man's bold' system of overprinting is used to achieve
+% boldness where this is possible.
+%
+% The settings are made at the time this package is read, and so
+% it is best to load this package late, after any font loading packages
+% have been loaded. Symbol fonts loaded after this package will get the
+% offset of zero, so they will still be made bold by |\bm| as long as an
+% appropriate font is declared for the bold math version.
+%
+% |\bm@boldtable| and |\bm@heavytable| are set up using very similar
+% code, which is temporarily defined to |\bm|, to save wasting a csname.
+% Similarly |\bm@pmb|\ldots\ (which will be defined later) are used
+% as scratch macros.
+%
+% The general plan. Run through the fonts allocated to the normal math
+% version. Ignore \meta{math alphabet} allocations\footnote{For now?}
+% but for each math symbol font, look in the math version specified by
+% |#1| (bold or heavy). If the font there is different, then allocate
+% a new symbol font in the normal math version to access that bold font
+% and place the numerical difference between the allocations of the bold
+% and normal font into the table being built (|\bm@boldtable|, if |#1|
+% is bold). If the symbol allocation is already greater than |\bmmax|
+% do not allocate a new symbol font, but rather set the offset in the
+% table to zero. |\bm| will detect this, and use |\boldmath| on its
+% argument in this case, so the bold font will be accessed but more
+% slowly than using a direct access to a bold font allocated into the
+% normal math version. If the font allocated in the bold math version is
+% the same as the font in the normal math version, set the offset to
+% $-1$, which is a flag value that causes |\bm| to use `poor man's bold'
+% overprinting three copies of the symbol, offset slightly to give an
+% appearance of boldness.
+%
+% Fonts containing delimiters and math accents \emph{must} be allocated
+% into the normal math version if they are to be used with |\bm|. (In
+% these cases |\bm| will produce the normal weight symbol, rather than
+% using |\boldmath| or poor man's bold.)
+%
+% \begin{macrocode}
+\def\bm#1#2{%
+% \end{macrocode}
+% This code can not work inside a group, as that would affect any symbol
+% font allocations, so instead use some scratch macros to save and
+% restore the definitions of commands we need to change locally.
+% \begin{macrocode}
+ \let\bm@pmb\install@mathalphabet
+ \let\bm@pmb@\getanddefine@fonts
+ \let\bm@pmb@@\or
+ \edef\bm@general{\f@encoding/\f@family/\f@series/\f@shape/\f@size}%
+% \end{macrocode}
+%
+% |#2| specifies the maximum number of fonts to allocate
+% (either |\bmmax| or |\hmmax|). First check against |\count18|
+% that there are that many slots left, and if not reduce accordingly.
+% Put the resulting value in |\@tempcnta|.
+% \begin{macrocode}
+ \@tempcnta#2%
+ \count@-\count18%
+ \advance\count@-\@tempcnta
+ \advance\count@15\relax
+ \ifnum\count@<\z@
+ \advance\@tempcnta\count@
+ \fi
+% \end{macrocode}
+% Make |\or| non-expandable, so we can build an |\ifcase| bit-by-bit
+% in a sequence of |\edef|s.
+% \begin{macrocode}
+ \let\or\relax
+% \end{macrocode}
+%
+% Initialise the table (to |\@gobble| to remove the first |\or|).
+% \begin{macrocode}
+ \expandafter\let\csname bm@#1table\endcsname\@gobble
+% \end{macrocode}
+%
+% Helper macro that adds the next entry to the table being built.
+% \begin{macrocode}
+ \def\bm@define##1{%
+ \expandafter\xdef\csname bm@#1table\endcsname{%
+ \csname bm@#1table\endcsname\or##1}}%
+% \end{macrocode}
+%
+% Each symbol font is recorded in the math version list by a sequence
+% such as:\\
+% | \getanddefine@fonts \symsymbols \OMS/cmsy/m/n|\\
+% Where the first argument is a chardef token carrying the number
+% allocated (to symbols, in this example), and the second argument is a
+% csname whose \emph{name} denotes the font used.
+% So locally redefine |\getanddefine@fonts| to compare |#2| with
+% the name in the appropriate slot in the bold math version.
+% \begin{macrocode}
+ \def\getanddefine@fonts##1##2{%
+ \def\@tempa{##2}%
+% \end{macrocode}
+%
+% \begin{macrocode}
+ \def\@tempb####1##1####2####3\@nil{\def\@tempb{####2}}%
+% \end{macrocode}
+%
+% \begin{macrocode}
+ \expandafter\expandafter\expandafter
+ \@tempb\csname mv@#1\endcsname\@nil
+% \end{macrocode}
+%
+% Now |\@tempa| and |\@tempb| contain the names of the fonts allocated
+% to this slot in the two math versions.
+% \begin{macrocode}
+ \ifx\@tempa\@tempb
+% \end{macrocode}
+% If they are the same, set this offset to $-1$, as a flag to use
+% poor man's bold.
+% \begin{macrocode}
+ \bm@define\m@ne
+ \else
+% \end{macrocode}
+% Else make a new name by adjoining |#1| to the name of the symbol font
+% eg, |\symboldsymbols| to match |\symsymbols|. If that font has already
+% been allocated, or if |\@tempcnta| is positive so we can allocate a
+% new slot for this font, then the table will be
+% set with the offset between the two fonts. otherwise set the offset to
+% zero (so |\boldmath| will be used to access the font).
+% \begin{macrocode}
+ \edef\@tempa{sym#1\expandafter\@gobblefour\string##1}%
+ \ifnum\@tempcnta<%
+ \expandafter\ifx\csname\@tempa\endcsname\relax
+ \@ne
+ \else
+ \m@ne
+ \fi
+% \end{macrocode}
+%
+% \begin{macrocode}
+ \bm@define\z@
+ \else
+% \end{macrocode}
+%
+% If the font is not yet allocated, allocate it now, using
+% an internal hack into |\DeclareMathSymbolFont|.
+%
+% However before allocating it look in the bold math version
+% to see if it is the same, and if so use that. For example
+% with Mathtime the `operators' font in the `heavy' math version
+% is different from that in `normal', but it is the same as
+% the font in `bold' (Times bold). So rather than allocate
+% |\symheavyoperators| just set it equal to |\symboldoperators|.
+% \begin{macrocode}
+ \expandafter\ifx\csname\@tempa\endcsname\relax
+ \begingroup
+ \escapechar\m@ne
+ \edef\@tempb{\endgroup
+ \noexpand\split@name
+ \expandafter\string\@tempb}%
+ \@tempb/\@nil
+% \end{macrocode}
+%
+% \begin{macrocode}
+ \expandafter\ifx
+ \csname symbold\expandafter\@gobblefour\string##1\endcsname
+ \relax
+% \end{macrocode}
+% If no font has been allocated for |\bm| yet, then allocate it now.
+% \begin{macrocode}
+ \expandafter\new@mathgroup\csname\@tempa\endcsname
+ \expandafter\new@symbolfont\csname\@tempa\endcsname
+ \f@encoding\f@family\f@series\f@shape
+% \end{macrocode}
+% Reduce by one the number of fonts we can still allocate.
+% \begin{macrocode}
+ \advance\@tempcnta\m@ne
+% \end{macrocode}
+%
+% \begin{macrocode}
+ \else
+% \end{macrocode}
+% Else do a similar look into the bold mathgroup.
+% Use |\bm@expand| as a scratch macro to save on string space.
+% \begin{macrocode}
+ \def\bm@expand####1##1####2####3\@nil{\def\bm@expand{####2}}%
+ \expandafter\expandafter\expandafter
+ \bm@expand\csname mv@bold\endcsname\@nil
+% \end{macrocode}
+%
+% \begin{macrocode}
+ \ifx\bm@expand\@tempb
+% \end{macrocode}
+% If the font just found (in heavy) is the same as the font in bold
+% use the slot (in normal) previously allocated for the bold font.
+% (That clear?)
+% \begin{macrocode}
+ \expandafter\let\csname\@tempa\expandafter\endcsname
+ \csname symbold\expandafter
+ \@gobblefour\string##1\endcsname
+% \end{macrocode}
+%
+% \begin{macrocode}
+ \else
+% \end{macrocode}
+% Otherwise allocate a new slot for it.
+% \begin{macrocode}
+ \expandafter\new@mathgroup\csname\@tempa\endcsname
+ \expandafter\new@symbolfont\csname\@tempa\endcsname
+ \f@encoding\f@family\f@series\f@shape
+ \advance\@tempcnta\m@ne
+% \end{macrocode}
+%
+% \begin{macrocode}
+ \fi
+ \fi
+% \end{macrocode}
+%
+% \begin{macrocode}
+ \else
+% \end{macrocode}
+% If the font has been allocated already, use the existing allocation.
+% \begin{macrocode}
+ \PackageInfo{bm}%
+ {Symbol font \@tempa\space already defined.\MessageBreak
+ Not overwriting it}%
+ \fi
+% \end{macrocode}
+% Whether the font has just been allocated, or whether it was previously
+% allocated, compute the offset and add it to the table.
+% \begin{macrocode}
+ \count@\csname\@tempa\endcsname
+ \advance\count@-##1%
+ \bm@define{\the\count@\relax}%
+ \fi
+ \fi}%
+% \end{macrocode}
+%
+% The math version list also contains information about math alphabet
+% commands, but we want to ignore those here, so \ldots
+% \begin{macrocode}
+ \let\install@mathalphabet\@gobbletwo
+% \end{macrocode}
+%
+% Having set up the local definitions, execute the list for the normal
+% math version.
+% \begin{macrocode}
+ \mv@normal
+% \end{macrocode}
+%
+% So now the offsets are all entered into the table, separated by
+% |\or|.
+% Finish off the definition by making this an |\ifcase|. Add a default
+% value of zero, so that any symbol fonts declared later will also
+% work, as long as a bold version is assigned to the bold math version.
+% \begin{macrocode}
+ \expandafter\xdef\csname bm@#1table\endcsname{%
+ \noexpand\ifcase\@tempcnta
+ \csname bm@#1table\endcsname
+ \noexpand\else
+ \z@
+ \noexpand\fi}%
+% \end{macrocode}
+%
+% Put things back as they were.
+% \begin{macrocode}
+ \expandafter\split@name\bm@general\@nil
+ \let\install@mathalphabet\bm@pmb
+ \let\getanddefine@fonts\bm@pmb@
+ \let\or\bm@pmb@@}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\bmmax}
+% To save declaring too many symbol fonts, do not auto-declare
+% any more than |\bmmax| bold symbol fonts into the normal math
+% version. Any bold fonts not so allocated will be accessed via
+% |\boldmath| which is slower and doesnt work for delimiters
+% and accents. It may be set in the preamble with |\newcommand|
+% but use |\chardef| here for a slight efficiency gain.
+%
+% If this is set to a higher value before this
+% package is loaded, keep that value.
+% \begin{macrocode}
+\ifx\bmmax\@undefined
+ \chardef\bmmax=4
+\fi
+% \end{macrocode}
+%
+% If there is no bold math version, It is very easy to set up
+% the table, no need to use all the tricky code above.
+% Also, at the end of the package redefine the internal macro
+% that |\bm| uses to call |\boldmath|, to use poor man's bold
+% instead.
+% \begin{macrocode}
+\ifx\mv@bold\@undefined
+ \def\bm@boldtable{\m@ne}
+ \AtEndOfPackage{%
+ \def\bm@gr@up#1#2{%
+ \bm@pmb{#2}}}
+\else
+% \end{macrocode}
+% Otherwise use the definition of |\bm| above to set up |\bm@boldtable|
+% by comparing the fonts available in the normal and bold math versions.
+% \begin{macrocode}
+ \bm{bold}\bmmax
+% \end{macrocode}
+%
+% \begin{macro}{\mathbf}
+% As the bold font has been defined as a symbol font, make |\mathbf|
+% access that rather than have it allocate a new math group for the
+% same font. (Just in case there were no free slots wrap this
+% in an extra test.)
+% \begin{macrocode}
+ \@ifundefined{symboldoperators}
+ {}
+ {\DeclareSymbolFontAlphabet\mathbf{boldoperators}}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macrocode}
+\fi
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\hmmax}
+%
+% Same for heavy (but default to three this time (enough for mathtime
+% plus, as no heavy operators font).
+% \begin{macrocode}
+\ifx\hmmax\@undefined
+ \chardef\hmmax=3
+\fi
+% \end{macrocode}
+%
+% Similarly if there is a heavy math version, set up |\bm@heavytable|.
+% (If there is no heavy math version, do nothing here, as |\hm| will be
+% set to |\bm| later, once that is defined.)
+% \begin{macrocode}
+\ifx\mv@heavy\@undefined
+\else
+ \bm{heavy}\hmmax
+\fi
+% \end{macrocode}
+% \end{macro}
+%
+%
+% \begin{macro}{\bm@general}
+% \changes{v1.0d}{1997/11/15}
+% {extra code to support prime lookahead and breqn}
+% \changes{v1.0h}{2002/11/22}{Pass math version as third (new) argument}
+%
+% |\bm| is pretty much |\bmdefine\bm@command| followed by executing
+% |\bm@command|. It would in principle be possible to execute the
+% emboldened tokens directly, rather than building up a macro first,
+% but (as I learned the hard way) it's difficult to do this in the midst
+% of all these nested |\if| constructs.
+% First extract the central bit of code for |\hm| |\bm| |\hmdefine| and
+% |\bmdefine|. Note that in the case of the inline versions they take
+% an argument and brace it, rather than relying on |\bm@general| to pick
+% up the argument. This makes the code robust with respect to premature
+% expansion.
+% \begin{macrocode}
+\begingroup
+\catcode`\'=\active
+\@firstofone{\endgroup
+\def\bm@general#1#2#3#4#5{%
+ \begingroup
+% \end{macrocode}
+% \changes{v1.0d}{1997/11/15}
+% {make nested \cs{bm} vanish completely, not leave a brace group}
+% First locally disable |\bm| and |\hm|, as they would mess things
+% up terribly, and the original Spivak versions used the syntax
+% |\bmdefine\balpha{\bm\alpha}|.
+% \begin{macrocode}
+ \let\bm\@firstofone
+ \let\hm\@firstofone
+% \end{macrocode}
+% Now initialise the commands used to save the tokens constructed.
+% \begin{macrocode}
+ \global\let\bm@command\@empty
+ \let\@let@token\@empty
+% \end{macrocode}
+% As we want to expand the macros to look at their definition
+% turn off protection. Otherwise the |\protect| will be carried over
+% and apply to the wrong token, eg |{|.
+% \begin{macrocode}
+ \let\protect\@empty
+ \let\@typeset@protect\@empty
+% \end{macrocode}
+% Set up either bold or heavy
+% \begin{macrocode}
+ \def\bm@mathchoice{\bm@m@thchoice#1}%
+ \def\bm@group{\bm@gr@up#1}%
+ \let\bm@table#2%
+% \end{macrocode}
+% Make sure |\left| and |\right| are really non expandable,
+% and not |\ifx| equal to anything else.
+% \changes{v1.0d}{1997/11/15}
+% {make sure \cs{left} is primitive}
+% \begin{macrocode}
+ \let\left\holdinginserts
+% \end{macrocode}
+% These three save on the number of |\ifx| tests below.
+% \changes{v1.1a}{2003/09/01}{Forgotten to check for \cs{hskip} (pr/3572)}
+% \begin{macrocode}
+ \let\right\left
+ \let\mskip\mkern
+ \let\hskip\kern
+% \end{macrocode}
+% Definition of |'| locally modified so as not to use |\futurelet|
+% in the look ahead, but to make the |\prime| available at the top level
+% to be made bold, or heavy or whatever.
+% |'| is locally active for this definition.
+% \changes{v1.0d}{1997/11/15}
+% {prime code added}
+% \begin{macrocode}
+ \let\bm@prime\copy
+ \def'{\bm@prime\prime\relax}%
+% \end{macrocode}
+% For optional argument commands. This expandable version of
+% |\@ifnextchar| is not 100\% safe, but works for |\sqrt| unless
+% you put something really strange in the arguments.
+% \changes{v0.11}{1997/01/06}
+% {\cs{@ifnextchar} made safe.}
+% \begin{macrocode}
+ \def\@ifnextchar##1##2##3##4{%
+ \if##1##4%
+ \expandafter\@firstoftwo
+ \else
+ \expandafter\@secondoftwo
+ \fi
+ {##2##4}{##3{##4}}}%
+% \end{macrocode}
+% For Vladimir Volovich\ldots
+% \changes{v1.0f}{1998/12/10}
+% {Errors and warnings made safe. tools/2917}
+% \begin{macrocode}
+ \def\GenericWarning##1##2{%
+ \unvcopy{\GenericWarning{##1}{##2}}}%
+ \def\GenericError##1##2##3##4{%
+ \unvcopy{\GenericError{##1}{##2}{##3}{##4}}}%
+% \end{macrocode}
+% For AMS definitions.
+% \begin{macrocode}
+ \let\DN@\copy
+ \let\FN@\copy
+ \let\next@\copy
+ \global\let\bm@first\@empty
+% \end{macrocode}
+% For AMS version of |\sqrt|: don't expand just wrap in brace group
+% so that it can be made bold in a safe but slow way. Do the same for
+% internal accent command
+% \changes{v1.1b}{2003/10/05}{AMS \cs{sqrt} not working}
+%
+% \changes{v1.1c}{2004/02/26}{\cs{accentV} made safe (pr/3625)}
+% Code for AMS accent allows bm to be used (just) with accent
+% but stops the nested accents stacking correctly, this can be
+% corrected by using an extra brace group as usual.
+% |\bm{{\hat{\hat{F}}}}|
+% \begin{macrocode}
+ \ifx\uproot@\undefined\else
+ \def\root##1\of##2{{\root##1\of{##2}}}%
+ \fi
+ \def\mathaccentV##1{\mathaccent"\accentclass@}%
+% \end{macrocode}
+% For breqn definitions.
+% \begin{macrocode}
+ \let\@ifnext\@ifnextchar
+ \let\measure@lhs\copy
+ \let \rel@break\copy
+ \let \bin@break\copy
+ \let \after@open\copy
+ \let \after@close\copy
+% \end{macrocode}
+% Make sure things like |\pounds| take the `math branch' even
+% in |\bmdefine| (which is not executed in math mode).
+% \begin{macrocode}
+ \let\ifmmode\iftrue
+% \end{macrocode}
+% We have to ensure that the math alphabets have definitions that
+% correspond the the ``bold'' math version we are going to switch
+% to. As these definitions are globally assigned when a math
+% version is changed it is likely that right now we have those of
+% the normal math version active. Argument |#3| holds either
+% |\mv@bold| or |\mv@heavy| and we execute that after redefining
+% |\install@mathalphabet| and |\getanddefine@fonts| suitably.
+% The definitions are reverted back to their original the moment
+% the scanning is done
+% \changes{v1.0h}{2002/11/22}{Get math alphabets right (pr/3476)}
+% \begin{macrocode}
+ \let\install@mathalphabet\def
+ \let\getanddefine@fonts\@gobbletwo
+ #3%
+% \end{macrocode}
+% The last redefinition just makes |\mathit| type commands re-insert
+% themselves (more or less) as if they are allowed to expand
+% they die horribly if the expansions are put into |\mathchoice|
+% and so executed more than once.
+% \begin{macrocode}
+ \def\select@group##1##2##3##4{{%
+ \protect##1{##4}}}%
+ \def\use@mathgroup##1##2##3{{%
+ \protect\use@mathgroup##1{##2}{##3}}}%
+% \end{macrocode}
+%
+% So now start looking at the argument.
+% \changes{v0.10}{1997/01/04}
+% {Use \cs{bm@end}}
+% \begin{macrocode}
+ \bm@expand#5\bm@end
+ \endgroup
+% \end{macrocode}
+%
+% Finally outside the group either execute |\bm@command| (for |\bm|)
+% or save its definition (for |\bmdefine|).
+% \begin{macrocode}
+ #4}
+% \end{macrocode}
+% End of the |\@firstofone| above, and the scope of the active |'|.
+% \begin{macrocode}
+}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\bm}
+% \changes{v1.0d}{1997/11/15}
+% {Make \cs{bm} grab its argument even when protected}
+% Set up the bold (rather than heavy) version, and run |\bm@command|
+% right at the end, to execute the emboldened argument.
+% The argument is grabbed by the top level function, and explicitly
+% braced, so that |\bm| works even if the braces are omitted round
+% its argument in a `moving argument'.
+% \changes{v1.0h}{2002/11/22}{Pass math version as third (new) argument}
+% \begin{macrocode}
+\DeclareRobustCommand\bm{%
+ \bm@general\boldmath\bm@boldtable\mv@bold\bm@command}
+\protected@edef\bm#1{\bm{#1}}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\DeclareBoldMathCommand}
+% \changes{v0.07}{1996/12/14}
+% {Macro added}
+% \begin{macro}{\bm@declare}
+% \changes{v0.07}{1996/12/14}
+% {Macro added}
+% |DeclareBoldMathCommand|%^^A
+% \oarg{mathversion}\marg{command}\marg{math expression}\\
+% looks like |\bm| except at the end the specified command is
+% globally defined to be |\bm@command|.
+% The \meta{mathversion} defaults to `bold'.
+% \begin{macrocode}
+\def\DeclareBoldMathCommand{\@testopt\bm@declare{bold}}
+% \end{macrocode}
+%
+% \changes{v1.0h}{2002/11/22}{Pass math version as third (new) argument}
+% \begin{macrocode}
+\def\bm@declare[#1]#2{%
+ \expandafter\bm@general
+ \csname #1math\expandafter\endcsname
+ \csname bm@#1table\expandafter\endcsname
+ \csname mv@#1\endcsname
+ {\bm@define#2}}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\bmdefine}
+% |\bmdefine| Shorthand for |\DeclareBoldMathCommand[bold]|.
+%
+% |\bm| is empty within the definition, so that either\\
+% |\bmdefine\balpha{\bm\alpha}| or |\bmdefine\balpha{\alpha}| \\
+% may be used. (The former just for compatibility with the original
+% version for plain \TeX).
+% \begin{macrocode}
+\def\bmdefine{\DeclareBoldMathCommand[bold]}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\hm}
+% \changes{v1.0d}{1997/11/15}
+% {Make \cs{hm} grab its argument even when protected}
+% \begin{macro}{\hmdefine}
+% Same again for |\hm|.
+% \begin{macrocode}
+\ifx\mv@heavy\@undefined
+% \end{macrocode}
+%
+% If there is no heavy math version defined, let |\hm| be defined
+% as |\bm|. Currently there is no warning given, perhaps there should
+% be, or even an error?
+% \begin{macrocode}
+ \let\hm\bm
+ \let\heavymath\boldmath
+ \let\bm@heavytable\bm@boldtable
+% \end{macrocode}
+%
+% \begin{macrocode}
+\else
+% \end{macrocode}
+%
+% Otherwise define |\hm| and |\hmdefine| in direct analogy with the
+% above.
+% \changes{v1.0h}{2002/11/22}{Pass math version as third (new) argument}
+% \begin{macrocode}
+ \DeclareRobustCommand\hm{%
+ \bm@general\heavymath\bm@heavytable\mv@heavy\bm@command}
+ \protected@edef\hm#1{\hm{#1}}
+% \end{macrocode}
+%
+% \begin{macrocode}
+ \def\hmdefine{\DeclareBoldMathCommand[heavy]}
+% \end{macrocode}
+%
+% \begin{macrocode}
+\fi
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\bm@end}
+% \changes{v0.10}{1997/01/04}
+% {Macro added}
+% Normally speaking |\outer| declarations should be avoided at all
+% costs. (\LaTeX\ redefines all of plain \TeX's allocation macros
+% to be non-outer.) However this is one place where it seems like a
+% good idea. If a command taking an argument is put in |\bm| without
+% its argument, then the |\@@end| terminating token would be taken as
+% the argument, and so the rest of the paragraph would be gobbled up
+% and the \LaTeX\ would die horribly. So make the internal terminating
+% token |\outer|. (The actual test for termination is made against
+% |\@@end| not |\bm@end| as this macro will be expanded by the look-ahead
+% system.)
+% \begin{macrocode}
+\outer\def\bm@end{\@@end}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\bm@expand}
+% \changes{v0.11}{1997/01/06}
+% {Double up.}
+% \begin{macro}{\bm@exp@nd}
+% \changes{v0.11}{1997/01/06}
+% {Macro added}
+% |\afterassignment| trick to fully expand the following tokens until
+% the first non-expandable token is revealed. This may discard a space
+% token (which is what \TeX\ is looking for) but that doesn't matter in
+% math mode. The expansion lookahead is done twice in case any stray
+% space tokens have crept in.\footnote{The need for this was noticed
+% while testing \cs{sqrt}. The definition of \cs{root} inherited from
+% plain \TeX\ has an anomalous space token, that is normally harmless
+% (just wastes memory), but which killed earlier versions of this
+% package.}
+% \begin{macrocode}
+\def\bm@expand{\afterassignment\bm@exp@nd\count@`\a}
+% \end{macrocode}
+%
+% \begin{macrocode}
+\def\bm@exp@nd{\afterassignment\bm@test\count@`\a}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\bm@test}
+% Normally we will grab the non-expandable token as a macro argument
+% but better check it is not |{| first. Save the previous token
+% so we can check later if it was |\left|, in which case use the delcode
+% rather than the mathcode if the current token is a character.
+% \begin{macrocode}
+\def\bm@test{%
+ \let\bm@previous\@let@token
+ \futurelet\@let@token\bm@test@}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\bm@test@}
+% If looking at a single token, switch to |\bm@test@token|, else if
+% looking at a |{ }| group, grab the whole group with |\bm@group|.
+% A |\bgroup| token will take the wrong branch here (currently not
+% trapped).
+% \begin{macrocode}
+\def\bm@test@{%
+ \ifx\@let@token\bgroup
+ \expandafter\bm@group
+ \else
+ \expandafter\bm@test@token
+ \fi}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\bm@gr@up}
+% \changes{v1.0c}{1997/10/09}
+% {Extra brace around argument for \cs{over}}
+% If faced with a group,
+% If we are in math mode, stick it in a |\boldsymbol| like construct
+% and then recurse on |\bm@expand|.
+% Otherwise just use |\bfseries\boldmath|.
+% The actual test is deferred till `run time'.
+% Here and elsewhere could deal with the inner list with an inner call
+% to |\bm|, but that doesn't seem to gain very much, and complicates the
+% code quite a bit.
+%
+% |#1| is either |\boldmath| or |\heavymath|.
+% Need to add an extra set of explicit braces around |#2| as otherwise
+% the math style commands applied in |\mathchoice| might only apply
+% to the first half of an |\over| construction.
+% \begin{macrocode}
+\def\bm@gr@up#1#2{%
+ \bm@add{{\bm@gr@@p#1{{#2}}}}}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\bm@gr@@p}
+% |#1| is either |\boldmath| or |\heavymath|.
+% \begin{macrocode}
+\def\bm@gr@@p#1#2{%
+ \ifmmode
+ \bm@mchoice#1{#2}{#2}{#2}{#2}%
+ \else
+ \bfseries#1#2%
+ \fi}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\bm@test@token}
+% If not facing a |{ }| group then test to see what we have.
+% Basic idea: Trap |\mathchardef| tokens, character tokens, and calls to
+% |\mathchar|, |\mathaccent|, etc, and change the \emph{math-group}
+% (fam) to point at the bold version.
+% Other things just copy straight over to the command being built.
+% (Anything inside a |\mathop| or similar will end up being made bold
+% as the |\mathop| will be copied over, but its argument will be made
+% bold by the group code above.
+% \begin{macrocode}
+\def\bm@test@token#1{%
+ \let\bm@next\@empty
+% \end{macrocode}
+%
+% Stop here. Note that it is vital that the terminating token
+% is non-expandable and defined, rather than the usual \LaTeX\
+% terminators |\@nil| or |\@@|. (Worse still would be a `quark'
+% like |docstrip|'s |\qStop|.)
+% \begin{macrocode}
+ \ifx#1\@@end
+% \end{macrocode}
+%
+% |\bm@mathchoice| uses macro arguments, so need to make the tail
+% recursion explicit here. All the other cases recurse by way of
+% |\afterassignment| which means all the trailing |\fi| are eaten
+% while making the assignment.
+% \begin{macrocode}
+ \else\ifx#1\mathchoice
+ \let\bm@next\bm@mathchoice
+% \end{macrocode}
+%
+% The main point: Find these expressions, and change the mathgroup.
+% \begin{macrocode}
+ \else\ifx#1\mathchar
+ \afterassignment\bm@mathchar\count@
+ \else\ifx#1\mathaccent
+ \afterassignment\bm@mathaccent\count@
+ \else\ifx#1\delimiter
+ \afterassignment\bm@delimiter\count@
+ \else\ifx#1\radical
+ \afterassignment\bm@radical\count@
+% \end{macrocode}
+%
+% Need to trap spaces otherwise digits will get turned to bold
+% mathchars.
+% \changes{v1.1a}{2003/09/01}{Forgotten to check for \cs{hskip} (pr/3572)}
+% \begin{macrocode}
+ \else\ifx#1\mkern
+ \bm@register#1{\muskip\z@}%
+ \else\ifx#1\kern
+ \bm@register#1\skip@
+ \else\ifx#1\penalty
+ \bm@register#1\count@
+% \end{macrocode}
+%
+% \changes{v1.0f}{1998/12/10}
+% {Add possibility to copy brace group unmodified. tools/2917}
+% |\vcopy| is a flag to copy the next group unchanged to the
+% result command.
+% \begin{macrocode}
+ \else\ifx#1\unvcopy
+ \let\bm@next\bm@add
+% \end{macrocode}
+%
+% \begin{macrocode}
+ \else\ifcat\noexpand#1\relax
+% \end{macrocode}
+% Other command, look if it's a mathchardef token (otherwise just add
+% it).
+% \begin{macrocode}
+ \xdef\meaning@{\meaning#1}%
+ \expandafter\bm@mchar@test\meaning@""\@nil#1%
+% \end{macrocode}
+% \changes{v1.0d}{1997/11/15}
+% {New active \cs{mathcode} code.}
+% Character token.
+% If it is of catcode 11 or 12, get its mathcode.
+% If that is |"8000| replace the token by its active version, and then
+% let bm expansion look again at the character. Being really active
+% this time, it will expand away (probably).
+%
+% If the previous token was |\left| or |\right|, get the delcode
+% instead of the mathcode.
+% \begin{macrocode}
+ \else\ifcat.\ifcat a#1.\else#1\fi
+ \count@\mathcode`#1\relax
+ \ifnum\count@=\mathcode`\'%
+ \begingroup\uccode`\~`#1\uppercase{\endgroup
+ \def\bm@next{\bm@expand~}}%
+ \else
+ \ifx\bm@previous\left
+ \count@\delcode`#1\relax
+ \bm@delimiter
+ \else
+ \bm@mathchar
+ \fi
+ \fi
+ \else
+% \end{macrocode}
+% And final possibility:
+% a character token of catcode other than 11 or 12.
+% \begin{macrocode}
+ \bm@add{#1}%
+ \fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi
+ \bm@next}
+% \end{macrocode}
+% \end{macro}
+%
+%
+% \begin{macro}{\bm@define}
+% \changes{v0.08}{1996/12/18}
+% {Defined commands now always robust}
+% End code for |\bmdefine|. Define the given command name to the
+% robust form of the accumulated code.
+%
+% If |\bm@command| is equal to |\@gtempa| then it is a macro whose
+% expansion is a single call to |\mathchar|, so that can be optimised
+% with a |\mathchardef|.
+% \begin{macrocode}
+\def\bm@define#1{%
+ \begingroup
+ \ifx\bm@command\@gtempa
+ \def\mathchar{\global\mathchardef#1}%
+ \bm@command
+ \else
+% \end{macrocode}
+% Rather than simply |\let#1\bm@command|, make the defined command
+% robust. |\bm@first| is normally empty, but might be something like
+% |\DOTSI| which needs to be lifted to the top level, in front
+% of any |\protect| because of the lookahead mechanism used
+% in the \textsf{amsmath} package.
+% \begin{macrocode}
+ \toks@\expandafter{\bm@command}%
+ \xdef#1{\bm@first\noexpand\bm@protect\noexpand#1{\the\toks@}}%
+ \fi
+ \endgroup}
+% \end{macrocode}
+% \end{macro}
+%
+%
+% \begin{macro}{\bm@protect}
+% \changes{v0.08}{1996/12/18}
+% {macro added}
+% Commands defined by |\bmdefine| re-insert themselves
+% if protection is enabled.
+% \begin{macrocode}
+\def\bm@protect#1{%
+ \ifx\protect\@typeset@protect
+ \expandafter\@firstofone
+ \else
+ \protect#1\expandafter\@gobble
+ \fi}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\bm@mchoice}
+% |\boldsymbol|, more or less.
+% |#1| is either |\boldmath| or |\heavymath|.
+% \begin{macrocode}
+\def\bm@mchoice#1#2#3#4#5{%
+ \mathchoice{\hbox{#1$\displaystyle\m@th#2$}}%
+ {\hbox{#1$\textstyle\m@th#3$}}%
+ {\hbox{#1$\scriptstyle\m@th#4$}}%
+ {\hbox{#1$\scriptscriptstyle\m@th#5$}}}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\bm@m@thchoice}
+% Action if you find a |\mathchoice|. Add the bold version to
+% |\bm@command| then recurse.
+%
+% |#1| is either |\boldmath| or |\heavymath|.
+% \begin{macrocode}
+\def\bm@m@thchoice#1#2#3#4#5{%
+ \bm@add{\bm@mchoice#1{#2}{#3}{#4}{#5}}}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\bm@register}
+% \changes{v0.07}{1996/12/14}
+% {Macro added}
+% Combined code for setting up |\bm@r@gister| with the correct
+% register type.
+% \begin{macrocode}
+\def\bm@register#1#2{%
+ \def\@tempa{#1\the#2}%
+ \afterassignment\bm@r@gister#2}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\bm@r@gister}
+% \changes{v0.06}{1996/12/12}
+% {Support \cs{mskip}}
+% \changes{v0.07}{1996/12/14}
+% {Combine all register macros}
+% |\mkern| itself would transfer to |\bm@command| without any special
+% test, but any explict dimension following would be converted to
+% |\mathchar|. So trap this and grab the muskip as a muskip.
+% This is used in |\iiint|. |\penalty| was needed for the
+% AMS version of |\colon|, and so do most of the others as well.
+% \begin{macrocode}
+\def\bm@r@gister{%
+ \bm@xadd{\@tempa\space}}
+% \end{macrocode}
+% \end{macro}
+%
+%
+% \begin{macro}{\bm@mathchar}
+% \changes{v0.10}{1997/01/04}
+% {Modify to use \cs{boldmath} or \cs{pmb} if needed.}
+% Change the family (math group) of a mathcode and then
+% use the modified code with |\mathchar|. If there is no
+% suitable bold font in the current math version, use the original
+% unmodified mathcode, but switch to |\boldmath| (if there is a bold
+% font there) or use `poor man's bold'. Note that these other
+% possibilities are only possible here, not for the otherwise similar
+% code for |\delimiter| or |\mathaccent|, as those commands
+% must work with fonts from the same math version.
+%
+% Finally recurse down the list.
+% \begin{macrocode}
+\def\bm@mathchar{%
+% \end{macrocode}
+%
+% \begin{macrocode}
+ \@tempcntb\count@
+ \let\@tempa\bm@group
+% \end{macrocode}
+%
+% |\bm@changefam| will isolate the math group from the mathcode
+% and look up the offset in the current table.
+% \begin{macrocode}
+ \bm@changefam{}%
+% \end{macrocode}
+%
+% If the mathcode has changed, then just add the new |\mathchar|
+% (saving |\@gtempa| allows |\bmdefine| to optimise this to a
+% mathchardef if it turns out to be the only symbol in the argument).
+% \begin{macrocode}
+ \ifnum\count@>\@tempcntb
+% \end{macrocode}
+%
+% \begin{macrocode}
+ \ifx\bm@command\@empty
+ \xdef\@gtempa{\mathchar\the\count@\space}%
+ \fi
+ \bm@xadd{\mathchar\the\count@\space}%
+ \else
+% \end{macrocode}
+%
+% Otherwise grab the math class from the math code
+% and add that (locally zapping |\bm@expand| as we don't want
+% to recurse at this point).
+% \begin{macrocode}
+ \begingroup
+ \divide\count@"1000
+ \let\bm@expand\relax
+ \bm@xadd\bm@class
+ \endgroup
+% \end{macrocode}
+% |\@tempa| will be |\bm@group| (which applies |\boldmath| and
+% |\mathchoice|) unless it was changed by |\bm@changefam| to |\bm@pmb|
+% (which applies a `poor man's bold' construction in a |\mathchoice|).
+% \begin{macrocode}
+ \edef\@tempb{%
+ \noexpand\@tempa{\mathchar\the\count@\space}}%
+ \@tempb
+ \fi}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\bm@pmb}
+% \changes{v0.10}{1997/01/04}
+% {Macro added}
+% Add a poor man's bold construction to the list being built.
+% \begin{macrocode}
+\def\bm@pmb#1{%
+ \bm@add{\bm@pmb@{#1}}}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\bm@pmb@}
+% \changes{v0.10}{1997/01/04}
+% {Macro added}
+% |\pmb| variant. (See \TeX{}Book, or AMS \textsf{amsbsy} package).
+% This one takes a bit more care to use smaller offsets in subscripts.
+% \begin{macrocode}
+\def\bm@pmb@#1{{%
+ \setbox\tw@\hbox{$\m@th\mkern.4mu$}%
+ \mathchoice
+ \bm@pmb@@\displaystyle\@empty{#1}%
+ \bm@pmb@@\textstyle\@empty{#1}%
+ \bm@pmb@@\scriptstyle\defaultscriptratio{#1}%
+ \bm@pmb@@\scriptscriptstyle\defaultscriptscriptratio{#1}}}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\bm@pmb@@}
+% \changes{v0.10}{1997/01/04}
+% {Macro added}
+% Helper macro. Box |#3| and set it three times in the style |#1|,
+% offset by an amount reduced by the ratio specified in |#2|.
+% \begin{macrocode}
+\def\bm@pmb@@#1#2#3{{%
+ \setbox\z@\hbox{$\m@th#1#3$}%
+ \dimen@#2\wd\tw@
+ \rlap{\copy\z@}%
+ \kern\dimen@
+ \raise1.5\dimen@\rlap{\copy\z@}%
+ \kern\dimen@
+ \box\z@}}%
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\bm@class}
+% \changes{v0.10}{1997/01/04}
+% {Macro added}
+% Convert a numeric math class back to a math class command.
+% |\mathord| is omitted in class $0$ and $7$ to save space and so
+% things work out right in constructions such as |x^a| where
+% |x^\mathord{a}| would not work.
+% \begin{macrocode}
+\def\bm@class{%
+ \ifcase\count@
+ \or
+ \mathop\or
+ \mathbin\or
+ \mathrel\or
+ \mathopen\or
+ \mathclose\or
+ \mathpunct\or
+ \fi}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\bm@add}
+% \changes{v0.07}{1996/12/14}
+% {macro added}
+% A version of |\g@addto@macro| that internally uses a |\begingroup|
+% rather than a brace group\footnote{This bug is fixed in the \LaTeX\
+% kernel of 1996/12/01}, to save creating a mathord.
+%
+% As need to redefine it anyway, save some tokens by making
+% it specific to |\bm@command|, and to execute |\bm@expand|
+% to continue the loop.
+% \begin{macrocode}
+\def\bm@add#1{%
+ \begingroup
+ \toks@\expandafter{\bm@command#1}%
+ \xdef\bm@command{\the\toks@}%
+ \endgroup
+ \bm@expand}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\bm@xadd}
+% An |\xdef| version of |\bm@add|.
+% \begin{macrocode}
+\def\bm@xadd#1{%
+ \begingroup
+ \toks@\expandafter{\bm@command}%
+ \xdef\bm@command{\the\toks@#1}%
+ \endgroup
+ \bm@expand}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\bm@mathaccent}
+% \changes{v1.0e}{1997/11/21}
+% {Use bm on argument group, as spotted on c.t.t.}
+% |\mathaccent| version of |\bm@mathchar|.
+% \begin{macrocode}
+\def\bm@mathaccent{%
+ \bm@changefam{}%
+% \end{macrocode}
+% The next four lines were added a v1.0e. Without them |\bm{\hat{A}}|
+% makes the accent bold using |\bm| but the group |{A}| is made bold
+% via a |\mathchoice| construction as for any other group, as |\bm|
+% does not attempt to parse inside brace groups. While that produces
+% something acceptable for lower case letters, it produces
+% $\bm{\hat{{A}}}$ which is not too good. The braces may simply be
+% omitted:
+% |\bm{\hat A}| would work, producing $\bm{\hat A}$, however I did not
+% want to document such a restriction, so now modify bm so that such
+% brace groups are handled gracefully.
+%
+% It would be possible to locally make mathaccents take an argument
+% during the bm look-ahead, so the brace groups would then vanish
+% during expansion, however I would then need to explitly skip past
+% \meta{filler} and also make sure that the end of parse token
+% was not gobbled in marginal cases like |$\bm\hat$|.
+%
+% So instead do the following which gets rid of \meta{filler}
+% with a redefinition of |\relax|, and just locally changes
+% |\bm@group| so that instead of doing a |\mathchoice| it simply adds
+% |\bgroup| and |\egroup| around the tokens, and lets bm modify the
+% tokens of the `argument'. This means that |\bm{\hat{A}}| now produces
+%\begin{verbatim}
+% \mathaccent 29790 \bgroup \mathchar 30017 \egroup
+%\end{verbatim}
+% The inner math list is a single mathchar, and so \TeX\ will not box
+% it, and the math accent will correctly position, taking into account
+% the skewchar information.
+%
+% As the normal bm lookahead is used, it is automatic that the parse
+% will end without trying to go past |\bm@end|.
+%
+% One disadvantage is that the group will mean that |\bm@previous|
+% will not be correctly updated. However that is only used for
+% delimiter checking, so can not matter here.
+% \begin{macrocode}
+ \begingroup
+ \def\bm@group##1{\endgroup\bm@xadd{\bgroup}##1\egroup}%
+ \def\bm@test@token{\endgroup\bm@test@token}%
+ \let\relax\@empty
+% \end{macrocode}
+%
+% \begin{macrocode}
+ \bm@xadd{\mathaccent\the\count@\space}}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\bm@delimiter}
+% \changes{v1.0d}{1997/11/15}
+% {Support \cs{left}. null delimiter.}
+% Change both families (math groups) of a delcode and then
+% use the modified code with |\delimiter|. Don't change code `0'
+% as that denotes a null delimiter.
+% \begin{macrocode}
+\def\bm@delimiter{%
+ \ifnum\count@>\z@
+ \bm@changefam{}%
+ \bm@changefam{000}%
+ \fi
+ \bm@xadd{\delimiter\the\count@\space}}%
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\bm@radical}
+% Same for |\radical|.
+% \begin{macrocode}
+\def\bm@radical{%
+ \bm@changefam{}%
+ \bm@changefam{000}%
+ \bm@xadd{\radical\the\count@\space}}%
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\bm@mchar@}
+% Catcode 12 |\mathchar|, for |\ifx| tests.
+% \begin{macrocode}
+\edef\bm@mchar@{\meaning\mathchar}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\bm@mchar@test}
+% Test if the |\meaning| starts with |\mathchar|. If it does, grab the
+% value into |\count@| and call |\bm@mathchar|, else just copy the
+% command into the accumulated tokens.
+% |#1|, |#2|, |#3| are all |\meaning| produced tokens, or `dummy tokens'
+% added at the time this is called. |#4| is the original token, in case
+% decide not to use the |\meaning|.
+% \begin{macrocode}
+\def\bm@mchar@test#1"#2"#3\@nil#4{%
+ \xdef\meaning@{#1}%
+ \ifx\meaning@\bm@mchar@
+ \count@"#2\relax
+ \bm@mathchar
+ \else
+% \end{macrocode}
+% Some other command: copy it straight over. If it is the first thing
+% added, and it is a |\relax| token, save it in |\bm@first| for use
+% in |\bm@define|.
+% \begin{macrocode}
+ \ifx\bm@previous\@empty
+ \ifx\relax#4%
+ \gdef\bm@first{#4}%
+ \fi
+ \fi
+ \bm@add{#4}%
+ \fi}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\bm@changefam}
+% \changes{v0.10}{1997/01/04}
+% {Rewrite for new \cs{bm@table} system}
+% Pull out one specified hex digit and passes
+% it to |\bm@modify| to change. argument is empty normally but |000| to
+% access the second math group in a delimiter code.
+% \begin{macrocode}
+\def\bm@changefam#1{%
+ \@tempcnta\count@
+ \divide\@tempcnta"1000#1 %
+ \multiply\@tempcnta"1000#1 %
+ \advance\@tempcnta-\count@
+ \divide\@tempcnta-"100#1 %
+% \end{macrocode}
+% Having isolated the required math group (fam), look up
+% the offset in the current table.
+% \begin{macrocode}
+ \@tempcnta\bm@table
+% \end{macrocode}
+% If the offset is $-1$, keep |\count@| unchanged, but set |\@tempa|
+% to use poor man's bold. Otherwise increment |\count@| to change the
+% math group specified.
+% \begin{macrocode}
+ \ifnum\@tempcnta=\m@ne
+ \let\@tempa\bm@pmb
+ \else
+ \multiply\@tempcnta"100#1 %
+ \advance\count@\@tempcnta
+ \fi}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\bm@prime}
+% \changes{v1.0d}{1997/11/15}
+% {Macro added}
+% Support |'|. Earlier versions did not make the prime bold in a'.
+%
+% |\bm{a''}| will now produce (with the normal encodings)
+%\begin{verbatim}
+% \mathchar 30049
+% \bm@prime \mathchar 1584 \relax
+% \bm@prime \mathchar 1584 \relax
+%\end{verbatim}
+% So |\bm@prime| does essentially the same as the active definition of
+% |'|, which is to start a superscript group then keep adding |\prime|
+% for each |'| (or |\bm@prime|) following. Here modified to grab a
+% |\relax| delimited argument and use that instead of |\prime|.
+% |\bm@prime| is locally |\let| to |'| so the |\ifx| tests in |\pr@m@s|
+% don't need changing.
+% \begin{macrocode}
+\def\bm@prime{^\bgroup
+ \let\bm@prime'%
+ \def\prim@s##1\relax{##1\futurelet\@let@token\pr@m@s}%
+ \prim@s}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\boldsymbol}
+% \changes{v1.0b}{1997/04/14}
+% {Macro added}
+% \begin{macro}{\heavysymbol}
+% Finally, to ease conversion of documents between this package and
+% the \textsf{amsbsy} package:
+% \begin{macrocode}
+\let\boldsymbol\bm
+% \end{macrocode}
+%
+% \begin{macrocode}
+\let\heavysymbol\hm
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \begin{macrocode}
+%</package>
+% \end{macrocode}
+%
+% \Finale
+%
diff --git a/Master/texmf-dist/source/latex/tools/calc.dtx b/Master/texmf-dist/source/latex/tools/calc.dtx
new file mode 100644
index 00000000000..a96821e3c3f
--- /dev/null
+++ b/Master/texmf-dist/source/latex/tools/calc.dtx
@@ -0,0 +1,950 @@
+% \iffalse meta-comment
+%
+% Copyright 1993 1994 1995 1996 1997 1998 1999 2000 2001 2002 2003
+% The LaTeX3 Project and any individual authors listed elsewhere
+% in this file.
+%
+% This file is part of the Standard LaTeX `Tools Bundle'.
+% -------------------------------------------------------
+%
+% It 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.3 or later is part of all distributions of LaTeX
+% version 2003/12/01 or later.
+%
+% The list of all files belonging to the LaTeX `Tools Bundle' is
+% given in the file `manifest.txt'.
+%
+% \fi
+% \iffalse
+%% File `calc.dtx'.
+%% Copyright (C) 1992--1995
+%% Kresten Krab Thorup and Frank Jensen.
+%% Copyright (C) 1997--1998
+%% Kresten Krab Thorup, Frank Jensen and the LaTeX3 Project.
+%%
+%% The original authors (fj@hugin.dk and krab@daimi.aau.dk) have
+%% contributed this package to the LaTeX distribution.
+%% Problems with this package should now be sent using latexbug.tex to
+%% the normal LaTeX bug report address.
+%
+%<*dtx>
+ \ProvidesFile{calc.dtx}
+%</dtx>
+%<package>\NeedsTeXFormat{LaTeX2e}
+%<package>\ProvidesPackage{calc}
+%<driver> \ProvidesFile{calc.drv}
+% \fi
+% \ProvidesFile{calc.dtx}
+ [1998/07/07 v4.1b Infix arithmetic (KKT,FJ)]
+%
+% \iffalse
+%<*driver>
+\documentclass{ltxdoc}
+\usepackage{calc}
+\begin{document}
+\DocInput{calc.dtx}
+\end{document}
+%</driver>
+% \fi
+%
+% \GetFileInfo{calc.dtx}
+% \CheckSum{426}
+%
+% \title{The \texttt{calc} package\\Infix notation
+% arithmetic in \LaTeX\thanks{We thank Frank Mittelbach for his
+% valuable comments and suggestions which have greatly improved
+% this package.}}
+% \author{Kresten Krab Thorup, Frank Jensen (and Chris Rowley)}
+% \date{\filedate}
+%
+% \maketitle
+%
+% \changes{v4.0d}{1997/11/08}
+% {Contributed to tools distribution}
+% \changes{v4.1a}{1998/06/07}
+% {Added text sizes: CAR}
+% \changes{v4.1a}{1998/06/07}
+% {Attempt to make user-syntax robust: CAR}
+%
+% \newenvironment{calc-syntax}
+% {\par
+% \parskip\medskipamount
+% \def\is{\ \hangindent3\parindent$\longrightarrow$~}%
+% \def\alt{\ $\vert$~}%
+% \rightskip 0pt plus 1fil
+% \def\<##1>{\mbox{\NormalSpaces$\langle$##1\/$\rangle$}}%
+% \IgnoreSpaces\obeyspaces%
+% }{\par\vskip\parskip}
+% {\obeyspaces\gdef\NormalSpaces{\let =\space}\gdef\IgnoreSpaces{\def {}}}
+%
+% \def\<#1>{$\langle$#1\/$\rangle$}%
+% \def\s#1{\ensuremath{[\![#1]\!]}}
+% \def\savecode#1{\hbox{${}_{\hookrightarrow[#1]}$}}
+% \def\gassign{\Leftarrow}
+% \def\lassign{\leftarrow}
+%
+% \begin{abstract}
+% The \texttt{calc} package reimplements the \LaTeX\ commands
+% |\setcounter|, |\addtocounter|, |\setlength|, and |\addtolength|.
+% Instead of a simple value, these commands now accept an infix
+% notation expression.
+% \end{abstract}
+%
+% \section{Introduction}
+%
+% Arithmetic in \TeX\ is done using low-level operations such as
+% |\advance| and |\multiply|. This may be acceptable when developing
+% a macro package, but it is not an acceptable interface for the
+% end-user.
+%
+% This package introduces proper infix notation arithmetic which is
+% much more familiar to most people. The infix notation is more
+% readable and easier to modify than the alternative: a sequence of
+% assignment and arithmetic instructions. One of the arithmetic
+% instructions (|\divide|) does not even have an equivalent in
+% standard \LaTeX.
+%
+% The infix expressions can be used in arguments to macros (the
+% \texttt{calc} package doesn't employ category code changes to
+% achieve its goals)\footnote{However, it therefore assumes that the
+% category codes of the special characters, such as \texttt{(*/)}
+% in its syntax do not change.}.
+%
+% \section{Informal description}
+%
+% Standard \LaTeX\ provides the following set of commands to
+% manipulate counters and lengths \cite[pages 194 and~216]{latexman}.
+% \begin{itemize}
+% \item[]\hskip-\leftmargin
+% |\setcounter{|\textit{ctr}|}{|\textit{num}|}| sets the
+% value of the counter \textit{ctr} equal to (the value of)
+% \textit{num}. (Fragile)
+% \item[]\hskip-\leftmargin
+% |\addtocounter{|\textit{ctr}|}{|\textit{num}|}|
+% increments the value of the counter \textit{ctr} by (the
+% value of) \textit{num}. (Fragile)
+%
+% \item[]\hskip-\leftmargin
+% |\setlength{|\textit{cmd}|}{|\textit{len}|}| sets the value of
+% the length command \textit{cmd} equal to (the value of) \textit{len}.
+% (Robust)
+% \item[]\hskip-\leftmargin
+% |\addtolength{|\textit{cmd}|}{|\textit{len}|}| sets the value of
+% the length command \textit{cmd} equal to its current value plus
+% (the value of) \textit{len}. (Robust)
+% \end{itemize}
+% (The |\setcounter| and |\addtocounter| commands have global effect,
+% while the |\setlength| and |\addtolength| commands obey the normal
+% scoping rules.) In standard \LaTeX, the arguments to these commands
+% must be simple values. The \texttt{calc} package extends these
+% commands to accept infix notation expressions, denoting values of
+% appropriate types. Using the \texttt{calc} package, \textit{num} is
+% replaced by \<integer expression>, and \textit{len} is replaced by
+% \<glue expression>. The formal syntax of \<integer expression> and
+% \<glue expression> is given below.
+%
+% In addition to these commands to explicitly set a length, many \LaTeX\
+% commands take a length argument. After loading this package, most of
+% these commands will accept a \<glue expression>. This includes
+% the optional width argument of |\makebox|, the width argument of
+% |\parbox|, |minipage|, and a |tabluar| |p|-column, and many similar
+% constructions. (This package does not redefine any of these commands,
+% but they are defined by default to read their arguments by |\setlength|
+% and so automatically benefit from the enhanced |\setlength| command
+% provided by this package.)
+%
+% In the following, we shall use standard \TeX\ terminology. The
+% correspondence between \TeX\ and \LaTeX\ terminology is as follows:
+% \LaTeX\ counters correspond to \TeX's count registers; they hold
+% quantities of type \<number>. \LaTeX\ length commands correspond to
+% \TeX's dimen (for rigid lengths) and skip (for rubber lengths)
+% registers; they hold quantities of types \<dimen> and \<glue>,
+% respectively.
+%
+% \TeX\ gives us primitive operations to perform arithmetic on registers as
+% follows:
+% \begin{itemize}
+% \item addition and subtraction on all types of quantities without
+% restrictions;
+% \item multiplication and division by an \emph{integer} can be
+% performed on a register of any type;
+% \item multiplication by a \emph{real} number (i.e., a number with a
+% fractional part) can be performed on a register of any type,
+% but the stretch and shrink components of a glue quantity are
+% discarded.
+% \end{itemize}
+% The \texttt{calc} package uses these \TeX\ primitives but provides a
+% more user-friendly notation for expressing the arithmetic.
+%
+% An expression is formed of numerical quantities (such as explicit
+% constants and \LaTeX\ counters and length commands) and binary
+% operators (the tokens `\texttt{+}', `\texttt{-}', `\texttt{*}', and
+% `\texttt{/}' with their usual meaning) using the familiar infix
+% notation; parentheses may be used to override the usual precedences
+% (that multiplication/division have higher precedence than
+% addition/subtraction).
+%
+% Expressions must be properly typed. This means, e.g., that a dimen
+% expression must be a sum of dimen terms: i.e., you cannot say
+% `\texttt{2cm+4}' but `\texttt{2cm+4pt}' is valid.
+%
+% In a dimen term, the dimension part must come first; the same holds
+% for glue terms. Also, multiplication and division by non-integer
+% quantities require a special syntax; see below.
+%
+% Evaluation of subexpressions at the same level of precedence
+% proceeds from left to right. Consider a dimen term such as
+% ``\texttt{4cm*3*4}''. First, the value of the factor \texttt{4cm} is
+% assigned to a dimen register, then this register is multiplied
+% by~$3$ (using |\multiply|), and, finally, the register is multiplied
+% by~$4$ (again using |\multiply|). This also explains why the
+% dimension part (i.e., the part with the unit designation) must come
+% first; \TeX\ simply doesn't allow untyped constants to be assigned
+% to a dimen register.
+%
+% The \texttt{calc} package also allows multiplication and division by
+% real numbers. However, a special syntax is required: you must use
+% |\real{|\<decimal constant>|}|\footnote{Actually, instead of
+% \<decimal constant>, the more general \<optional signs>\<factor> can
+% be used. However, that doesn't add any extra expressive power to
+% the language of infix expressions.} or
+% |\ratio{|\<dimen expression>|}{|\<dimen expression>|}| to denote a
+% real value to be used for multiplication/division. The first form has
+% the obvious meaning, and the second form denotes the number obtained
+% by dividing the value of the first expression by the value of the
+% second expression.
+%
+% A later addition to the package (in June 1998) allows an additional
+% method of specifying a factor of type dimen by setting some text
+% (in LR-mode) and measuring its dimensions: these are denoted as
+% follows.
+%\begin{quote}
+% |\widthof{|\<text>|}|\quad
+% |\heightof{|\<text>|}|\quad
+% |\depthof{|\<text>|}|
+%\end{quote}
+% These calculate the natural sizes of the \<text> in exactly the
+% same way as is done for the commands |\settowidth| etc.~on
+% Page~216 of the manual~\cite{latexman}.
+%
+% Note that there is a small difference in the usage of these two
+% methods of accessing text dimensions. After
+% |\settowidth{\txtwd}{Some text}| you can use:
+%\begin{verbatim}
+% \setlength{\parskip}{0.68\textwd}
+%\end{verbatim}
+% whereas using the more direct access to the width of the text
+% requires the longer form for multiplication, thus:
+%\begin{verbatim}
+% \setlength{\parskip}{\widthof{Some text} * \real{0.68}}
+%\end{verbatim}
+%
+% \TeX\ discards the stretch and shrink components of glue when glue
+% is multiplied by a real number. So, for example,
+%\begin{verbatim}
+% \setlength{\parskip}{3pt plus 3pt * \real{1.5}}
+%\end{verbatim}
+% will set the paragraph separation to 4.5pt with no stretch or
+% shrink. (Incidentally, note how spaces can be used to enhance
+% readability.)
+%
+% When \TeX\ performs arithmetic on integers, any fractional part of
+% the results are discarded. For example,
+%\begin{verbatim}
+% \setcounter{x}{7/2}
+% \setcounter{y}{3*\real{1.6}}
+% \setcounter{z}{3*\real{1.7}}
+%\end{verbatim}
+% will assign the value~$3$ to the counter~\texttt{x}, the value~$4$
+% to~\texttt{y}, and the value~$5$ to~\texttt{z}. This truncation
+% also applies to \emph{intermediate} results in the sequential
+% computation of a composite expression; thus, the following command
+%\begin{verbatim}
+% \setcounter{x}{3 * \real{1.6} * \real{1.7}}
+%\end{verbatim}
+% will assign~$6$ to~\texttt{x}.
+%
+% As an example of the use of |\ratio|, consider the problem of
+% scaling a figure to occupy the full width (i.e., |\textwidth|) of
+% the body of a page. Assume that the original dimensions of the
+% figure are given by the dimen (length) variables, |\Xsize| and
+% |\Ysize|. The height of the scaled figure can then be expressed by
+%\begin{verbatim}
+% \setlength{\newYsize}{\Ysize*\ratio{\textwidth}{\Xsize}}
+%\end{verbatim}
+%
+% \section{Formal syntax}
+%
+% The syntax is described by the following set of rules.
+% Note that the definitions of \<number>, \<dimen>, \<glue>,
+% \<decimal constant>, and \<plus or minus> are
+% as in Chapter~24 of The \TeX book~\cite{texbook}; and \<text>
+% is LR-mode material, as in the manual~\cite{latexman}.
+% We use \textit{type} as a meta-variable, standing for
+% `integer', `dimen', and `glue'.\footnote{This version of the
+% \texttt{calc} package doesn't support evaluation of muglue expressions.}
+% \begin{calc-syntax}
+% \<\textit{type} expression>
+% \is \<\textit{type} term>
+% \alt \<\textit{type} expression> \<plus or minus> \<\textit{type} term>
+%
+% \<\textit{type} term>
+% \is \<\textit{type} factor>
+% \alt \<\textit{type} term> \<multiply or divide> \<integer factor>
+% \alt \<\textit{type} term> \<multiply or divide> \<real number>
+%
+% \<\textit{type} factor>
+% \is \<\textit{type}>
+% \alt \<text dimen factor>
+% \alt |(|$_{12}$ \<\textit{type} expression> |)|$_{12}$
+%
+% \<integer> \is \<number>
+%
+% \<text dimen factor>
+% \is \<text dimen command>|{| \<text> |}|
+%
+% \<text dimen command>
+% \is |\widthof|
+% \alt |\heightof|
+% \alt |\depthof|
+%
+% \<multiply or divide>
+% \is |*|$_{12}$
+% \alt |/|$_{12}$
+%
+% \<real number>
+% \is |\ratio{| \<dimen expression> |}{| \<dimen expression> |}|
+% \alt |\real{| \<decimal constant> |}|
+% \end{calc-syntax}
+%
+% Note that during most of the parsing of calc expressions, no
+% expansion happens; thus the above syntax must be
+% explicit\footnote{Two exceptions to this are: the first token
+% is expanded one-level (thus the whole expression can be put into a
+% macro); wherever a \<decimal constant> or \<\texttt{type}> is
+% expected.}.
+% \StopEventually{
+% \begin{thebibliography}{1}
+% \bibitem{texbook}
+% \textsc{D. E. Knuth}.
+% \newblock \textit{The \TeX{}book} (Computers \& Typesetting Volume A).
+% \newblock Addison-Wesley, Reading, Massachusetts, 1986.
+% \bibitem{latexman}
+% \textsc{L. Lamport}.
+% \newblock \textit{\LaTeX, A Document Preparation System.}
+% \newblock Addison-Wesley, Reading, Massachusetts, Second
+% edition 1994/1985.
+% \end{thebibliography}
+% }
+%
+% \section{The evaluation scheme}
+% \label{evaluation:scheme}
+%
+% In this section, we shall for simplicity consider only expressions
+% containing `$+$' (addition) and `$*$' (multiplication) operators.
+% It is trivial to add subtraction and division.
+%
+% An expression $E$ is a sum of terms: $T_1+\cdots+T_n$; a term is a
+% product of factors: $F_1*\cdots*F_m$; a factor is either a simple
+% numeric quantity~$f$ (like \<number> as described in the \TeX book),
+% or a parenthesized expression~$(E')$.
+%
+% Since the \TeX\ engine can only execute arithmetic operations in a
+% machine-code like manner, we have to find a way to translate the
+% infix notation into this `instruction set'.
+%
+% Our goal is to design a translation scheme that translates~$X$ (an
+% expression, a term, or a factor) into a sequence of \TeX\ instructions
+% that does the following [Invariance Property]: correctly
+% evaluates~$X$, leaves the result in a global register~$A$ (using a
+% global assignment), and does not perform global assignments to the
+% scratch register~$B$; moreover, the code sequence must be balanced
+% with respect to \TeX\ groups. We shall denote the code sequence
+% corresponding to~$X$ by \s{X}.
+%
+% In the replacement code specified below, we use the following
+% conventions:
+% \begin{itemize}
+% \item $A$ and $B$ denote registers; all assignments to~$A$ will
+% be global, and all assignments to~$B$ will be local.
+% \item ``$\gassign$'' means global assignment to the register on
+% the lhs.
+% \item ``$\lassign $'' means local assignment to the register on
+% the lhs.
+% \item ``\savecode C'' means ``save the code~$C$ until the current
+% group (scope) ends, then execute it.'' This corresponds to
+% the \TeX-primitive |\aftergroup|.
+% \item ``$\{$'' denotes the start of a new group, and ``$\}$''
+% denotes the end of a group.
+% \end{itemize}
+%
+% Let us consider an expression $T_1+T_2+\cdots+T_n$. Assuming that
+% \s{T_k} ($1\le k\le n$) attains the stated goal, the following code
+% clearly attains the stated goal for their sum:
+% \begin{eqnarray*}
+% \s{T_1+T_2+\cdots+T_n}&\Longrightarrow&
+% \{\,\s{T_1}\,\} \; B\lassign A \quad
+% \{\,\s{T_2}\,\} \; B\lassign B+A \\
+% &&\qquad \ldots \quad \{\,\s{T_n}\,\} \; B\lassign B+A
+% \quad A\gassign B
+% \end{eqnarray*}
+% Note the extra level of grouping enclosing each of \s{T_1}, \s{T_2},
+% \ldots,~\s{T_n}. This will ensure that register~$B$, used to
+% compute the sum of the terms, is not clobbered by the intermediate
+% computations of the individual terms. Actually, the group
+% enclosing~\s{T_1} is unnecessary, but it turns out to be simpler if
+% all terms are treated the same way.
+%
+% The code sequence ``$\{\,\s{T_2}\,\}\;B\lassign B+A$'' can be translated
+% into the following equivalent code sequence:
+% ``$\{\savecode{B\lassign B+A}\,\s{T_2}\,\}$''. This observation turns
+% out to be the key to the implementation: The ``$\savecode{B\lassign
+% B+A}$'' is generated \emph{before} $T_2$ is translated, at the same
+% time as the `$+$' operator between $T_1$ and~$T_2$ is seen.
+%
+% Now, the specification of the translation scheme is straightforward:
+% \begin{eqnarray*}
+% \s{f}&\Longrightarrow&A\gassign f\\[\smallskipamount]
+% \s{(E')}&\Longrightarrow&\s{E'}\\[\smallskipamount]
+% \s{T_1+T_2+\cdots+T_n}&\Longrightarrow&
+% \{\savecode{B\lassign A}\,\s{T_1}\,\} \quad
+% \{\savecode{B\lassign B+A}\,\s{T_2}\,\} \\
+% &&\qquad \ldots \quad \{\savecode{B\lassign B+A}\,\s{T_n}\,\}
+% \quad A\gassign B
+% \\[\smallskipamount]
+% \s{F_1*F_2*\cdots*F_m}&\Longrightarrow&
+% \{\savecode{B\lassign A}\,\s{F_1}\,\} \quad
+% \{\savecode{B\lassign B*A}\,\s{F_2}\,\}\\
+% &&\qquad \ldots \quad \{\savecode{B\lassign B*A}\,\s{F_m}\,\}
+% \quad A\gassign B
+% \end{eqnarray*}
+% By structural induction, it is easily seen that the stated property
+% is attained.
+%
+% By inspection of this translation scheme, we see that we have to
+% generate the following code:
+% \begin{itemize}
+% \item we must generate ``$\{\savecode{B\lassign
+% A}\{\savecode{B\lassign A}$'' at the left border of an
+% expression (i.e., for each left parenthesis and the implicit
+% left parenthesis at the beginning of the whole expression);
+% \item we must generate ``$\}A\gassign B\}A\gassign B$'' at the
+% right border of an expression (i.e., each right parenthesis
+% and the implicit right parenthesis at the end of the full
+% expression);
+% \item `\texttt{*}' is replaced by ``$\}\{\savecode{B\lassign
+% B*A}$'';
+% \item `\texttt{+}' is replaced by
+% ``$\}A\gassign B\}\{\savecode{B\lassign
+% B+A}\{\savecode{B\lassign A}$'';
+% \item when we see (expect) a numeric quantity, we insert the
+% assignment code ``$A\gassign$'' in front of the quantity and let
+% \TeX\ parse it.
+% \end{itemize}
+%
+% \section{Implementation}
+%
+% For brevity define
+% \begin{calc-syntax}
+% \<numeric> \is \<number> \alt \<dimen> \alt \<glue> \alt \<muglue>
+% \end{calc-syntax}
+% So far we have ignored the question of how to determine the type of
+% register to be used in the code. However, it is easy to see that
+% (1)~`$*$' always initiates an \<integer factor>, (2)~all
+% \<numeric>s in an expression, except those which are part of an
+% \<integer factor>, are of the same type as the whole expression, and
+% all \<numeric>s in an \<integer factor> are \<number>s.
+%
+% We have to ensure that $A$ and~$B$ always have an appropriate type
+% for the \<numeric>s they manipulate. We can achieve this by having
+% an instance of $A$ and~$B$ for each type. Initially, $A$~and~$B$
+% refer to registers of the proper type for the whole expression.
+% When an \<integer factor> is expected, we must change $A$ and~$B$ to
+% refer to integer type registers. We can accomplish this by
+% including instructions to change the type of $A$ and~$B$ to integer
+% type as part of the replacement code for~`$*$; if we append such
+% instructions to the replacement code described above, we also ensure
+% that the type-change is local (provided that the type-changing
+% instructions only have local effect). However, note that the
+% instance of~$A$ referred to in $\savecode{B\lassign B*A}$ is the
+% integer instance of~$A$.
+%
+% We shall use |\begingroup| and |\endgroup| for the open-group and
+% close-group characters. This avoids problems with spacing in math
+% (as pointed out to us by Frank Mittelbach).
+%
+% \subsection{Getting started}
+%
+% Now we have enough insight to do the actual implementation in \TeX.
+% First, we announce the macro package\footnote{Code moved to top of file}.
+% \begin{macrocode}
+%<*package>
+%\NeedsTeXFormat{LaTeX2e}
+%\ProvidesPackage{calc}[\filedate\space\fileversion]
+% \end{macrocode}
+%
+% \subsection{Assignment macros}
+%
+% \begin{macro}{\calc@assign@generic}
+% The |\calc@assign@generic| macro takes four arguments: (1~and~2) the
+% registers to be used
+% for global and local manipulations, respectively; (3)~the lvalue
+% part; (4)~the expression to be evaluated.
+%
+% The third argument (the lvalue) will be used as a prefix to a
+% register that contains the value of the specified expression (the
+% fourth argument).
+%
+% In general, an lvalue is anything that may be followed by a variable
+% of the appropriate type. As an example, |\linepenalty| and
+% |\global\advance\linepenalty| may both be followed by an \<integer
+% variable>.
+%
+% The macros described below refer to the registers by the names
+% |\calc@A| and |\calc@B|; this is accomplished by
+% |\let|-assignments.
+%
+% As discovered in Section~\ref{evaluation:scheme}, we have to
+% generate code as
+% if the expression is parenthesized. As described below,
+% |\calc@open| is the macro that replaces a left parenthesis by its
+% corresponding \TeX\ code sequence. When the scanning process sees
+% the exclamation point, it generates an |\endgroup| and stops. As we
+% recall from Section~\ref{evaluation:scheme}, the correct expansion
+% of a right
+% parenthesis is ``$\}A\gassign B\}A\gassign B$''. The remaining
+% tokens of this expansion are inserted explicitly, except that the
+% last assignment has been replaced by the lvalue part (i.e.,
+% argument~|#3| of |\calc@assign@generic|) followed by |\calc@B|.
+% \end{macro}
+% \begin{macrocode}
+\def\calc@assign@generic#1#2#3#4{\let\calc@A#1\let\calc@B#2%
+ \expandafter\calc@open\expandafter(#4!%
+ \global\calc@A\calc@B\endgroup#3\calc@B}
+% \end{macrocode}
+% (The |\expandafter| tokens allow the user to use expressions stored
+% one-level deep in a macro as arguments in assignment commands.)
+%
+% \begin{macro}{\calc@assign@count}
+% \begin{macro}{\calc@assign@dimen}
+% \begin{macro}{\calc@assign@skip}
+% We need three instances of the |\calc@assign@generic| macro,
+% corresponding to the types \<integer>, \<dimen>, and \<glue>.
+% \begin{macrocode}
+\def\calc@assign@count{\calc@assign@generic\calc@Acount\calc@Bcount}
+\def\calc@assign@dimen{\calc@assign@generic\calc@Adimen\calc@Bdimen}
+\def\calc@assign@skip{\calc@assign@generic\calc@Askip\calc@Bskip}
+% \end{macrocode}
+% \end{macro}\end{macro}\end{macro}
+% These macros each refer to two registers, one
+% to be used globally and one to be used locally.
+% We must allocate these registers.
+% \begin{macrocode}
+\newcount\calc@Acount \newcount\calc@Bcount
+\newdimen\calc@Adimen \newdimen\calc@Bdimen
+\newskip\calc@Askip \newskip\calc@Bskip
+% \end{macrocode}
+%
+% \subsection{The \LaTeX\ interface}
+%
+% As promised, we redefine the following standard \LaTeX\ commands:
+% |\setcounter|,
+% |\addtocounter|, |\setlength|, and |\addtolength|.
+% \begin{macrocode}
+\def\setcounter#1#2{\@ifundefined{c@#1}{\@nocounterr{#1}}%
+ {\calc@assign@count{\global\csname c@#1\endcsname}{#2}}}
+\def\addtocounter#1#2{\@ifundefined{c@#1}{\@nocounterr{#1}}%
+ {\calc@assign@count{\global\advance\csname c@#1\endcsname}{#2}}}
+% \end{macrocode}
+% \begin{macrocode}
+\DeclareRobustCommand\setlength{\calc@assign@skip}
+\DeclareRobustCommand\addtolength[1]{\calc@assign@skip{\advance#1}}
+% \end{macrocode}
+% (|\setlength| and |\addtolength| are robust according to
+% \cite{latexman}.)
+%
+% \subsection{The scanner}
+%
+% We evaluate expressions by explicit scanning of characters. We do
+% not rely on active characters for this.
+%
+% The scanner consists of two parts, |\calc@pre@scan| and
+% |\calc@post@scan|; |\calc@pre@scan| consumes left parentheses, and
+% |\calc@post@scan| consumes binary operator, |\real|, |\ratio|, and
+% right parenthesis tokens.
+% \begin{macro}{\calc@pre@scan}
+%
+% Note that this is called at least once on every use of calc
+% processing, even when none of the extended syntax is present; it
+% therefore needs to be made very efficient.
+%
+% It reads the initial part of expressions, until some \<text dimen
+% factor> or \<numeric> is seen; in fact, anything not explicitly
+% recognized here is taken to be a \<numeric> of some sort as this
+% allows unary
+% `\texttt{+}' and unary `\texttt{-}' to be treated easily and
+% correctly\footnote{In the few contexts where signs are allowed:
+% this could, I think, be extended (CAR).} but means that anything
+% illegal will simply generate a \TeX-level error, often a
+% reasonably comprehensible one!
+%
+% The many |\expandafter|s are needed to efficiently end the nested
+% conditionals so that |\calc@textsize| can process its argument.
+% \changes{v4.1a}{1998/06/07}
+% {Added code for text sizes: CAR}
+% \changes{v4.1b}{1998/07/07}
+% {Correction to ifx true case}
+% \begin{macrocode}
+\def\calc@pre@scan#1{%
+ \ifx(#1%
+ \expandafter\calc@open
+ \else
+ \ifx\widthof#1%
+ \expandafter\expandafter\expandafter\calc@textsize
+ \else
+ \calc@numeric% no \expandafter needed for this one.
+ \fi
+ \fi
+ #1}
+% \end{macrocode}
+% \end{macro}
+% |\calc@open| is used when there is a left parenthesis right ahead.
+% This parenthesis is replaced by \TeX\ code corresponding to the code
+% sequence ``$\{\savecode{B\lassign A}\{\savecode{B\lassign A}$''
+% derived in Section~\ref{evaluation:scheme}. Finally,
+% |\calc@pre@scan| is
+% called again.
+% \begin{macrocode}
+\def\calc@open({\begingroup\aftergroup\calc@initB
+ \begingroup\aftergroup\calc@initB
+ \calc@pre@scan}
+\def\calc@initB{\calc@B\calc@A}
+% \end{macrocode}
+% |\calc@numeric| assigns the following value to |\calc@A| and then
+% transfers control to |\calc@post@scan|.
+% \begin{macrocode}
+\def\calc@numeric{\afterassignment\calc@post@scan \global\calc@A}
+% \end{macrocode}
+%
+% \begin{macro}{\widthof}
+% \begin{macro}{\heightof}
+% \begin{macro}{\depthof}
+% \changes{v4.1a}{1998/06/07}
+% {Added macros: CAR}
+%
+% These do not need any particular definition when they are scanned
+% so, for efficiency and robustness, we make them all equivalent to
+% the same harmless (I hope) unexpandable command\footnote{If this
+% level of safety is not needed then the code can be speeded up:
+% CAR.}. Thus the test in |\calc@pre@scan| finds any of them.
+% They are first defined using |\newcommand| so that they appear to
+% be normal user commands to a \LaTeX{} user\footnote{Is this
+% necessary, CAR?}.
+% \begin{macrocode}
+\newcommand\widthof{}
+\let\widthof\ignorespaces
+\newcommand\heightof{}
+\let\heightof\ignorespaces
+\newcommand\depthof{}
+\let\depthof\ignorespaces
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\calc@textsize}
+% \changes{v4.1a}{1998/06/07}
+% {Added macro: CAR}
+% The presence of the above three commands invokes this code, where
+% we must distinguish them from each other.
+% This implementation is somewhat optimized by using low-level
+% code from the commands |\settowidth|, etc\footnote{It is based on
+% suggestions by Donald Arsenau and David Carlisle.}.
+%
+% Within the text argument we must restore the normal meanings of
+% the three user-level commands since arbitrary material can appear
+% in here, including further uses of calc.
+% \begin{macrocode}
+\def\calc@textsize #1#2{%
+ \begingroup
+ \let\widthof\wd
+ \let\heightof\ht
+ \let\depthof\dp
+ \@settodim #1%
+ {\global\calc@A}%
+ {%
+ \let\widthof\ignorespaces
+ \let\heightof\ignorespaces
+ \let\depthof\ignorespaces
+ #2}%
+ \endgroup
+ \calc@post@scan}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\calc@post@scan}
+% The macro |\calc@post@scan| is called right after a value has been
+% read. At this point, a binary operator, a sequence of right
+% parentheses, and the end-of-expression mark (`|!|') is
+% allowed\footnote{Is \texttt{!} a good choice, CAR?}.
+% Depending on our findings, we call a suitable macro to generate the
+% corresponding \TeX\ code (except when we detect the
+% end-of-expression marker: then scanning ends, and
+% control is returned to |\calc@assign@generic|).
+%
+% This macro may be optimized by selecting a different order of
+% |\ifx|-tests. The test for `\texttt{!}' (end-of-expression) is
+% placed first as it will always be performed: this is the only test
+% to be performed if the expression consists of a single \<numeric>.
+% This ensures that documents that do not use the extra expressive
+% power provided by the \texttt{calc} package only suffer a minimum
+% slowdown in processing time.
+% \end{macro}
+% \begin{macrocode}
+\def\calc@post@scan#1{%
+ \ifx#1!\let\calc@next\endgroup \else
+ \ifx#1+\let\calc@next\calc@add \else
+ \ifx#1-\let\calc@next\calc@subtract \else
+ \ifx#1*\let\calc@next\calc@multiplyx \else
+ \ifx#1/\let\calc@next\calc@dividex \else
+ \ifx#1)\let\calc@next\calc@close \else \calc@error#1%
+ \fi
+ \fi
+ \fi
+ \fi
+ \fi
+ \fi
+ \calc@next}
+% \end{macrocode}
+%
+% The replacement code for the binary operators `\texttt{+}' and
+% `\texttt{-}' follow a common pattern; the only difference is the
+% token that is stored away by |\aftergroup|. After this replacement
+% code, control is transferred to |\calc@pre@scan|.
+% \begin{macrocode}
+\def\calc@add{\calc@generic@add\calc@addAtoB}
+\def\calc@subtract{\calc@generic@add\calc@subtractAfromB}
+\def\calc@generic@add#1{\endgroup\global\calc@A\calc@B\endgroup
+ \begingroup\aftergroup#1\begingroup\aftergroup\calc@initB
+ \calc@pre@scan}
+\def\calc@addAtoB{\advance\calc@B\calc@A}
+\def\calc@subtractAfromB{\advance\calc@B-\calc@A}
+% \end{macrocode}
+%
+% \begin{macro}{\real}
+% \begin{macro}{\ratio}
+% The multiplicative operators, `\texttt{*}' and `\texttt{/}', may be
+% followed by a |\real| or a |\ratio| token. Those control sequences
+% are not defined (at least not by the \texttt{calc} package); this,
+% unfortunately, leaves them highly non-robust. We therefore
+% equate them to |\relax| but only if they have not already been
+% defined\footnote{Suggested code from David Carlisle.}
+% (by some other package: dangerous but possible!); this
+% will also make them appear to be undefined to a \LaTeX{} user
+% (also possibly dangerous).
+% \changes{v4.1a}{1998/06/07}
+% {Added macro set-ups to make them robust but undefined: CAR}
+% \begin{macrocode}
+\ifx\real\@undefined\let\real\relax\fi
+\ifx\ratio\@undefined\let\ratio\relax\fi
+% \end{macrocode}
+% In order to test for them, we define these two\footnote{May not
+% need the extra names, CAR?}.
+% \begin{macrocode}
+\def\calc@ratio@x{\ratio}
+\def\calc@real@x{\real}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macrocode}
+\def\calc@multiplyx#1{\def\calc@tmp{#1}%
+ \ifx\calc@tmp\calc@ratio@x \let\calc@next\calc@ratio@multiply \else
+ \ifx\calc@tmp\calc@real@x \let\calc@next\calc@real@multiply \else
+ \let\calc@next\calc@multiply
+ \fi
+ \fi
+ \calc@next#1}
+\def\calc@dividex#1{\def\calc@tmp{#1}%
+ \ifx\calc@tmp\calc@ratio@x \let\calc@next\calc@ratio@divide \else
+ \ifx\calc@tmp\calc@real@x \let\calc@next\calc@real@divide \else
+ \let\calc@next\calc@divide
+ \fi
+ \fi
+ \calc@next#1}
+% \end{macrocode}
+% The binary operators `\texttt{*}' and `\texttt{/}' also insert code
+% as determined above. Moreover, the meaning of |\calc@A| and
+% |\calc@B| is changed as factors following a multiplication and
+% division operator always have integer type; the original meaning of
+% these macros will be restored when the factor has been read and
+% evaluated.
+% \begin{macrocode}
+\def\calc@multiply{\calc@generic@multiply\calc@multiplyBbyA}
+\def\calc@divide{\calc@generic@multiply\calc@divideBbyA}
+\def\calc@generic@multiply#1{\endgroup\begingroup
+ \let\calc@A\calc@Acount \let\calc@B\calc@Bcount
+ \aftergroup#1\calc@pre@scan}
+\def\calc@multiplyBbyA{\multiply\calc@B\calc@Acount}
+\def\calc@divideBbyA{\divide\calc@B\calc@Acount}
+% \end{macrocode}
+% Since the value to use in the multiplication/division operation is
+% stored in the |\calc@Acount| register, the |\calc@multiplyBbyA| and
+% |\calc@divideBbyA| macros use this register.
+%
+% |\calc@close| generates code for a right parenthesis (which was
+% derived to be ``$\}A\gassign B\}A\gassign B$'' in
+% Section~\ref{evaluation:scheme}). After this code, the control is
+% returned to
+% |\calc@post@scan| in order to look for another right parenthesis or
+% a binary operator.
+% \begin{macrocode}
+\def\calc@close
+ {\endgroup\global\calc@A\calc@B
+ \endgroup\global\calc@A\calc@B
+ \calc@post@scan}
+% \end{macrocode}
+%
+% \subsection{Calculating a ratio}
+%
+% When |\calc@post@scan| encounters a |\ratio| control sequence, it hands
+% control to one of the macros |\calc@ratio@multiply| or |\calc@ratio@divide|,
+% depending on the preceding character. Those macros both forward the
+% control to the macro |\calc@ratio@evaluate|, which performs two steps: (1) it
+% calculates the ratio, which is saved in the global macro token
+% |\calc@the@ratio|; (2) it makes sure that the value of |\calc@B| will be
+% multiplied by the ratio as soon as the current group ends.
+%
+% The following macros call |\calc@ratio@evaluate| which multiplies
+% |\calc@B| by the ratio, but |\calc@ratio@divide| flips the arguments
+% so that the `opposite' fraction is actually evaluated.
+% \begin{macrocode}
+\def\calc@ratio@multiply\ratio{\calc@ratio@evaluate}
+\def\calc@ratio@divide\ratio#1#2{\calc@ratio@evaluate{#2}{#1}}
+% \end{macrocode}
+% We shall need two registers for temporary usage in the
+% calculations. We can save one register since we can reuse
+% |\calc@Bcount|.
+% \begin{macrocode}
+\let\calc@numerator=\calc@Bcount
+\newcount\calc@denominator
+% \end{macrocode}
+% Here is the macro that handles the actual evaluation of ratios. The
+% procedure is
+% this: First, the two expressions are evaluated and coerced to
+% integers. The whole procedure is enclosed in a group to be able to
+% use the registers |\calc@numerator| and |\calc@denominator| for temporary
+% manipulations.
+% \begin{macrocode}
+\def\calc@ratio@evaluate#1#2{%
+ \endgroup\begingroup
+ \calc@assign@dimen\calc@numerator{#1}%
+ \calc@assign@dimen\calc@denominator{#2}%
+% \end{macrocode}
+% Here we calculate the ratio. First, we check for negative numerator
+% and/or denominator; note that \TeX\ interprets two minus signs the
+% same as a plus sign. Then, we calculate the integer part.
+% The minus sign(s), the integer part, and a decimal point, form the
+% initial expansion of the |\calc@the@ratio| macro.
+% \begin{macrocode}
+ \gdef\calc@the@ratio{}%
+ \ifnum\calc@numerator<0 \calc@numerator-\calc@numerator
+ \gdef\calc@the@ratio{-}%
+ \fi
+ \ifnum\calc@denominator<0 \calc@denominator-\calc@denominator
+ \xdef\calc@the@ratio{\calc@the@ratio-}%
+ \fi
+ \calc@Acount\calc@numerator
+ \divide\calc@Acount\calc@denominator
+ \xdef\calc@the@ratio{\calc@the@ratio\number\calc@Acount.}%
+% \end{macrocode}
+% Now we generate the digits after the decimal point, one at a time.
+% When \TeX\ scans these digits (in the actual multiplication
+% operation), it forms a fixed-point number with 16~bits for
+% the fractional part. We hope that six digits is sufficient, even
+% though the last digit may not be rounded correctly.
+% \begin{macrocode}
+ \calc@next@digit \calc@next@digit \calc@next@digit
+ \calc@next@digit \calc@next@digit \calc@next@digit
+ \endgroup
+% \end{macrocode}
+% Now we have the ratio represented (as the expansion of the global
+% macro |\calc@the@ratio|) in the syntax \<decimal constant>
+% \cite[page~270]{texbook}. This is fed to |\calc@multiply@by@real|
+% that will
+% perform the actual multiplication. It is important that the
+% multiplication takes place at the correct grouping level so that the
+% correct instance of the $B$ register will be used. Also note that
+% we do not need the |\aftergroup| mechanism in this case.
+% \begin{macrocode}
+ \calc@multiply@by@real\calc@the@ratio
+ \begingroup
+ \calc@post@scan}
+% \end{macrocode}
+% The |\begingroup| inserted before the |\calc@post@scan| will be
+% matched by the |\endgroup| generated as part of the replacement of a
+% subsequent binary operator or right parenthesis.
+% \begin{macrocode}
+\def\calc@next@digit{%
+ \multiply\calc@Acount\calc@denominator
+ \advance\calc@numerator -\calc@Acount
+ \multiply\calc@numerator 10
+ \calc@Acount\calc@numerator
+ \divide\calc@Acount\calc@denominator
+ \xdef\calc@the@ratio{\calc@the@ratio\number\calc@Acount}}
+% \end{macrocode}
+% In the following code, it is important that we first assign the
+% result to a dimen register. Otherwise, \TeX\ won't allow us to
+% multiply with a real number.
+% \begin{macrocode}
+\def\calc@multiply@by@real#1{\calc@Bdimen #1\calc@B \calc@B\calc@Bdimen}
+% \end{macrocode}
+% (Note that this code wouldn't work if |\calc@B| were a muglue
+% register. This is the real reason why the \texttt{calc} package
+% doesn't support muglue expressions. To support muglue expressions
+% in full, the |\calc@multiply@by@real| macro must use a muglue register
+% instead of |\calc@Bdimen| when |\calc@B| is a muglue register;
+% otherwise, a dimen register should be used. Since integer
+% expressions can appear as part of a muglue expression, it would be
+% necessary to determine the correct register to use each time a
+% multiplication is made.)
+%
+% \subsection{Multiplication by real numbers}
+%
+% This is similar to the |\calc@ratio@evaluate| macro above, except that
+% it is considerably simplified since we don't need to calculate the
+% factor explicitly.
+% \begin{macrocode}
+\def\calc@real@multiply\real#1{\endgroup
+ \calc@multiply@by@real{#1}\begingroup
+ \calc@post@scan}
+\def\calc@real@divide\real#1{\calc@ratio@evaluate{1pt}{#1pt}}
+% \end{macrocode}
+%
+% \section{Reporting errors}
+%
+% \changes{v4.0d}{1997/11/08}
+% {Use \cs{PackageError} for error messages (DPC)}
+% \changes{v4.0e}{1997/11/11}
+% {typo fixed}
+% If |\calc@post@scan| reads a character that is not one of `\texttt{+}',
+% `\texttt{-}', `\texttt{*}', `\texttt{/}', or `\texttt{)}', an error
+% has occurred, and this is reported to the user. Violations in the
+% syntax of \<numeric>s will be detected and reported by \TeX.
+% \changes{v4.1a}{1998/06/07}
+% {Improved, I hope, error message: CAR}
+% \begin{macrocode}
+\def\calc@error#1{%
+ \PackageError{calc}%
+ {`#1' invalid at this point}%
+ {I expected to see one of: + - * / )}}
+%</package>
+% \end{macrocode}
+%
+% \Finale
+\endinput
+
diff --git a/Master/texmf-dist/source/latex/tools/dcolumn.dtx b/Master/texmf-dist/source/latex/tools/dcolumn.dtx
new file mode 100644
index 00000000000..e8d4720819d
--- /dev/null
+++ b/Master/texmf-dist/source/latex/tools/dcolumn.dtx
@@ -0,0 +1,360 @@
+% \iffalse meta-comment
+%
+% Copyright 1993 1994 1995 1996 1997 1998 1999 2000 2001 2002 2003
+% The LaTeX3 Project and any individual authors listed elsewhere
+% in this file.
+%
+% This file is part of the Standard LaTeX `Tools Bundle'.
+% -------------------------------------------------------
+%
+% It 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.3 or later is part of all distributions of LaTeX
+% version 2003/12/01 or later.
+%
+% The list of all files belonging to the LaTeX `Tools Bundle' is
+% given in the file `manifest.txt'.
+%
+% \fi
+% \iffalse
+%% File: dcolumn.dtx Copyright (C) 1992-1996 1999-2001 David Carlisle
+%
+%<*dtx>
+ \ProvidesFile{dcolumn.dtx}
+%</dtx>
+%<package>\NeedsTeXFormat{LaTeX2e}
+%<package>\ProvidesPackage{dcolumn}
+%<driver>\ProvidesFile{dcolumn.drv}
+% \fi
+% \ProvidesFile{dcolumn.dtx}
+ [2001/05/28 v1.06 decimal alignment package (DPC)]
+%
+% \iffalse
+%<*driver>
+\documentclass{ltxdoc}
+ \usepackage{dcolumn}
+ \DeleteShortVerb{\|}
+\begin{document}
+ \DocInput{dcolumn.dtx}
+\end{document}
+%</driver>
+% \fi
+%
+% \GetFileInfo{dcolumn.dtx}
+%
+% \title{The \textsf{dcolumn} package\thanks{This file
+% has version number \fileversion, last
+% revised \filedate.}}
+% \author{David Carlisle}
+% \date{\filedate}
+% \author{David Carlisle}
+% \maketitle
+%
+%
+% \changes{v1.00}{1992/02/17}{Initial version}
+% \changes{v1.01}{1992/06/12}{Re-issue for the new doc and docstrip.}
+% \changes{v1.02}{1994/03/14}{Re-issue for LaTeX2e}
+% \changes{v1.03}{1996/02/28}{New feature, after tools/2093}
+% \changes{v1.05}{1999/07/05}
+% {Minor doc changes latex/3058}
+% \changes{v1.06}{2001/05/28}
+% {More doc changes (suggested by BNB, done by CAR) latex/3315}
+%
+% \CheckSum{143}
+%
+%
+% \begin{abstract}
+% This package defines a system for defining columns of entries in an
+% \texttt{array} or \texttt{tabular} which are to be aligned on a
+% `decimal point'.
+% \end{abstract}
+%
+% \MakeShortVerb{\"}
+%
+% This package defines {\tt D} to be a column specifier with three
+% arguments.\\
+% "D{"\meta{sep.tex}"}{"\meta{sep.dvi}"}{"\meta{decimal
+% places}"}"
+%
+% \meta{sep.tex} should be a single character, this is used as the
+% separator in the {\tt .tex} file. Thus it will usually be `{\tt.}' or
+% `{\tt,}'.
+%
+% \mbox{\meta{sep.dvi}} is used as the separator in the output, this may
+% be the same as the first argument, but may be any math-mode
+% expression, such as "\cdot". It should be noted that \texttt{dcolumn}
+% always uses math mode for the digits as well as the separator.
+%
+% \meta{decimal places} should be the maximum number of decimal places
+% in the column. If this is negative, any number of decimal places can
+% be used in the column, and all entries will be centred on
+% (the leading edge of) the
+% separator. Note that this can cause a column to be too wide, compare
+% the first two columns in the example below. If this argument is
+% positive, the column uses macros equivalent to "\rightdots"
+% "\endrightdots" of {\tt array.sty}, otherwise the macros are
+% essentially equivalent to "\centerdots" "\endcenterdots".
+%
+% You may not want to use all three entries in the {\tt array} or {\tt
+% tabular} preamble, so you may define your own preamble specifiers
+% using "\newcolumntype".
+%
+% For example we may say:
+%
+% \noindent"\newcolumntype{d}[1]{D{.}{\cdot}{#1}}"
+%
+% {\tt d} takes a single argument specifying the number of decimal
+% places, and the {\tt .tex} file should use {\tt.}, with $\cdot$ being
+% used in the output.
+%
+% \noindent"\newcolumntype{.}{D{.}{.}{-1}}"
+%
+% {\tt .} specifies a column of entries to be centred on the~$.$.
+%
+% \noindent"\newcolumntype{,}{D{,}{,}{2}}"
+%
+% {\tt ,} specifies takes a column of entries with at most two decimal
+% places after a~$,$.
+%
+% \newcolumntype{d}[1]{D{.}{\cdot}{#1}}
+% \newcolumntype{.}{D{.}{.}{-1}}
+% \newcolumntype{,}{D{,}{,}{2}}
+%
+% The following table begins "\begin{tabular}{|d{-1}|d{2}|.|,|}"
+%
+% \begin{center}
+% \begin{tabular}{|d{-1}|d{2}|.|,|}
+% 1.2 & 1.2 &1.2 &1,2 \\
+% 1.23 & 1.23 &12.5 &300,2 \\
+% 1121.2& 1121.2&861.20 &674,29 \\
+% 184 & 184 &10 &69 \\
+% .4 & .4 & &,4 \\
+% & &.4 &
+% \end{tabular}
+% \end{center}
+%
+% Note that the first column, which had a negative \meta{decimal places}
+% argument is wider than the second column, so that the decimal point
+% appears in the middle of the column.
+% Also note that this package deals correctly with entries with no
+% decimal part, no integer part, and blank entries.
+%
+% If you have table headings (inserted with "\multicolumn{1}{c}{..}"
+% to over-ride the "D" column type) then it may be that neither of the
+% above `centred' or `right aligned' forms is quite what you want.
+% \begin{center}\small
+% \begin{tabular}[t]{|D..{-1}|D..{1}|D..{5.1}|}
+%\multicolumn{1}{|c|}{head}&
+%\multicolumn{1}{c|}{head}&
+%\multicolumn{1}{c|}{head}\\[3pt]
+% 1.2 & 1.2 &1.2 \\
+% 11212.2& 11212.2&11212.2 \\
+% .4 & .4 &.4
+% \end{tabular}
+% \hfill
+% \begin{tabular}[t]{|D..{-1}|D..{1}|D..{1.1}|}
+%\multicolumn{1}{|c|}{wide heading}&
+%\multicolumn{1}{c|}{wide heading}&
+%\multicolumn{1}{c|}{wide heading}\\[3pt]
+% 1.2 & 1.2 &1.2 \\
+% .4 & .4 &.4
+% \end{tabular}
+% \end{center}
+%
+% In both of these tables the first column is set with "D{.}{.}{-1}"
+% to produce a column centered on the ".", and the second column is
+% set with "D{.}{.}{1}" to produce a right aligned column.
+%
+% The centered column produces columns that are wider than necessary
+% to fit in the numbers under a heading as it has to ensure that the
+% decimal point is centred. The right aligned column two does not have
+% this drawback, but under a wide heading a column of small right
+% aligned figures looks a bit odd.
+%
+% In version v1.03 a third possibility is introduced. The third
+% \meta{decimal places} argument may specify \emph{both} the number of
+% digits to the left and to the right of the decimal place. The third
+% column in the first table above is set with "D{.}{.}{5.1}" and in the
+% second table, "D{.}{.}{1.1}", to specify
+% `five places to the left and one to the right' and `one place to the
+% left and% one to the right' respectively. (You may use `,' or other
+% tokens, not necessarily `.' in this argument.) The column of figures
+% is then positioned such that a number with the specified numbers of
+% digits is centred in the column.
+%
+% This notation also enables columns that are centred on the mid-point
+% of the separator, rather than its leading edge; for example
+% "D{+}{\,\pm\,}{3,3}" will give nice, symmetric layout of up to three
+% digits on either side of a $\pm$ sign.
+%
+% \StopEventually{}
+%
+%
+% \section{The Macros}
+%
+% \begin{macrocode}
+%<*package>
+% \end{macrocode}
+%
+% First we load {\tt array.sty} if it not already loaded.
+% \begin{macrocode}
+\RequirePackage{array}
+% \end{macrocode}
+%
+% The basic ideas behind these macros are explained in the documentation
+% for {\tt array.sty}. However they use three
+% tricks which may be useful in other contexts.
+% \begin{itemize}
+% \item The separator is surrounded in extra "{ }", so that it is set
+% with "\mathord" spacing, otherwise, for instance a `,' would have
+% extra space after it.
+% \item The separator is not given its special definition by making it
+% active, as this would not work for an entry such as "& .5 &", as the
+% first token of an alignment entry is read {\em before\/} the preamble
+% part, incase it is an "\omit", in which case the preamble is to be
+% omitted. Instead we switch the mathcode to (hex) 8000, which makes the
+% token act as if it were active.
+% \item Although \verb|\mathcode`.="8000| makes {\tt.} act as if it
+% were active, it is still not allowed in constructions such as
+% "\def.{}", even in math-mode, so we have to construct an active
+% version of the separator, this is done by making it the uppercase of
+% "~", and then using the construct\\
+% "\uppercase{\def~}{"\meta{definition}"}".\\
+% Note that the \meta{definition} is not uppercased, so the definition
+% can refer to the standard, non-active use of the separator.
+% \end{itemize}
+%
+% \begin{macro}{\DC@}
+% \changes{v1.03}{1996/02/28}{New feature, after tools/2093}
+% Set up uppercase tables as required, and then grab the first part of
+% the numerical argument into "\count@".
+% \begin{macrocode}
+\def\DC@#1#2#3{%
+ \uccode`\~=`#1\relax
+ \m@th
+ \afterassignment\DC@x\count@#3\relax{#1}{#2}}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\DC@x}
+% \changes{v1.03}{1996/02/28}{Macro added}
+% If "\count@" is negative, centre on the decimal point. If it is
+% positive either "#1" will be empty in which case bad out decimal
+% part to the number of digits specified by "\count@" or (new feature
+% in v1.03) it is none empty in which case "\count@" contains the
+% number of digits to the left of the point, and "#1" contains a junk
+% token (probably ".") followed by the number of digits to the right
+% of the point. In either of these latter cases, "\DC@right" is used.
+% \begin{macrocode}
+\def\DC@x#1\relax#2#3{%
+ \ifnum\z@>\count@
+ \expandafter\DC@centre
+ \else
+ \expandafter\DC@right
+ \fi
+ {#2}{#3}{#1}}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\DC@centre}
+% If centering on the decimal point, just need to box up the two halves.
+% \begin{macrocode}
+\def\DC@centre#1#2#3{%
+ \let\DC@end\DC@endcentre
+ \uppercase{\def~}{$\egroup\setbox\tw@=\hbox\bgroup${#2}}%
+ \setbox\tw@=\hbox{${\phantom{{#2}}}$}%
+ \setbox\z@=\hbox\bgroup$\mathcode`#1="8000 }
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\DC@endcentre}
+% and then pad out the smaller of the two boxes so there is the same
+% amount of stuff either side of the point.
+% \begin{macrocode}
+\def\DC@endcentre{$\egroup
+ \ifdim \wd\z@>\wd\tw@
+ \setbox\tw@=\hbox to\wd\z@{\unhbox\tw@\hfill}%
+ \else
+ \setbox\z@=\hbox to\wd\tw@{\hfill\unhbox\z@}\fi
+ \box\z@\box\tw@}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\DC@right}
+% \changes{v1.03}{1996/02/28}{Re-implemented, after tools/2093}
+% This deals with both the cases where a specified number of decimal
+% places is given.
+% \begin{macrocode}
+\def\DC@right#1#2#3{%
+ \ifx\relax#3\relax
+% \end{macrocode}
+% If "#3" is empty, add "\hfill" to right align the column, and
+% Just set "\DC@rl" to begin a group, so nothing fancy is done with
+% the whole number part.
+% \begin{macrocode}
+ \hfill
+ \let\DC@rl\bgroup
+ \else
+% \end{macrocode}
+% Otherwise set "\DC@rl" so that the whole number part is put in a
+% box "\count@" times as wide as a digit.
+% In order to share code with the other branch, then move "#3" (the
+% number of decimal places) into "\count@" throwing away the `.' from
+% the user syntax.
+% \changes{v1.04}{1996/09/23}{Add \cs{hfill} so integer part
+% is still flush right if no decimal point used.}
+% \begin{macrocode}
+ \edef\DC@rl{to\the\count@\dimen@ii\bgroup\hss\hfill}%
+ \count@\@gobble#3\relax
+ \fi
+% \end{macrocode}
+%
+% \begin{macrocode}
+ \let\DC@end\DC@endright
+% \end{macrocode}
+% Box 2 contains the decimal part, set to "\dimen@" which is
+% calculated below to be "\count@" times the width of a digit, plus
+% the with of the `decimal point'.
+% \begin{macrocode}
+ \uppercase{\def~}{$\egroup\setbox\tw@\hbox to\dimen@\bgroup${#2}}%
+ \setbox\z@\hbox{$1$}\dimen@ii\wd\z@
+ \dimen@\count@\dimen@ii
+ \setbox\z@\hbox{${#2}$}\advance\dimen@\wd\z@
+ \setbox\tw@\hbox to\dimen@{}%
+% \end{macrocode}
+% Box 0 contains the whole number part, either just at its natural
+% size for right aligned columns, or set to (the old value of)
+% "\count@" times the width of a digit. "\DC@rl" defined above
+% determines the two cases.
+% \begin{macrocode}
+ \setbox\z@\hbox\DC@rl$\mathcode`#1="8000 }
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\DC@endright}
+% \changes{v1.03}{1996/02/28}{Re-implemented, after tools/2093}
+% Just finish off the second box, and then put out both boxes.
+% \begin{macrocode}
+\def\DC@endright{$\hfil\egroup\box\z@\box\tw@}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{D}
+% The user interface, define the {\tt D} column to take three arguments.
+% For special purposes, you may need to directly access "\DC@" rather
+% than the "D" column, eg to get a bold version you could use
+%\begin{verbatim}
+% \newcolumntype{E}[3]{>{\boldmath\DC@{#1}{#2}{#3}}c<{\DC@end}}
+%\end{verbatim}
+% \begin{macrocode}
+\newcolumntype{D}[3]{>{\DC@{#1}{#2}{#3}}c<{\DC@end}}
+%</package>
+% \end{macrocode}
+% \end{macro}
+%
+%
+% \Finale
+\endinput
diff --git a/Master/texmf-dist/source/latex/tools/delarray.dtx b/Master/texmf-dist/source/latex/tools/delarray.dtx
new file mode 100644
index 00000000000..2754b070969
--- /dev/null
+++ b/Master/texmf-dist/source/latex/tools/delarray.dtx
@@ -0,0 +1,205 @@
+% \iffalse meta-comment
+%
+% Copyright 1993 1994 1995 1996 1997 1998 1999 2000 2001 2002 2003
+% The LaTeX3 Project and any individual authors listed elsewhere
+% in this file.
+%
+% This file is part of the Standard LaTeX `Tools Bundle'.
+% -------------------------------------------------------
+%
+% It 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.3 or later is part of all distributions of LaTeX
+% version 2003/12/01 or later.
+%
+% The list of all files belonging to the LaTeX `Tools Bundle' is
+% given in the file `manifest.txt'.
+%
+% \fi
+% \iffalse
+%% File: delarray.dtx Copyright (C) 1991-1994 David Carlisle
+%
+%<package>\NeedsTeXFormat{LaTeX2e}
+%<package>\ProvidesPackage{delarray}
+%<package> [1994/03/14 v1.01 array delimiter package (DPC)]
+%
+%<*driver>
+\documentclass{ltxdoc}
+\usepackage{delarray}
+\GetFileInfo{delarray.sty}
+\begin{document}
+\title{The \textsf{delarray} package\thanks{This file
+ has version number \fileversion, last
+ revised \filedate.}}
+\author{David Carlisle\\carlisle@cs.man.ac.uk}
+\date{\filedate}
+ \maketitle
+ \DocInput{delarray.dtx}
+\end{document}
+%</driver>
+% \fi
+%
+%
+% \changes{v1.00}{1992/07/06}
+% {Initial version after merging of newarray.sty to array.sty}
+%
+% \changes{v1.01}{1994/03/14}
+% {Update to LaTeX2e}
+%
+% \CheckSum{64}
+%
+% \section{Examples}
+%
+%
+% The addition to {\tt array.sty} added in {\tt delarray.sty} is
+% a system of implicit |\left| |\right| pairs. If you want an array
+% surrounded by parentheses, you can enter:\\
+% |\begin{array}({cc})| \ldots
+% \[ \begin{array}({cc})a&b\\c&d\end{array} \]
+%
+% Similarly if an environment equivalent to \PlainTeX's |\cases| could
+% be defined by:\\
+% |\begin{array}\{{lL}.| \ldots
+%
+% \newcolumntype{L}{>{$}l<{$}}
+% \[ f(x)=\begin{array}\{{lL}.
+% 0 &if $x=0$\\
+% \sin(x)/x&otherwise
+% \end{array} \]
+% Here |L| is supposed to denote a column of left aligned L-R text. It
+% may be defined via: |\newcolumntype{L}{>{$}l<{$}}|, as discussed in
+% {\tt array.sty}.
+% Note that as the delimiters must always be used in pairs, the `|.|'
+% must be used to denote a `null delimiter'.
+%
+% This feature is especially useful if the |[t]| or |[b]|
+% arguments are also used. In these cases the result is not equivalent
+% to surrounding the environment by |\left|\ldots|\right|, as
+% can be seen from the following example:
+% \[
+% \begin{array}[t]({c}) 1\\2\\3 \end{array}
+% \begin{array}[c]({c}) 1\\2\\3 \end{array}
+% \begin{array}[b]({c}) 1\\2\\3 \end{array}
+% \quad\mbox{not}\quad
+% \left(\begin{array}[t]{c} 1\\2\\3 \end{array}\right)
+% \left(\begin{array}[c]{c} 1\\2\\3 \end{array}\right)
+% \left(\begin{array}[b]{c} 1\\2\\3 \end{array}\right)
+% \]
+% \begin{verbatim}
+% \begin{array}[t]({c}) 1\\2\\3 \end{array}
+% \begin{array}[c]({c}) 1\\2\\3 \end{array}
+% \begin{array}[b]({c}) 1\\2\\3 \end{array}
+% \quad\mbox{not}\quad
+% \left(\begin{array}[t]{c} 1\\2\\3 \end{array}\right)
+% \left(\begin{array}[c]{c} 1\\2\\3 \end{array}\right)
+% \left(\begin{array}[b]{c} 1\\2\\3 \end{array}\right)
+% \end{verbatim}
+%
+%
+% \StopEventually{}
+%
+% \section{The Macros}
+%
+% \begin{macrocode}
+%<*package>
+% \end{macrocode}
+%
+% \begin{macrocode}
+\RequirePackage{array}[1994/02/03]
+% \end{macrocode}
+%
+% \begin{macro}{\@tabarray}
+% This macro tests for an optional bracket and then calls up
+% |\@@array| or |\@@array[c]| (as default).
+% \begin{macrocode}
+\def\@tabarray{\@ifnextchar[{\@@array}{\@@array[c]}}
+% \end{macrocode}
+% \end{macro}
+% \begin{macro}{\@@array}
+% This macro tests for an optional delimiter before the left brace
+% of the main preamble argument. If there is no delimiter,
+% |\@arrayleft| and |\@arrayright| are made a no-ops, and
+% |\@array| is called with the positional argument. Otherwise
+% call |\@del@array|.
+% \begin{macrocode}
+\def\@@array[#1]{\@ifnextchar\bgroup
+ {\let\@arrayleft\relax\let\@arrayright\relax\@array[#1]}%
+ {\@del@array[#1]}}
+% \end{macrocode}
+% \end{macro}
+% \begin{macro}{\@del@array}
+% We now know that we have an {\tt array} (or {\tt tabular}) with
+% delimiters.
+% \begin{macrocode}
+\def\@del@array[#1]#2#3#4{%
+% \end{macrocode}
+% The following line is completely redundant but it does catch errors
+% involving delimiters before the processing of the alignment begins.
+% A common error is likely to be omiting the `.' in a
+% |\cases|-type construction. This causes the first token of the
+% alignment to be gobbled, possibly causing lots of spurious errors
+% before the cause of the error, the missing delimiter, is discovered as
+% |\@arrayright| puts the alignment and the delimiters together.
+% \begin{macrocode}
+ \setbox\z@\hbox{$\left#2\right#4$}%
+% \end{macrocode}
+% In the case of a `c' argument we do not need to rebox the alignment,
+% so we can define |\@arrayleft| and |\@arrayright| just to
+% insert the delimiters.
+% \begin{macrocode}
+ \if#1c\def\@arrayleft{\left#2}\def\@arrayright{\right#4}%
+% \end{macrocode}
+% Otherwise we (should) have a {\tt[t]} or {\tt[b]} argument, so first we
+% store the alignment, without delimiters in box0.
+% \begin{macrocode}
+ \else\def\@arrayleft{\setbox\z@}%
+% \end{macrocode}
+% Then after the alignment is finished:
+% \begin{macrocode}
+ \def\@arrayright{%
+% \end{macrocode}
+% Calculate the amount the box needs to be lowered (this will be
+% negative in the case of |[b]|). A little bit of arithmetic cf.\
+% the \TeX{}Book, Appendix G, rule 8. We calculate the amount this
+% way, rather than just taking the difference between the depth of box0
+% and the depth of the box defined below, as the depth of that box may
+% be affected by the delimiters if |\delimitershortfall| or
+% |\delimiterfactor| have non-standard values.
+% \begin{macrocode}
+ \dimen@=\dp\z@
+ \advance\dimen@-\ht\z@
+ \divide \dimen@ by \tw@
+ \advance\dimen@ by\fontdimen22 \textfont\tw@
+% \end{macrocode}
+% Now lower the alignment and the delimiters into place.
+% \begin{macrocode}
+ \lower\dimen@\hbox{$\left#2\vcenter{\unvbox\z@}\right#4$}}%
+% \end{macrocode}
+% End the |\if#1c|
+% \begin{macrocode}
+ \fi
+% \end{macrocode}
+% Now that we have defined |\@arrayleft| and |\@arrayright|, call
+% |\@array|.
+% \begin{macrocode}
+ \@array[#1]{#3}}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macrocode}
+%</package>
+% \end{macrocode}
+%
+%
+% \subsection{newarray.sty}
+% All the features of the old {\tt newarray} style option have been
+% merged into the {\tt array} or {\tt delarray} options.
+% \changes{v1.00}{1992/07/06}
+% {Stop generating a `shell' newarray.sty}
+%
+%
+% \Finale
+\endinput
diff --git a/Master/texmf-dist/source/latex/tools/enumerate.dtx b/Master/texmf-dist/source/latex/tools/enumerate.dtx
new file mode 100644
index 00000000000..e2a006af788
--- /dev/null
+++ b/Master/texmf-dist/source/latex/tools/enumerate.dtx
@@ -0,0 +1,335 @@
+% \iffalse meta-comment
+%
+% Copyright 1993 1994 1995 1996 1997 1998 1999 2000 2001 2002 2003
+% The LaTeX3 Project and any individual authors listed elsewhere
+% in this file.
+%
+% This file is part of the Standard LaTeX `Tools Bundle'.
+% -------------------------------------------------------
+%
+% It 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.3 or later is part of all distributions of LaTeX
+% version 2003/12/01 or later.
+%
+% The list of all files belonging to the LaTeX `Tools Bundle' is
+% given in the file `manifest.txt'.
+%
+% \fi
+% \iffalse
+%% File: enumerate.dtx Copyright 1993 1994 1999 David Carlisle
+%
+%<*dtx>
+ \ProvidesFile{enumerate.dtx}
+%</dtx>
+%<package>\NeedsTeXFormat{LaTeX2e}
+%<package>\ProvidesPackage{enumerate}
+%<driver> \ProvidesFile{enumerate.drv}
+% \fi
+% \ProvidesFile{enumerate.dtx}
+ [1999/03/05 v3.00 enumerate extensions (DPC)]
+%
+% \iffalse
+%<*driver>
+\documentclass{ltxdoc}
+\usepackage{enumerate}
+\begin{document}
+\DocInput{enumerate.dtx}
+\end{document}
+%</driver>
+% \fi
+%
+% \GetFileInfo{enumerate.dtx}
+% \title{The \textsf{enumerate} package\thanks{This file
+% has version number \fileversion, last
+% revised \filedate.}}
+% \author{David Carlisle}
+% \date{\filedate}
+% \maketitle
+%
+% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%
+% \CheckSum{200}
+%
+% \changes{v1.00}{1990/00/00}{First version (since lost)}
+% \changes{v2.00}{1991/07/25}{New Algorithm}
+% \changes{v2.01}{1992/06/26}{Re-issue for the new doc and docstrip.}
+% \changes{v2.02}{1994/01/31}{Update for LaTeX2e}
+% \changes{v3.00}{1999/03/05}{Add extension hook for tools/2916}
+%
+% \begin{abstract}
+% This package gives the enumerate environment an optional argument
+% which determines the style in which the counter is printed.
+%
+% An occurence of one of the tokens |A a I i| or |1| produces the value
+% of the counter printed with (respectively) |\Alph \alph \Roman \roman|
+% or |\arabic|.
+%
+% These letters may be surrounded by any strings involving any other
+% \TeX\ expressions, however the tokens |A a I i 1| must be inside a
+% |{ }| group if they are not to be taken as special.
+% \end{abstract}
+%
+% \section{Examples}
+%\showboxdepth=10
+% \showboxbreadth=10
+% \[
+% \parbox{2.2in}{\hbadness2000
+% \begin{enumerate}[EX i.]
+% \item one one one one one one one
+% one one one one one\label{LA}
+% \item two
+% \begin{enumerate}[{example} a)]
+% \item one of two one of two one of two\label{LB}
+% \item two of two
+% \end{enumerate}
+% \end{enumerate}
+% \begin{enumerate}[{A}-1]
+% \item one\label{LC}
+% \item two
+% \end{enumerate}}
+% \hspace{20pt}
+% \vcenter{\hsize=2.4in
+% \begin{verbatim}
+% \begin{enumerate}[EX i.]
+% \item one one one one one one one
+% one one one one\label{LA}
+% \item two
+% \begin{enumerate}[{example} a)]
+% \item one of two one of two
+% one of two\label{LB}
+% \item two of two
+% \end{enumerate}
+% \item two of two
+% \end{enumerate}
+% \end{enumerate}
+%
+% \begin{enumerate}[{A}-1]
+% \item one\label{LC}
+% \item two
+% \end{enumerate}
+% \end{verbatim}
+% }\]
+%
+% |\label| and |\ref| may be used as with the standard {\tt
+% enumerate} environment. |\ref| only produces the counter value,
+% not the whole label. |\ref| prints the value in the same style
+% as |\item|, as determined by the presence of one of the tokens
+% |A a I i 1| in the optional argument. In the above example
+% |\ref{LA}|, |\ref{LB}| and |\ref{LC}| produce
+% `\ref{LA}', `\ref{LB}' and `\ref{LC}' respectively.
+%
+% \StopEventually{}
+%
+%\section{Macros}
+%
+% \begin{macrocode}
+%<*package>
+% \end{macrocode}
+%
+% \begin{macro}{\@enlab}
+% Internal token register used to build up the label command from the
+% optional argument.
+% \begin{macrocode}
+\newtoks\@enLab
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\@enQmark}
+% This just expands to a `?'. |\ref| will produce this, if no counter
+% is printed.
+% \begin{macrocode}
+\def\@enQmark{?}
+% \end{macrocode}
+% \end{macro}
+%
+% The next four macros build up the command that will print the item
+% label. They each gobble one token or group from the optional argument,
+% and add corresponding tokens to the register |\@enLab|. They each end
+% with a call to |\@enloop|, which starts the processing of the next
+% token.
+% \begin{macro}{\@enLabel}
+% Add the counter to the label. |#2| will be one of the `special'
+% tokens |A a I i 1|, and is thrown away. |#1| will be a command
+% like |\Roman|.
+% \begin{macrocode}
+\def\@enLabel#1#2{%
+ \edef\@enThe{\noexpand#1{\@enumctr}}%
+ \@enLab\expandafter{\the\@enLab\csname the\@enumctr\endcsname}%
+ \@enloop}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\@enSpace}
+% \begin{macro}{\@enSp@ce}
+% Add a space to the label. The tricky bit is to gobble the space token,
+% as you can not do this with a macro argument.
+% \begin{macrocode}
+\def\@enSpace{\afterassignment\@enSp@ce\let\@tempa= }
+\def\@enSp@ce{\@enLab\expandafter{\the\@enLab\space}\@enloop}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\@enGroup}
+% Add a |{ }| group to the label.
+% \begin{macrocode}
+\def\@enGroup#1{\@enLab\expandafter{\the\@enLab{#1}}\@enloop}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\@enOther}
+% Add anything else to the label
+% \begin{macrocode}
+\def\@enOther#1{\@enLab\expandafter{\the\@enLab#1}\@enloop}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\@enloop}
+% \begin{macro}{\@enloop@}
+% The body of the main loop.
+% Eating tokens this way instead of using |\@tfor| lets you see
+% spaces and {\bf all} braces. |\@tfor| would treat {\tt a} and
+% |{a}| as special, but not |{{a}}|.
+% \begin{macrocode}
+\def\@enloop{\futurelet\@entemp\@enloop@}
+% \end{macrocode}
+% \begin{macrocode}
+\def\@enloop@{%
+ \ifx A\@entemp \def\@tempa{\@enLabel\Alph }\else
+ \ifx a\@entemp \def\@tempa{\@enLabel\alph }\else
+ \ifx i\@entemp \def\@tempa{\@enLabel\roman }\else
+ \ifx I\@entemp \def\@tempa{\@enLabel\Roman }\else
+ \ifx 1\@entemp \def\@tempa{\@enLabel\arabic}\else
+ \ifx \@sptoken\@entemp \let\@tempa\@enSpace \else
+ \ifx \bgroup\@entemp \let\@tempa\@enGroup \else
+ \ifx \@enum@\@entemp \let\@tempa\@gobble \else
+ \let\@tempa\@enOther
+% \end{macrocode}
+% Hook for possible extensions
+% \begin{macrocode}
+ \@enhook
+% \end{macrocode}
+%
+% \begin{macrocode}
+ \fi\fi\fi\fi\fi\fi\fi\fi
+% \end{macrocode}
+% \end{macro}
+% Process the current token, then look at the next.
+% \begin{macrocode}
+ \@tempa}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\@enhook}
+% Hook for possible extensions.
+% Some packages may want to extend the number of special characters
+% that are associated with counter representations. This feature
+% was requested to enable Russian alphabetic counting, but here
+% I give an example of a footnote symbol counter, triggered by |*|.
+%
+% To enable a new counter type based on a letter, you just need
+% to add a new |\ifx| clause by analogy with the code above.
+% So for example to make |*| trigger footnote symbol counting.
+% a package should do the following.
+%
+% Initialise the hook, in case the package is loaded before
+% \textsf{enumerate}.
+%\begin{verbatim}
+% \providecommand\@enhook{}
+%\end{verbatim}
+%
+% Add to the hook a new |\ifx| clause that associates |*| with the
+% |\fnsymbol| counter command.
+%\begin{verbatim}
+% \g@addto@macro\@enhook{%
+% \ifx *\@entemp
+% \def\@tempa{\@enLabel\fnsymbol}%
+% \fi}
+%\end{verbatim}
+% This code sequence should work whether it is loaded before or after
+% this enumerate package. Any number of new counter types may be added
+% in this way.
+%
+% At this point we just need initialise the hook, taking care not
+% to over write any definitions another package may already have added.
+% \begin{macrocode}
+\providecommand\@enhook{}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\enumerate}
+% The new {\tt enumerate} environment. This is the first half of the
+% original enumerate environment. If there is an optional argument, call
+% |\@@enum@| to define the label commands, otherwise call
+% |\@enum@| which is the second half of the original definition.
+% \begin{macrocode}
+\def\enumerate{%
+ \ifnum \@enumdepth >3 \@toodeep\else
+ \advance\@enumdepth \@ne
+ \edef\@enumctr{enum\romannumeral\the\@enumdepth}\fi
+ \@ifnextchar[{\@@enum@}{\@enum@}}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\@@enum@}
+% Handle the optional argument..
+% \begin{macrocode}
+\def\@@enum@[#1]{%
+% \end{macrocode}
+% Initialise the loop which will break apart the optional argument.
+% The command to print the label is built up in |\@enlab|.
+% |\@enThe| will be used to define |\theenum|\,$n$.
+% \begin{macrocode}
+ \@enLab{}\let\@enThe\@enQmark
+% \end{macrocode}
+% The |\@enum@| below is never expanded, it is used to detect the end
+% of the token list.
+% \begin{macrocode}
+ \@enloop#1\@enum@
+% \end{macrocode}
+% Issue a warning if we did not find one of the `special' tokens.
+% \begin{macrocode}
+ \ifx\@enThe\@enQmark\@warning{The counter will not be printed.%
+ ^^J\space\@spaces\@spaces\@spaces The label is: \the\@enLab}\fi
+% \end{macrocode}
+% Define |\labelenum|$\,n$ and |\theenum|$\,n$.
+% \begin{macrocode}
+ \expandafter\edef\csname label\@enumctr\endcsname{\the\@enLab}%
+ \expandafter\let\csname the\@enumctr\endcsname\@enThe
+% \end{macrocode}
+% Set the counter to 7 so that we get the width of `vii' if roman
+% numbering is in force then set |\leftmargin|$\,n$. to the width of the
+% label plus |\labelsep|.
+% \begin{macrocode}
+ \csname c@\@enumctr\endcsname7
+ \expandafter\settowidth
+ \csname leftmargin\romannumeral\@enumdepth\endcsname
+ {\the\@enLab\hspace{\labelsep}}%
+% \end{macrocode}
+% Finally call |\@enum@| which is the second half of the original
+% definition.
+% \begin{macrocode}
+ \@enum@}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\@enum@}
+% All the list parameters have now been defined, so call |\list|. This
+% is taken straight from the original definition of |\enumerate|.
+% \begin{macrocode}
+\def\@enum@{\list{\csname label\@enumctr\endcsname}%
+ {\usecounter{\@enumctr}\def\makelabel##1{\hss\llap{##1}}}}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macrocode}
+%</package>
+% \end{macrocode}
+%
+% \Finale
+%
+\endinput
diff --git a/Master/texmf-dist/source/latex/tools/fileerr.dtx b/Master/texmf-dist/source/latex/tools/fileerr.dtx
new file mode 100644
index 00000000000..d44b4bc05ed
--- /dev/null
+++ b/Master/texmf-dist/source/latex/tools/fileerr.dtx
@@ -0,0 +1,137 @@
+% \iffalse meta-comment
+%
+% Copyright 1993 1994 1995 1996 1997 1998 1999 2000 2001 2002 2003
+% The LaTeX3 Project and any individual authors listed elsewhere
+% in this file.
+%
+% This file is part of the Standard LaTeX `Tools Bundle'.
+% -------------------------------------------------------
+%
+% It 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.3 or later is part of all distributions of LaTeX
+% version 2003/12/01 or later.
+%
+% The list of all files belonging to the LaTeX `Tools Bundle' is
+% given in the file `manifest.txt'.
+%
+% \fi
+% \def\fileversion{v1.1a} \def\filedate{2003/12/28}
+% \CheckSum{18}
+% \iffalse This is a METACOMMENT
+% Doc-Source file to use with LaTeX2e
+% Copyright (C) 1994-2004 Frank Mittelbach, all rights reserved.
+% \fi
+% \title{File not found error\thanks{This file has version
+% \fileversion\ last revised \filedate}}
+% \author{Frank Mittelbach}
+% \maketitle
+%
+% \changes{v1.0e}{97/07/07}{Added q and r replies (PR/2525).}
+%
+% \section{Introduction}
+% When \LaTeXe{} is unable to find a file it will ask for an
+% alternative file name. However, sometimes the problem is
+% only noticed by \TeX{}, and in that case \TeX{} insists on
+% getting a valid file name; any other attempt to leave this
+% error loop will fail.\footnote{On some systems, \TeX{}
+% accepts a special character denoting the end of file to
+% return from this loop, e.g.\ Control-D on UNIX or Control-Z
+% on DOS.} Many users try to respond in the same way as to
+% normal error messages, e.g.\ by typing \meta{return}, or |s|
+% or |x|, but \TeX{} will interpret this as a file name and
+% will ask again.
+% \par To provide a graceful exit out of this loop, we define
+% a number of files which emulate the normal behavior of
+% \TeX{} in the error loop as far as possible.
+% \par After installing these files the user can respond with
+% |h|, |q|, |r|, |s|, |e|, |x|, and on some systems also with
+% \meta{return} to \TeX's missing file name question.
+% \StopEventually{}
+%
+% \section{The documentation driver}
+% This code will generate the documentation. Since it is the
+% first piece of code in the file, the documentation can be
+% obtained by simply processing this file with \LaTeXe.
+% \begin{macrocode}
+%<*driver>
+\documentclass{ltxdoc}
+\begin{document} \DocInput{fileerr.dtx} \end{document}
+%</driver>
+% \end{macrocode}
+% \section{The files}
+%
+% \subsection{Asking for help with {\tt h}}
+% When the user types |h| in the file error loop \TeX{} will
+% look for the file |h.tex|. In this file we put a message
+% informing the user about the situation (we use |^^J| to
+% start new lines in the message) and then finish with a
+% normal |\errmessage| command thereby bringing up \TeX's
+% normal error mechanism.
+% \begin{macrocode}
+%<*help>
+\newlinechar=`\^^J
+\message{! The file name provided could not be found.^^J%
+Use `<enter>' to continue processing,^^J%
+`S' to scroll future errors^^J%
+`R' to run without stopping,^^J%
+`Q' to run quietly,^^J%
+or `X' to terminate TeX}
+\errmessage{}
+%</help>
+% \end{macrocode}
+%
+% \subsection{Scrolling this and further errors with {\tt s}}
+% For the response |s| we put a message into the file |s.tex|
+% and start |\scrollmode| to scroll further error messages in
+% this run. On systems that allow |.tex| as a file name we
+% can also trap a single \meta{return} from the user.
+% \begin{macrocode}
+%<+scroll|return|run,batch> \message{File ignored}
+%<+scroll> \scrollmode
+%<+run> \nonstopmode
+%<+batch> \batchmode
+% \end{macrocode}
+%
+% \subsection{Exiting the run with {\tt x} or {\tt e}}
+%
+% If the user enters |x| or |e| to stop \TeX{}, we need to put
+% something into the corresponding file which will force \TeX{} to
+% give up. We achieve this by turning off terminal output and then
+% asking \TeX{} to stop: first by using the internal \LaTeX{} name
+% |\@@end|, and if that doesn't work because something other than
+% \LaTeX{} is used, by trying the \TeX{} primitive |\end|. The
+% |\errmessage| is there to ensure that \TeX{}'s internal "history"
+% variable is set to |error_message_issued|. This in turn will
+% hopefully set the exit code on those operating systems that
+% implement return codes (though there is no guarantee for this).
+% \changes{v1.1a}{2003/12/28}{Attempt to set exit code (pr/3538).}
+% \begin{macrocode}
+%<+edit|exit> \batchmode \errmessage{}\csname @@end\endcsname \end
+% \end{macrocode}
+% We end every file with an explicit |\endinput| which prevents
+% the docstrip program from putting the character table into
+% the generated files.
+% \begin{macrocode}
+\endinput
+% \end{macrocode}
+%% \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 \~}
+%%
+% \Finale
diff --git a/Master/texmf-dist/source/latex/tools/fontsmpl.dtx b/Master/texmf-dist/source/latex/tools/fontsmpl.dtx
new file mode 100644
index 00000000000..31f085a75f1
--- /dev/null
+++ b/Master/texmf-dist/source/latex/tools/fontsmpl.dtx
@@ -0,0 +1,352 @@
+% \iffalse meta-comment
+%
+% Copyright 1993 1994 1995 1996 1997 1998 1999 2000 2001 2002 2003
+% The LaTeX3 Project and any individual authors listed elsewhere
+% in this file.
+%
+% This file is part of the Standard LaTeX `Tools Bundle'.
+% -------------------------------------------------------
+%
+% It 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.3 or later is part of all distributions of LaTeX
+% version 2003/12/01 or later.
+%
+% The list of all files belonging to the LaTeX `Tools Bundle' is
+% given in the file `manifest.txt'.
+%
+% \fi
+% \title{A font sampler}
+% \author{Alan Jeffrey}
+% \date{v0.11}
+%
+% \maketitle
+%
+% \CheckSum{335}
+%
+%% \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 \~}
+%%
+%
+% \changes{v0.01}{1994/05/01}{Created this test document as part of
+% accents.dtx.}
+% \changes{v0.02}{1994/05/12}{Added the t1enc and ot1enc packages.}
+% \changes{v0.03}{1994/05/14}{Moved fontsmpl to its own dtx file.}
+% \changes{v0.03}{1994/05/14}{Removed the t1enc and ot1enc packages.}
+% \changes{v0.04}{1994/05/14}{Removed some debugging code, improved
+% documentation.}
+% \changes{v0.05}{1994/05/14}{Tidied up some more. Removed the fontenc
+% package.}
+% \changes{v0.06}{1994/10/27}{Added testing for all the commands in
+% ltoutenc.}
+% \changes{v0.06}{1994/10/27}{Switched off error for `commands not
+% defined in this encoding'.}
+% \changes{v0.07}{1994/10/29}{Added testing for \cs{dots},
+% \cs{copyright} and \cs{textregistered}.}
+% \changes{v0.07}{1994/10/29}{Replaced ??? for missing characters by
+% \textbf{?}.}
+% \changes{v0.08}{1994/10/30}{Added testing for \cs{k} and \cs{t}.}
+% \changes{v0.08}{1994/10/30}{Removed testing for any glyphs not in
+% usrguide.}
+% \changes{v0.08}{1994/10/30}{Allowed overfull boxes in the accent test
+% to extend out into the right margin.}
+% \changes{v0.10}{1995/09/19}{Corrected placement of docstrip guard.}
+% \changes{v0.11}{1997/05/13}{Replaced \cs{@changed@x@err} by
+% \cs{TextSymbolUnavailable}, according to the change in
+% \texttt{ltoutenc.dtx}.}
+%
+% \section{Introduction}
+%
+% This document describes the font test document |fontsmpl.tex| and the
+% accompanying package |fontsmpl.sty|. This produces a test of a font
+% family, printing a sample text, a table of accents, and a sample of
+% commands such as |\pounds|.
+%
+% It can be used in two ways. The |fontsmpl| package provides the
+% command |\fontsample|, which produces a sample of the current font.
+%
+% The |fontsmpl| document prompts interactively for a font family (for
+% example `|cmr|') and produces a sample of that family.
+%
+% \StopEventually{}
+%
+% \section{Documentation}
+%
+% This docstrip document has three docstrip options:
+% \begin{itemize}
+% \item |document| the code for |fontsmpl.tex|.
+% \item |package| the code for |fontsmpl.sty|.
+% \item |driver| this documentation.
+% \end{itemize}
+% The code for the driver is:
+% \begin{macrocode}
+%<*driver>
+\NeedsTeXFormat{LaTeX2e}
+\documentclass{ltxdoc}
+\begin{document}
+ \DocInput{fontsmpl.dtx}
+\end{document}
+%</driver>
+% \end{macrocode}
+%
+% \section{Font sample document}
+%
+% The sample document prompts for a family, and uses the |fontsmpl|
+% package. If there is a file |fontsmpl.cfg|, this is loaded.
+% \changes{v0.9}{1995/05/07}{Removed \cs{pagestyle} empty}
+% \begin{macrocode}
+%<*document>
+\NeedsTeXFormat{LaTeX2e}
+\documentclass{article}
+\usepackage{fontsmpl}
+\makeatletter
+\InputIfFileExists{fontsmpl.cfg}{}{}
+\makeatother
+\typein[\family]{Please enter a family name (for example `cmr').}
+\title{Test of \LaTeX{} font family `\family'}
+\author{Font sample produced with `fontsmpl'}
+\raggedright
+\begin{document}
+\maketitle
+\fontfamily{\family}\selectfont
+\fontencoding{T1}\selectfont\fontsample
+\fontencoding{OT1}\selectfont\fontsample
+\itshape
+\fontencoding{T1}\selectfont\fontsample
+\fontencoding{OT1}\selectfont\fontsample
+\slshape
+\fontencoding{T1}\selectfont\fontsample
+\fontencoding{OT1}\selectfont\fontsample
+\scshape
+\fontencoding{T1}\selectfont\fontsample
+\fontencoding{OT1}\selectfont\fontsample
+\upshape\bfseries
+\fontencoding{T1}\selectfont\fontsample
+\fontencoding{OT1}\selectfont\fontsample
+\itshape
+\fontencoding{T1}\selectfont\fontsample
+\fontencoding{OT1}\selectfont\fontsample
+\slshape
+\fontencoding{T1}\selectfont\fontsample
+\fontencoding{OT1}\selectfont\fontsample
+\scshape
+\fontencoding{T1}\selectfont\fontsample
+\fontencoding{OT1}\selectfont\fontsample
+\end{document}
+%</document>
+% \end{macrocode}
+%
+% \section{Font sample package}
+%
+% The |fontsmpl| package is a \LaTeXe{} package.
+% \begin{macrocode}
+%<*package>
+\NeedsTeXFormat{LaTeX2e}
+\ProvidesPackage{fontsmpl}[1994/10/29 Font sample package]
+% \end{macrocode}
+%
+% \begin{macro}{\fontsample}
+% The |\fontsample| command prints out a sample text, a
+% selection of glyphs, and a table of accents.
+% \begin{macrocode}
+\newcommand{\fontsample}{%
+ Test of font \f@encoding/\f@family/\f@series/\f@shape.
+ \fontsampletext
+ \fontsampleglyphs
+ \fontsampleaccents
+}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\fontsampletext}
+% A sample text, taken from Knuth's |testfont.tex|.
+% \begin{macrocode}
+\newcommand{\fontsampletext}{%
+ Some text:
+ \begin{quote}\begin{flushleft}
+ On November 14, 1885, Senator \& Mrs.~Leland Stanford called
+ together at their San Francisco mansion the 24~prominent men who
+ had been chosen as the first trustees of The Leland Stanford
+ Junior University. They handed to the board the Founding Grant
+ of the University, which they had executed three days before.
+ This document---with various amendments, legislative acts, and
+ court decrees---remains as the University's charter. In bold,
+ sweeping language it stipulates that the objectives of the
+ University are ``to qualify students for personal success and
+ direct usefulness in life; and to promote the publick welfare by
+ exercising an influence in behalf of humanity and civilization,
+ teaching the blessings of liberty regulated by law, and
+ inculcating love and reverence for the great principles of
+ government as derived from the inalienable rights of man to life,
+ liberty, and the pursuit of happiness.''
+ \\
+ (!`THE DAZED BROWN FOX QUICKLY GAVE 12345--67890 JUMPS!)
+ \\
+ ?`But aren't Kafka's Schlo\ss\
+ and \AE sop's \OE uvres often na\"\i ve vis-\`a-vis the
+ d\ae monic ph\oe nix's official r\^ole in fluffy s\t ouffl\'es?
+ \\
+
+ \end{flushleft}\end{quote}
+}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\fontsampleglyphs}
+% \begin{macro}{\fontsampleglyph}
+% A list of sample glyph commands.
+% \begin{macrocode}
+\newcommand{\fontsampleglyphs}{%
+ Some glyphs:
+ \begin{quote}\begin{flushleft}
+ \fontsampleglyph{\#}
+ \fontsampleglyph{\$}
+ \fontsampleglyph{\%}
+ \fontsampleglyph{\&}
+ \fontsampleglyph{\AA}
+ \fontsampleglyph{\AE}
+ \fontsampleglyph{\DH}
+ \fontsampleglyph{\DJ}
+ \fontsampleglyph{\L}
+ \fontsampleglyph{\NG}
+ \fontsampleglyph{\OE}
+ \fontsampleglyph{\O}
+ \fontsampleglyph{\P}
+ \fontsampleglyph{\SS}
+ \fontsampleglyph{\S}
+ \fontsampleglyph{\TH}
+ \fontsampleglyph{\_}
+ \fontsampleglyph{\aa}
+ \fontsampleglyph{\ae}
+ \fontsampleglyph{\copyright}
+ \fontsampleglyph{\dag}
+ \fontsampleglyph{\ddag}
+ \fontsampleglyph{\dh}
+ \fontsampleglyph{\dj}
+ \fontsampleglyph{\dots}
+ \fontsampleglyph{\guillemotleft}
+ \fontsampleglyph{\guillemotright}
+ \fontsampleglyph{\guilsinglleft}
+ \fontsampleglyph{\guilsinglright}
+ \fontsampleglyph{\i}
+ \fontsampleglyph{\j}
+ \fontsampleglyph{\l}
+ \fontsampleglyph{\ng}
+ \fontsampleglyph{\oe}
+ \fontsampleglyph{\o}
+ \fontsampleglyph{\pounds}
+ \fontsampleglyph{\quotedblbase}
+ \fontsampleglyph{\quotesinglbase}
+ \fontsampleglyph{\ss}
+ \fontsampleglyph{\textasciicircum}
+ \fontsampleglyph{\textasciitilde}
+ \fontsampleglyph{\textbackslash}
+ \fontsampleglyph{\textbar}
+ \fontsampleglyph{\textbullet}
+ \fontsampleglyph{\textcompwordmark}
+ \fontsampleglyph{\textemdash}
+ \fontsampleglyph{\textendash}
+ \fontsampleglyph{\textexclamdown}
+ \fontsampleglyph{\textgreater}
+ \fontsampleglyph{\texthyphenchar}
+ \fontsampleglyph{\textless}
+ \fontsampleglyph{\textperiodcentered}
+ \fontsampleglyph{\textquestiondown}
+ \fontsampleglyph{\textquotedblleft}
+ \fontsampleglyph{\textquotedblright}
+ \fontsampleglyph{\textquotedbl}
+ \fontsampleglyph{\textquoteleft}
+ \fontsampleglyph{\textquoteright}
+ \fontsampleglyph{\textvisiblespace}
+ \fontsampleglyph{\th}
+ \fontsampleglyph{\{}
+ \fontsampleglyph{\}}
+ \end{flushleft}\end{quote}
+}
+\newcommand{\fontsampleglyph}[1]{%
+ \ifx#1\@undefined
+ {\typewriterfont\string#1}~is~undefined
+ \else
+ {\typewriterfont\string#1}~is~`#1'
+ \fi
+}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\fontsampleaccents}
+% \begin{macro}{\fontsampleaccent}
+% A sample of accents.
+% \begin{macrocode}
+\newcommand{\fontsampleaccents}{%
+ Some accents:
+ \begin{quote}\begin{flushleft}
+ \fontsampleaccent{\"} \\
+ \fontsampleaccent{\'} \\
+ \fontsampleaccent{\.} \\
+ \fontsampleaccent{\=} \\
+ \fontsampleaccent{\H} \\
+ \fontsampleaccent{\^} \\
+ \fontsampleaccent{\`} \\
+ \fontsampleaccent{\b} \\
+ \fontsampleaccent{\c} \\
+ \fontsampleaccent{\d} \\
+ \fontsampleaccent{\k} \\
+ \fontsampleaccent{\u} \\
+ \fontsampleaccent{\v} \\
+ \fontsampleaccent{\~}
+ \end{flushleft}\end{quote}
+}
+\newcommand{\fontsampleaccent}[1]{%
+ \makebox[1em][r]{\typewriterfont\string#1}
+ \makebox[15em][l]{%
+ #1A#1C#1D#1E#1G#1I#1L#1N%
+ #1O#1R#1S#1T#1U#1Y#1Z%
+ #1a#1c#1d#1e#1g#1\i#1i#1l#1n%
+ #1o#1r#1s#1t#1u#1y#1z%
+ }
+}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\typewriterfont}
+% Not all sites have the T1 typewriter fonts, so we set the
+% typewriter font to be a fixed font.
+% \begin{macrocode}
+\DeclareFixedFont{\typewriterfont}
+ {\encodingdefault}{\ttdefault}{\mddefault}{\updefault}{10}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\TextSymbolUnavailable}
+% Switch off the error message from missing glyphs.
+% \begin{macrocode}
+\def\TextSymbolUnavailable#1{%
+ \textbf{?}\PackageInfo{fontsmpl}{%
+ Command \protect#1 undefined in encoding \f@encoding%
+ }%
+}
+%</package>
+% \end{macrocode}
+% \end{macro}
+%\Finale
+\endinput
+
+
diff --git a/Master/texmf-dist/source/latex/tools/ftnright.dtx b/Master/texmf-dist/source/latex/tools/ftnright.dtx
new file mode 100644
index 00000000000..a8282d85816
--- /dev/null
+++ b/Master/texmf-dist/source/latex/tools/ftnright.dtx
@@ -0,0 +1,995 @@
+% \iffalse meta-comment
+%
+% Copyright 1993 1994 1995 1996 1997 1998 1999 2000 2001 2002 2003
+% The LaTeX3 Project and any individual authors listed elsewhere
+% in this file.
+%
+% This file is part of the Standard LaTeX `Tools Bundle'.
+% -------------------------------------------------------
+%
+% It 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.3 or later is part of all distributions of LaTeX
+% version 2003/12/01 or later.
+%
+% The list of all files belonging to the LaTeX `Tools Bundle' is
+% given in the file `manifest.txt'.
+%
+% \fi
+%\iffalse % this is a METACOMMENT !
+%
+%% Package `ftnright' to use with LaTeX 2e
+%% Copyright (C) 1989-2004 Frank Mittelbach, all rights reserved.
+%<+package>\NeedsTeXFormat{LaTeX2e}[1995/06/01]
+%<+package>\ProvidesPackage{ftnright}
+%<+package> [2004/01/16 v1.1e footnote layout package (FMi)]
+%
+% \fi
+%%
+%% \CheckSum{426}
+%% \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 \~}
+%%
+%
+%
+% \DoNotIndex{\;}
+%^^A \DoNotIndex{\@cclv}
+%^^A \DoNotIndex{\@colht}
+%^^A \DoNotIndex{\@colroom}
+% \DoNotIndex{\@combinedblfloats}
+% \DoNotIndex{\@combinefloats}
+% \DoNotIndex{\@dblfloatplacement}
+% \DoNotIndex{\@deferlist}
+% \DoNotIndex{\@empty}
+%^^A \DoNotIndex{\@fcolmadefalse}
+%^^A \DoNotIndex{\@firstcolumnfalse}
+%^^A \DoNotIndex{\@firstcolumntrue}
+% \DoNotIndex{\@freelist}
+% \DoNotIndex{\@ixpt}
+%^^A \DoNotIndex{\@leftcolumn}
+%^^A \DoNotIndex{\@m}
+%^^A \DoNotIndex{\@makecol}
+%^^A \DoNotIndex{\@makefntext}
+%^^A \DoNotIndex{\@maxdepth}
+% \DoNotIndex{\@midlist}
+%^^A \DoNotIndex{\@outputbox}
+%^^A \DoNotIndex{\@outputdblcol}
+%^^A \DoNotIndex{\@outputpage}
+% \DoNotIndex{\@ptsize}
+%^^A \DoNotIndex{\@setsize}
+% \DoNotIndex{\@spaces}
+%^^A \DoNotIndex{\@startcolumn}
+%^^A \DoNotIndex{\@startdblcolumn}
+% \DoNotIndex{\@tempdima}
+% \DoNotIndex{\@textbottom}
+% \DoNotIndex{\@texttop}
+%^^A \DoNotIndex{\@thefnmark}
+% \DoNotIndex{\@viiipt}
+% \DoNotIndex{\@whilesw}
+% \DoNotIndex{\@width}
+%^^A \DoNotIndex{\@xstartcol}
+% \DoNotIndex{\@xpt}
+% \DoNotIndex{\advance}
+% \DoNotIndex{\begingroup}
+% \DoNotIndex{\box}
+%^^A \DoNotIndex{\boxmaxdepth}
+%^^A \DoNotIndex{\columnseprule}
+%^^A \DoNotIndex{\columnwidth}
+% \DoNotIndex{\count}
+% \DoNotIndex{\def}
+% \DoNotIndex{\dimen}
+% \DoNotIndex{\dp}
+% \DoNotIndex{\else}
+% \DoNotIndex{\endgroup}
+% \DoNotIndex{\fi}
+% \DoNotIndex{\filedate}
+% \DoNotIndex{\filename}
+% \DoNotIndex{\fileversion}
+%^^A \DoNotIndex{\footins}
+%^^A \DoNotIndex{\footnoterule}
+%^^A \DoNotIndex{\footnotesep}
+%^^A \DoNotIndex{\footnotesize}
+%^^A \DoNotIndex{\ftn@amount}
+% \DoNotIndex{\gdef}
+% \DoNotIndex{\global}
+% \DoNotIndex{\hbox}
+% \DoNotIndex{\hfil}
+% \DoNotIndex{\hss}
+% \DoNotIndex{\ht}
+%^^A \DoNotIndex{\if@fcolmade}
+%^^A \DoNotIndex{\if@firstcolumn}
+% \DoNotIndex{\ifcase}
+%^^A \DoNotIndex{\ifvoid}
+% \DoNotIndex{\ifx}
+%^^A \DoNotIndex{\insert}
+% \DoNotIndex{\ixpt}
+% \DoNotIndex{\let}
+% \DoNotIndex{\llap}
+% \DoNotIndex{\long}
+%^^A \DoNotIndex{\maxdepth}
+%^^A \DoNotIndex{\newdimen}
+%^^A \DoNotIndex{\newskip}
+% \DoNotIndex{\noindent}
+% \DoNotIndex{\normalsize}
+% \DoNotIndex{\or}
+%^^A \DoNotIndex{\parindent}
+%^^A \DoNotIndex{\preparefootins}
+%^^A \DoNotIndex{\rcol@footinsskip}
+%^^A \DoNotIndex{\saved@footinsskip}
+% \DoNotIndex{\setbox}
+% \DoNotIndex{\skip}
+% \DoNotIndex{\space}
+%^^A \DoNotIndex{\strutbox}
+%^^A \DoNotIndex{\textheight}
+%^^A \DoNotIndex{\textwidth}
+% \DoNotIndex{\unvbox}
+% \DoNotIndex{\vbox}
+% \DoNotIndex{\viiipt}
+% \DoNotIndex{\vrule}
+% \DoNotIndex{\vskip}
+%^^A \DoNotIndex{\wlog}
+% \DoNotIndex{\xdef}
+% \DoNotIndex{\xpt}
+% \DoNotIndex{\z@}
+%
+% \changes{v1.1a}{1994/01/24}{Upgrades for LaTeX2e}
+% \changes{v1.1b}{1994/01/24}{Driver moved in front}
+% \changes{v1.1c}{1996/01/01}{Use article.cls for documentation}
+%
+% \renewcommand{\.}{\penalty500} %^^A for certain breaks
+%
+% \setlength{\hfuzz}{2pt} ^^A allow small overshot in verbatim
+%
+% \GetFileInfo{ftnright.sty}
+%
+% \title{Footnotes in a multi-column layout\thanks
+% {The \LaTeX{} package {\tt \filename} which is described
+% in this article has the version number \fileversion{} dated
+% \filedate.}}
+% \author{Frank Mittelbach\\
+% Electronic Data Systems (Deutschland) GmbH\\
+% Eisenstra\ss e 58 \\
+% 65428 R\"usselsheim}
+%
+%
+% \maketitle
+%
+% \pageshrink 1pt %^^A compensate for the \thanks marker
+%
+%
+% \section{Preface to version 1.1}
+%
+% The new release is a basically unchanged version of the original. I
+% upgraded the macros so that they work with \LaTeXe{} and used some
+% of the additional flexibility introduced therein. For example, the
+% command |\preparefootins| is now automatically called at
+% |\begin{document}|, thus allowing the user to adjust the
+% |\textheight| in the preamble.
+%
+% It is not surprisingly that I was forced to change some of the
+% macros because they dig deep into \LaTeX{}'s output routines.
+% Fortunately this is something normally not necessary when upgrading
+% other \LaTeX~2.09 styles to \LaTeXe{} packages.
+%
+% I also upgraded the documentation to conform to the \LaTeXe{}
+% terminology, e.g., this is a package since document classes will not
+% know about it. However it is very likely that i have missed some
+% necessary corrections.
+%
+% \section{Introduction}
+%
+%
+% The placement of footnotes in a multicolumn layout always bothered
+% me. The approach taken by \LaTeX{} (i.e., placing the footnotes
+% separately under each column) might be all right if nearly no
+% footnotes are present. But it looks clumsy when both columns contain
+% footnotes, especially when they occupy different amounts of space.
+%
+% In the multicolumn package~\cite{art:FMi89b}, I used page-wide
+% footnotes at the bottom of the page, but again the result doesn't
+% look very pleasant since short footnotes produce undesired gaps of
+% white space. Of course, the main goal of this package was a
+% balancing algorithm for columns which would allow switching between
+% different numbers of columns on the same page. With this feature,
+% the natural place for footnotes seems to be the bottom of the
+% page\footnote{You cannot use column footnotes at the bottom, since
+% the number of columns can differ on one page.} but looking at some
+% of the results it seems best to avoid footnotes in such a layout
+% entirely.
+%
+%
+% Another possibility is to turn footnotes into endnotes, i.e.,
+% printing them at the end of every chapter or the end of the entire
+% document. But I assume everyone who has ever read a book using such
+% a layout will agree with me, that it is a pain to search back and
+% forth, so that the reader is tempted to ignore the endnotes
+% entirely.
+%
+% When I wrote the article about ``Future extensions of
+% \TeX{}''~\cite{inproc:FMi90} I was again dissatisfied with the
+% outcome of the footnotes, and since this article should show certain
+% aspects of high quality typesetting, I decided to give the footnote
+% problem a try and modified the \LaTeX{} output routine for this
+% purpose. The layout I used was inspired by the yearbook of the
+% Gutenberg Gesellschaft Mainz \cite{book:GG}. Later on, I found that
+% it is also recommended by Jan White \cite{book:JWh88}. On the layout
+% of footnotes I also consulted books by Jan Tschichold
+% \cite{book:JTs87} and Manfred Simoneit \cite{book:MSi89}, books I
+% would recommend to everyone being able to read German texts.
+%
+%
+% \subsection{Description of the new layout}
+%
+% The result of this effort is presented in this paper and the reader
+% can judge for himself whether it was successful or
+% not.\footnote{Please note, that this option only changed the
+% placement of footnotes. Since this article also makes use of the
+% {\tt doc} package \cite{bk:GMS94}, that assigns tiny numbers to
+% code lines sprinkled throughout the text, the resulting design is
+% not perfect. This package is now a standard part of \LaTeXe.}
+% The main idea for this layout is to assemble the
+% footnotes of all columns on a page and place them all together at
+% the bottom of the right column. Allowing for enough space between
+% footnotes and text, and in addition, setting the footnotes in
+% smaller type\footnote{The standard layout in \TUB{} uses the same
+% size for footnotes and text, giving the footnotes, in my opinion,
+% much too much prominence.} I decided that one could omit the
+% footnote separator rule which is used in most publications prepared
+% with \TeX{}.\footnote{People who prefer the rule can add it by
+% redefining the command {\tt\bslash footnoterule}
+% \cite[p.~156]{book:LLa86}. Please, note, that this command should
+% occupy no space, so that a negative space should be used to
+% compensate for the width of the rule used.} Furthermore, I decided
+% to place the footnote markers\footnote{\label{thisftn}The tiny
+% numbers or symbols, e.g., the `\ref{thisftn}' in front of this
+% footnote.} at the baseline instead of raising them as
+% superscripts.\footnote{Of course, this is done only for the mark
+% preceding the footnote text and not the one used within the main
+% text where a raised number or symbol set in smaller type will help
+% to keep the flow of thoughts, uninterrupted.}
+%
+% All in all, I think this generates a neat layout, and surprisingly
+% enough, the necessary changes to the \LaTeX{} output routine are
+% nevertheless astonishingly simple.
+%
+% \subsection{The use of the package}
+%
+% This package might be used together with any other package
+% for \LaTeX{} which does not change the three internals changed by
+% {\tt \filename}.\footnote{These are the macros {\tt\bslash
+% @startcolumn}, {\tt\bslash @makecol}, and {\tt\bslash @outputdblcol},
+% as we will see below. Of course, the package will take only effect
+% with a document class using a two-column layout (like {\tt ltugboat})
+% or when the user additionally specifies {\tt twocolumn} as a
+% document class option in the {\tt\bslash documentclass} command.} In
+% most cases, it is best to use this package as the very last
+% package in the preamble to make sure that its
+% settings are not overwritten by other packages.
+%
+% It is unfortunate that the current \LaTeX{} has nearly no provisions
+% to make such changes without overwriting the internal routines. In
+% the \LaTeX3 implementation, we will certainly add some hooks that
+% will make such changes more easy.
+%
+%
+%
+% \StopEventually{
+%
+% \begin{small}
+% \begin{thebibliography}{1}
+%
+% \bibitem{bk:GMS94} \textsc{M.~Goossens}, \textsc{F.~Mittelbach}
+% and \textsc{A.~Samarin}.
+% \newblock The \LaTeX{} Companion.
+% \newblock
+% Addison-Wesley, Reading, Massachusetts, 1994.
+%
+% \bibitem{book:GG}
+% Hans-Joachim Koppitz, editor.
+% \newblock {\em {Gutenberg Jahrbuch}}.
+% \newblock Gutenberg-Gesellschaft, Mainz.
+%
+% \bibitem{book:LLa86}
+% Leslie Lamport.
+% \newblock {\em {\LaTeX:} A Document Preparation System}.
+% \newblock Addison-Wesley, Reading, Massachusetts, 1986.
+%
+% \bibitem{src:ltxiii94}
+% \LaTeX3 project.
+% \newblock \LaTeXe distribution, 1994.
+% \newblock Souces for {\LaTeXe} the successor to \LaTeX~2.09.
+%
+% \bibitem{art:FMi89b}
+% Frank Mittelbach
+% \newblock An environment for multi-column output.
+% \newblock {\em TUGboat}, 10(3):407--415, November 1989.
+%
+% \bibitem{inproc:FMi90}
+% Frank Mittelbach
+% \newblock E-{\TeX}: Guidelines to future {\TeX} extensions.
+% \newblock In Lincoln K. Durst, editor, {\em \TUB}, 11(3):
+% {\em 1990 TUG Annual Meeting Proceedings}, pages
+% 337--345, September 1990.
+%
+% \bibitem{book:MSi89}
+% Manfred Siemoneit.
+% \newblock {\em Typographisches {G}estalten}.
+% \newblock Polygraph Verlag, Frankfurt am Main, second edition, 1989.
+%
+% \bibitem{book:JTs87}
+% Jan Tschichold.
+% \newblock {\em {Ausgew\"ahlte Aufs\"atze \"uber Fragen der Gestalt des
+% Buches}}.
+% \newblock Birkh\"auser Verlag, Basel, 1987.
+% \newblock Second printing.
+%
+% \bibitem{book:JWh88}
+% Jan White.
+% \newblock {\em Graphic Design for the Electronic Age}.
+% \newblock Watson Guptill, Xerox Press, New York, 1988.
+%
+% \end{thebibliography}
+% \end{small}
+%
+% \onecolumn
+% \PrintIndex
+% \PrintChanges
+% }
+%
+%
+%
+% \section{The documentation driver}
+%
+% The first 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 {\tt
+% docstrip} program. If you don't want to make any changes to the
+% presentation you can alternatively process the \texttt{.dtx} file
+% directly with \LaTeXe{} to obtain the documentation.
+% \changes{v1.0d}{1992/04/19}{Added driver file to source}
+% \changes{v1.0e}{1993/05/13}{Added history generation}
+% \begin{macrocode}
+%<*driver>
+\documentclass[twocolumn]{article}
+
+\usepackage{ftnright}
+\usepackage{doc}
+\AtBeginDocument{\MakeShortVerb{\|}}
+
+\newcommand{\TUB}{{\sl TUGboat\/}}
+\renewcommand\DescribeMacro[1]{\fbox
+ {\PrintDescribeMacro{#1}}}
+\renewcommand\DescribeEnv[1]{\fbox
+ {\PrintDescribeEnv{#1}}}
+\renewcommand\PrintMacroName[1]{}
+
+\setlength{\parindent}{1em}
+\setlength{\parskip}
+ {2pt plus1pt minus1pt}
+\setlength{\headsep}{20pt}
+\setlength{\columnsep}{1.5pc}
+\renewcommand{\bottomfraction}{.4}
+
+\flushbottom
+\CodelineIndex
+\RecordChanges % produce history
+\EnableCrossrefs
+
+\setcounter{IndexColumns}{2}
+\IndexPrologue{\section{Index}
+ All numbers denote code lines where
+ the corresponding entry is used,
+ underlined entries point to the
+ definition.}
+
+\begin{document}
+ \DocInput{ftnright.dtx}
+\end{document}
+%</driver>
+% \end{macrocode}
+%
+% \section{The Implementation}
+%
+%
+% As usual, we start by identifying the current version of this package
+% file in the transcript file.\footnote{Nico Poppelier suggested
+% omitting the {\tt\bslash typeout} statements in the production
+% version of the files to avoid showing all that unnecessary
+% information to the user. While I accept his criticism as valid, I
+% decided that this information should at least be placed into the
+% transcript file to make it easier to detect problems arising from
+% the use of older versions. This happens now automatically as the command
+% \texttt{\string\ProvidesPackage} will only write to the transcript file.}
+% This actually happens at the very top of this file so it is commented out
+% here.
+%\begin{verbatim}
+%\ProvidesPackage{ftnright}[\filedate\space
+% LaTeX2e package \fileversion]
+%\end{verbatim}
+%
+% To implement the layout described, above we have to distinguish
+% between the left and the right column on a page. For this purpose
+% \LaTeX{} maintains the switch |\if@firstcolumn|. When assembling
+% material for the left (i.e., the first) column, footnotes should
+% take up no space, since they are held over for the second column. In
+% the second column these footnotes are combined with the ones found
+% there and placed a suitable distance from the main text at the
+% bottom of this column.
+%
+% This means that we have to change certain parameters for the
+% insertion |\footins| when we construct the second column. The right
+% place to do this is in the \LaTeX{} macro |\@outputdblcol| which we
+% are going to change later on. What settings for the insertion
+% parameters are appropriate? For setting the first column
+% |\count|\.|\footins| and |\skip|\.|\footins| should both be zero
+% since footnotes are held over while for the second column
+% |\count|\.|\footins| should be $1000$ and the |\skip|\.|\footins|
+% has to be set to the desired separation between main text and
+% footnotes.\footnote{A value of $1000$ means that there is a
+% one-to-one relationship between the real size of the footnote and
+% the size finally occupied by the footnote on the current page.}
+%
+%
+% We will allow one column of footnotes (i.e., the right column) at
+% most, so that |\dimen|\.|\footins| has to equal |\textheight|. In
+% principle, it would be possible to allow for even more footnotes,
+% but this would complicate matters enormously.\footnote{It is not
+% possible to make {\tt\bslash dimen\bslash footins} larger than
+% {\tt\bslash textheight} directly, because this would result in a
+% full left column (with text) and more than one column of footnotes.
+% Instead, one has to make footnotes visible to the page generation
+% algorithm again at the moment when a full column of footnotes is
+% assembled, but we still have some space left in the first column. It
+% is a nice enhancement, and, I suppose, it is of some value for
+% preparing publications in certain disciplines, so here is the
+% challenge~\ldots}
+%
+%
+% \begin{macro}{\preparefootins}
+% \begin{macro}{\saved@footinsskip}
+% Since a document usually starts with a left column, we have to
+% set |\count| and |\skip|\.|\footins| on top-level to zero. For
+% this purpose, we define a macro |\preparefootins| which will
+% first save the current value of |\skip|\.|\footins| in a safe
+% place. This saved value will be used later for the second column.
+% In this way, it is possible for the user or a designer of a
+% document class to adjust this parameter without fiddling with the
+% code of this package file.
+% \begin{macrocode}
+%<*package>
+\def\preparefootins{%
+ \global\rcol@footinsskip\skip\footins
+ \global\skip\footins\z@
+ \global\count\footins\z@
+% \end{macrocode}
+% We will also assign |\textheight| to |\dimen|\.|\footins| to
+% allow the user to change this parameter in the preamble.
+% \begin{macrocode}
+ \global\dimen\footins\textheight}
+% \end{macrocode}
+% It is necessary to make the assignments above |\global| because
+% we are going to use this macro in the output routine which has an
+% implicit grouping level to keep the changes made by it local.
+% \end{macro}
+% Of course, we have to allocate the {\sf skip} register that we
+% used above:
+% \begin{macrocode}
+\newskip\rcol@footinsskip
+% \end{macrocode}
+% \end{macro}
+%
+%
+% \begin{macro}{\@outputdblcol}
+% Now we have all the necessary tools available to tackle
+% |\@outputdblcol|. We have to remember that when
+% |\if@firstcolumn| equals |\iftrue|, we are currently starting to
+% build the second column, i.e., that the first column is already
+% assembled. Therefore, the macro will start with the following
+% code:
+% \begin{macrocode}
+\def\@outputdblcol{\if@firstcolumn
+ \global\@firstcolumnfalse
+% \end{macrocode}
+% After changing the switch, we save the first column (which was
+% placed by preceeding macros in |\@outputbox|) in the box register
+% |\@leftcolumn|. Since we are inside the output routine, all those
+% assignments have to be |\global| to take any effect.
+% \begin{macrocode}
+ \global\setbox\@leftcolumn\box\@outputbox
+% \end{macrocode}
+% Then, we make the footnotes visible to the page generation
+% algorithm by setting |\count\footins| to $1000$ (|\@m| is an
+% abbreviation for this number) and |\skip\footins| to its saved
+% value (i.e., |\rcol@footinsskip|).
+% \begin{macrocode}
+ \global\count\footins\@m
+ \global\skip\footins\rcol@footinsskip
+% \end{macrocode}
+% We also have to reinsert all footnotes left over from the first
+% column to make sure that they are reconsidered by the page
+% generation algorithm of \TeX{} using the new values for |\count|
+% and |\skip|\.|\footins|. But this will be done later in the
+% macro |\@startcolumn|.
+%
+% If we have just finished the right column, i.e., when
+% |\if@firstcolumn| equals |\iffalse|, we will reset the |\footins|
+% parameters as explained above using the utitlity macro
+% |\preparefootins|.
+% \begin{macrocode}
+ \else \preparefootins
+% \end{macrocode}
+% Then, we compose both columns in |\@outputbox|, combine them with
+% all page-wide floats for this page (|\@combinedblfloats|), attach
+% header and footer, and ship out the result (|\@outputpage|).
+% Finally we look to see whether it is possible to generate
+% following pages consisting only of page-wide
+% floats.\footnote{This part is copied directly from the original
+% \LaTeX{} macro. Details about the used macros, their interfaces
+% and meanings can be found in the \LaTeXe{} source
+% code~\cite{src:ltxiii94}.}
+% \begin{macrocode}
+ \global\@firstcolumntrue
+ \setbox\@outputbox\vbox{\hbox to\textwidth
+ {\hbox to\columnwidth
+ {\box\@leftcolumn\hss}%
+ \hfil\vrule\@width\columnseprule\hfil
+ \hbox to\columnwidth
+ {\box\@outputbox\hss}}}%
+ \@combinedblfloats\@outputpage
+ \begingroup
+ \@dblfloatplacement\@startdblcolumn
+ \@whilesw\if@fcolmade\fi
+ {\@outputpage\@startdblcolumn}%
+ \endgroup
+ \fi}
+% \end{macrocode}
+% \end{macro}
+%
+%
+% \begin{macro}{\@startcolumn}
+% \changes{v1.0b}{1990/08/11}{Macro added to correct float problems}
+% There is a fundamental flaw in \LaTeX's output routine for float
+% columns and float pages: split footnotes, i.e., footnotes which
+% are only partly typeset on the preceding page are not resolved.
+% They are held over until \LaTeX{} starts a page (or column)
+% containing text besides floats again. For our current layout,
+% this would mean, that if \LaTeX{} decided to make the right
+% column of a page a float column, footnotes from the left column
+% would appear on a later page. A real cure for this problem would
+% be to rewrite two-thirds of \LaTeX{}'s output routine, so I am
+% leaving this open for the interested reader.
+%
+% \begin{figure}[b]
+% \fbox{%^^A
+% \newlength{\puzzlewd}%^^A
+% \setlength{\puzzlewd}{\columnwidth}%^^A
+% \addtolength{\puzzlewd}{-2.1\fboxsep}%^^A
+% \begin{minipage}{\puzzlewd}
+% \vspace{17pt}
+% \begin{center}
+% \bf Puzzle:
+% \end{center}
+% \vspace{-3pt}
+% \small
+% \begin{quote}
+% \rightskip \leftmargini plus 2.5em
+% Given a simple \TeX{} document containing only straight text, is
+% it possible for the editor, after
+% deleting one sentence, to end up with a document
+% producing an extra page?
+%
+% We assume that the deleted text contains no \TeX{} macros and
+% that the document was prepared
+% with a standard macro package like the one used for \TUB\/ production.
+% \end{quote}
+% \vspace{7pt}
+% \begin{flushright}
+% The answer will be given in the next issue.
+% \end{flushright}
+% \vspace{7pt}
+% \end{minipage}}
+% \end{figure}
+%
+% But the problem shows up even if only one float is contributed to
+% the right column since \LaTeX{} assumes that the whole column is
+% usable, whereas some of it might actually be already devoted to
+% footnotes from the left column. So we have to change the output
+% routine at least in the part that contributes floats to the next
+% column. The macro involved is called |\@startcolumn|. The first
+% thing we do is to check and see whether any deferred floats
+% exists.
+% \begin{macrocode}
+\def\@startcolumn{%
+ \ifx\@deferlist\@empty
+% \end{macrocode}
+% If not, we set the switch |\if@fcolmade| to {\tt false} which
+% says that we did not succeed in making a float column. Then, we
+% set |\@colroom| to |\@colht|. The register |\@colht| holds the
+% amount of space that is available for floats, text, and footnotes
+% in one column, i.e., it equals |\textheight| minus the space
+% devoted to page-wide floats. |\@colroom| is a similar register
+% which holds the value |\@colht| minus space for column floats
+% that are already contributed to the current column. Of course,
+% both values should be equal when we start a new column.
+% \begin{macrocode}
+ \global\@fcolmadefalse
+ \global\@colroom\@colht
+ \else
+% \end{macrocode}
+% If there are floats waiting for a change to be processed, the
+% situation is more difficult. In this case, we have to reduce both
+% |\@colht| and |\@colroom| by the amount of space that will be
+% needed for the footnotes from the left column. So we must check
+% whether such footnotes are present. As we have not reinserted
+% them in |\@outputdblcol|, we can check the |\footins| box.
+% \begin{macrocode}
+ \ifvoid\footins\else
+% \end{macrocode}
+% If there are some, we measure the space that will be occupied by
+% them. This measurement is not really exact. If we have a full
+% column of footnotes, it will be too high, but this does matter
+% since we need it only for an upper bound on the free space
+% available for floats.
+% \begin{macrocode}
+ \ftn@amount\ht\footins
+ \advance\ftn@amount\dp\footins
+ \advance\ftn@amount\skip\footins
+ \fi
+% \end{macrocode}
+% We then reduce the |\@colht| by this amount and again assign
+% |\@colroom| the value of |\@colht|. If no footnotes are present,
+% we substract zero, so there is no harm in doing this operation
+% all the time.
+% \begin{macrocode}
+ \global\advance\@colht-\ftn@amount
+ \global\@colroom\@colht
+% \end{macrocode}
+% Now, we call another internal \LaTeX{} macro that will try to
+% contribute floats to the next column. It will use the register
+% |\@colht| when trying to build up a float column, which is the
+% reason for reducing this register. If it succeeds, it will set the
+% switch |\if@fcolmade| to {\tt true}, otherwise, to {\tt false}. If
+% no float column is possible, it will try to place some or all of
+% the deferred floats to the top or the bottom of the next column,
+% thereby, using and reducing the value of the register |\@colroom|.
+% \begin{macrocode}
+ \@xstartcol
+% \end{macrocode}
+% Afterwards, we have to restore the correct values for |\@colht|
+% and |\@colroom| again, but this time, they may differ, so that we
+% have to |\advance| both registers separately by |\ftn@amount|.
+% \begin{macrocode}
+ \global\advance\@colht\ftn@amount
+ \global\advance\@colroom\ftn@amount
+ \fi
+% \end{macrocode}
+% Now, after doing the things depending on the status of the
+% |\@deferlist|, we have to incorporate the left over footnotes in
+% the new column. First we check whether a float column was
+% produced by |\@xstartcol| or not.
+% \begin{macrocode}
+ \if@fcolmade
+% \end{macrocode}
+% If so, we do something awful. To make use of the |\@makecol|
+% macro, which attaches footnotes to |\box| $255$ and places the
+% result in the box register |\@outputbox|, we have to assign
+% |\@outputbox| (i.e., the result of |\@xstartcol|) to |\box|
+% $255$.\footnote{In German, we call this ``from the back through
+% the chest into the eyes''.}
+% \begin{macrocode}
+ \setbox\@cclv\box\@outputbox
+ \@makecol
+ \else
+% \end{macrocode}
+% If no float column was produced, we reinsert the held over
+% footnotes so that they can be reconsidered by the page generation
+% algorithm of \TeX. But it is necessary to ensure that this
+% operation is done only when footnotes are actually
+% present.\footnote{Otherwise, we might get an undesired extra
+% vertical space coming from {\tt\bslash skip\bslash footins}, even
+% if there are no footnotes on the page.}
+% \begin{macrocode}
+ \ifvoid\footins\else
+ \insert\footins{\unvbox\footins}\fi
+ \fi}
+% \end{macrocode}
+% \begin{macro}{\ftn@amount}
+% Of course, we also have to allocate the {\sf dimen} register. It
+% will be automatically initialized to zero.
+% \begin{macrocode}
+\newdimen\ftn@amount
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+
+
+% \begin{macro}{\@xstartcol}
+% \changes{v1.1a}{1994/01/24}{Macro reintroduced}
+% The macro |\@xtsartcol| was removed in \LaTeXe{} but we introduce
+% it here again for the moment.
+% \begin{macrocode}
+\def\@xstartcol{%
+ \@tryfcolumn \@deferlist
+ \if@fcolmade
+ \else
+ \begingroup
+ \let \@tempb \@deferlist
+ \global \let \@deferlist \@empty
+ \let \@elt \@scolelt
+ \@tempb
+ \endgroup
+ \fi
+}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\@makecol}
+% The other internal macro that we have to change is |\@makecol|, a
+% macro that is called whenever one column of material is assembled
+% and column floats and footnotes have to be added. Again, we have
+% to distinguish between actions for the first and the second
+% column.
+% \begin{macrocode}
+\def\@makecol{\if@firstcolumn
+% \end{macrocode}
+% For the first column, we leave the footnotes in their box and
+% simply save the contents of box $255$ in the |\box| register
+% |\@outputbox|.
+% \begin{macrocode}
+ \setbox\@outputbox\box\@cclv
+% \end{macrocode}
+%
+% But if the user errously forgot to specify a twocolumn layout, we
+% will always typeset the first column, so that the footnotes are
+% never printed. Therefore we better check for this special case
+% and output the footnotes on a separate page in an
+% emergency.\footnote{Otherwise, the footnotes are held over for
+% ever, preventing \TeX{} from finishing the document successfully.
+% Instead, \TeX{} will produce infinity many empty pages at the end
+% of the document, trying in vain to output the held over
+% footnotes. This problem was found by Rainer Sch\"opf when we
+% prepared the paper for the Cork conference.}
+% \changes{v1.0c}{1990/08/24}{Introduced crude recovery if
+% twocolumn false.}
+% \changes{v1.0d}{1992/06/19}{Better help message}
+% \begin{macrocode}
+ \if@twocolumn \else
+ \ifvoid\footins \else
+ \@latexerr{ftnright package
+ used in one-column mode}%
+ {The ftnright package was designed to
+ work with LaTeX's standard^^Jtwocolumn
+ option. It does *not* work with the
+ multicol package.^^JSo please specify
+ `twocolumn' in the
+ \noexpand\documentclass command.}%
+ \shipout\box\footins \fi\fi
+ \else
+% \end{macrocode}
+% When we construct the second column, we must first check whether
+% footnotes are actually present. If not, we perform the same
+% actions as before.
+% \begin{macrocode}
+ \ifvoid\footins
+ \setbox\@outputbox\box\@cclv
+ \else
+% \end{macrocode}
+% But, if footnotes are present, it may be possible that the whole
+% column consists of footnotes, i.e., |\box| $255$ is empty. In
+% this case, there is no use in placing any glue (|\skip\footins|)
+% in front,\footnote{In fact, it would be a mistake since this glue
+% was not taken into account when the footnotes where assembled, so
+% it would produce an overfull box.} so we have to check for this
+% possibility.
+% \begin{macrocode}
+ \setbox\@outputbox\vbox
+ {\ifvoid\@cclv \else
+ \unvbox\@cclv
+ \vskip\skip\footins\fi
+% \end{macrocode}
+% But in any case, we place the |\footnoterule| in front of the
+% footnotes even if this macro is not used by this
+% package.\footnote{This decision is certainly open to criticism,
+% since there is nothing to separate. On the other hand, a rule or
+% some other ornament in front of the footnotes is part of the
+% design which should be used concistently throughout a document.
+% As a last argument in favor of the rule, consider the situation
+% where \LaTeX{} decided to place only floats and footnotes into
+% the right hand column. In this case a separator again seems
+% adequate. In this situation one can even argue that it is
+% necessary to put in the {\tt \bslash skip\.\bslash footins}.}
+% This ends the if-statement testing whether footnotes are present
+% or not. It also ends the code which differs depending on the
+% column number.
+% \changes{v1.1d}{1998/12/02}{Added the color@group macros and
+% \texttt{\protect\bslash normalcolor} to make this colorsafe}
+% \begin{macrocode}
+ \color@begingroup
+ \normalcolor
+ \footnoterule\unvbox\footins
+ \color@endgroup}\fi
+ \fi
+% \end{macrocode}
+% Now the column floats are added at the top and the bottom, and
+% the |\@outputbox| is adjusted to the full column height so that
+% the glue inside will stretch in certain situations.\footnote{It
+% is an interesting question as to whether the current layout works
+% well with bottom floats or not. Actually, I would prefer to place
+% the footnotes below the bottom floats instead of above, as it is
+% done here. At least when the floats are part of the document and
+% not puzzles thrown in. But I was too lazy to implement it
+% because I seldom use floats. If somebody implements this layout
+% (some parts of this macro have to be changed) I would be
+% interested in seeing the code and some sample results.} Again,
+% this code is copied verbatim from the original source, so I won't
+% dwell on details.\footnote{I only changed {\tt\bslash dimen128}
+% into {\tt\bslash @tempdima} which is, besides being faster and
+% shorter, only a cosmetic change. The use of this hardwired {\sf
+% dimen} register seems to indicate that this part of \LaTeX{} was
+% written very early and left unchanged since then: an interesting
+% fact for software archeologists.}\footnote{For the \LaTeXe{}
+% upgrade I had to add the support for the
+% {\tt\string\enlargethispage} command---let's hope I did it in the
+% correct way.}
+% \changes{v1.1a}{1994/01/24}{Upgrades for LaTeX2e}
+% \begin{macrocode}
+ \xdef\@freelist{\@freelist\@midlist}%
+ \global \let \@midlist \@empty
+ \@combinefloats
+ \ifvbox\@kludgeins
+ \@makespecialcolbox
+ \else
+ \setbox\@outputbox\vbox to\@colht
+ {\boxmaxdepth\maxdepth
+ \@texttop
+ \@tempdima\dp\@outputbox
+ \unvbox\@outputbox
+ \vskip-\@tempdima
+ \@textbottom}%
+ \fi
+ \global\maxdepth\@maxdepth}
+% \end{macrocode}
+% \end{macro}
+%
+%
+% \begin{macro}{\footnotesize}
+% \changes{v1.1a}{1994/01/24}{Upgrades for LaTeX2e}
+% Now we can tackle the remaining small changes to the standard
+% layout. I decided to use a smaller size for footnotes but with a
+% slightly larger leading than usual. This means that we have to
+% redefine the |\footnotesize| macro which depends on options like
+% {\tt 11pt} etc. Fortunately, there is a simple way to find out
+% the main size of the document: the macro |\@ptsize| contains $0$,
+% $1$, or $2$ standing for $10$, $11$, or $12$ points document text
+% size.\footnote{In the new release I used the definitions from the
+% class option files \texttt{size1?.clo} and modified them
+% slightly. In the previous release there was no correction for the
+% list parameters etc., thus giving you incorrect spacing if
+% somebody used display lists in footnotes.}
+% \begin{macrocode}
+\ifcase \@ptsize
+\renewcommand\footnotesize{%
+ \@setfontsize\footnotesize\@viiipt{9.9}%
+ \abovedisplayskip 6\p@\@plus2\p@\@minus4\p@
+ \abovedisplayshortskip \z@ \@plus\p@
+ \belowdisplayshortskip
+ 3\p@\@plus\p@\@minus2\p@
+ \def\@listi{\leftmargin\leftmargini
+ \topsep 3\p@ \@plus\p@ \@minus\p@
+ \parsep 2\p@ \@plus\p@ \@minus\p@
+ \itemsep \parsep}%
+ \belowdisplayskip \abovedisplayskip
+}
+\or
+\renewcommand\footnotesize{%
+ \@setfontsize\footnotesize\@ixpt{11.1}%
+ \abovedisplayskip 8\p@\@plus2\p@\@minus4\p@
+ \abovedisplayshortskip \z@ \@plus\p@
+ \belowdisplayshortskip
+ 4\p@ \@plus2\p@ \@minus2\p@
+ \def\@listi{\leftmargin\leftmargini
+ \topsep 4\p@ \@plus2\p@\@minus2\p@
+ \parsep 2\p@ \@plus\p@ \@minus\p@
+ \itemsep \parsep}%
+ \belowdisplayskip \abovedisplayskip
+}
+\or
+\renewcommand\footnotesize{%
+ \@setfontsize\footnotesize\@xpt{12.3}%
+ \abovedisplayskip10\p@\@plus2\p@\@minus5\p@
+ \abovedisplayshortskip \z@ \@plus3\p@
+ \belowdisplayshortskip
+ 6\p@ \@plus3\p@ \@minus3\p@
+ \def\@listi{\leftmargin\leftmargini
+ \topsep 6\p@ \@plus2\p@ \@minus2\p@
+ \parsep 3\p@ \@plus2\p@ \@minus\p@
+ \itemsep \parsep}%
+ \belowdisplayskip \abovedisplayskip
+}
+\fi
+% \end{macrocode}
+% \end{macro}
+%
+%
+%
+% \begin{macro}{\footnoterule}
+% Setting footnotes in smaller type and separating them with
+% sufficiant space from the main text allow us to omit the
+% |\footnoterule| normally used.
+% \begin{macrocode}
+\let\footnoterule\@empty
+% \end{macrocode}
+% \end{macro}
+%
+%
+%
+% \begin{macro}{\footnotesep}
+% \changes{v1.1a}{1994/01/24}{Upgrades for LaTeX2e}
+% Individual footnotes are separated from each other by a more or
+% less baseline skip of the text size. This can be specified with
+% the following code:
+% \begin{macrocode}
+\AtBeginDocument
+ {\global\footnotesep\ht\strutbox}
+% \end{macrocode}
+% The use of the \LaTeXe{} hook |\AtBeginDocument| is a big help
+% since it allows us to defer everything that might depend on user
+% setting inside the preamble to the |\begin{document}| environment
+% start.
+% \end{macro}
+%
+%
+%
+% \begin{macro}{\@makefntext}
+% And finally, a small but nice change, to the mark at the
+% beginning of the footnote text. We will place it at the baseline
+% instead of raising it as a superscript. Additionally, it will get
+% a dot as punctuation.
+% \changes{v1.0c}{1990/08/24}{Added dot as recommended by Tschichold.}
+% \changes{v1.1e}{2000/04/14}{Don't use math mode for footnote symbol
+% (pr/3172)}
+% \begin{macrocode}
+\long\def\@makefntext#1{\parindent 1em
+ \noindent\hbox to 2em{}%
+ \llap{\@thefnmark.\,\,}#1}
+% \end{macrocode}
+% \end{macro}
+%
+%
+% \section{Initialisation}
+%
+% We defined the macro |\preparefootins| above, but we also have to use
+% it to prepare typesetting the first column. As a default for the
+% separation of footnotes and text on the second column, we use the
+% following:
+% \begin{macrocode}
+\setlength{\skip\footins}
+ {10pt plus 5pt minus 3pt}
+\AtBeginDocument{\preparefootins}
+%</package>
+% \end{macrocode}
+% Of course, this value can be changed by the user as
+% described in the introduction.
+%
+% \Finale
+%
+%
+%
+
+\endinput
diff --git a/Master/texmf-dist/source/latex/tools/hhline.dtx b/Master/texmf-dist/source/latex/tools/hhline.dtx
new file mode 100644
index 00000000000..f539e1669a9
--- /dev/null
+++ b/Master/texmf-dist/source/latex/tools/hhline.dtx
@@ -0,0 +1,321 @@
+% \iffalse meta-comment
+%
+% Copyright 1993 1994 1995 1996 1997 1998 1999 2000 2001 2002 2003
+% The LaTeX3 Project and any individual authors listed elsewhere
+% in this file.
+%
+% This file is part of the Standard LaTeX `Tools Bundle'.
+% -------------------------------------------------------
+%
+% It 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.3 or later is part of all distributions of LaTeX
+% version 2003/12/01 or later.
+%
+% The list of all files belonging to the LaTeX `Tools Bundle' is
+% given in the file `manifest.txt'.
+%
+% \fi
+% \iffalse
+%% File: hhline.dtx Copyright (C) 1991-1994 David Carlisle
+%
+%<package>\NeedsTeXFormat{LaTeX2e}
+%<package>\ProvidesPackage{hhline}
+%<package> [1994/05/23 v2.03 Table rule package (DPC)]
+%
+%<*driver>
+\documentclass{ltxdoc}
+\usepackage{hhline}
+\GetFileInfo{hhline.sty}
+\begin{document}
+\title{The \textsf{hhline} package\thanks{This file
+ has version number \fileversion, last
+ revised \filedate.}}
+\author{David Carlisle\\carlisle@cs.man.ac.uk}
+\date{\filedate}
+ \maketitle
+ \DeleteShortVerb{\|}
+ \DocInput{hhline.dtx}
+\end{document}
+%</driver>
+% \fi
+%
+%
+% \changes{v1.00}{1991/06/04}{Initial Version}
+% \changes{v2.00}{1991/11/06}
+% {Add tilde which allows \cmd\cline-like constructions.}
+% \changes{v2.01}{1992/06/26}
+% {Re-issue for the new doc and docstrip.}
+% \changes{v2.02}{1994/03/14}
+% {Update for LaTeX2e.}
+% \changes{v2.03}{1994/05/23}
+% {New style warning.}
+%
+%
+% \CheckSum{244}
+%
+% \MakeShortVerb{\"}
+%
+% \begin{abstract}
+% "\hhline" produces a line like "\hline", or a double line like
+% "\hline\hline", except for its interaction with vertical lines.
+% \end{abstract}
+%
+% \arrayrulewidth=1pt
+% \doublerulesep=3pt
+%
+% \section{Introduction}
+% The argument to "\hhline" is similar to the preamble of an {\tt
+% array} or {\tt tabular}. It consists of a list of tokens with the
+% following meanings:
+% \[
+% \begin{tabular}{cl}
+% "=" & A double hline the width of a column.\\
+% "-" & A single hline the width of a column.\\[10pt]
+% "~" & A column with no hline.\\[10pt]
+%
+% "|" & A vline which `cuts' through a double (or single) hline.\\
+% ":" & A vline which is broken by a double hline.\\[10pt]
+%
+% "#" & A double hline segment between two vlines.\\
+% "t" & The top half of a double hline segment.\\
+% "b" & The bottom half of a double hline segment.\\
+%
+% "*" & "*{3}{==#}" expands to "==#==#==#",
+% as in the {\tt*}-form for the preamble.
+% \end{tabular}
+% \]
+% If a double vline is specified ("||" or "::") then the hlines
+% produced by "\hhline" are broken. To obtain the effect of an hline
+% `cutting through'the double vline, use a "#" or omit the vline
+% specifiers, depending on whether or not you wish the double vline to
+% break.
+%
+% The tokens {\tt t} and {\tt b} must be used between two vertical
+% rules. "|tb|" produces the same lines as "#", but is much less
+% efficient. The main use for these are to make constructions like
+% "|t:" (top left corner) and ":b|" (bottom right corner).
+%
+% If "\hhline" is used to make a single hline, then the argument
+% should only contain the tokens "-", "~" and "|" (and
+% {\tt*}-expressions).
+%
+% An example using most of these features is:
+% \[
+% \vcenter{\hsize=2in\begin{verbatim}
+% \begin{tabular}{||cc||c|c||}
+% \hhline{|t:==:t:==:t|}
+% a&b&c&d\\
+% \hhline{|:==:|~|~||}
+% 1&2&3&4\\
+% \hhline{#==#~|=#}
+% i&j&k&l\\
+% \hhline{||--||--||}
+% w&x&y&z\\
+% \hhline{|b:==:b:==:b|}
+% \end{tabular}
+% \end{verbatim}
+% }
+% \qquad
+% \begin{tabular}{||cc||c|c||}
+% \hhline{|t:==:t:==:t|}
+% a&b&c&d\\
+% \hhline{|:==:|~|~||}
+% 1&2&3&4\\
+% \hhline{#==#~|=#}
+% i&j&k&l\\
+% \hhline{||--||--||}
+% w&x&y&z\\
+% \hhline{|b:==:b:==:b|}
+% \end{tabular}
+% \]
+%
+% The lines produced by \LaTeX's "\hline" consist of a single (\TeX\
+% primitive) "\hrule". The lines produced by "\hhline" are made
+% up of lots of small line segments. \TeX\ will place these very
+% accurately in the {\tt .dvi} file, but the program that you use to
+% print the {\tt .dvi} file may not line up these segments exactly. (A
+% similar problem can occur with diagonal lines in the {\tt picture}
+% environment.)
+%
+% If this effect causes a problem, you could try a different driver
+% program, or if this is not possible, increasing "\arrayrulewidth"
+% may help to reduce the effect.
+%
+% \StopEventually{}
+%
+% \section{The Macros}
+%
+% \begin{macrocode}
+%<*package>
+% \end{macrocode}
+%
+% \begin{macro}{\HH@box}
+% Makes a box containing a double hline segment. The most common case,
+% both rules of length "\doublerulesep" will be stored in "\box1", this
+% is not initialised until "\hhline" is called as the user may change
+% the parameters "\doublerulesep" and "\arrayrulewidth". The two
+% arguments to "\HH@box" are the widths (ie lengths) of the top and
+% bottom rules.
+% \begin{macrocode}
+\def\HH@box#1#2{\vbox{%
+ \hrule \@height \arrayrulewidth \@width #1
+ \vskip \doublerulesep
+ \hrule \@height \arrayrulewidth \@width #2}}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\HH@add}
+% Build up the preamble in the register "\toks@".
+% \begin{macrocode}
+\def\HH@add#1{\toks@\expandafter{\the\toks@#1}}
+% \end{macrocode}
+% \end{macro}
+
+% \begin{macro}{\HH@xexpast}
+% \begin{macro}{\HH@xexnoop}
+% We `borrow' the version of "\@xexpast" from Mittelbach's array.sty,
+% as this allows "#" to appear in the argument list.
+% \begin{macrocode}
+\def\HH@xexpast#1*#2#3#4\@@{%
+ \@tempcnta #2
+ \toks@={#1}\@temptokena={#3}%
+ \let\the@toksz\relax \let\the@toks\relax
+ \def\@tempa{\the@toksz}%
+ \ifnum\@tempcnta >0 \@whilenum\@tempcnta >0\do
+ {\edef\@tempa{\@tempa\the@toks}\advance \@tempcnta \m@ne}%
+ \let \@tempb \HH@xexpast \else
+ \let \@tempb \HH@xexnoop \fi
+ \def\the@toksz{\the\toks@}\def\the@toks{\the\@temptokena}%
+ \edef\@tempa{\@tempa}%
+ \expandafter \@tempb \@tempa #4\@@}
+
+\def\HH@xexnoop#1\@@{}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\hhline}
+% Use a simplified version of "\@mkpream" to break apart the argument
+% to "\hhline". Actually it is oversimplified, It assumes that the
+% vertical rules are at the end of the column. If you were to specify
+% "c|@{xx}|" in the array argument, then "\hhline" would not be
+% able to access the first vertical rule. (It ought to have an "@"
+% option, and add "\leaders" up to the width of a box containing the
+% "@"-expression. We use a loop made with "\futurelet" rather
+% than "\@tfor" so that we can use "#" to denote the crossing of
+% a double hline with a double vline.\\
+% "\if@firstamp" is true in the first column and false otherwise.\\
+% "\if@tempswa" is true if the previous entry was a vline
+% (":", "|" or "#").
+% \begin{macrocode}
+\def\hhline#1{\omit\@firstamptrue\@tempswafalse
+% \end{macrocode}
+% Put two rules of width "\doublerulesep" in "\box1"
+% \begin{macrocode}
+\global\setbox\@ne\HH@box\doublerulesep\doublerulesep
+% \end{macrocode}
+% If Mittelbach's {\tt array.sty} is loaded, we do not need the negative
+% "\hskip"'s around vertical rules.
+% \begin{macrocode}
+ \xdef\@tempc{\ifx\extrarowheight\HH@undef\hskip-.5\arrayrulewidth\fi}%
+% \end{macrocode}
+% Now expand the {\tt*}-forms and add dummy tokens ( "\relax" and
+% "`" ) to either end of the token list. Call "\HH@let" to start
+% processing the token list.
+% \begin{macrocode}
+ \HH@xexpast\relax#1*0x\@@\toks@{}\expandafter\HH@let\@tempa`}
+% \end{macrocode}
+% \end{macro}
+
+% \begin{macro}{\HH@let}
+% Discard the last token, look at the next one.
+% \begin{macrocode}
+\def\HH@let#1{\futurelet\@tempb\HH@loop}
+% \end{macrocode}
+% \end{macro}
+
+% \begin{macro}{\HH@loop}
+% The main loop. Note we use "\ifx" rather than "\if" in
+% version~2 as the new token "~" is active.
+% \begin{macrocode}
+\def\HH@loop{%
+% \end{macrocode}
+% If next token is "`", stop the loop and put the lines into this row
+% of the alignment.
+% \begin{macrocode}
+ \ifx\@tempb`\def\next##1{\the\toks@\cr}\else\let\next\HH@let
+% \end{macrocode}
+% "|", add a vertical rule (across either a double or
+% single hline).
+% \begin{macrocode}
+ \ifx\@tempb|\if@tempswa\HH@add{\hskip\doublerulesep}\fi\@tempswatrue
+ \HH@add{\@tempc\vline\@tempc}\else
+% \end{macrocode}
+% ":", add a broken vertical rule (across a double hline).
+% \begin{macrocode}
+ \ifx\@tempb:\if@tempswa\HH@add{\hskip\doublerulesep}\fi\@tempswatrue
+ \HH@add{\@tempc\HH@box\arrayrulewidth\arrayrulewidth\@tempc}\else
+% \end{macrocode}
+% "#", add a double hline segment between two vlines.
+% \begin{macrocode}
+ \ifx\@tempb##\if@tempswa\HH@add{\hskip\doublerulesep}\fi\@tempswatrue
+ \HH@add{\@tempc\vline\@tempc\copy\@ne\@tempc\vline\@tempc}\else
+% \end{macrocode}
+% "~", A column with no hline (this gives an effect similar to
+% \verb+\cline+).
+% \begin{macrocode}
+ \ifx\@tempb~\@tempswafalse
+ \if@firstamp\@firstampfalse\else\HH@add{&\omit}\fi
+ \HH@add{\hfil}\else
+% \end{macrocode}
+% "-", add a single hline across the column.
+% \begin{macrocode}
+ \ifx\@tempb-\@tempswafalse
+ \if@firstamp\@firstampfalse\else\HH@add{&\omit}\fi
+ \HH@add{\leaders\hrule\@height\arrayrulewidth\hfil}\else
+% \end{macrocode}
+% "=", add a double hline across the column.
+% \begin{macrocode}
+ \ifx\@tempb=\@tempswafalse
+ \if@firstamp\@firstampfalse\else\HH@add{&\omit}\fi
+% \end{macrocode}
+% Put in as many copies of "\box1" as possible with
+% "\leaders", this may leave gaps at the ends, so put an extra box
+% at each end, overlapping the "\leaders".
+% \begin{macrocode}
+ \HH@add
+ {\rlap{\copy\@ne}\leaders\copy\@ne\hfil\llap{\copy\@ne}}\else
+% \end{macrocode}
+% "t", add the top half of a double hline segment, in a "\rlap"
+% so that it may be used with {\tt b}.
+% \begin{macrocode}
+ \ifx\@tempb t\HH@add{\rlap{\HH@box\doublerulesep\z@}}\else
+% \end{macrocode}
+% "b", add the bottom half of a double hline segment in a "\rlap"
+% so that it may be used with {\tt t}.
+% \begin{macrocode}
+ \ifx\@tempb b\HH@add{\rlap{\HH@box\z@\doublerulesep}}\else
+% \end{macrocode}
+% Otherwise ignore the token, with a warning.
+% \begin{macrocode}
+ \PackageWarning{hhline}%
+ {\meaning\@tempb\space ignored in \noexpand\hhline argument%
+ \MessageBreak}%
+ \fi\fi\fi\fi\fi\fi\fi\fi\fi
+% \end{macrocode}
+% Go around the loop again.
+% \begin{macrocode}
+ \next}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macrocode}
+%</package>
+% \end{macrocode}
+%
+% \Finale
+\endinput
diff --git a/Master/texmf-dist/source/latex/tools/indentfirst.dtx b/Master/texmf-dist/source/latex/tools/indentfirst.dtx
new file mode 100644
index 00000000000..765517a1a8a
--- /dev/null
+++ b/Master/texmf-dist/source/latex/tools/indentfirst.dtx
@@ -0,0 +1,75 @@
+% \iffalse meta-comment
+%
+% Copyright 1993 1994 1995 1996 1997 1998 1999 2000 2001 2002 2003
+% The LaTeX3 Project and any individual authors listed elsewhere
+% in this file.
+%
+% This file is part of the Standard LaTeX `Tools Bundle'.
+% -------------------------------------------------------
+%
+% It 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.3 or later is part of all distributions of LaTeX
+% version 2003/12/01 or later.
+%
+% The list of all files belonging to the LaTeX `Tools Bundle' is
+% given in the file `manifest.txt'.
+%
+% \fi
+% \iffalse
+%% File: indent.dtx Copyright (C) 1991-1994 David Carlisle
+%
+%<package>\NeedsTeXFormat{LaTeX2e}
+%<package>\ProvidesPackage{indentfirst}
+%<package> [1995/11/23 v1.03 Indent first paragraph (DPC)]
+%
+%<*driver>
+\documentclass{ltxdoc}
+\usepackage{indentfirst}
+\GetFileInfo{indentfirst.sty}
+\begin{document}
+\title{The \textsf{indentfirst} package\thanks{This file
+ has version number \fileversion, last
+ revised \filedate.}}
+\author{David Carlisle\\carlisle@cs.man.ac.uk}
+\date{\filedate}
+\maketitle
+\DocInput{indentfirst.dtx}
+\end{document}
+%</driver>
+% \fi
+%
+% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%
+% \changes{v1.00}{1991/01/02}{Initial version}
+% \changes{v1.01}{1992/06/26}{Re-issue for the new doc and docstrip}
+% \changes{v1.02}{1994/01/31}{Re-issue for LaTeX2e}
+% \changes{v1.03}{1995/11/23}{Typo fixes in documentation}
+%
+% \begin{abstract}
+% Make the first line of all sections etc., be indented by the usual
+% paragraph indentation. This should work with all the standard document
+% classes.
+% \end{abstract}
+%
+% \CheckSum{4}^^A Still I think a record:-)
+%
+% \StopEventually{}
+%
+% \begin{macro}{\if@afterindent}
+% \LaTeX\ uses the switch |\if@afterindent| to decide whether to indent
+% after a section heading. We just need to make sure that this is always
+% true.
+% \begin{macrocode}
+%<*package>
+\let\@afterindentfalse\@afterindenttrue
+\@afterindenttrue
+%</package>
+% \end{macrocode}
+% \end{macro}
+%
+% \Finale
+%
diff --git a/Master/texmf-dist/source/latex/tools/layout.dtx b/Master/texmf-dist/source/latex/tools/layout.dtx
new file mode 100644
index 00000000000..dc404c3f306
--- /dev/null
+++ b/Master/texmf-dist/source/latex/tools/layout.dtx
@@ -0,0 +1,1024 @@
+% \iffalse meta-comment
+%
+% Copyright 1993 1994 1995 1996 1997 1998 1999 2000 2001 2002 2003
+% The LaTeX3 Project and any individual authors listed elsewhere
+% in this file.
+%
+% This file is part of the Standard LaTeX `Tools Bundle'.
+% -------------------------------------------------------
+%
+% It 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.3 or later is part of all distributions of LaTeX
+% version 2003/12/01 or later.
+%
+% The list of all files belonging to the LaTeX `Tools Bundle' is
+% given in the file `manifest.txt'.
+%
+% \fi
+% \CheckSum{920}
+%\iffalse
+% This file is built for \LaTeXe, so we make sure an error is
+% generated when it is used with another format
+%<*dtx>
+\ProvidesFile{layout.dtx}
+%</dtx>
+%<+package>\NeedsTeXFormat{LaTeX2e}
+%<+package>\ProvidesPackage{layout}
+%<+driver>\ProvidesFile{layout.drv}
+%\ProvidesFile{layout.dtx}
+ [2000/09/25 v1.2c Show layout parameters]
+%
+% A short driver is provided that can be extracted if necessary by
+% the \textsf{DocStrip} program provided with \LaTeXe.
+% \begin{macrocode}
+%<*driver>
+\documentclass{ltxdoc}
+
+\usepackage{layout}
+
+\newcommand\Lopt[1]{\textsf{#1}}
+\pagestyle{myheadings}
+\DisableCrossrefs
+\begin{document}
+\DocInput{layout.dtx}
+\end{document}
+%</driver>
+% \end{macrocode}
+%\fi
+% \changes{v1.1c}{1994/07/13}{Moved Identification code to the front
+% and removed the permanent use of \cs{filedate} and friends}
+% \changes{v1.1d}{1994/09/08}{Stored texts in control sequences to
+% allow other languages}
+%
+% \GetFileInfo{layout.dtx}
+% \title{Displaying page layout variables}
+% \author{Kent McPherson a.o.\thanks{Converted for \LaTeXe\ by
+% Johannes Braams and modified by Hideo Umeki}}
+% \date{\filedate}
+%
+% \markboth{layout package version \fileversion\space as of \filedate}
+% {layout package version \fileversion\space as of \filedate}
+%
+% \maketitle
+%
+% \section{Introduction}
+%
+% This \LaTeXe\ package is a reimplementation of
+% \texttt{layout.sty} by Kent McPherson. It defines the command
+% |\layout| which produces an overview of the layout of the current
+% document. The command |\layout*| recomputes the values it uses to
+% produce the overview.
+%
+% The figure on the next page shows the output of the |\layout|
+% command for this document.
+%
+% \begin{figure}[p]
+% \layout
+% \end{figure}
+%
+% \StopEventually{}
+%
+% \section{The implementation}
+%
+% \changes{v1.1b}{1994/03/23}{removed the \cs{wlog} as
+% \cs{ProvidesPackage} does that now}
+% \changes{v1.1d}{1994/09/08}{Added language options dutch and
+% english}
+%
+% This package prints a figure to illustrate the layout that is
+% implemented by the document class. In the figure several words
+% appear. They are stored in control sequences to be able to select
+% a different language.
+% \changes{v1.1e}{1994/10/29}{The dutch texts should be one word.}
+% \changes{v1.1f}{1995/03/14}{Added \cs{notshown}}
+% \changes{v1.1f}{1995/03/14}{Added option french}
+% \changes{v1.1j}{1995/10/29}{Added the options spanish, brazilian and
+% portuguese}
+% \changes{v1.1k}{1995/11/23}{Documentation fixes}
+% \changes{v1.2}{1998/04/13}{Redesign of the output by Hideo Umeki}
+% \changes{v1.2c}{2000/09/21}{Added option german}
+% \changes{v1.2c}{2000/09/25}{Added option for italian by Claudio Beccari}
+% \begin{macrocode}
+%<*package>
+\DeclareOption{dutch}{%
+ \def\Headertext{Kopregel}
+ \def\Bodytext{Broodtekst}
+ \def\Footertext{Voetregel}
+ \def\MarginNotestext{Marge\\Notities}
+ \def\oneinchtext{een inch}
+ \def\notshown{niet getoond}
+ }
+\DeclareOption{german}{%
+ \def\Headertext{Kopfzeile}
+ \def\Bodytext{Haupttext}
+ \def\Footertext{Fu{\ss}zeile}
+ \def\MarginNotestext{Rand-\\ notizen}
+ \def\oneinchtext{ein Zoll}
+ \def\notshown{ohne Abbildung}
+ }
+\DeclareOption{ngerman}{\ExecuteOptions{german}}
+\DeclareOption{english}{%
+ \def\Headertext{Header}
+ \def\Bodytext{Body}
+ \def\Footertext{Footer}
+ \def\MarginNotestext{Margin\\Notes}
+ \def\oneinchtext{one inch}
+ \def\notshown{not shown}
+ }
+\DeclareOption{french}{%
+ \def\Headertext{Ent\^{e}te}
+ \def\Bodytext{Corps}
+ \def\Footertext{Pied de page}
+ \def\MarginNotestext{Marge\\Notes}
+ \def\oneinchtext{un pouce}
+ \def\notshown{non affich\'{e}}
+ }
+\DeclareOption{francais}{\ExecuteOptions{french}}
+\DeclareOption{spanish}{%
+ \def\Headertext{Encabezamiento}
+ \def\Bodytext{Cuerpo}
+ \def\Footertext{Pie de p\'agina}
+ \def\MarginNotestext{Notas\\ Marginales}
+ \def\oneinchtext{una pulgada}
+ \def\notshown{no mostradas}
+ }
+\DeclareOption{portuguese}{%
+ \def\Headertext{Cabe\c{c}alho}
+ \def\Bodytext{Corpo}
+ \def\Footertext{Rodap\'e}
+ \def\MarginNotestext{Notas\\ Marginais}
+ \def\oneinchtext{uma polegada}
+ \def\notshown{n\~ao mostradas}
+ }
+\DeclareOption{brazilian}{%
+ \def\Headertext{Cabe\c{c}alho}
+ \def\Bodytext{Corpo}
+ \def\Footertext{Rodap\'e}
+ \def\MarginNotestext{Notas\\ Marginais}
+ \def\oneinchtext{uma polegada}
+ \def\notshown{n\~ao mostradas}
+ }
+\DeclareOption{italian}{%
+ \def\Headertext{Testatina}
+ \def\Bodytext{Corpo}
+ \def\Footertext{Piedino}
+ \def\MarginNotestext{Note\\ Marginali}
+ \def\oneinchtext{un pollice}
+ \def\notshown{non mostrato}
+ }
+% \end{macrocode}
+%
+% This package has an option \Lopt{verbose}. Using it will make the
+% command |\layout| type some of the parameters on the terminal.
+% \begin{macrocode}
+\DeclareOption{verbose}{\let\LayOuttype\typeout}
+\DeclareOption{silent}{\let\LayOuttype\@gobble}
+% \end{macrocode}
+%
+% \changes{v1.1h}{1995/04/07}{Added the options \Lopt{integers}
+% (default) and \Lopt{reals}}
+%
+% The normal behaviour of this package when showing the values of
+% the parameters is to truncate them. However, if you want to see
+% the real parameter values you can use the option \Lopt{reals} to
+% get that effect.
+% \changes{v1.1i}{1995/06/25}{\LaTeX\ release 1995/06/01 no longer
+% needs double hashmarks in the argument of \cs{DeclareOption}}
+% \begin{macrocode}
+\def\lay@value{}
+\DeclareOption{integers}{%
+ \renewcommand*{\lay@value}[2]{%
+ \expandafter\number\csname #1@#2\endcsname pt}}
+\DeclareOption{reals}{%
+ \renewcommand*{\lay@value}[2]{\the\csname #2\endcsname}}
+% \end{macrocode}
+%
+% The default language is English, the default mode is
+% \Lopt{silent} and the default way of showing parameter values is
+% to use integers.
+% \begin{macrocode}
+\ExecuteOptions{english,silent,integers}
+\ProcessOptions
+% \end{macrocode}
+%
+% \begin{macro}{\LayOutbs}
+% Define |\LayOutbs| to produce a backslash. We use a definition
+% which also works with OT1 fonts.
+% \changes{v1.2b}{1998/06/21}{Renamed \cs{bs} to avoid possible conflicts
+% with other packages}
+% \begin{macrocode}
+\newcommand\LayOutbs{}
+\chardef\LayOutbs`\\
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\ConvertToCount}
+% This macro stores the value of a \emph{length} register in a
+% \emph{count} register.
+% \begin{macrocode}
+\def\ConvertToCount#1#2{%
+% \end{macrocode}
+% First copy the value
+% \begin{macrocode}
+ #1=#2
+% \end{macrocode}
+% Then divide it by 65536.
+% \begin{macrocode}
+ \divide #1 by 65536}
+% \end{macrocode}
+% The result of this is that the \emph{count} register holds the
+% value of the \emph{length} register in points.
+% \end{macro}
+%
+% \begin{macro}{\SetToHalf}
+% \begin{macro}{\SetToQuart}
+% Small macros used in computing positions.
+% \begin{macrocode}
+\def\SetToHalf#1#2{#1=#2\relax\divide#1by\tw@}
+\def\SetToQuart#1#2{#1=#2\relax\divide#1by4}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\Identify}
+% A small macro used in identifying dimensions.
+% \begin{macrocode}
+\def\Identify#1{%
+ \put(\PositionX,\PositionY){\circle{20}}
+ \put(\PositionX,\PositionY){\makebox(0,0){\tiny #1}}
+}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\InsideHArrow}
+% This macro is used to produce two horizontal arrows inside a box.
+% The argument gives the width of the box.
+% \changes{v1.1c}{1994/07/14}{Added check for a negative arrow length}
+% \begin{macrocode}
+\def\InsideHArrow#1{{%
+ \ArrowLength = #1
+ \divide\ArrowLength by \tw@
+ \advance\ArrowLength by -10
+ \advance\PositionX by -10
+ \ifnum\ArrowLength<\z@
+ \put(\PositionX,\PositionY){\vector(1,0){-\ArrowLength}}
+ \advance\PositionX by 20
+ \put(\PositionX,\PositionY){\vector(-1,0){-\ArrowLength}}
+ \else
+ \put(\PositionX,\PositionY){\vector(-1,0){\ArrowLength}}
+ \advance\PositionX by 20
+ \put(\PositionX,\PositionY){\vector(+1,0){\ArrowLength}}
+ \fi
+}}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\InsideVArrow}
+% This macro is used to produce two vertical arrows inside a box.
+% The argument gives the height of the box.
+% \begin{macrocode}
+\def\InsideVArrow#1{{%
+ \ArrowLength = #1
+ \divide\ArrowLength by \tw@
+ \advance\ArrowLength by -10
+ \advance\PositionY by -10
+ \put(\PositionX,\PositionY){\vector(0,-1){\ArrowLength}}
+ \advance\PositionY by 20
+ \put(\PositionX,\PositionY){\vector(0,+1){\ArrowLength}}
+}}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\OutsideHArrow}
+% This macro is used to produce two horizontal arrows to delimit a
+% length. The first argument is the position for the right arrow,
+% the second argument gives the length and the third specifies the
+% length of the arrows.
+% \begin{macrocode}
+\def\OutsideHArrow#1#2#3{{%
+ \PositionX = #1
+ \advance\PositionX by #3
+ \put(\PositionX,\PositionY){\vector(-1,0){#3}}
+ \PositionX = #1 \advance\PositionX-#2
+ \advance\PositionX by -#3
+ \put(\PositionX,\PositionY){\vector(+1,0){#3}}
+}}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\OutsideVArrow}
+% This macro is used to produce two vertical arrows to delimit a
+% length. The first argument is the position for the lower arrow,
+% the second argument gives the length and the third and fourth
+% specify the lenghts of the lower and upper arrow.
+% \begin{macrocode}
+\def\OutsideVArrow#1#2#3#4{{%
+ \PositionY = #1
+ \advance\PositionY by -#3
+ \put(\PositionX,\PositionY){\vector(0,+1){#3}}
+ \PositionY = #1
+ \advance\PositionY#2
+ \advance\PositionY#4
+ \put(\PositionX,\PositionY){\vector(0,-1){#4}}
+}}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\Show}
+% \changes{v1.1g}{1995/04/03}{Simplified the definition, now show
+% complete value}
+% \changes{v1.1h}{1995/04/07}{Use \cs{lay@value} to show the value
+% because of the option which decides which of two ways of doing it
+% should be used}
+%
+% Macro used in the table that shows the setting of the parameters.
+% \begin{macrocode}
+\def\Show#1#2{\LayOutbs #2 = \lay@value{#1}{#2}}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\Type}
+% \changes{v1.1g}{1995/04/03}{Simplified the definition, now show
+% complete value}
+% \changes{v1.1h}{1995/04/07}{Use \cs{lay@value} to show the value
+% because of the option which decides which of two ways of doing it
+% should be used}
+% \changes{v1.2b}{1998/06/21}{Renamed \cs{type} to \cs{LayOuttype}
+% to avoid possible conflicts with other packages}
+%
+% Macro used to show a setting of a parameter on the terminal.
+% \begin{macrocode}
+\def\Type#1#2{%
+ \LayOuttype{#2 = \lay@value{#1}{#2}}}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\oneinch}
+% A constant, giving the length of an inch in points (approximately)
+% \begin{macrocode}
+\newcount\oneinch
+\oneinch=72
+% \end{macrocode}
+% \end{macro}
+%
+% Because the overview of the layout is produced in a figure
+% environment we need to allocate a number of counters that are
+% used to store the values of various dimensions.
+%
+% \begin{macro}{\cnt@paperwidth}
+% \begin{macro}{\cnt@paperheight}
+% The dimensions of the paper
+% \begin{macrocode}
+\newcount\cnt@paperwidth
+\newcount\cnt@paperheight
+\ConvertToCount\cnt@paperwidth\paperwidth
+\ConvertToCount\cnt@paperheight\paperheight
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\cnt@hoffset}
+% \begin{macro}{\cnt@voffset}
+% the offsets,
+% \begin{macrocode}
+\newcount\cnt@hoffset
+\newcount\cnt@voffset
+\ConvertToCount\cnt@hoffset\hoffset
+\ConvertToCount\cnt@voffset\voffset
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\cnt@textheight}
+% \begin{macro}{\cnt@textwidth}
+% dimensions of the text area,
+% \begin{macrocode}
+\newcount\cnt@textheight
+\newcount\cnt@textwidth
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\cnt@topmargin}
+% \begin{macro}{\cnt@oddsidemargin}
+% \begin{macro}{\cnt@evensidemargin}
+% margins,
+% \begin{macrocode}
+\newcount\cnt@topmargin
+\newcount\cnt@oddsidemargin
+\newcount\cnt@evensidemargin
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\cnt@headheight}
+% \begin{macro}{\cnt@headsep}
+% dimensions of the running heads,
+% \begin{macrocode}
+\newcount\cnt@headheight
+\newcount\cnt@headsep
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\cnt@marginparsep}
+% \begin{macro}{\cnt@marginparwidth}
+% \begin{macro}{\cnt@marginparpush}
+% marginal paragraphs,
+% \begin{macrocode}
+\newcount\cnt@marginparsep
+\newcount\cnt@marginparwidth
+\newcount\cnt@marginparpush
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\cnt@footskip}
+% the distance between the running footers and the text,
+% \begin{macrocode}
+\newcount\cnt@footskip
+% \end{macrocode}
+% \end{macro}
+% and the height of the footers, which is needed here to display a
+% box, but which isn't used by \LaTeX.
+% \begin{macro}{\fheight}
+% \begin{macrocode}
+\newcount\fheight
+\fheight=12
+% \end{macrocode}
+% \end{macro}
+%
+% Apart from integer representations of the page layout parameters
+% we also need registers to store reference values in.
+%
+% \begin{macro}{\ref@top}
+% The position of the top of the `printable area' is
+% one inch below the top of the paper by default. The value of
+% |\ref@top| is relative to the lower left corner of the picture
+% environment that will be used.
+%
+% \begin{macrocode}
+\newcount\ref@top
+\ref@top=\cnt@paperheight \advance\ref@top by -\oneinch
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\ref@hoffset}
+% \begin{macro}{\ref@voffset}
+% For the offsets,
+% \begin{macrocode}
+\newcount\ref@hoffset
+\newcount\ref@voffset
+% \end{macrocode}
+% The |\hoffset| and |\voffset| values are added to the default
+% offset of one inch.
+% \begin{macrocode}
+\ref@hoffset=\cnt@hoffset \advance\cnt@hoffset by \oneinch
+\ref@voffset=\cnt@voffset
+% \end{macrocode}
+%
+% |\cnt@voffset| is converted to be relative to the origin of the
+% picture.
+% \begin{macrocode}
+\cnt@voffset=\ref@top
+\advance\cnt@voffset by -\ref@voffset
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\ref@head}
+% and the text areas, running heads,
+% \begin{macrocode}
+\newcount\ref@head
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\ref@body}
+% body of the text
+% \begin{macrocode}
+\newcount\ref@body
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\ref@foot}
+% and running footers.
+% \begin{macrocode}
+\newcount\ref@foot
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\ref@margin}
+% \begin{macro}{\ref@marginwidth}
+% \begin{macro}{\ref@marginpar}
+% These are different for even and odd pages, so they are computed
+% by |\layout|.
+% \begin{macrocode}
+\newcount\ref@margin
+\newcount\ref@marginwidth
+\newcount\ref@marginpar
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+% The following are a number of scratch registers, used in the
+% positioning of the various pices of the picture.
+% \begin{macrocode}
+\newcount\Interval
+\newcount\ExtraYPos
+\newcount\PositionX
+\newcount\PositionY
+\newcount\ArrowLength
+% \end{macrocode}
+%
+% \begin{macro}{\lay@getvalues}
+% \changes{v1.1j}{1995/10/30}{Added macro to compute values at later
+% time}
+% All values that might change during the document are computed by
+% calling the macro |\lay@getvalues|. By default this macro is
+% executed at |\begin{document}|.
+% \begin{macrocode}
+\def\lay@getvalues{%
+ \ConvertToCount\cnt@textheight\textheight
+ \ConvertToCount\cnt@textwidth\textwidth
+ \ConvertToCount\cnt@topmargin\topmargin
+ \ConvertToCount\cnt@oddsidemargin\oddsidemargin
+ \ConvertToCount\cnt@evensidemargin\evensidemargin
+ \ConvertToCount\cnt@headheight\headheight
+ \ConvertToCount\cnt@headsep\headsep
+ \ConvertToCount\cnt@marginparsep\marginparsep
+ \ConvertToCount\cnt@marginparwidth\marginparwidth
+ \ConvertToCount\cnt@marginparpush\marginparpush
+ \ConvertToCount\cnt@footskip\footskip
+ \ref@head=\ref@top
+ \advance\ref@head by -\ref@voffset
+ \advance\ref@head by -\cnt@topmargin
+ \advance\ref@head by -\cnt@headheight
+ \ref@body=\ref@head
+ \advance\ref@body by -\cnt@headsep
+ \advance\ref@body by -\cnt@textheight
+ \ref@foot=\ref@body
+ \advance\ref@foot by -\cnt@footskip
+ }
+\AtBeginDocument{\lay@getvalues}
+% \end{macrocode}
+% \end{macro}
+% \begin{macro}{\computevalues}
+%
+% \begin{macro}{\layout}
+% \begin{macro}{\layout*}
+% The command |\layout| makes the picture and table that display
+% the current settings of the layout parameters.
+%
+% \changes{v1.1b}{1994/03/23}{Produce two pages in twoside mode}
+% \changes{v1.1j}{1995/10/30}{Added \cs{layout*}}
+% \begin{macrocode}
+\newcommand\layout{%
+ \@ifstar{\lay@getvalues\lay@xlayout}{\lay@xlayout}}
+\def\lay@xlayout{%
+ \lay@layout
+ \if@twoside
+ \lay@layout
+ \fi}
+% \end{macrocode}
+%
+% \begin{macro}{\lay@layout}
+% The internal macro |\lay@layout| does all the dirty work.
+% \begin{macrocode}
+\newcommand\lay@layout{%
+ \thispagestyle{empty}
+% \end{macrocode}
+%
+% The actions of |\layout| depend on the pagestyle.
+% \begin{macrocode}
+ \if@twoside
+ \ifodd\count\z@
+% \end{macrocode}
+%
+% Here we deal with an odd page in the twosided case.
+%
+% \begin{macrocode}
+ \typeout{Two-sided document style, odd page.}
+% \end{macrocode}
+%
+% So we compute |\ref@marginwidth|, |\ref@marginpar| and
+% |\ref@margin|.
+% \changes{v1.1}{1994/02/23}{Added check for reversemargin}
+% \begin{macrocode}
+ \ref@marginwidth=\cnt@oddsidemargin
+ \ref@marginpar=\oneinch
+ \advance\ref@marginpar by \ref@hoffset
+ \advance\ref@marginpar by \cnt@oddsidemargin
+ \ref@margin\ref@marginpar
+ \if@reversemargin
+ \advance\ref@marginpar by -\cnt@marginparsep
+ \advance\ref@marginpar by -\cnt@marginparwidth
+ \else
+ \advance\ref@marginpar by \cnt@textwidth
+ \advance\ref@marginpar by \cnt@marginparsep
+ \fi
+% \end{macrocode}
+%
+% \begin{macrocode}
+ \else
+% \end{macrocode}
+%
+% Here we deal with an even page in the twosided case.
+%
+% \begin{macrocode}
+ \typeout{Two-sided document style, even page.}
+% \end{macrocode}
+%
+% So we compute |\ref@marginwidth|, |\ref@marginpar| and
+% |\ref@margin|.
+% \changes{v1.1}{1994/02/23}{Added check for reversemargin}
+% \begin{macrocode}
+ \ref@marginwidth=\cnt@evensidemargin
+ \ref@marginpar=\oneinch
+ \advance\ref@marginpar by \ref@hoffset
+ \advance\ref@marginpar by \cnt@evensidemargin
+ \ref@margin\ref@marginpar
+ \if@reversemargin
+ \advance\ref@marginpar by \cnt@textwidth
+ \advance\ref@marginpar by \cnt@marginparsep
+ \else
+ \advance\ref@marginpar by -\cnt@marginparsep
+ \advance\ref@marginpar by -\cnt@marginparwidth
+ \fi
+% \end{macrocode}
+%
+% \begin{macrocode}
+ \fi
+ \else
+% \end{macrocode}
+%
+% Finally we the case for single sided printing.
+%
+% \changes{v1.1}{1994/02/23}{Added check for reversemargin}
+% \begin{macrocode}
+ \typeout{One-sided document style.}
+ \ref@marginwidth=\cnt@oddsidemargin
+ \ref@marginpar=\oneinch
+ \advance\ref@marginpar by \ref@hoffset
+ \advance\ref@marginpar by \cnt@oddsidemargin
+ \ref@margin\ref@marginpar
+ \if@reversemargin
+ \advance\ref@marginpar by -\cnt@marginparsep
+ \advance\ref@marginpar by -\cnt@marginparwidth
+ \else
+ \advance\ref@marginpar by \cnt@textwidth
+ \advance\ref@marginpar by \cnt@marginparsep
+ \fi
+ \fi
+% \end{macrocode}
+%
+%
+% Now we begin the picture environment; dividing all the lengths by
+% two is done by setting |\unitlength| to \texttt{0.5pt}
+% \begin{macrocode}
+ \setlength{\unitlength}{.5pt}
+ \begin{picture}(\cnt@paperwidth,\cnt@paperheight)
+ \centering
+ \thicklines
+% \end{macrocode}
+%
+% First we have the pagebox and reference lines,
+%
+% \begin{macrocode}
+ \put(0,0){\framebox(\cnt@paperwidth,\cnt@paperheight){\mbox{}}}
+ \put(0,\cnt@voffset){\dashbox{10}(\cnt@paperwidth,0){\mbox{}}}
+ \put(\cnt@hoffset,0){\dashbox{10}(0,\cnt@paperheight){\mbox{}}}
+% \end{macrocode}
+%
+% then the header,
+%
+% \begin{macrocode}
+ \put(\ref@margin,\ref@head){%
+ \framebox(\cnt@textwidth,\cnt@headheight)%
+ {\footnotesize\Headertext}}
+% \end{macrocode}
+%
+% the body of the text area,
+%
+% \begin{macrocode}
+ \put(\ref@margin,\ref@body){%
+ \framebox(\cnt@textwidth,\cnt@textheight){\Bodytext}}
+% \end{macrocode}
+%
+% the footer
+%
+% \begin{macrocode}
+ \put(\ref@margin,\ref@foot){%
+ \framebox(\cnt@textwidth,\fheight){\footnotesize\Footertext}}
+% \end{macrocode}
+%
+% and the space for marginal notes.
+%
+% \begin{macrocode}
+ \put(\ref@marginpar,\ref@body){%
+ \framebox(\cnt@marginparwidth,\cnt@textheight)%
+ {\footnotesize\shortstack{\MarginNotestext}}}
+% \end{macrocode}
+%
+% Then we start putting in `arrows' to mark the various parameters.
+% From here we use |\thinlines|.
+% \begin{macrocode}
+ \thinlines
+% \end{macrocode}
+%
+% |\PositionX| and |\PositionY| will be the coordinates of the center of
+% the arrow displaying |\textwidth|.
+% \begin{macrocode}
+ \SetToHalf\PositionX\cnt@textwidth
+ \advance\PositionX by \ref@margin
+% \end{macrocode}
+% The arrow should be a bit above the bottom of the `body box'.
+% \begin{macrocode}
+ \PositionY = \ref@body
+ \advance\PositionY by 50
+% \end{macrocode}
+% An identifying number is put here, in a circle.
+% \begin{macrocode}
+ \Identify{8}
+% \end{macrocode}
+% Then the arrow is drawn.
+% \begin{macrocode}
+ \InsideHArrow\cnt@textwidth
+% \end{macrocode}
+%
+% Now the |\textheight|
+% \begin{macrocode}
+ \SetToHalf\PositionY\cnt@textheight
+ \advance\PositionY by \ref@body
+% \end{macrocode}
+%
+% The x-psition of the arrow is at $4/5$ of the width of the `body
+% box'.
+% \begin{macrocode}
+ \PositionX = \cnt@textwidth
+ \divide\PositionX by 5
+ \multiply \PositionX by 4
+ \advance\PositionX by \ref@margin
+% \end{macrocode}
+%
+% An identifying number is put here, in a circle.
+% \begin{macrocode}
+ \Identify{7}
+ \InsideVArrow\cnt@textheight
+% \end{macrocode}
+%
+%
+% The |\hoffset|,
+% \changes{v1.2}{1998/04/13}{\cs{PositionY} for label 1 is
+% fixed at 50}
+% \begin{macrocode}
+ \PositionY = 50
+ \SetToHalf\PositionX\cnt@hoffset
+ \Identify{1}
+ \InsideHArrow\cnt@hoffset
+% \end{macrocode}
+%
+%
+% The width of the margin.
+% \changes{v1.2}{1998/04/13}{The direction of the arrows should be
+% switched by the sign of \cs{oddsidemargin}}
+% \begin{macrocode}
+ \SetToQuart\PositionY\cnt@textheight
+ \advance\PositionY by \ref@body
+ \ifnum\ref@marginwidth > 0
+ \OutsideHArrow\ref@margin\ref@marginwidth{20}
+ \PositionX = \cnt@hoffset
+ \else
+ \OutsideHArrow\cnt@hoffset{-\ref@marginwidth}{20}
+ \PositionX = \ref@margin
+ \fi
+ \advance\PositionX by -30
+ \Identify{3}
+% \end{macrocode}
+%
+% the |\marginparwidth|,
+% \begin{macrocode}
+ \SetToQuart\PositionY\cnt@textheight
+ \advance\PositionY by \ref@body
+% \end{macrocode}
+% This arrow has to be bit below the one for the |\oddsidemargin|
+% or\\ |\evensidemargin|.
+% \begin{macrocode}
+ \advance\PositionY by 30
+ \SetToHalf\PositionX\cnt@marginparwidth
+ \advance\PositionX by \ref@marginpar
+ \Identify{10}
+ \InsideHArrow\cnt@marginparwidth
+% \end{macrocode}
+%
+%
+% The |\marginparsep|, this depends on single or double sided
+% printing.
+% \begin{macrocode}
+ \advance\PositionY by 30
+ \if@twoside
+% \end{macrocode}
+%
+% Twosided mode, reversemargin;
+% \changes{v1.1b}{1994/03/23}{\cs{OutSideHArrow} should be
+% \cs{OutsideHArrow}}
+% \changes{v1.2}{1998/04/13}{Added check for reversemargin}
+% \begin{macrocode}
+ \if@reversemargin
+ \ifodd\count\z@
+ \OutsideHArrow\ref@margin\cnt@marginparsep{20}
+ \PositionX = \ref@margin
+ \else
+ \OutsideHArrow\ref@marginpar\cnt@marginparsep{20}
+ \PositionX = \ref@marginpar
+ \fi
+ \else
+% \end{macrocode}
+% Not reversemargin;
+% \begin{macrocode}
+ \ifodd\count\z@
+ \OutsideHArrow\ref@marginpar\cnt@marginparsep{20}
+ \PositionX = \ref@marginpar
+ \else
+ \OutsideHArrow\ref@margin\cnt@marginparsep{20}
+ \PositionX = \ref@margin
+ \fi
+ \fi
+ \else
+% \end{macrocode}
+%
+% Single sided mode.
+% \changes{v1.2}{1998/04/13}{Added check for reversemargin}
+% \begin{macrocode}
+ \if@reversemargin
+ \OutsideHArrow\ref@margin\cnt@marginparsep{20}
+ \PositionX = \ref@margin
+ \else
+ \OutsideHArrow\ref@marginpar\cnt@marginparsep{20}
+ \PositionX = \ref@marginpar
+ \fi
+ \fi
+% \end{macrocode}
+% \changes{v1.2}{1998/04/13}{The \cs{PositionX} of the label 9 is
+% changed to the left side of the arrows}
+% \begin{macrocode}
+ \advance\PositionX by -\cnt@marginparsep
+ \advance\PositionX by -30
+ \Identify{9}
+% \end{macrocode}
+%
+% Identify the |\footskip|. The arrow will be located on $1/8$th of
+% the |\textwidth|.
+% \changes{v1.2}{1998/04/13}{The \cs{PositionY} of the label 11 is
+% changed to the upper side of the arrows}
+% \begin{macrocode}
+ \PositionX = \cnt@textwidth
+ \divide\PositionX by 8
+ \advance\PositionX by \ref@margin
+ \OutsideVArrow\ref@foot\cnt@footskip{20}{20}
+ \PositionY = \ref@foot
+ \advance\PositionY by \cnt@footskip
+ \advance\PositionY by 30
+ \Identify{11}
+% \end{macrocode}
+%
+% Identify the |\voffset|. The arrow will be located a bit to the
+% left of the edge of the paper.
+% \begin{macrocode}
+ \PositionX = \cnt@paperwidth
+ \advance\PositionX by -50
+ \PositionY = \cnt@paperheight
+ \ExtraYPos = \PositionY
+ \advance\ExtraYPos by -\cnt@voffset
+ \advance\PositionY by \cnt@voffset
+ \divide\PositionY by \tw@
+ \Identify{2}
+ \InsideVArrow\ExtraYPos
+% \end{macrocode}
+%
+% Identify |\topmargin|, |\headheight| and |\headsep|.
+%
+% The arrows will be located on $1/8$th of the |\textwidth|, with
+% intervals of the same size, stored in |\Interval|.
+% \begin{macrocode}
+ \Interval = \cnt@textwidth
+ \divide\Interval by 8
+ \PositionX = \ref@margin
+ \advance\PositionX by \Interval
+% \end{macrocode}
+% First the |\topmargin|. If |\topmargin| has a positive value, the
+% arrow is upward. Otherwise, it is downward. The number label is
+% always placed at the base of the arrow.
+% \changes{v1.2}{1998/04/13}{The direction of the arrows should be
+% switched by the sign of \cs{topmargin}}
+% \begin{macrocode}
+ \ifnum\cnt@topmargin > \z@
+ \ExtraYPos = \ref@head
+ \advance\ExtraYPos\cnt@headheight
+ \OutsideVArrow\ExtraYPos\cnt@topmargin{20}{20}
+ \PositionY = \ExtraYPos
+ \advance\PositionY by \cnt@topmargin
+ \else
+ \ExtraYPos = \cnt@voffset
+ \OutsideVArrow\ExtraYPos{-\cnt@topmargin}{20}{20}
+ \PositionY = \ExtraYPos
+ \advance\PositionY by -\cnt@topmargin
+ \fi
+ \advance\PositionY by 30
+ \Identify{4}
+ \advance\PositionX by \Interval
+% \end{macrocode}
+% Then the |\headheight|
+% \changes{v1.2}{1998/04/13}{The \cs{PositionY} of the label 5 is
+% fixed}
+% \begin{macrocode}
+ \OutsideVArrow\ref@head\cnt@headheight{20}{20}
+ \PositionY = \ref@head
+ \advance\PositionY by \cnt@headheight
+ \advance\PositionY by 30
+ \Identify{5}
+ \advance\PositionX by \Interval
+% \end{macrocode}
+% and finally the |\headsep|
+% \changes{v1.2}{1998/04/13}{The \cs{PositionY} of the label 6 is
+% fixed}
+% \begin{macrocode}
+ \ExtraYPos=\ref@body
+ \advance\ExtraYPos\cnt@textheight
+ \OutsideVArrow\ExtraYPos\cnt@headsep{20}{20}
+ \PositionY = \ref@body
+ \advance\PositionY by \cnt@textheight
+ \advance\PositionY by -30
+ \Identify{6}
+% \end{macrocode}
+%
+% Here we can end the picture environment and insert a little
+% space.
+% \begin{macrocode}
+ \end{picture}
+
+ \medskip
+% \end{macrocode}
+%
+% Below the picture we put a table to show the actual values of the
+% parameters. Note that fractional points are truncated, i.e.,
+% \texttt{72.27pt} is displayed as \texttt{72pt}
+%
+% The table is typeset inside a box with a depth of 0 to always
+% keep it on the same page as the picture.
+% \changes{v1.1b}{1994/03/23}{Showing oddside and evenside margins was
+% defective}
+% \changes{v1.1c}{1994/07/14}{in compatibility mode \cs{footnotesize}
+% calls \cs{normalfont}; therefore we need to switch to a tt font
+% later}
+% \changes{v1.1f}{1995/03/14}{introduced \cs{notshown}}
+% \begin{macrocode}
+ \vtop to 0pt{%
+ \@minipagerestore\footnotesize\ttfamily
+ \begin{tabular}{@{}rl@{\hspace{20pt}}rl}
+ 1 & \oneinchtext\ + \LayOutbs\texttt{hoffset}
+ & 2 & \oneinchtext\ + \LayOutbs\texttt{voffset} \\
+ 3 & \if@twoside
+ \ifodd\count\z@ \Show{cnt}{oddsidemargin}
+ \else \Show{cnt}{evensidemargin}
+ \fi
+ \else
+ \Show{cnt}{oddsidemargin}
+ \fi & 4 & \Show{cnt}{topmargin} \\
+ 5 & \Show{cnt}{headheight} & 6 & \Show{cnt}{headsep} \\
+ 7 & \Show{cnt}{textheight} & 8 & \Show{cnt}{textwidth} \\
+ 9 & \Show{cnt}{marginparsep}&10& \Show{cnt}{marginparwidth} \\
+ 11& \Show{cnt}{footskip} & & \Show{cnt}{marginparpush}
+ \rlap{(\notshown)}\\
+ & \Show{ref}{hoffset} & & \Show{ref}{voffset} \\
+ & \Show{cnt}{paperwidth} & & \Show{cnt}{paperheight} \\
+
+ \end{tabular}\vss}
+% \end{macrocode}
+% When the option \Lopt{verbose} was used the following lines will
+% show dimensions on the terminal.
+% \begin{macrocode}
+ \Type{ref}{hoffset}
+ \Type{ref}{voffset}
+ \Type{cnt}{textheight}
+ \Type{cnt}{textwidth}
+% \end{macrocode}
+% Finally we start a new page.
+% \begin{macrocode}
+ \newpage
+}
+%</package>
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+% \Finale
+\endinput
diff --git a/Master/texmf-dist/source/latex/tools/longtable.dtx b/Master/texmf-dist/source/latex/tools/longtable.dtx
new file mode 100644
index 00000000000..81136b5cbae
--- /dev/null
+++ b/Master/texmf-dist/source/latex/tools/longtable.dtx
@@ -0,0 +1,2146 @@
+% \iffalse meta-comment
+%
+% Copyright 1993 1994 1995 1996 1997 1998 1999 2000 2001 2002 2003
+% The LaTeX3 Project and any individual authors listed elsewhere
+% in this file.
+%
+% This file is part of the Standard LaTeX `Tools Bundle'.
+% -------------------------------------------------------
+%
+% It 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.3 or later is part of all distributions of LaTeX
+% version 2003/12/01 or later.
+%
+% The list of all files belonging to the LaTeX `Tools Bundle' is
+% given in the file `manifest.txt'.
+%
+% \fi
+% \iffalse
+%% File: longtable.dtx Copyright (C) 1990-2001 David Carlisle
+%
+%<*dtx>
+ \ProvidesFile{longtable.dtx}
+%</dtx>
+%<package>\NeedsTeXFormat{LaTeX2e}[1995/06/01]
+%<package>\ProvidesPackage{longtable}
+%<driver> \ProvidesFile{longtable.drv}
+% \fi
+% \ProvidesFile{longtable.dtx}
+ [2004/02/01 v4.11 Multi-page Table package (DPC)]
+%
+% \iffalse
+%<*driver>
+\documentclass{ltxdoc}
+\usepackage{longtable}
+\begin{document}
+\DocInput{longtable.dtx}
+\end{document}
+%</driver>
+% \fi
+%
+% \GetFileInfo{longtable.dtx}
+% \title{The \textsf{longtable} package\thanks{This file
+% has version number \fileversion, last
+% revised \filedate.}}
+% \author{David Carlisle\thanks{The new algorithm for aligning `chunks'
+% of a table used in version 4 of this package was devised coded
+% and documented by David Kastrup,
+% \texttt{dak@neuroinformatik.ruhr-uni-bochum.de}.}}
+% \date{\filedate}
+%
+% \let\package\textsf
+% \let\env\textsf
+% \providecommand\finalclearpage{\clearpage}
+%
+% \maketitle
+%
+% \begin{abstract}
+% This package defines the \env{longtable} environment, a multi-page
+% version of \env{tabular}.
+% \end{abstract}
+%
+% \DeleteShortVerb{\|}
+% \MakeShortVerb{\"}
+%
+% \changes{v0.00}{1989/11/06}
+% {`Version 0' distributed as longtab.sty
+% always used just one chunk for the whole table}
+%
+% \changes{v1.00}{1990/12/20}
+% {Initial version}
+%
+% \changes{v2.00}{1991/06/17}
+% {Support NFSS and array.sty}
+%
+% \changes{v3.00}{1992/03/16}
+% {New implementation. tables may now start anywhere on the page.}
+%
+% \changes{v3.01}{1992/04/06}
+% {(Michel Goossens) If a chunk ends on a line in which the first
+% entry is empty, wierd errors occur. Added special begin and end
+% groups, (\cs{ifnum}0 ) stuff as explained in Appendix D.}
+%
+% \changes{v3.02}{1992/04/09}
+% {(Michel Goossens) Longtable fails if the table counter is reset
+% during a document. Now use an internal counter, but still
+% increment table so \cs{caption} and \cs{label} work out right.}
+%
+% \changes{v3.03}{1992/06/25}
+% {Add \cs{@ifundefined\{reset@font\}} so that the documentation may
+% be processed with old versions of \LaTeX.}
+% \changes{v3.03}{1992/06/25}
+% {Modify the treatment of \cs{d@llar} to match the new versions of
+% Mittelbach's array.sty (array.sty v2.0h)}
+%
+% \changes{v3.04}{1992/11/12}
+% {(Jean-Pierre Drucbert) Longtable failed when used with
+% \cs{includeonly}.}
+% \changes{v3.04}{1992/11/12}
+% {Fix bug which stopped \cs{kill} working correctly in headings.}
+% \changes{v3.04}{1992/11/12}
+% {(Graham Gough) Made \cs{setlongtables} issue a warning message.}
+% \changes{v3.04}{1992/11/12}
+% {(Sebastian Rahtz) longtable ran out of memory on really long
+% tables. Another bug introduced in V3.}
+%
+% \changes{v3.05}{1992/11/20}
+% {(Juergen Peus) Table was hard coded into the captions, Now the
+% captions use \cs{fnum@table}, so \cs{tablename} will be used.}
+%
+% \changes{v3.06}{1993/01/21}
+% {(Ingo Hoffmann) longtable fails with letter style.
+% The table counter is not defined, and the .aux file is not used in
+% the same way. This version will use a .lta file for letter style.}
+%
+% \changes{v3.07}{1993/06/09}
+% {Allow the \LaTeX\ syntax \cs{setcounter}\{LTchunksize\}\{10\}}
+%
+% \changes{v3.08}{1993/06/09}
+% {Update for \LaTeXe}
+%
+% \changes{v3.09}{1994/03/15}
+% {New ltxdoc style}
+%
+% \changes{v3.11}{1994/05/22}
+% {Option handling added, new style errors and warnings}
+%
+% \changes{v3.12}{1994/06/30}
+% {Remove special letter class handling from v3.06, not needed for
+% new letter class}
+%
+% \changes{v4.00}{1996/04/08}
+% {(DK) New algorithm to align chunks devised and coded by David
+% Kastrup}
+%
+% \changes{v4.02}{1996/04/16}
+% {(DPC/DK) documentation improvements}
+%
+% \changes{v4.06}{1997/06/28}
+% {(DK) new email address}
+%
+% \CheckSum{1045}
+%
+%
+% \makeatletter
+% \def\@oddfoot{\normalfont\rmfamily\dotfill Page \thepage\dotfill}
+% \def\@oddhead{\dotfill{\normalfont\ttfamily longtable.sty}\dotfill}
+% \def\ps@titlepage{\let\@oddhead\@empty}
+% \makeatother
+%
+%
+% \setlength\LTleft\parindent
+% \setlength\LTright\fill
+% \setcounter{LTchunksize}{10}
+%
+% \def\v{\char`}
+%
+% ^^A \vbox to 100pt makes the page breaks the same on the first run.
+% \changes{v3.08}{1993/06/09}
+% {No need to use \cs{vbox} with \LaTeXe\ minipage}
+% \noindent\begin{minipage}[t][130pt]{\textwidth}
+% \listoftables
+% \end{minipage}
+%
+% \section{Introduction}
+%
+% The \package{longtable} package defines a new environment,
+% \DescribeEnv{longtable}
+% \env{longtable}, which has most of the features of the \env{tabular}
+% environment, but produces tables which may be broken by \TeX's
+% standard page-breaking algorithm. It also shares some features with
+% the \env{table} environment. In particular it uses the same counter,
+% \texttt{table}, and has a similar "\caption" command. Also, the
+% standard "\listoftables" command lists tables produced by either the
+% \env{table} or \env{longtable} environments.
+%
+% The following example uses most of the features of the \env{longtable}
+% environment. An edited listing of the input for this example appears
+% in Section~\ref{listing}.
+%
+% \textbf{Note:} Various parts of the following table will
+% \textbf{not} line up correctly until this document has been run
+% through \LaTeX\ several times. This is a characteristic feature of
+% this package, as described below.
+%
+% \begin{longtable}{@{*}r||p{1in}@{*}}
+% KILLED & LINE!!!! \kill
+% \caption
+% [An optional table caption (used in the list of tables)]
+% {A long table\label{long}}\\
+% \hline\hline
+% \multicolumn{2}{@{*}c@{*}}%
+% {This part appears at the top of the table}\\
+% \textsc{First}&\textsc{Second}\\
+% \hline\hline
+% \endfirsthead
+% \caption[]{(continued)}\\
+% \hline\hline
+% \multicolumn{2}{@{*}c@{*}}%
+% {This part appears at the top of every other page}\\
+% \textbf{First}&\textbf{Second}\\
+% \hline\hline
+% \endhead
+% \hline
+% This goes at the&bottom.\\
+% \hline
+% \endfoot
+% \hline
+% These lines will&appear\\
+% in place of the & usual foot\\
+% at the end& of the table\\
+% \hline
+% \endlastfoot
+% \env{longtable} columns are specified& in the \\
+% same way as in the \env{tabular}& environment.\\
+% "@{*}r||p{1in}@{*}"& in this case.\\
+% Each row ends with a& "\\" command.\\
+% The "\\" command has an& optional\\
+% argument, just as in& the\\
+% \env{tabular}&environment.\\[10pt]
+% See the effect of "\\[10pt]"&?\\
+% Lots of lines& like this.\\
+% Lots of lines& like this.\\
+% Lots of lines& like this.\\
+% Lots of lines& like this.\\
+% Also "\hline" may be used,& as in \env{tabular}.\\
+% \hline
+% That was a "\hline"&.\\
+% \hline\hline
+% That was "\hline\hline"&.\\
+% \multicolumn{2}{||c||}%
+% {This is a \ttfamily\v\\multicolumn\v{2\v}\v{||c||\v}}\\
+% If a page break occurs at a "\hline" then& a line is drawn\\
+% at the bottom of one page and at the& top of the next.\\
+% \hline
+% The "[t] [b] [c]" argument of \env{tabular}& can not be used.\\
+% The optional argument may be one of& "[l] [r] [c]"\\
+% to specify whether the table should be& adjusted\\
+% to the left, right& or centrally.\\
+% \hline\hline
+% Lots of lines& like this.\\
+% Lots of lines& like this.\\
+% Lots of lines& like this.\\
+% Lots of lines& like this.\\
+% Lots of lines& like this.\\
+% Lots of lines& like this.\\
+% Lots of lines& like this.\\
+% Lots of lines& like this.\\
+% Lots of lines& like this.\\
+% Lots of lines& like this.\\
+% Lots of lines& like this.\\
+% Lots of lines& like this.\\
+% Lots of lines& like this.\\
+% Lots of lines& like this.\\
+% Lots of lines& like this.\\
+% Lots of lines& like this.\\
+% Lots of lines& like this.\\
+% Lots of lines& like this.\\
+% Lots of lines& like this.\\
+% Lots of lines& like this.\\
+% Some lines may take up a lot of space, like this: &
+% \raggedleft This last column is a ``p'' column so this
+% ``row'' of the table can take up several lines. Note however that
+% \TeX\ will never break a page within such a row. Page breaks only
+% occur between rows of the table or at "\hline" commands.
+% \tabularnewline
+% Lots of lines& like this.\\
+% Lots of lines& like this.\\
+% Lots of lines& like this.\\
+% Lots of lines& like this.\\
+% Lots of lines& like this.\\
+% Lots of lines& like this.\\
+% Lots of lines& like this.\\
+% \hline
+% Lots\footnote{This is a footnote.} of lines& like this.\\
+% Lots of lines& like this\footnote{\env{longtable} takes special
+% precautions, so that footnotes may also be used in `p' columns.}\\
+% \hline
+% Lots of lines& like this.\\
+% Lots of lines& like this.
+% \end{longtable}
+%
+% \section{Chunk Size}
+%
+% \DescribeMacro{LTchunksize}
+% In order to \TeX\ multi-page tables, it is necessary to break up the
+% table into smaller chunks, so that \TeX\ does not have to keep
+% everything in memory at one time. By default \env{longtable} uses 20
+% rows per chunk, but this can be set by the user, with e.g.,
+% "\setcounter{LTchunksize}{10}".\footnote
+% {You can also use the plain \TeX\ syntax
+% {\ttfamily\v\\LTchunksize=10.}}
+% These chunks do not affect page breaking,
+% thus if you are using a \TeX\ with a lot of memory, you can set
+% "LTchunksize" to be several pages of the table. \TeX\ will run
+% faster with a large "LTchunksize". However, if necessary,
+% \env{longtable} can work with "LTchunksize" set to 1, in which case
+% the memory taken up is negligible.
+% Note that if you use the commands for setting the table head or foot
+% (see below), the "LTchunksize" must be at least as large as the
+% number of rows in each of the head or foot sections.
+%
+% This document specifies "\setcounter{LTchunksize}{10}". If you look
+% at the previous table, after the \emph{first} run of \LaTeX\ you will
+% see that various parts of the table do not line up.
+% \LaTeX\ will also have printed a warning that the column
+% widths had changed. \env{longtable} writes information onto the
+% ".aux" file, so that it can line up the different chunks.
+% Prior to version~4 of this package, this information was not used
+% unless a "\setlongtables" command was issued, however, now the
+% information is always used, using a new algorithm\footnote{Due to
+% David Kastrup.} and so "\setlongtables" is no longer needed. It is
+% defined (but does nothing) for the benefit of old documents that
+% use it.
+%
+% \begin{table}
+% \centering
+% \begin{tabular}{||l|l|l||}
+% \hline\hline
+% A&\env{tabular}& environment\\
+% \hline
+% within&a floating&\env{table}\\
+% \hline\hline
+% \end{tabular}
+% \caption{A floating table}
+% \end{table}
+%
+% \section{Captions and Headings}
+%
+% At the start of the table one may specify lines which are to appear at
+% the top of every page (under the headline, but before the other lines
+% of the table).
+% \DescribeMacro{\endhead}
+% The lines are entered as normal, but the last "\\" command is
+% replaced by a "\endhead" command.
+% \DescribeMacro{\endfirsthead}
+% If the first page should have a different heading, then this should be
+% entered in the same way, and terminated with the "\endfirsthead"
+% command. The "LTchunksize" should be at least as large as the
+% number of rows in the heading.
+% \DescribeMacro{\endfoot}
+% There are also "\endfoot" and "\endlastfoot"
+%\DescribeMacro{\endlastfoot}
+% commands which are used in the same way (at the \emph{start} of the
+% table) to specify rows (or an "\hline") to appear at the bottom of
+% each page. In certain situations, you may want to place lines which
+% logically belong in the table body at the end of the \env{firsthead},
+% or the beginning of the \env{lastfoot}. This helps to control which
+% lines appear on the first and last page of the table.
+%
+% \DescribeMacro{\caption}%
+% The "\caption{...}" command is essentially equivalent to\\
+% "\multicolumn{n}{c}{\parbox{\LTcapwidth}{...}}"\\
+% where \texttt{n} is the number of columns of the table. You may set
+% the width of the caption with a command such as
+% "\setlength{\LTcapwidth}{2in}"
+% in the preamble of your document. The default is 4in. "\caption" also
+% writes the information to produce an entry in the list of tables. As
+% with the "\caption" command in the \env{figure} and \env{table}
+% environments, an optional argument specifies the text to appear in the
+% list of tables if this is different from the text to appear in the
+% caption. Thus the caption for table \ref{long} was specified as
+% {\ttfamily
+% "\caption"[An optional table caption
+% (used in the list of tables)]\v{A long
+% table"\label{long}"\v}}.
+%
+% You may wish the caption on later pages to be different to that on the
+% first page. In this case put the "\caption" command in the first
+% heading, and put a subsidiary caption in a "\caption[]" command in
+% the main heading. If the optional argument to "\caption" is empty,
+% no entry is made in the list of tables. Alternatively, if you do not
+% want the table number to be printed each time, use the "\caption*"
+% command.
+%
+% The captions are set based on the code for the \package{article}
+% class.
+% If you have redefined the standard "\@makecaption" command to produce
+% a different format for the captions, you may
+% need to make similar changes to the \package{longtable} version,
+% "\LT@makecaption". See the code section for more details.
+%
+% A more convenient method of customising captions is given by the
+% \package{caption(2)} package, which provides commands for customising
+% captions, and arranges that the captions in standard environments, and
+% many environments provided by packages (including \package{longtable})
+% are modified in a compatible manner.
+%
+% You may use the "\label" command so that you can cross reference
+% \env{longtable}s with "\ref". Note however, that the "\label" command
+% should not be used in a heading that may appear more than once. Place
+% it either in the \env{firsthead}, or in the body of the table. It
+% should not be the \emph{first} command in any entry.
+%
+% \section{Multicolumn entries}
+%
+% The "\multicolumn" command may be used in \env{longtable} in exactly
+% the same way as for \env{tabular}. So you may want to skip this
+% section, which is rather technical, however coping with "\multicolumn"
+% is one of the main problems for an environment such as
+% \env{longtable}. The main effect that a user will see is that
+% certain combinations of "\multicolumn" entries will result in a
+% document needing more runs of \LaTeX\ before the various `chunks' of
+% a table align.
+%
+% The examples in this section are set with "LTchunksize" set to the
+% minimum value of one, to demonstrate the effects when "\multicolumn"
+% entries occur in different chunks.
+%
+% \begin{table}[!htp]
+% \begin{center}
+% \LTchunksize=1
+% \makeatletter
+%
+% \global\let\LT@save@row\relax
+% \let\LT@warn\@gobble
+% \let\LT@final@warn\relax
+%
+% \newcommand\ltexample[1]{
+% \stepcounter{LT@tables}
+% \expandafter\let\csname LT@\romannumeral\c@LT@tables\endcsname
+% \LT@save@row
+% \addtocounter{LT@tables}{-1}
+% \begin{longtable}{|c|c|c|}
+% \caption{A difficult {\cs{multicolumn}} combination:
+% pass #1\label{pass#1}}\\
+% \hline
+% 1&2&3\\
+% \multicolumn{3}{|c|}{wide multicolumn spanning 1--3}\\
+% \multicolumn{2}{|c|}{multicolumn 1--2}&3\\
+% wide 1&2&3\\
+% \hline
+% \end{longtable}
+% }
+%
+% \ltexample{1}
+%
+% \ltexample{2}
+%
+% \ltexample{3}
+%
+% \ltexample{4}
+%
+% \end{center}
+% \end{table}
+%
+% Consider Table~\ref{pass1}.
+% In the second chunk, \env{longtable} sees the wide
+% multicolumn entry. At this point it thinks that the first two
+% columns are very narrow. All
+% the width of the multicolumn entry is assumed to be in the
+% third column. (This is a `feature' of \TeX's primitive "\halign"
+% command.) \env{longtable} then passes the information that there
+% is a wide third column to the later chunks, with the result that the
+% first pass over the table is too wide.
+%
+% If the `saved row' from this first pass was re-inserted into the
+% table on the next pass, the table would line up in two passes, but
+% would be much two wide.
+%
+% \DescribeMacro{\kill}%
+% The solution to this problem used in Versions 1~and~2, was to use a
+% "\kill" line. If a line is "\kill"ed, by using "\kill" rather than
+% "\\" at the end of the line, it is used in calculating
+% column widths, but removed from the final table. Thus entering
+% "\kill"ed copies of the last two rows before the wide multicolumn
+% entry would mean that "\halign" `saw' the wide entries in the first
+% two columns, and so would not widen the third column by so much to
+% make room for the multicolumn entry.
+%
+% In Version~3, a new solution was introduced. If the saved row in
+% the ".aux" file was not being used, \env{longtable} used a special
+% `draft' form of "\multicolumn", this modified the definition, so the
+% spanning entry was never considered to be wider than the columns it
+% spanned. So after the first pass, the ".aux" file stored the
+% widest normal entry for each column, no column was widened due to
+% "\span"ned columns. By default \env{longtable} ignored the ".aux"
+% file, and so each run of \LaTeX\ was considered a first pass. Once the
+% "\setlongtables" declaration was given, the saved row in the ".aux"
+% file, and the proper definition of "\multicolumn" were used. If any
+% "\multicolumn" entry caused one of the columns to be widened, this
+% information could not be passed back to earlier chunks, and so the
+% table would not correctly line up until the third pass. This algorithm
+% always converged in three passes as described above, but in examples
+% such as the ones in Tables \ref{pass1}--\ref{pass4}, the final
+% widths were not optimal as the width of column~2, which is
+% determined by a "\multicolumn" entry was not known when the final
+% width for column~3 was fixed, due to the fact that \emph{both}
+% "\multicolumn" commands were switched from `draft' mode to `normal'
+% mode at the same time.
+%
+% Version~4 alleviates the problem considerably.
+% The first pass of the table will
+% indeed have the third column much too wide. However, on the next pass
+% \env{longtable} will notice the error and reduce the column width
+% accordingly. If this has to propagate to chunks before the
+% "\multicolumn" one, an additional pass will, of course, be
+% needed. It is possible to construct tables where this rippling up of
+% the correct widths taks several passes to `converge' and produce a
+% table with all chunks aligned. However in
+% order to need many passes one needs to construct a table with
+% many overlapping "\multicolumn" entries, all being wider than the
+% natural widths of the columns they span, and all occuring in
+% different chunks. In the typical case the algorithm will converge
+% after three or four passes, and, the benefits of not needing to edit
+% the document before the final run to add "\setlongtables", and the
+% better choice of final column widths in the case of multiple
+% "\multicolumn" entries will hopefully more than pay for the extra
+% passes that may possibly be needed.
+%
+% So Table~\ref{pass1} converges after 4~passes, as seen in
+% Table~\ref{pass4}.
+%
+% You can still speed the convergence by introducing judicious "\kill"
+% lines, if you happen to have constellations like the above.
+%
+% If you object even to \LaTeX-ing a file twice, you should
+% make the first line of
+% every \env{longtable} a "\kill" line that contains the widest entry
+% to be used in each column. All chunks will then line up on the first
+% pass.
+%
+% \section{Adjustment}
+%
+% The optional argument of \env{longtable} controls the
+% horizontal alignment of the table. The possible options are "[c]",
+% "[r]" and "[l]", for centring,
+% right and left adjustment, respectively.
+% \DescribeMacro{\LTleft}
+% Normally centring is the default, but this document specifies
+% \DescribeMacro{\LTright}
+%\begin{verbatim}
+% \setlength\LTleft\parindent
+% \setlength\LTright\fill
+%\end{verbatim}
+% in the preamble,
+% which means that the tables are set flush left, but
+% indented by the usual paragraph indentation. Any lengths can be
+% specified for these two parameters, but at least one of them should be
+% a rubber length so that it fills up the width of the page, unless
+% rubber lengths are added between the columns using the
+% "\extracolsep" command.
+% For instance
+%\begin{verbatim}
+% \begin{tabular*}{\textwidth}{@{\extracolsep{...}}...}
+%\end{verbatim}
+% produces a full width table, to get a similar effect with
+% \env{longtable} specify
+%\begin{verbatim}
+% \setlength\LTleft{0pt}
+% \setlength\LTright{0pt}
+% \begin{longtable}{@{\extracolsep{...}}...}
+%\end{verbatim}
+%
+% \section{Changes}
+%
+% This section highlights the major changes since version~2. A more
+% detailed change log may be produced at the end of the code listing
+% if the "ltxdoc.cfg" file specifies
+%\begin{verbatim}
+% \AtBeginDocument{\RecordChanges}
+% \AtEndDocument{\PrintChanges}
+%\end{verbatim}
+%
+% Changes made between versions 2 and 3.
+% \begin{itemize}
+% \item The mechanism for adding the head and foot of the table has been
+% completely rewritten. With this new mechanism, \env{longtable} does
+% not need to issue a "\clearpage" at the start of the table, and so the
+% table may start half way down a page. Also the "\endlastfoot" command
+% which could not safely be implemented under the old scheme, has been
+% added.
+% \item \env{longtable} now issues an error if started in the scope of
+% "\twocolumn", or the \env{multicols} environment.
+% \item The separate documentation file "longtable.tex" has been
+% merged with the package file, "longtable.dtx" using Mittelbach's
+% \package{doc} package.
+% \item Support for footnotes has been added. Note however that
+% "\footnote" will not work in the `head' or `foot' sections of the
+% table. In order to put a footnote in those sections (e.g., inside a
+% caption), use "\footnotemark" at that point, and "\footnotetext"
+% anywhere in the table \emph{body} that will fall on the same page.
+% \item The treatment of "\multicolumn" has changed, making
+% "\kill" lines unnecessary, at the price of sometimes requiring a
+% third pass through \LaTeX.
+% \item The "\newpage" command now works inside a \env{longtable}.
+% \end{itemize}
+%
+% Changes made between versions 3 and 4.
+% \begin{itemize}
+% \item A new algorithm is used for aligning chunks. As well as the
+% widest width in each column, \package{longtable} remembers which
+% chunk produced this maximum. This allows it to check that the
+% maximum is still achieved in later runs. As \package{longtable} can
+% now deal with columns shrinking as the file is edited, the
+% "\setlongtables" system is no longer needed and is disabled.
+%
+% \item An extra benefit of the new algorithm's ability to deal with
+% `shrinking' columns is that it can give better (narrower) column
+% widths in the case of overlapping "\multicolumn" entries in
+% different chunks than the previous algorithm produced.
+%
+% \item The `draft' multicolumn system has been removed, along with
+% related commands such as "\LTmulticolumn".
+%
+% \item The disadvantage of the new algorithm is that it can take more
+% passes. The theoretical maximum is approximately twice the length
+% of a `chain' of columns with overlapping "\multicolumn" entries,
+% although in practice it usually converges as fast as the old
+% version. (Which always converged in three passes once
+% "\setlongtables" was activated.)
+%
+% \item "\\*" and "\nopagebreak" commands may be used to control page
+% breaking.
+%
+% \end{itemize}
+%
+%
+% \section{Summary}
+%
+% ^^A Allow the table to stick into the left margin.
+% \setlength{\LTleft}{0pt plus 1fill minus 1fill}
+% \setlength{\LTright}{0pt}
+%
+% \begin{longtable}{@{}l@{\hspace{10pt}}p{.8\linewidth}@{}}
+% \caption[A summary of \env{longtable} commands]%
+% {\normalsize A summary of \env{longtable} commands}\\
+% \multicolumn{2}{c}{\textbf{Parameters}}\\*
+% \hline
+% "\LTleft"&
+% Glue to the left of the table. \hfill("\fill")\\
+% "\LTright"&
+% Glue to the right of the table. \hfill("\fill")\\
+% "\LTpre"&
+% Glue before the the table. \hfill("\bigskipamount")\\
+% "\LTpost"&
+% Glue after the the table. \hfill("\bigskipamount")\\
+% "\LTcapwidth"&
+% The width of a parbox containing the caption.\hfill(4in)\\
+% "LTchunksize"&
+% The number of rows per chunk. \hfill(20)\\[5pt]
+% \multicolumn{2}{c}{\textbf{Optional
+% arguments to} \ttfamily\v\\begin\v{longtable\v}}\\*
+% \hline
+% \it none& Position as specified by "\LTleft" and "\LTright".\\
+% "[c]"& Centre the table.\\
+% "[l]"& Place the table flush left.\\
+% "[r]"& Place the table flush right.\\[5pt]
+% \pagebreak[2]
+% \multicolumn{2}{c}{\textbf{Commands
+% to end table rows}}\\*
+% \hline
+% "\\"&
+% Specifies the end of a row\\
+% "\\"\oarg{dim}& Ends row, then adds vertical space
+% (as in the \env{tabular} environment).\\
+% "\\*"&
+% The same as "\\" but disallows a page break after the row.\\
+% "\tabularnewline"&
+% Alternative to "\\" for use in the scope of "\raggedright" and
+% similar commands that redefine "\\".\\
+% "\kill"&
+% Row is `killed', but is used in calculating widths.\\
+% "\endhead"&
+% Specifies rows to appear at the top of every page.\\
+% "\endfirsthead"&
+% Specifies rows to appear at the top the first page.\\
+% "\endfoot"&
+% Specifies rows to appear at the bottom of every page.\\
+% "\endlastfoot"&
+% Specifies rows to appear at the bottom of the last page.\\[5pt]
+% \multicolumn{2}{c}{\textbf{\env{longtable} caption commands}}\\*
+% \hline
+% "\caption"\marg{caption}&
+% Caption `Table ?: \meta{caption}', and a `\meta{caption}'
+% entry in the list of tables.\\
+% "\caption"\oarg{lot}\marg{caption}&
+% Caption `Table ?: \meta{caption}', and a `\meta{lot}'
+% entry in the list of tables.\\
+% "\caption[]"\marg{caption}&
+% Caption `Table ?: \meta{caption}',
+% but no entry in the list of tables.\\
+% "\caption*"\marg{caption}&
+% Caption `\meta{caption}', but no entry in the list of tables.\\[5pt]
+% \multicolumn{2}{c}{%^^A
+% \textbf{Commands available at the start of a row}}\\*
+% \hline
+% "\pagebreak"&
+% Force a page break.\\*
+% "\pagebreak"\oarg{val}& A `hint' between 0 and 4
+% of the desirability of a break.\\
+% "\nopagebreak"& Prohibit a page break.\\*
+% "\nopagebreak"\oarg{val}& A `hint' between 0 and 4 of the undesirability
+% of a break.\\
+% "\newpage"&
+% Force a page break.\\[5pt]
+% \multicolumn{2}{c}{\textbf{Footnote commands
+% available inside \env{longtable}}}\\*
+% \hline
+% "\footnote"&
+% Footnotes, but may not be used in the table head \& foot.\\*
+% "\footnotemark"&
+% Footnotemark, may be used in the table head \& foot.\\*
+% "\footnotetext"&
+% Footnote text, use in the table body.\\[5pt]
+% \multicolumn{2}{c}{\textbf{Setlongtables}}\\
+% \hline
+% "\setlongtables"& Obsolete command. Does nothing now.
+% \end{longtable}
+%
+%
+% \finalclearpage
+% \section{Verbatim highlights from Table \protect\ref{long}}
+% \label{listing}
+% \begingroup\catcode`\/=0
+% \begin{verbatim}
+% \begin{longtable}{@{*}r||p{1in}@{*}}
+% KILLED & LINE!!!! \kill
+% \caption[An optional table caption /ldots]{A long table\label{long}}\\
+% \hline\hline
+% \multicolumn{2}{@{*}c@{*}}%
+% {This part appears at the top of the table}\\
+% \textsc{First}&\textsc{Second}\\
+% \hline\hline
+% \endfirsthead
+% \caption[]{(continued)}\\
+% \hline\hline
+% \multicolumn{2}{@{*}c@{*}}%
+% {This part appears at the top of every other page}\\
+% \textbf{First}&\textbf{Second}\\
+% \hline\hline
+% \endhead
+% \hline
+% This goes at the&bottom.\\
+% \hline
+% \endfoot
+% \hline
+% These lines will&appear\\
+% in place of the & usual foot\\
+% at the end& of the table\\
+% \hline
+% \endlastfoot
+% \env{longtable} columns are specified& in the \\
+% same way as in the \env{tabular}& environment.\\
+% /ldots
+% \multicolumn{2}{||c||}{This is a /ldots}\\
+% /ldots
+% Some lines may take/ldots&
+% \raggedleft This last column is a ``p'' column/ldots
+% \tabularnewline
+% /ldots
+% Lots of lines& like this.\\
+% /ldots
+% \hline
+% Lots\footnote{/ldots} of lines& like this.\\
+% Lots of lines& like this\footnote{/ldots}\\
+% \hline
+% Lots of lines& like this.\\
+% /ldots
+% \end{longtable}
+% \end{verbatim}
+% \endgroup
+%
+% \StopEventually{}
+%
+% \finalclearpage
+% \section{The Macros}
+%
+% \begin{macrocode}
+%<*package>
+% \end{macrocode}
+%
+% \subsection{Initial code}
+%
+% Before declaring the package options, we must define some defaults
+% here.
+%
+% \begin{macro}{\LT@err}
+% The error generating command
+% \begin{macrocode}
+\def\LT@err{\PackageError{longtable}}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\LT@warn}
+% The warning generating command
+% \begin{macrocode}
+\def\LT@warn{\PackageWarning{longtable}}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\LT@final@warn}
+% \changes{v4.04}{1996/05/24}
+% {Macro added}
+% If any \env{longtable}s have not aligned, generate a warning at the
+% end of the run at "\AtEndDocument".
+% \begin{macrocode}
+\def\LT@final@warn{%
+ \AtEndDocument{%
+ \LT@warn{Table \@width s have changed. Rerun LaTeX.\@gobbletwo}}%
+ \global\let\LT@final@warn\relax}
+% \end{macrocode}
+% \end{macro}
+%
+% \subsection{Options}
+%
+% The first two options deal with error handling. They are compatible
+% with the options used by the \texttt{tracefnt} package.
+%
+% \begin{macro}{errorshow}
+% \emph{Only} show errors on the terminal. `warnings' are just sent to
+% the log file.
+% \changes{v3.14}{1995/04/25}
+% {Change string from LT to longtable}
+% \begin{macrocode}
+\DeclareOption{errorshow}{%
+ \def\LT@warn{\PackageInfo{longtable}}}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{pausing}
+% \changes{v3.14}{1995/04/25}
+% {Change string from LT to longtable}
+% \changes{v3.15}{1995/06/15}
+% {Use single hash for latex/1557}
+% Make every warning message into an error so \TeX\ stops.
+% May be useful for debugging.
+% \begin{macrocode}
+\DeclareOption{pausing}{%
+ \def\LT@warn#1{%
+ \LT@err{#1}{This is not really an error}}}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{set}
+% \begin{macro}{final}
+% \changes{v4.01}{1996/04/11}
+% {(DPC) make set and final options no op}
+% The next options are just alternative syntax for the
+% "\setlongtables" declaration.
+% \begin{macrocode}
+\DeclareOption{set}{}
+\DeclareOption{final}{}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+%
+% \begin{macrocode}
+\ProcessOptions
+% \end{macrocode}
+%
+% \subsection{User Setable Parameters}
+%
+% \begin{macro}{\LTleft}
+% \begin{macro}{\LTright}
+% Glue to the left and right of the table, default "\fill" (ie
+% centred).
+% \begin{macrocode}
+\newskip\LTleft \LTleft=\fill
+\newskip\LTright \LTright=\fill
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\LTpre}
+% \begin{macro}{\LTpost}
+% Glue before and after the \env{longtable}. "\bigskip" by default.
+% \begin{macrocode}
+\newskip\LTpre \LTpre=\bigskipamount
+\newskip\LTpost \LTpost=\bigskipamount
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\LTchunksize}
+% Chunk size (The number of rows taken per "\halign"). Default 20.
+% \begin{macrocode}
+\newcount\LTchunksize \LTchunksize=20
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\c@LTchunksize}
+% Added in V3.07 to allow the \LaTeX\ syntax
+% "\setcounter{LTchunksize}{10}".
+% \begin{macrocode}
+\let\c@LTchunksize\LTchunksize
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\LTcapwidth}
+% Width of the "\parbox" containing the caption. Default 4in.
+% \begin{macrocode}
+\newdimen\LTcapwidth \LTcapwidth=4in
+% \end{macrocode}
+% \end{macro}
+%
+% \subsection{Internal Parameters}
+%
+% \begin{macro}{\LT@head}
+% \begin{macro}{\LT@firsthead}
+% \begin{macro}{\LT@foot}
+% \begin{macro}{\LT@lastfoot}
+% Boxes for the table head and foot.
+% \begin{macrocode}
+\newbox\LT@head
+\newbox\LT@firsthead
+\newbox\LT@foot
+\newbox\LT@lastfoot
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\LT@cols}
+% Counter for number of columns.
+% \begin{macrocode}
+\newcount\LT@cols
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\LT@rows}
+% Counter for rows up to chunksize.
+% \begin{macrocode}
+\newcount\LT@rows
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\c@LT@tables}
+% Counter for the tables, added in V3.02. Previous versions just used
+% the \LaTeX\ counter "table", but this fails if "table" is
+% reset during a document, eg \package{report} class resets it every
+% chapter.
+%
+% This was changed from "\newcount\LT@tables" in V3.04. \LaTeX\ counters
+% are preserved correctly when "\includeonly" is used. In the rest of
+% the file "\LT@tables" has been replaced by "\c@LT@tables" without
+% further comment.
+% \begin{macrocode}
+\newcounter{LT@tables}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\c@LT@chunks}
+% \changes{v4.00}{1996/04/08}
+% {(DK) Chunk counter added}
+% We need to count through the chunks of our tables from Version~4 on.
+% \begin{macrocode}
+\newcounter{LT@chunks}[LT@tables]
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\c@table}
+% \begin{macro}{\fnum@table}
+% \begin{macro}{\tablename}
+% If the "table" counter is not defined (eg in "letter" style), define
+% it. (Added in V3.06.)
+% \begin{macrocode}
+\ifx\c@table\undefined
+ \newcounter{table}
+ \def\fnum@table{\tablename~\thetable}
+\fi
+\ifx\tablename\undefined
+ \def\tablename{Table}
+\fi
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\LT@out}
+% In a normal style, "longtable" uses the ".aux" file to record the
+% column widths. With "letter.sty", use a separate ".lta" file.
+% (Added in V3.06.)
+%
+% Not needed for new letter class.
+%\begin{verbatim}
+%\ifx\startlabels\undefined
+% \let\@auxout\@auxout
+%\else
+% {\@input{\jobname.lta}}%
+% \newwrite\@auxout
+% \immediate\openout\@auxout=\jobname.lta
+%\fi
+%\end{verbatim}
+% \end{macro}
+%
+% \begin{macro}{\LT@p@ftn}
+% Temporary storage for footnote text in a `p' column.
+% \begin{macrocode}
+\newtoks\LT@p@ftn
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\LT@end@pen}
+% Special penalty for the end of the table. Done this way to save using
+% up a count register.
+% \begin{macrocode}
+\mathchardef\LT@end@pen=30000
+% \end{macrocode}
+% \end{macro}
+%
+% \subsection{The \env{longtable} environment}
+%
+% \begin{macro}{\longtable}
+% Called by "\begin{longtable}". This implementation does not work in
+% multiple column formats. "\par" added at V3.04.
+% \begin{macrocode}
+\def\longtable{%
+ \par
+ \ifx\multicols\@undefined
+ \else
+ \ifnum\col@number>\@ne
+ \@twocolumntrue
+ \fi
+ \fi
+ \if@twocolumn
+ \LT@err{longtable not in 1-column mode}\@ehc
+ \fi
+ \begingroup
+% \end{macrocode}
+% Check for an optional argument.
+% \begin{macrocode}
+ \@ifnextchar[\LT@array{\LT@array[x]}}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\LT@array}
+% Start setting the alignment.
+% Based on "\@array" from the \LaTeX\ kernel
+% and the \package{array} package.
+%
+% Since Version 3.02, \package{longtable} has used the internal counter
+% "\c@LT@tables". The \LaTeX\ counter "table" is still incremented
+% so that "\caption" works correctly.
+% \begin{macrocode}
+\def\LT@array[#1]#2{%
+ \refstepcounter{table}\stepcounter{LT@tables}%
+% \end{macrocode}
+% Set up the glue around the table if an optional argument given.
+% \begin{macrocode}
+ \if l#1%
+ \LTleft\z@ \LTright\fill
+ \else\if r#1%
+ \LTleft\fill \LTright\z@
+ \else\if c#1%
+ \LTleft\fill \LTright\fill
+ \fi\fi\fi
+% \end{macrocode}
+% Set up these internal commands for \env{longtable}.
+% \changes{v3.13}{1994/12/08}
+% {add \cs{tabularnewline}}
+% \changes{v3.14}{1995/04/25}
+% {(Mike Van Geest) rename \cs{LT@mc} to
+% \cs{LT@mcol} to allow 1100 tables}
+% \changes{v4.01}{1996/04/11}
+% {(DPC) dont need multicolumn warning}
+%\begin{verbatim}
+% \global\let\LT@mcw@rn\relax
+%\end{verbatim}
+% \begin{macrocode}
+ \let\LT@mcol\multicolumn
+% \end{macrocode}
+% \changes{v3.17}{1996/01/31}
+% {Reset \cs{hline} and \cs{multicolumn} in nested tabular
+% and array, for tools/2068}
+% Now redefine "\@tabarray" to restore "\hline" and "\multicolumn" so
+% that arrays and tabulars nested in longtable (or in page headings on
+% longtable pages) work out OK. Saving the original definitions done
+% here so that you can load the \package{array} package before or after
+% \package{longtable}.
+% \begin{macrocode}
+ \let\LT@@tabarray\@tabarray
+ \let\LT@@hl\hline
+ \def\@tabarray{%
+ \let\hline\LT@@hl
+% \end{macrocode}
+%\begin{verbatim}
+% \let\multicolumn\LT@mcol
+%\end{verbatim}
+% \begin{macrocode}
+ \LT@@tabarray}%
+ \let\\\LT@tabularcr\let\tabularnewline\\%
+ \def\newpage{\noalign{\break}}%
+% \end{macrocode}
+% \changes{v4.05}{1996/11/12}
+% {\cs{nopagebreak} and \cs{pagebreak} added}
+% More or less standard definitions, but first start a "\noalign".
+% \begin{macrocode}
+ \def\pagebreak{\noalign{\ifnum`}=0\fi\@testopt{\LT@no@pgbk-}4}%
+ \def\nopagebreak{\noalign{\ifnum`}=0\fi\@testopt\LT@no@pgbk4}%
+% \end{macrocode}
+%
+% \begin{macrocode}
+ \let\hline\LT@hline \let\kill\LT@kill\let\caption\LT@caption
+ \@tempdima\ht\strutbox
+% \end{macrocode}
+%
+% \changes{v4.08}{1998/01/20}
+% {Move \cs{@endpbox} definition earlier and define \cs{@@endpbox}
+% and \cs{@@startpbox} for non-array case. tools/2736}
+% \begin{macrocode}
+ \let\@endpbox\LT@endpbox
+% \end{macrocode}
+% Set up internal commands according to Lamport or Mittelbach.
+% \begin{macrocode}
+ \ifx\extrarowheight\@undefined
+% \end{macrocode}
+% Initialise these commands as in \env{tabular} from the \LaTeX\ kernel.
+% \begin{macrocode}
+ \let\@acol\@tabacol
+ \let\@classz\@tabclassz \let\@classiv\@tabclassiv
+ \def\@startpbox{\vtop\LT@startpbox}%
+ \let\@@startpbox\@startpbox
+ \let\@@endpbox\@endpbox
+ \let\LT@LL@FM@cr\@tabularcr
+ \else
+% \end{macrocode}
+% Initialise these commands as in \package{array}. "\d@llar"
+% replaced by "\d@llarbegin" "\d@llarend" in V3.03 to match
+% \package{array} V2.0h. We do not need to set "\d@llarbegin" and
+% "\d@llarend" as the \package{array} package gives them the correct
+% values at the top level.
+% \begin{macrocode}
+ \advance\@tempdima\extrarowheight
+ \col@sep\tabcolsep
+ \let\@startpbox\LT@startpbox\let\LT@LL@FM@cr\@arraycr
+ \fi
+% \end{macrocode}
+% The rest of this macro is mainly based on \package{array} package, but
+% should work for the standard \env{tabular} too.
+% \begin{macrocode}
+ \setbox\@arstrutbox\hbox{\vrule
+ \@height \arraystretch \@tempdima
+ \@depth \arraystretch \dp \strutbox
+ \@width \z@}%
+ \let\@sharp##\let\protect\relax
+% \end{macrocode}
+% Interpret the preamble argument.
+% \begin{macrocode}
+ \begingroup
+ \@mkpream{#2}%
+% \end{macrocode}
+% We need to rename "\@preamble" here as F.M.'s scheme uses
+% "\global", and we may need to nest "\@mkpream", eg for
+% "\multicolumn"
+% or an \env{array}.
+% We do not need to worry about nested \env{longtable}s though!
+% \begin{macrocode}
+ \xdef\LT@bchunk{%
+% \end{macrocode}
+% \changes{v4.00}{1996/04/08}
+% {(DK) Increment Chunk counter}
+% \begin{macrocode}
+ \global\advance\c@LT@chunks\@ne
+ \global\LT@rows\z@\setbox\z@\vbox\bgroup
+% \end{macrocode}
+% \changes{v4.05}{1996/11/12}
+% {\cs{LT@setprevdepth} added}
+% The following line was added in v4.05.
+% In order to get the "\penalties" to work at chunk boundaries
+% Need to take more care about where and when "\lineskip" glue
+% is added. The following does nothing at top of table, and in
+% header chunks, but in normal body chunks it sets "\prevdepth"
+% (to 0pt, but any value would do) so that "\lineskip" glue will
+% be added. the important thing to note is that the glue will be
+% added \emph{after} any vertical material coming from "\noalign".
+% \begin{macrocode}
+ \LT@setprevdepth
+% \end{macrocode}
+%
+% \changes{v4.10}{2000/10/22}
+% {\cs{noexpand} added (as in array.sty) for mathtext.sty, CAR}
+% \begin{macrocode}
+ \tabskip\LTleft \noexpand\halign to\hsize\bgroup
+% \tabskip\LTleft\halign to\hsize\bgroup
+ \tabskip\z@ \@arstrut \@preamble \tabskip\LTright \cr}%
+ \endgroup
+% \end{macrocode}
+% Find out how many columns we have (store in "\LT@cols").
+% \begin{macrocode}
+ \expandafter\LT@nofcols\LT@bchunk&\LT@nofcols
+% \end{macrocode}
+% Get the saved row from "\LT@i"\ldots"\LT@ix" (from the
+% ".aux" file), or make a new blank row.
+% \begin{macrocode}
+ \LT@make@row
+% \end{macrocode}
+% A few more internal commands for \env{longtable}.
+% \begin{macrocode}
+ \m@th\let\par\@empty
+ \everycr{}\lineskip\z@\baselineskip\z@
+% \end{macrocode}
+% Start the first chunk.
+% \begin{macrocode}
+ \LT@bchunk}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\LT@no@pgbk}
+% \changes{v4.05}{1996/11/12}
+% {Macro added}
+% Can simplify the standard "\@no@pgbk" as this is vmode only
+% but then need to close the "\noalign".
+% \begin{macrocode}
+\def\LT@no@pgbk#1[#2]{\penalty #1\@getpen{#2}\ifnum`{=0\fi}}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\LT@start}
+% This macro starts the process of putting the table on the current
+% page. It is not called until either a "\\" or "\endlongtable" command
+% ends a chunk, as we do not know until that point which of the four
+% possible head or foot sections have been specified.
+%
+% It begins by redefining itself, so that the table is only started
+% once! Until V3.04, was redefined to "\relax", now use "\endgraf" to
+% force the page-breaker to wake up.
+% \begin{macrocode}
+\def\LT@start{%
+ \let\LT@start\endgraf
+ \endgraf\penalty\z@\vskip\LTpre
+% \end{macrocode}
+% Start a new page if there is not enough room for the table head, foot,
+% and one extra line.
+% \begin{macrocode}
+ \dimen@\pagetotal
+ \advance\dimen@ \ht\ifvoid\LT@firsthead\LT@head\else\LT@firsthead\fi
+ \advance\dimen@ \dp\ifvoid\LT@firsthead\LT@head\else\LT@firsthead\fi
+ \advance\dimen@ \ht\LT@foot
+% \end{macrocode}
+% \changes{v3.16}{1995/11/09}
+% {Measure the first line of the table}
+% At this point I used to add "\ht\@arstrutbox" and "\dp\@arstrutbox"
+% as a measure of a row size. However this can fail spectacularly
+% for "p" columns which might be much larger. Previous versions could
+% end up with the table starting with a foot, then a page break then
+% a head \emph{then} a `first head'! So now measure the first line of
+% the table accurately by "\vsplit"ting it out of the first chunk.
+% \begin{macrocode}
+ \dimen@ii\vfuzz
+ \vfuzz\maxdimen
+ \setbox\tw@\copy\z@
+ \setbox\tw@\vsplit\tw@ to \ht\@arstrutbox
+ \setbox\tw@\vbox{\unvbox\tw@}%
+ \vfuzz\dimen@ii
+ \advance\dimen@ \ht
+ \ifdim\ht\@arstrutbox>\ht\tw@\@arstrutbox\else\tw@\fi
+ \advance\dimen@\dp
+ \ifdim\dp\@arstrutbox>\dp\tw@\@arstrutbox\else\tw@\fi
+% \end{macrocode}
+%
+% \begin{macrocode}
+ \advance\dimen@ -\pagegoal
+ \ifdim \dimen@>\z@\vfil\break\fi
+% \end{macrocode}
+% Store height of page minus table foot in "\@colroom".
+% \changes{v3.14}{1995/05/02}
+% {Set \cs{@colroom}, for tools/1584}
+% \begin{macrocode}
+ \global\@colroom\@colht
+% \end{macrocode}
+% If the foot is non empty, reduce the "\vsize" and "\@colroom"
+% accordingly.
+% \begin{macrocode}
+ \ifvoid\LT@foot\else
+ \advance\vsize-\ht\LT@foot
+ \global\advance\@colroom-\ht\LT@foot
+ \dimen@\pagegoal\advance\dimen@-\ht\LT@foot\pagegoal\dimen@
+ \maxdepth\z@
+ \fi
+% \end{macrocode}
+% Put the table head on the page, and then switch to the new output
+% routine.
+% \changes{v4.11}{2004/02/01}
+% {\cs{nobreak}, for tools/3484}
+% \begin{macrocode}
+ \ifvoid\LT@firsthead\copy\LT@head\else\box\LT@firsthead\fi\nobreak
+ \output{\LT@output}}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\endlongtable}
+% Called by "\end{longtable}".
+% \begin{macrocode}
+\def\endlongtable{%
+% \end{macrocode}
+% Essentially add a final "\\". But as we now know the number of
+% actual chunks, we first strip away all entries referring to a
+% maximum entry beyond the table (this can only happen if a table has
+% been shortened, or the table numbering has gone awry). In that case
+% we at least start collecting valid new information with the last
+% chunk of this table, by removing the width constraint.
+% \changes{v4.01}{1996/04/11}
+% {(DPC) use \cs{noalign} to sneak in \cs{LT@entry@chop}}
+% \begin{macrocode}
+ \crcr
+ \noalign{%
+ \let\LT@entry\LT@entry@chop
+ \xdef\LT@save@row{\LT@save@row}}%
+ \LT@echunk
+ \LT@start
+ \unvbox\z@
+ \LT@get@widths
+% \end{macrocode}
+% Write the dummy row to the ".aux" file.
+% Since V3.06, use ".lta" for "letter.sty".
+% \changes{v3.12}{1994/06/30}
+% {Do not write if \cs{nofiles} in operation.}
+% \begin{macrocode}
+ \if@filesw
+ {\let\LT@entry\LT@entry@write\immediate\write\@auxout{%
+% \end{macrocode}
+% Since Version 3.02, \package{longtable} has used the internal counter
+% "\c@LT@tables" rather than the \LaTeX\ counter \textsf{table}. This
+% information looks entirely different from version~3
+% information. Still, we don't need to rename the macro name because
+% later code will consider the information to have no columns, and
+% thus will throw the old data away.
+% \begin{macrocode}
+ \gdef\expandafter\noexpand
+ \csname LT@\romannumeral\c@LT@tables\endcsname
+ {\LT@save@row}}}%
+ \fi
+% \end{macrocode}
+% At this point used to
+% issue a warning if a "\multicolumn" has been set in draft mode.
+% \changes{v4.01}{1996/04/11}
+% {(DPC) No need for multicolumn warnings}
+%\begin{verbatim}
+% \LT@mcw@rn
+%\end{verbatim}
+% If the last chunk has different widths than the first, warn the user.
+% Also trigger a warning to rerun \LaTeX\ at the end of the document.
+% \changes{v4.04}{1996/05/24}
+% {Use \cs{LT@final@warn}}
+% \begin{macrocode}
+ \ifx\LT@save@row\LT@@save@row
+ \else
+ \LT@warn{Column \@width s have changed\MessageBreak
+ in table \thetable}%
+ \LT@final@warn
+ \fi
+% \end{macrocode}
+% Force one more go with the \env{longtable} output routine.
+% \begin{macrocode}
+ \endgraf\penalty -\LT@end@pen
+% \end{macrocode}
+% Now close the group to return to the standard routine.
+% \begin{macrocode}
+ \endgroup
+% \end{macrocode}
+% Reset "\@mparbottom" to allow marginpars close to the end of the
+% table.\footnote{This can not be the correct. However if it is omitted,
+% there is a problem with marginpars, for example on page~3 of this
+% document. Any Output Routine Gurus out there?}
+% \begin{macrocode}
+ \global\@mparbottom\z@
+ \pagegoal\vsize
+ \endgraf\penalty\z@\addvspace\LTpost
+% \end{macrocode}
+% Footnotes. As done in the \package{multicol} package.
+% \begin{macrocode}
+ \ifvoid\footins\else\insert\footins{}\fi}
+% \end{macrocode}
+% \end{macro}
+%
+% \subsection{Counting Columns}
+%
+% Columns are counted by examining "\@preamble", rather than simply
+% getting "\@mkpream" to increment the counter as it builds the
+% preamble so that this package works with many of the packages which
+% add extra column specifiers to \LaTeX's standard ones.
+%
+% Version~1 counted "\@sharp"'s to calculate the number of columns,
+% this was changed for Version~2 as it does not work with the NFSS. Now
+% count "&"'s. ("lfonts.new" (and now the Standard \LaTeX\ definition)
+% defines "\@tabclassz" so that "\@sharp" is inside a group.)
+%
+% \begin{macro}{\LT@nofcols}
+% Find the next "&", then look ahead to see what is next.
+% \begin{macrocode}
+\def\LT@nofcols#1&{%
+ \futurelet\@let@token\LT@n@fcols}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\LT@n@fcols}
+% Add one, then stop at an "\LT@nofcols" or look for the next
+% "&". The "\expandafter" trick was added in Version~3, also the
+% name changed from "\@LT@nofcols" to preserve the "\LT@" naming
+% convention.
+% \begin{macrocode}
+\def\LT@n@fcols{%
+ \advance\LT@cols\@ne
+ \ifx\@let@token\LT@nofcols
+ \expandafter\@gobble
+ \else
+ \expandafter\LT@nofcols
+ \fi}
+% \end{macrocode}
+% \end{macro}
+%
+% \subsection{The {\ttfamily\bslash\bslash} and \cs{kill} Commands}
+%
+% \begin{macro}{\LT@tabularcr}
+% \changes{v4.05}{1996/11/12}
+% {Code re-organised for the *-form processing.}
+% The internal definition of "\\".
+% In the "*" form, insert a "\nobreak" after the next "\cr" (or "\crcr").
+%
+% This star form processing was finally added in v4.05. For the previous
+% six or seven years the comment at this point said
+% \begin{quote}\small
+% This definition also accepts "\\*", which acts in the same way as
+% "\\". \env{tabular} does this, but \env{longtable} probably ought to
+% make "\\*" prevent page breaking.
+% \end{quote}
+%
+% "{\ifnum0=`}\fi" added in version 3.01, required if the first entry
+% is empty.
+% The above in fact is not good enough, as with \package{array} package
+% it can introduce a "{}" group in math mode, which changes the spacing.
+% So use the following variant. Added in v3.14.
+% \changes{v3.14}{1995/04/25}
+% {More fun with \cs{ifnum} cf tools/1571}
+% \begin{macrocode}
+\def\LT@tabularcr{%
+ \relax\iffalse{\fi\ifnum0=`}\fi
+ \@ifstar
+ {\def\crcr{\LT@crcr\noalign{\nobreak}}\let\cr\crcr
+ \LT@t@bularcr}%
+ {\LT@t@bularcr}}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\LT@crcr}
+% \changes{v4.05}{1996/11/12}
+% {Macro added}
+% \begin{macrocode}
+\let\LT@crcr\crcr
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\LT@setprevdepth}
+% \changes{v4.05}{1996/11/12}
+% {Macro added}
+% This will be redefined to set the "\prevdepth"
+% at the start of a chunk.
+% \begin{macrocode}
+\let\LT@setprevdepth\relax
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\LT@t@bularcr}
+% \begin{macrocode}
+\def\LT@t@bularcr{%
+% \end{macrocode}
+% Increment the counter, and do \env{tabular}'s "\\" or finish the
+% chunk.\\ The "\expandafter" trick was added in Version~3.
+% Set the "\prevdepth" at the start of a new chunk. (Done here
+% so not set in header chunks).
+% \begin{macrocode}
+ \global\advance\LT@rows\@ne
+ \ifnum\LT@rows=\LTchunksize
+ \gdef\LT@setprevdepth{%
+ \prevdepth\z@\global
+ \global\let\LT@setprevdepth\relax}%
+ \expandafter\LT@xtabularcr
+ \else
+ \ifnum0=`{}\fi
+ \expandafter\LT@LL@FM@cr
+ \fi}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\LT@xtabularcr}
+% This justs looks for an optional argument.
+% \begin{macrocode}
+\def\LT@xtabularcr{%
+ \@ifnextchar[\LT@argtabularcr\LT@ntabularcr}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\LT@ntabularcr}
+% The version with no optional argument.
+% "\ifnum0=`{\fi}" added in version 3.01. Changed in 3.14.
+% \begin{macrocode}
+\def\LT@ntabularcr{%
+ \ifnum0=`{}\fi
+ \LT@echunk
+ \LT@start
+ \unvbox\z@
+ \LT@get@widths
+ \LT@bchunk}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\LT@argtabularcr}
+% The version with an optional argument.
+% "\ifnum0=`{\fi}" added in version 3.01. Changed in 3.14.
+% \begin{macrocode}
+\def\LT@argtabularcr[#1]{%
+ \ifnum0=`{}\fi
+ \ifdim #1>\z@
+ \unskip\@xargarraycr{#1}%
+ \else
+ \@yargarraycr{#1}%
+ \fi
+% \end{macrocode}
+% Add the dummy row, and finish the "\halign".
+% \begin{macrocode}
+ \LT@echunk
+ \LT@start
+ \unvbox\z@
+ \LT@get@widths
+ \LT@bchunk}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\LT@echunk}
+% \changes{v4.05}{1996/11/12}
+% {\cs{unskip} added for pagebreak support}
+% This ends the current chunk, and removes the dummy row.
+% \begin{macrocode}
+\def\LT@echunk{%
+ \crcr\LT@save@row\cr\egroup
+ \global\setbox\@ne\lastbox
+% \end{macrocode}
+% The following line was added in v4.05.
+% \package{longtable} relies on "\lineskip" glue (which is 0pt) to
+% provide break points between each row so the table may be split
+% into pages.
+%
+% Previous releases left the "\lineskip" glue at the end of each chunk
+% that had been added when the dummy row was added. There was no glue
+% at the start of the next chunk as \TeX\ normally dooes not put
+% "\lineskip" glue at the top of a box. This meant that normally the
+% chunks fitted together perfectly, however "\noalign" material at a
+% chunk boundary came before the first row of the next chunk
+% but after the lineskip glue at the end of this chunk. This is the
+% wrong place, e.g., it means even a "\penalty10000" does not stop a
+% break as the "\lineskip" glue in the previous item on the list
+% provides a legal breakpoint. So now remove the "\lineskip" glue that
+% was before the dummy row and introduce "\LT@setprevdepth" to set the
+% "\prevdepth" at the start of the next chunk, to make sure "\lineskip"
+% glue is added later.
+% \begin{macrocode}
+ \unskip
+ \egroup}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\LT@entry}
+% \changes{v4.00}{1996/04/08}
+% {(DK) Macro added}
+% \changes{v4.01}{1996/04/11}
+% {(DPC) Use \cs{ifhmode} trick to determine first entry}
+% We here give the `basic' definition of "\LT@entry", namely that used
+% in alignment templates. It has a "\kern" only if the maximum is
+% imposed from a different chunk.
+% The "\ifhmode" test reveals the first entry, when we don't want to add
+% an "&".
+% \begin{macrocode}
+\def\LT@entry#1#2{%
+ \ifhmode\@firstofone{&}\fi\omit
+ \ifnum#1=\c@LT@chunks
+ \else
+ \kern#2\relax
+ \fi}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\LT@entry@chop}
+% \changes{v4.00}{1996/04/08}
+% {(DK) Macro added}
+% This definition for the argument of "\LT@save@row" is used to scrap
+% all those maxima which could not be verified because they occur
+% after the end of the table. This can happen only if a table has been
+% shortened (or the sequencing got mixed up) since the
+% previous run.
+% Note that this is premature: the last chunk still is going to be
+% set, and with the chopped limits.
+% \begin{macrocode}
+\def\LT@entry@chop#1#2{%
+ \noexpand\LT@entry
+ {\ifnum#1>\c@LT@chunks
+ 1}{0pt%
+ \else
+ #1}{#2%
+ \fi}}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\LT@entry@write}
+% \changes{v4.07}{1997/10/16}
+% {Avoid use of percent. tools/2631}
+% To write an entry for the "aux" file, we use a slightly
+% surprising definition which has the sole purpose of avoiding
+% overfull lines (which might break \TeX{}'s limits when reading the
+% "aux" file, probably you'd need to have a few hundred columns before
+% this happened but\ldots).
+% \begin{macrocode}
+\def\LT@entry@write{%
+ \noexpand\LT@entry^^J%
+ \@spaces}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\LT@kill}
+% This ends the current chunk as above, but strips off two rows, the
+% `dummy row' and the `killed row' before starting the next chunk.
+% Since V3.04, the old chunk is reboxed at the start of the box
+% containing the next chunk. This allows "\kill" to be used in headers,
+% which must be processed in a single box.
+% \begin{macrocode}
+\def\LT@kill{%
+ \LT@echunk
+ \LT@get@widths
+ \expandafter\LT@rebox\LT@bchunk}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\LT@rebox}
+% Drop the old chunk (box0) back at the top of the new chunk, removing
+% the killed row. This macro added at V3.04.
+% \begin{macrocode}
+\def\LT@rebox#1\bgroup{%
+ #1\bgroup
+ \unvbox\z@
+ \unskip
+ \setbox\z@\lastbox}
+% \end{macrocode}
+% \end{macro}
+%
+% \subsection{The Dummy Row}
+%
+% The dummy row is kept inside of the macro "\LT@save@row".
+%
+% \begin{macro}{\LT@blank@row}
+% \begin{macro}{\LT@build@blank}
+% \changes{v4.00}{1996/04/08}
+% {(DK) Macro added}
+% \changes{v4.01}{1996/04/11}
+% {(DPC) Dont mess with \cs{multicolumn} on draft passes}
+% Create a blank row if we are not using the info in the ".aux" file.
+% \begin{macrocode}
+\def\LT@blank@row{%
+ \xdef\LT@save@row{\expandafter\LT@build@blank
+ \romannumeral\number\LT@cols 001 }}
+% \end{macrocode}
+% Whoops! What's that supposed to be? A drop-in replacement for the
+% first task of Appendix~D in the \TeX book. The "\romannumeral"
+% produces "\LT@cols" instances of "m" followed by "i". The below
+% macro then replaces the "m"s by appropriate entries.
+% \begin{macrocode}
+\def\LT@build@blank#1{%
+ \if#1m%
+ \noexpand\LT@entry{1}{0pt}%
+ \expandafter\LT@build@blank
+ \fi}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\LT@make@row}
+% \changes{v4.00}{1996/04/08}
+% {(DK) New implementation}
+% \changes{v4.01}{1996/04/11}
+% {(DPC) Make this the default behaviour, not needing
+% \cs{setlongtables}}
+%
+% Prior to version 4, by default did not use information in the
+% ".aux" file but now we can define "\LT@make@row" to use the ".aux"
+% file, even on the `draft' passes.
+% \begin{macrocode}
+\def\LT@make@row{%
+ \global\expandafter\let\expandafter\LT@save@row
+ \csname LT@\romannumeral\c@LT@tables\endcsname
+ \ifx\LT@save@row\relax
+ \LT@blank@row
+% \end{macrocode}
+% Now a slightly difficult part comes. Before we decide making the
+% template from the ".aux" file info we check that the number of
+% fields has remained the same. If it hasn't, either the table format
+% has changed, or we have the wrong table altogether. In both cases,
+% we decide to better drop all gathered information and start over.
+% \changes{v4.01}{1996/04/11}
+% {(DPC) Use \cs{if} test rather than \cs{ifx}\cs{@empty}}
+%
+% The expansion between "!"\ldots"!" below will be empty if the number
+% of "\LT@entry" macros
+% including arguments in "\LT@save@row" is equal to "\LT@cols". If it
+% is not empty, we throw the row away and start from scratch.
+% \begin{macrocode}
+ \else
+ {\let\LT@entry\or
+ \if!%
+ \ifcase\expandafter\expandafter\expandafter\LT@cols
+ \expandafter\@gobble\LT@save@row
+ \or
+ \else
+ \relax
+ \fi
+ !%
+ \else
+ \aftergroup\LT@blank@row
+ \fi}%
+ \fi}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\setlongtables}
+% Redefine "\LT@make@row" to use information in the ".aux" file,
+% if there is a saved row for this table with the right number of
+% columns.
+%
+% Since Version 3.02, \package{longtable} has used the internal counter
+% "\c@LT@tables" rather than the \LaTeX\ counter \textsf{table}.
+% The warning message was added at V3.04, as was the "\global", to stop
+% save-stack overflow.
+%
+% Since Version 4.01 "\setlongtables" does nothing as it is not
+% needed, but is defined as "\relax" for the benefit of old documents.
+% \changes{v3.12}{1994/06/30}
+% {Warning altered to fit line on terminal.}
+% \changes{v4.01}{1996/04/11}
+% {(DPC) make into no op}
+% \begin{macrocode}
+\let\setlongtables\relax
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\LT@get@widths}
+% This is the heart of \package{longtable}. If it were not for the table
+% head and foot, this macro together with the modified "\\" command
+% would form the basis of quite a simple little package file for long
+% tables. It is closely modelled on the "\endvrulealign" macro of
+% appendix D of the \TeX book.
+% \begin{macrocode}
+\def\LT@get@widths{%
+% \end{macrocode}
+% "\global" added at V3.04, to stop save-stack overflow.
+% \begin{macrocode}
+% \end{macrocode}
+% Loop through the last row, discarding glue, and saving box widths. At
+% V3.04 changed the scratch box to 2, as the new "\kill" requires that
+% "\box0" be preserved.
+% \begin{macrocode}
+ \setbox\tw@\hbox{%
+ \unhbox\@ne
+ \let\LT@old@row\LT@save@row
+ \global\let\LT@save@row\@empty
+ \count@\LT@cols
+ \loop
+ \unskip
+ \setbox\tw@\lastbox
+ \ifhbox\tw@
+ \LT@def@row
+ \advance\count@\m@ne
+ \repeat}%
+% \end{macrocode}
+% Remember the widths if we are in the first chunk.
+% \begin{macrocode}
+ \ifx\LT@@save@row\@undefined
+ \let\LT@@save@row\LT@save@row
+ \fi}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\LT@def@row}
+% \changes{v4.00}{1996/04/08}
+% {(DK) New implementation}
+% Add a column to the dummy row. Name changed from "\defLT@save@row"
+% in Version~3, to preserve the "\LT@" naming convention.
+% \begin{macrocode}
+\def\LT@def@row{%
+% \end{macrocode}
+% We start by picking the respective entry from our old row.
+% These redefinitions of "\LT@entry" are local to the group started
+% in "\LT@get@widths".
+% \begin{macrocode}
+ \let\LT@entry\or
+ \edef\@tempa{%
+ \ifcase\expandafter\count@\LT@old@row
+ \else
+ {1}{0pt}%
+ \fi}%
+% \end{macrocode}
+% Now we tack the right combination in front of "\LT@save@row":
+% \begin{macrocode}
+ \let\LT@entry\relax
+ \xdef\LT@save@row{%
+ \LT@entry
+ \expandafter\LT@max@sel\@tempa
+ \LT@save@row}}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\LT@max@sel}
+% \changes{v4.00}{1996/04/08}
+% {(DK) macro added}
+% \changes{v4.01}{1996/04/11}
+% {(DPC) minor modifications}
+% And this is how to select the right combination. Note that we take
+% the old maximum information only if the size does not change in
+% \emph{either} direction. If the size has grown, we of course have a
+% new maximum. If the size has shrunk, the old maximum (which was
+% explicitly not enforced because of being in the current chunk) is
+% invalid, and we start with this chunk as the new size. Note that
+% even in the case of equality we \emph{must} use the "\the\wd\tw@"
+% construct instead of "#2" because "#2" might be read in from the
+% file, and so could have "\catcode"~11 versions of "p" and~"t" in~it
+% which we want to be replaced by their `proper' "\catcode"~12 versions.
+% \begin{macrocode}
+\def\LT@max@sel#1#2{%
+ {\ifdim#2=\wd\tw@
+ #1%
+ \else
+ \number\c@LT@chunks
+ \fi}%
+ {\the\wd\tw@}}
+% \end{macrocode}
+% \end{macro}
+%
+% \subsection{The \cs{hline} Command}
+%
+% \begin{macro}{\LT@hline}
+% "\hline" and "\hline\hline" both produce \emph{two} lines.
+% The only difference being the glue and penalties between them.
+% This is so that a page break at a "\hline" produces a line on both
+% pages.\footnote
+% {\env{longtable} has always done this, but perhaps it would be
+% better if hlines were \emph{omitted} at a page break, as the head and
+% foot usually put a hline here anyway.}
+% Also this "\hline" is more like a "\cline{1-\LT@cols}".
+% \env{tabular}'s "\hline" would draw lines the full width of the page.
+% \begin{macrocode}
+\def\LT@hline{%
+ \noalign{\ifnum0=`}\fi
+ \penalty\@M
+ \futurelet\@let@token\LT@@hline}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\LT@@hline}
+% This code is based on "\cline". Two copies of the line are produced,
+% as described above.
+% \begin{macrocode}
+\def\LT@@hline{%
+ \ifx\@let@token\hline
+ \global\let\@gtempa\@gobble
+ \gdef\LT@sep{\penalty-\@medpenalty\vskip\doublerulesep}%
+ \else
+ \global\let\@gtempa\@empty
+ \gdef\LT@sep{\penalty-\@lowpenalty\vskip-\arrayrulewidth}%
+ \fi
+ \ifnum0=`{\fi}%
+ \multispan\LT@cols
+ \unskip\leaders\hrule\@height\arrayrulewidth\hfill\cr
+ \noalign{\LT@sep}%
+ \multispan\LT@cols
+ \unskip\leaders\hrule\@height\arrayrulewidth\hfill\cr
+ \noalign{\penalty\@M}%
+ \@gtempa}
+% \end{macrocode}
+% \end{macro}
+%
+% \subsection{Captions}
+%
+% \begin{macro}{\LT@caption}
+% The caption is "\multicolumn{\LT@cols}{c}{"\meta{a parbox with the
+% table's caption}"}"
+% \begin{macrocode}
+\def\LT@caption{%
+ \noalign\bgroup
+ \@ifnextchar[{\egroup\LT@c@ption\@firstofone}\LT@capti@n}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\LT@c@ption}
+% Caption command (with [optional argument]). "\protect" added in
+% Version~3. "\fnum@table" added at V3.05.
+% \changes{v3.14}{1995/05/02}
+% {Call \cs{LT@makecaption} not \cs{LT@mkcaption}}
+% \changes{v3.14}{1995/05/24}
+% {Add new control argument}
+% \begin{macrocode}
+\def\LT@c@ption#1[#2]#3{%
+ \LT@makecaption#1\fnum@table{#3}%
+ \def\@tempa{#2}%
+ \ifx\@tempa\@empty\else
+ {\let\\\space
+ \addcontentsline{lot}{table}{\protect\numberline{\thetable}{#2}}}%
+ \fi}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\LT@capti@n}
+% Caption command (no [optional argument])
+% \changes{v3.14}{1995/05/02}
+% {Call \cs{LT@makecaptionx} not \cs{LT@mkcaption}}
+% \changes{v3.14}{1995/05/24}
+% {Call \cs{LT@makecaption} with \cs{@gobble} or \cs{@firstofone}}
+% \begin{macrocode}
+\def\LT@capti@n{%
+ \@ifstar
+ {\egroup\LT@c@ption\@gobble[]}%
+ {\egroup\@xdblarg{\LT@c@ption\@firstofone}}}
+% \end{macrocode}
+% \end{macro}
+%
+%
+% \begin{macro}{\LT@makecaption}
+% Put the caption in a box of width 0pt, so that it never affects the
+% column widths. Inside that is a "\parbox" of width
+% "\LTcapwidth".
+% \changes{v3.14}{1995/05/02}
+% {Renamed from \cs{LT@mkcaption},
+% and modified to call \cs{@makecaption}}
+% \changes{v3.14}{1995/05/02}
+% {Use the first arg to remove counter for star form}
+% \begin{macrocode}
+\def\LT@makecaption#1#2#3{%
+ \LT@mcol\LT@cols c{\hbox to\z@{\hss\parbox[t]\LTcapwidth{%
+% \end{macrocode}
+% Based on article class "\@makecaption", "#1" is "\@gobble" in star
+% form, and "\@firstofone" otherwise.
+% \begin{macrocode}
+ \sbox\@tempboxa{#1{#2: }#3}%
+ \ifdim\wd\@tempboxa>\hsize
+ #1{#2: }#3%
+ \else
+ \hbox to\hsize{\hfil\box\@tempboxa\hfil}%
+ \fi
+ \endgraf\vskip\baselineskip}%
+ \hss}}}
+% \end{macrocode}
+% \end{macro}
+%
+%
+% \subsection{The Output Routine}
+%
+% The method used here for interfacing a special purpose output routine
+% to the standard \LaTeX\ routine is lifted straight out of
+% F.~Mittelbach's \package{multicol} package.
+%
+% \begin{macro}{\LT@output}
+% Actually this is not so bad, with FM leading the way.
+% \begin{macrocode}
+\def\LT@output{%
+ \ifnum\outputpenalty <-\@Mi
+ \ifnum\outputpenalty > -\LT@end@pen
+% \end{macrocode}
+% If this was a float or a marginpar we complain.
+% \begin{macrocode}
+ \LT@err{floats and marginpars not allowed in a longtable}\@ehc
+ \else
+% \end{macrocode}
+% We have reached the end of the table, on the scroll at least,
+% \begin{macrocode}
+ \setbox\z@\vbox{\unvbox\@cclv}%
+ \ifdim \ht\LT@lastfoot>\ht\LT@foot
+% \end{macrocode}
+% The last foot might not fit, so:\footnote{An alternative would be to
+% vsplit off a bit of the last chunk, so that the last page did not just
+% have head and foot sections, but it is hard to do this in a consistent
+% manner.}
+% \begin{macrocode}
+ \dimen@\pagegoal
+ \advance\dimen@-\ht\LT@lastfoot
+ \ifdim\dimen@<\ht\z@
+ \setbox\@cclv\vbox{\unvbox\z@\copy\LT@foot\vss}%
+ \@makecol
+ \@outputpage
+ \setbox\z@\vbox{\box\LT@head}%
+% \end{macrocode}
+% End of "\ifdim\dimen@<\ht\@cclc".
+% \begin{macrocode}
+ \fi
+% \end{macrocode}
+% End of "\ifdim \ht\LT@lastfoot > \ht\LT@foot".
+% \begin{macrocode}
+ \fi
+% \end{macrocode}
+% Reset "\@colroom".
+% \changes{v3.14}{1995/05/02}
+% {Reset \cs{@colroom}, for tools/1584}
+% \begin{macrocode}
+ \global\@colroom\@colht
+ \global\vsize\@colht
+% \end{macrocode}
+% Put the last page of the table on to the main vertical list.
+% \begin{macrocode}
+ \vbox
+ {\unvbox\z@\box\ifvoid\LT@lastfoot\LT@foot\else\LT@lastfoot\fi}%
+% \end{macrocode}
+% End of "\ifnum\outputpenalty > -\LT@end@pen".
+% \begin{macrocode}
+ \fi
+% \end{macrocode}
+% Else "\outputpenalty > -\@Mi".
+% \begin{macrocode}
+ \else
+% \end{macrocode}
+% If we have not reached the end of the table,
+% \begin{macrocode}
+ \setbox\@cclv\vbox{\unvbox\@cclv\copy\LT@foot\vss}%
+ \@makecol
+ \@outputpage
+% \end{macrocode}
+% Reset "\vsize".
+% \changes{v3.14}{1995/05/02}
+% {Reset \cs{vsize}, for tools/1584}
+% \begin{macrocode}
+ \global\vsize\@colroom
+% \end{macrocode}
+% Put the head at the top of the next page.
+% \changes{v4.11}{2004/02/01}
+% {\cs{nobreak}, for tools/3484}
+% \begin{macrocode}
+ \copy\LT@head\nobreak
+% \end{macrocode}
+% End of "\ifnum\outputpenalty <-\@Mi".
+% \begin{macrocode}
+ \fi}
+% \end{macrocode}
+% \end{macro}
+%
+% \subsection{Commands for the the table head and foot}
+%
+% \begin{macro}{\LT@end@hd@ft}
+% The core of "\endhead" and friends. Store the current chunk in the
+% box specified by "#1". Issue an error if the table has already
+% started. Then start a new chunk.
+% \begin{macrocode}
+\def\LT@end@hd@ft#1{%
+ \LT@echunk
+% \end{macrocode}
+% Changed from "\relax" to "\endgraf" at V3.04, see "\LT@start".
+% \begin{macrocode}
+ \ifx\LT@start\endgraf
+ \LT@err
+ {Longtable head or foot not at start of table}%
+ {Increase LTchunksize}%
+ \fi
+ \setbox#1\box\z@
+ \LT@get@widths
+ \LT@bchunk}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\endfirsthead}
+% \begin{macro}{\endhead}
+% \begin{macro}{\endfoot}
+% \begin{macro}{\endlastfoot}
+% Call "\LT@end@hd@ft" with the appropriate box.
+% \begin{macrocode}
+\def\endfirsthead{\LT@end@hd@ft\LT@firsthead}
+\def\endhead{\LT@end@hd@ft\LT@head}
+\def\endfoot{\LT@end@hd@ft\LT@foot}
+\def\endlastfoot{\LT@end@hd@ft\LT@lastfoot}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+% \subsection{The \cs{multicolumn} command}
+%
+% Earlier versions needed a special `draft' form of "\multicolumn".
+% This is not needed in version~4, and so these commands have been
+% removed.
+%
+% \begin{macro}{\LTmulticolumn}
+% \changes{v4.01}{1996/04/11}
+% {(DPC) macro removed}
+% \end{macro}
+%
+% \begin{macro}{\LT@mcwarn}
+% \changes{v4.01}{1996/04/11}
+% {(DPC) macro removed}
+% \end{macro}
+%
+% \subsection{Footnotes}
+%
+% The standard "\footnote" command works in a "c" column, but we
+% need to modify the definition in a "p" column to overcome the
+% extra level of boxing. These macros are based on the \package{array}
+% package, but should be OK for the standard \env{tabular}.
+%
+% \begin{macro}{\LT@startpbox}
+% \changes{v4.09}{1998/05/13}
+% {Use \cs{setlength}, so that calc extensions apply. tools/2793}
+% Add extra code to switch the definition of "\@footnotetext".
+% \begin{macrocode}
+\def\LT@startpbox#1{%
+ \bgroup
+ \let\@footnotetext\LT@p@ftntext
+ \setlength\hsize{#1}%
+ \@arrayparboxrestore
+ \vrule \@height \ht\@arstrutbox \@width \z@}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\LT@endpbox}
+% After the parbox is closed, expand "\LT@p@ftn" which will execute a
+% series of\\
+% "\footnotetext["\meta{num}"]{"\meta{note}"}"\\
+% commands. After being lifted out of the parbox, they can migrate on
+% their own from here.
+% \changes{v3.10}{1994/05/15}
+% {Use \cs{@finalstrut}}
+% \changes{v4.03}{1996/05/07}
+% {Use \cs{hfil} for tools/2120}
+% \begin{macrocode}
+\def\LT@endpbox{%
+ \@finalstrut\@arstrutbox
+ \egroup
+ \the\LT@p@ftn
+ \global\LT@p@ftn{}%
+ \hfil}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\LT@p@ftntext}
+% Inside the `p' column, just save up the footnote text in a token
+% register.
+% \begin{macrocode}
+\def\LT@p@ftntext#1{%
+ \edef\@tempa{\the\LT@p@ftn\noexpand\footnotetext[\the\c@footnote]}%
+ \global\LT@p@ftn\expandafter{\@tempa{#1}}}%
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macrocode}
+%</package>
+% \end{macrocode}
+%
+% \Finale
+\endinput
+
diff --git a/Master/texmf-dist/source/latex/tools/multicol.dtx b/Master/texmf-dist/source/latex/tools/multicol.dtx
new file mode 100644
index 00000000000..4575bb41be0
--- /dev/null
+++ b/Master/texmf-dist/source/latex/tools/multicol.dtx
@@ -0,0 +1,3472 @@
+% \iffalse meta-comment
+%
+% Copyright 1993 1994 1995 1996 1997 1998 1999 2000 2001 2002 2003
+% The LaTeX3 Project and any individual authors listed elsewhere
+% in this file.
+%
+% This file is part of the Standard LaTeX `Tools Bundle'.
+% -------------------------------------------------------
+%
+% It 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.3 or later is part of all distributions of LaTeX
+% version 2003/12/01 or later.
+%
+% The list of all files belonging to the LaTeX `Tools Bundle' is
+% given in the file `manifest.txt'.
+%
+% \fi
+%
+% \iffalse This is a METACOMMENT
+%
+%% Package `multicol' to use with LaTeX2e
+%% Copyright 1989-2003 Frank Mittelbach
+%%
+%% In addition to the terms of LPPL any distributed version
+%% (unchanged or modified) of multicol has to keep the statement
+%% about the moral obligation for using multicol. In case of major
+%% changes where this would not be appropriate the author of the
+%% changed version should contact the copyright holder.
+%%
+%%
+%% Moral obligation for using multicol:
+%% ------------------------------------
+%%
+%% Users of multicol who wish to include or use multicol or a modified
+%% version in a proprietary and commercially market product are asked
+%% under certain conditions (see below) for the payment of a license
+%% fee. The size of this fee is to be determined, in each instance,
+%% by the commercial user, depending on his/her judgment of the value of
+%% multicol for his/her product.
+%%
+%%
+%% The conditions for this are as follows:
+%%
+%% The producer of a proprietary and commercially market product
+%% that involves typesetting using multicol is asked to determine
+%% the value of a license fee for using multicol if
+%%
+%% - the product is a document and the producer has decided to
+%% include multicol to typeset (parts of) the document or has
+%% directed the author of the document to include multicol (for
+%% example, by providing a class file to be used by the author)
+%%
+%% - the product is a LaTeX class or package that includes multicol
+%%
+%%
+%% There is no moral obligation in case
+%%
+%% - the product is a document but producer has not directed
+%% the author to include multicol (in that case the moral obligation
+%% lies with the author of the document)
+%%
+%% - the product does not involve typesetting, e.g., consists, for
+%% example, of distributing multicol and its documentation.
+%%
+%% - the product is not proprietary, i.e., is made available as free
+%% software itself (which doesn't prohibit its commercial marketing)
+%%
+%% - multicol is used for non-commercial purposes
+%%
+%%
+%% Determinating a license fee might result in a license fee of zero
+%% (i.e., no payment) in case a producer has determined that the use
+%% of multicol has no enhancing effect on the product. This is a
+%% plausible scenario, i.e., in the above two cases the producer is
+%% only asked to evaluate the value of multicol for the product
+%% not for the payment of a license fee per se (which might or might
+%% not follow from this evaluation).
+%%
+%% The license fee, if any, can be payed either to the LaTeX3 fund
+%% (see ltx3info.txt in the base LaTeX distribution) or to the author of
+%% the program who can be contacted at
+%%
+%% Frank.Mittelbach@latex-project.org
+%%
+%<*dtx>
+ \ProvidesFile{multicol.dtx}
+%</dtx>
+%<package>\NeedsTeXFormat{LaTeX2e}[1997/12/01]
+%<package>\ProvidesPackage{multicol}
+%<driver> \ProvidesFile{multicol.drv}
+% \fi
+% \ProvidesFile{multicol.dtx}
+ [2004/02/14 v1.6e multicolumn formatting (FMi)]
+%
+%
+%% \CheckSum{1561}
+%% \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 \~}
+%%
+%
+% \changes{v1.5n}{1997/06/05}{Applied improvement of documentation,
+% kindly done by Robin Fairbairns.}
+% \changes{v1.4h}{1992/06/04}{Added mark tracing with
+% tracingmulticols$\ge2$}
+% \changes{v1.4a}{1992/02/11}{Added support for multicol in inner mode}
+% \changes{v1.0d}{1989/05/17}{All lines shortened to 72 or less.}
+% \changes{v1.0e}{1989/06/21}{Redefinition of description env. to use
+% \cs{descriptionmargin}\quotechar=5pt
+% in documentation.}
+% \changes{v1.0f}{1989/07/11}{Changed \cs{z@} to 0pt in redefinition of
+% description.}
+% \changes{v1.1a}{1989/09/20}{\cs{multicolssep} changed to \cs{multicolsep}.}
+%
+% \def\description{\list{}{\labelwidth 0pt \leftmargin\descriptionmargin
+% \itemindent-\leftmargin \let\makelabel\descriptionlabel}}
+% \newdimen\descriptionmargin \descriptionmargin=5pt
+%
+% \DoNotIndex{\@M,\@Mi,\@bsphack,\@cclv,\@colht,\@currlist,\@deferlist}
+% \DoNotIndex{\@elt,\@esphack,\@floatplacement}
+% \DoNotIndex{\@ifundefined,\@ifnextchar,\@makecol}
+% \DoNotIndex{\@ne,\@outputpage,\@scolelt,\@spaces,\@tempb,\@tempcnta}
+% \DoNotIndex{\@width}
+% \DoNotIndex{\addvspace,\advance,\allowbreak}
+% \DoNotIndex{\baselineskip,\begingroup,\box,\columnsep,\copy,\count}
+% \DoNotIndex{\count@,\def,\dimen@,\divide,\docdate}
+% \DoNotIndex{\edef,\eject,\egroup,\else,\endgroup,\endinput}
+% \DoNotIndex{\fi,\fileversion,\filedate}
+% \DoNotIndex{\gdef,\global}
+% \DoNotIndex{\hbox,\hfil,\hrule,\ht,\hss}
+% \DoNotIndex{\ifdim,\ifnum,\ifvoid,\ignorespaces,\insert,\immediate}
+% \DoNotIndex{\let,\loop}
+% \DoNotIndex{\maxdepth,\message,\multiply}
+% \DoNotIndex{\newbox,\newcount,\newdimen,\newskip,\number,\newpage}
+% \DoNotIndex{\outputpenalty,\p@,\penalty}
+% \DoNotIndex{\relax,\repeat,\setbox,\skip,\space,\splitmaxdepth}
+% \DoNotIndex{\splittopskip,\string,\sixt@@n}
+% \DoNotIndex{\the,\thepage,\thr@@,\topskip,\tw@,\typeout}
+% \DoNotIndex{\unvbox,\vbox,\vfill,\vsplit,\voidb@x,\vrule}
+% \DoNotIndex{\write,\wd}
+% \DoNotIndex{\z@}
+%
+% \MakeShortVerb{\|}
+% \newcommand{\mc}{{\sf multicols}}
+% \newcommand{\TUB}{{\sl TUGboat\/}}
+% \newcommand{\TB}{{\sl\TeX book\/}}
+%
+%
+% \setcounter{StandardModuleDepth}{2}
+% \setcounter{collectmore}{3}
+%
+% \GetFileInfo{multicol.dtx}
+% \title{An environment for multicolumn output\thanks{This file
+% has version number \fileversion, last
+% revised \filedate.}%
+% \thanks{Note: This package is released under terms which affect
+% its use in commercial applications. Please see the details at
+% the top of the source file.}}
+% \author{Frank Mittelbach\\
+% {\rm Email:} see top of the source file}
+% \date{Printed \today}
+%
+% \maketitle
+%
+% \begin{abstract}
+% This article describes the use and the implementation of the \mc{}
+% environment. This environment allows switching between
+% one and multicolumn format on the same page. Footnotes are handled
+% correctly (for the most part), but will be placed at the bottom of
+% the page and not under each column. \LaTeX{}'s float mechanism,
+% however, is partly disabled in the current implementation. At the
+% moment only page-wide floats (i.e., star-forms) can be used within
+% the scope of the environment.
+% \end{abstract}
+%
+%
+% \begin{multicols}{3}[\section*{Preface to version 1.5 + 1.6}]
+% \hbadness=10000
+% The 1.5 release contains two major changes: \mc{} will now
+% support up to 10 columns and two more tuning possibilities have
+% been added to the balancing routine. The balancing routine now
+% checks the badness
+% of the resulting columns and rejects solutions that are larger
+% than a certain treshold.
+% At the same time \mc{} has been upgraded to run under \LaTeXe{}.
+%
+% Later changes to 1.5 include |\columnbreak| and |multicols*|.
+%
+% For version 1.6 micro-spacing around the boxes produced by \mc{}
+% has been improved to allow for baseline-grid typesetting.
+% \end{multicols}
+%
+%
+% \setcounter{collectmore}{2}
+% \begin{multicols}{3}[\section{Introduction}]
+% \hbadness=10000
+% Switching between two column and one column layout is possible in
+% \LaTeX{}, but every use of |\twocolumn| or |\onecolumn|
+% starts a new page. Moreover, the last page of two column output
+% isn't balanced and this often results in an empty, or nearly
+% empty, right column. When I started to write macros for {\sf
+% doc.sty} (see ``The {\tt doc}--Option'', \TUB\
+% volume 10~\#2, pp.~245--273) I thought that it would be nice to
+% place the index
+% on the same page as the bibliography. And balancing the last page
+% would not only look better, it also would save space; provided of
+% course that it is also possible to start the next article on the
+% same page. Rewriting the index environment was comparatively easy,
+% but the next goal, designing an environment which takes care of
+% footnotes, floats etc., was a harder task. It took me a whole
+% weekend\footnote{I started with the algorithm given in the \TeX
+% book on page 417. Without this help a weekend would not have been
+% enough. (This remark was made in the documentation of the initial
+% release, since then several hundreds more hours went into it
+% improving the original code.)} to get together the few lines of
+% code below and there is
+% still a good chance that I missed something after all.
+%
+% Try it and, hopefully, enjoy it; and {\em please\/} direct bug
+% reports and suggestions back to Mainz.
+% \end{multicols}
+%
+%
+% \setcounter{collectmore}{0}
+% \begin{multicols}{3}[\section{The User Interface}]
+% \hbadness=10000
+% To use the environment one simply says\\*[2mm]
+% \hspace*{2mm}|\begin{multicols}{|\meta{number}|}|
+% \hspace*{12mm}\meta{multicolumn text}\\
+% \hspace*{2mm}|\end{multicols}|\\[2mm]
+% where \meta{number} is the required number of columns and
+%^^A\meta{multicolumn text}
+% $\langle${\it multi\-column text\/}$\rangle$ may contain arbitrary
+% \LaTeX{} commands, except that floats and marginpars are not
+% allowed in the current implementation\footnote{This is dictated by
+% lack of time. To implement floats one has to reimplement the
+% whole \LaTeX{} output routine.}.
+%
+% \DescribeMacro\premulticols
+% As its first action, the {\sf multicols} environment measures the
+% current page to determine whether there is enough room for some
+% portion of multicolumn output. This is controlled by the
+% \meta{dimen} variable |\premulticols| which can be changed by
+% the user with ordinary \LaTeX{} commands.
+% \DescribeMacro\multicolsep
+% If the space is less than |\premulticols|, a new page is
+% started. Otherwise, a |\vskip| of |\multicolsep| is
+% added.\footnote{Actually the added space may be less because we use
+% \cs{addvspace} (see the \LaTeX{} manual for further
+% information about this command).}
+%
+% \DescribeMacro\postmulticols
+% When the end of the \mc{} environment is encountered, an
+% analogous mechanism is employed, but now we test whether there is a
+% space larger than |\postmulticols| available. Again we add
+% |\multicolsep| or start a new page.
+%
+% It is often convenient to spread some text over all columns, just
+% before the multicolumn output, without any page break in between. To
+% achieve this the \mc{} environment has an optional second
+% argument which can be used for this purpose. For example, the text
+% you are now reading was started with
+% \begin{verbatim}
+% \begin{multicols}{3}
+% [\section{The User
+% Interface}] ...
+%\end{verbatim}
+% If such text is unusually long (or short) the value of
+% |\premulticols| might need adjusting to prevent a bad page
+% break. We therefore provide a third argument which can be used to
+% overwrite the default value of |\premulticols| just for this
+% occasion. So if you want to combine some longer single column text
+% with a multicols environment you could write
+% \begin{verbatim}
+% \begin{multicols}{3}
+% [\section{Index}
+% This index contains ...]
+% [6cm]
+% ...
+%\end{verbatim}
+%
+%
+% \DescribeMacro\columnsep
+% The space between columns is controlled by the length parameter
+% |\columnsep|. The width for the individual columns is automatically
+% calculated from this parameter and the current |\linewidth|. In this
+% article a value of \textsf{\the\columnsep} was used.
+%
+%
+% \DescribeMacro\columnseprule
+% Separation of columns with vertical rules is achieved by setting the
+% parameter |\columnseprule| to some positive value. In this
+% article a value of {\sf.4pt} was used.
+%
+% \DescribeMacro\multicolbaselineskip
+% Since narrow columns tend to need adjustments in interline spacing
+% we also provide a \meta{skip} parameter called
+% |\multicolbaselineskip| which is added to the
+% |\baselineskip| parameter inside the \mc{}
+% environment. Please use this parameter with care or leave it alone;
+% it is intended only for package file designers since even small
+% changes might produce totally unexpected changes to your document.
+%
+%
+% \subsection{Balancing columns}
+%
+% Besides the previously mentioned parameters, some others are
+% provided to influence the layout of the columns generated.
+%
+% Paragraphing in \TeX{} is controlled by several parameters. One of
+% the most important is called |\tolerance|: this controls the
+% allowed `looseness' (i.e.\ the amount of blank space between words).
+% Its default value is 200 (the \LaTeX{} |\fussy|) which is too
+% small for narrow columns. On the other hand the |\sloppy|
+% declaration (which sets |\tolerance| to $10000=\infty$) is too
+% large, allowing really bad spacing.\footnote{Look at the next
+% paragraph, it was set with the \cs{sloppy} declaration.}
+%
+% \begin{sloppypar}
+% \DescribeMacro\multicoltolerance \DescribeMacro\multicolpretolerance
+% We therefore use a |\multicoltolerance| parameter for the
+% |\tolerance| value inside the \mc{} environment. Its default value
+% is 9999 which is less than infinity but `bad' enough for most
+% paragraphs in a multicolumn environment. Changing its value should
+% be done outside the \mc{} environment. Since |\tolerance| is set
+% to |\multicoltolerance| at the beginning of every {\sf multicols}
+% environment one can locally overwrite this default by assigning
+% \verb*+\tolerance = +\meta{desired value}. There also exists a
+% |\multicolpretolerance| parameter holding the value for
+% |\pretolerance| within a \mc{} environment. Both parameters are
+% usually used only by package designers.
+% \end{sloppypar}
+%
+% Generation of multicolumn output can be divided into two parts. In
+% the first part we are collecting material for a page, shipping it
+% out, collecting material for the next page, and so on. As a second
+% step, balancing will be done when the end of the \mc{} environment
+% is reached.
+% In the first step \TeX{} might consider more material whilst
+% finding the final columns than it actually use when shipping out the
+% page. This might cause a problem if a footnote is encountered in
+% the part of the input considered, but not used, on the current page.
+% In this case the footnote might show up on the current page, while the
+% footnotemark corresponding to this footnote might be set on the next
+% one.\footnote{The reason behind this behavior is the asynchronous
+% character of the \TeX{} {\it page\_builder}.
+% However, this
+% could be avoided by defining very complicated output
+% routines which don't use \TeX{} primitives like
+% \cs{insert} but do everything by hand.
+% This is clearly beyond the scope of a weekend problem.}
+% Therefore the \mc{} environment gives a warning
+% message\footnote{This message will be generated even if there are no
+% footnotes in this part of the text.} whenever it is unable to use
+% all the material considered so far.
+%
+% If you don't use footnotes too often the chances of something
+% actually going wrong are very slim, but if this happens you can help
+% \TeX{} by using a |\pagebreak| command in the final document.
+% Another way to influence the behavior of \TeX{} in this respect is
+% given by the counter variable `{\sf collectmore}'. If you use the
+% |\setcounter| declaration to set this counter to \meta{number},
+% \TeX{} will consider \meta{number} more (or less) lines before
+% making its final decision. So a value of $-1$ may solve all your
+% problems at the cost of slightly less optimal columns.
+%
+% In the second step (balancing columns) we have other bells and
+% whistles. First of all you can say |\raggedcolumns| if you
+% don't want the bottom lines to be aligned. The default is
+% |\flushcolumns|, so \TeX{} will normally try to make both the
+% top and bottom baselines of all columns align.
+%
+% \columnbreak
+%
+% Additionally you can set another counter, the `{\sf unbalance}'
+% counter, to some positive \meta{number}. This will make all but the
+% right-most column \meta{number} of lines longer than they would
+% normally have been. `Lines' in this context refer to normal text
+% lines (i.e.\ one |\baselineskip| apart); thus, if your columns
+% contain displays,
+% for example, you may need a higher \meta{number}
+% to shift something from one column into another.
+%
+% Unlike `{\sf collectmore},' the `{\sf unbalance}' counter is reset
+% to zero at the end of the environment so it only applies to one
+% \mc{} environment.
+%
+% The two methods may be combined but I suggest using these features
+% only when fine tuning important publications.
+%
+% Two more general tuning possibilities were added with version~1.5.
+% \TeX{} allows to measure the badness of a column in terms of an
+% integer value, where 0 means optimal and any higher value means a
+% certain amount of extra white space. 10000 is considered to be
+% infinitely bad (\TeX{} does not distinguish any further). In addition
+% the special value 100000 means overfull (i.e., the column contains
+% more text than could possibly fit into it).
+%
+% The new release now measures every generated column and ignores
+% solutions where at least one column has a badness being larger than
+% the value of the counter {\sf columnbadness}. The default value for
+% this counter is 10000, thus \TeX{} will accept all solutions except
+% those being overfull.
+% By setting the counter to a smaller value you can force the algorithm
+% to search for solutions that do not have columns with a lot of white
+% space.
+%
+% However, if the setting is too low, the algorithm may not find any
+% acceptable solution at all and will then finally choose the extreme
+% solution of placing all text into the first column.
+%
+% Often, when colunms are balanced, it is impossible to find a solution
+% that distributes the text evenly over all columns. If that is the case
+% the last column usually has less text than the others. In the earlier
+% releases this text was stretched to produce a column with the same
+% height as all others, sometimes resulting in really ugly looking
+% columns.
+%
+% In the new release this stretching is only done if the badness of
+% the final column is not larger than the value of the counter
+% {\sf finalcolumnbadness}. The default setting is 9999, thus preventing
+% the stretching for all columns that \TeX{} would consider infinitely
+% bad. In that case the final column is allowed to run short which gives
+% a much better result.
+%
+% And there are two more parameters of some experimental nature,
+% one called |\multicolovershoot| the other |\multicolundershoot|.
+% They control
+% the amount of space a column is allowed to be ``too full'' or ``too
+% short'' without affecting the column badness. They are set to 0pt
+% and 2pt, respectively.
+%
+% \subsection{Not balancing the columns}
+%
+% Although this package was written to solve the problem of balancing
+% columns, I got repeated requests to provide a version where all
+% white space is automatically placed in the last column or
+% columns. Since version v1.5q this now exists: if you use
+% \texttt{multicols*} instead of the usual environment the columns on
+% the last page are not balanced. Of course, this environment only
+% works on top-level, e.g., inside a box one has to balance to
+% determine a column height in absense of a fixed value.
+%
+%
+% \subsection{Manually breaking columns}
+%
+% Another request often voiced was: ``How to I tell \LaTeX{} that it
+% should break the first column after this particular line?''. The
+% |\pagebreak| command (which works with the two-column option of
+% \LaTeX{}) is of no use here since it would end the collection phase
+% of \mc{} and thus all columns on that page. So with version 1.5u
+% the |\columnbreak| command was added. If used within a paragraph it
+% marks the end of the current line as the desired breakpoint. You can
+% observe its effect on
+% the previous page where three lines of text have been artifically
+% forced into the second column (resulting in some white
+% space between paragraphs in the first column).
+%
+% \subsection{Floats inside a \mc{} environment}
+%
+% Within the \mc{} environment the usual star float commands are
+% available but their function is somewhat different as in the
+% two-column mode of standard \LaTeX. Stared floats, e.g., {\tt
+% figure*}, denote page wide floats that are handled in a similar
+% fashion as normal floats outside the \mc{} environment. However,
+% they will never show up on the page where they are encountered. In
+% other words, one can influence their placement by specifying a
+% combination of {\tt t}, {\tt b}, and/or {\tt p} in their optional
+% argument, but {\tt h} doesn't work because the first possible place
+% is the top of the next page. One should also note, that this means
+% that their placement behavior is determined by the values of
+% |\topfraction|, etc.\ rather then by |\dbl...|.
+%
+%
+% \subsection{Warnings}
+%
+% Under certain circumstances the use of the \mc{} environment may
+% result in some
+% warnings from \TeX{} or \LaTeX{}. Here is a list
+% of the important ones and the possible cause:
+% \begin{description}
+%
+% \item[] {\hspace*{-\labelsep}\tt Underfull \string\hbox\space
+% (badness ...)}
+%
+% As the columns are often very narrow \TeX{} wasn't able to find a
+% good way to break the paragraph. Underfull denotes a loose line but
+% as long the badness values is below $10000$ the result is probably
+% acceptable.
+%
+% \item[]
+% {\hspace*{-\labelsep}\tt Underfull \string\vbox\space ... while
+% \string\output\space is active}
+%
+% If a column contains an character with an unusual depth, for
+% example a `(', in the bottom line then this message may show up. It
+% usually has no significance as long as the value is not more than a
+% few points.
+%
+% \item[] {\hspace*{-\labelsep}\tt LaTeX Warning: I moved some lines
+% to the next page}
+%
+% As mentioned above, \mc{} sometimes screws up the footnote
+% numbering. As a precaution, whenever there is a footnote on a
+% page that where \mc{} had to leave a remainder for the following
+% page this warning appears. Check the footnote numbering on this
+% page. If it turns out that it is wrong you have to manually break
+% the page using |\newpage| or |\pagebreak[..]|.
+%
+% \item[] {\hspace*{-\labelsep}\tt Floats and marginpars not allowed
+% inside `multicols' environment!}
+%
+% This message appears if you try to use the |\marginpar| command or
+% an unstared version of the {\sf figure} or {\sf table} environment.
+% Such floats will disappear!
+%
+% \item[] {\hspace*{-\labelsep}\tt Very deep columns!
+% Grid alignment might be broken}
+%
+% This message can only appear if the option \texttt{grid} was
+% chosen. In that case it will show up if a column has a very large
+% depth so that \mc{} is unable to back up to its baseline. This
+% is only relevant if one tries to produce a document where all
+% text lines are aligned at an invisible grid, something that
+% requires careful adjustment of many parameters and macros, e.g.,
+% heading definitions.
+%
+% \end{description}
+%
+%
+% \subsection{Tracing the output}
+%
+% To understand the reasoning behind the decisions \TeX{} makes when
+% processing a \mc{} environment, a tracing mechanism is provided.
+% If you set the counter `\texttt{tracingmulticols}'
+% to a positive \meta{number} you then
+% will get some tracing information on the terminal and in the
+% transcript file:
+% \begin{description}
+% \item[$\meta{number}=1$.] \TeX{} will now tell you, whenever it
+% enters or leaves a \mc{} environment, the number of columns it
+% is working on and its decision about starting a new page before
+% or after the environment.
+% \item[$\meta{number}=2$.]
+% In this case you also get information from the balancing routine:
+% the heights tried for the left and right-most columns,
+% information about shrinking if the |\raggedcolumns|
+% declaration is in force and the value of the `{\sf unbalance}'
+% counter if positive.
+% \item[$\meta{number}= 3$.] Setting \meta{number}\pagebreak[2] to
+% this value will additionally trace the mark handling
+% algorithm. It will show what marks are found, what marks are
+% considered, etc. To fully understand this information you will
+% probably have to read carefully trough the implementation.
+% \item[$\meta{number}\geq 4$.] Setting \meta{number}\pagebreak[2] to
+% such a high value will additionally place an |\hrule| into your
+% output, separating the part of text which had already been
+% considered on the previous page from the rest. Clearly this
+% setting should {\em not\/} be used for the final output. It will
+% also activate even more debugging code for mark handling.
+% \end{description}
+%
+%
+% \end{multicols}
+%
+% \begin{multicols}{3}[\section{Prefaces to older versions}
+% \subsection{Preface to version 1.4}]
+% \hbadness=10000
+% Beside fixing some bugs as mentioned in the {\sf multicol.bug} file
+% this new release enhances the \mc{} environment by allowing for
+% balancing in arbitrary contexts. It is now, for example, possible
+% to balance text within a \mc{} or a {\sf minipage} as shown in
+% \ref{tab:newcmds} where a {\sf multicols} environment within a
+% {\sf quote} environment was used. It is now even possible to nest
+% \mc{} environments.
+%
+% The only restriction to such inner \mc{} environments (nested, or
+% within \TeX's internal vertical mode) is that such variants will
+% produce a box with the balanced material in it, so that they can
+% not be broken across pages or columns.
+%
+% Additionally I rewrote the algorithm for balancing so that it will
+% now produce slightly better results.
+%
+% I updated the source documentation but like to apologize in
+% advance for some `left over' parts that slipped through the
+% revision.
+%
+% A note to people who like to improve the balancing algorithm of
+% \mc{}: The balancing routine in now placed into a single macro
+% which is called |\balance@columns|. This means that one can easily
+% try different balancing routines by rewriting this macro. The
+% interface for it is explained in table \ref{tab:balance}. There are
+% several improvements possible, one can think of integrating the
+% |\badness| function of \TeX3, define a faster algorithm for finding
+% the right column height, etc. If somebody thinks he/she has an
+% enhancement I would be pleased to learn about it. But please obey
+% the copyright notice and don't change {\sf multicol.dtx} directly!
+% \begin{table*}
+% \begin{quote}
+% \begin{multicols}{2}
+% \raggedcolumns
+% The macro |\balance@columns| that contains the code for balancing
+% gathered material is a macro without parameters. It assumes that
+% the material for balancing is stored in the box |\mult@box| which
+% is a |\vbox|. It also ``knows'' about all parameters set up by the
+% \mc{} environment, like |\col@number|, etc. It can also assume
+% that |\@colroom| is the still available space on the current page.
+%
+% When it finishes it must return the individual columns in boxes
+% suitable for further processing with |\page@sofar|. This means
+% that the left column should be stored in box register
+% |\mult@gfirstbox|, the next
+% in register |\mult@firstbox|${}+2$, \ldots,
+% only the last one as an exception in
+% register |\mult@grightbox|. Furthermore it has to set up
+% two the macros
+% |\kept@firstmark| and |\kept@botmark| to hold the values for the
+% first and bottom mark as found in the individual columns. There
+% are some helper functions defined in section \ref{sec:v14} which
+% may be used for this. Getting the marks right ``by hand'' is
+% non-trivial and it may pay off to first take a look at the
+% documentation and implementation of |\balance@columns| below
+% before trying anew.
+% \end{multicols}
+% \end{quote}
+% \vspace*{-3ex}
+% \vspace*{-0ex}
+% \caption{Interface description for \cs{balance@columns}}
+% \label{tab:balance}
+% \end{table*}
+% \end{multicols}
+%
+% \begin{multicols}{3}[\subsection{Preface to version 1.2}]
+% \hbadness=10000
+% After the article about the \mc{} environment was published in
+% \TUB\ 10\#3, I got numerous requests for these macros. However, I
+% also got a changed version of my style file, together with a
+% letter asking me if I would include the changes to get better
+% paragraphing results in the case of narrow lines. The main
+% differences to my original style option were additional parameters
+% (like |\multicoladjdemerits| to be used for |\adjdemerits|, etc.)
+% which would influence the line breaking algorithm.
+%
+% But actually resetting such parameters to zero or even worse to a
+% negative value won't give better line breaks inside the \mc{}
+% environment. \TeX{}s line breaking algorithm will only look at
+% those possible line breaks which can be reached without a badness
+% higher than the current value of |\tolerance| (or |\pretolerance|
+% in the first pass). If this isn't possible, then, as a last
+% resort, \TeX{} will produce overfull boxes. All those (and only
+% those) possible break points will be considered and finally the
+% sequence which results in the fewest demerits will be chosen. This
+% means that a value of $-1000$ for |\adjdemerits| instructs \TeX{}
+% to prefer visibly incompatible lines instead of producing better
+% line breaks.
+%
+% However, with \TeX{} 3.0 it is possible to get decent line breaks
+% even in small columns by setting |\emergencystretch| to an
+% appropriate value. I implemented a version which is capable of
+% running both in the old and the new \TeX{} (actually it will
+% simply ignore the new feature if it is not available). The
+% calculation of |\emergencystretch| is probably incorrect. I
+% made a few tests but of course one has have much more experience
+% with the new possibilities to achieve the maximum quality.
+%
+% Version 1.1a had a nice `feature': the penalty for using the
+% forbidden floats was their ultimate removal from \LaTeX{}s
+% |\@freelist| so that after a few |\marginpar|s inside the \mc{}
+% environment floats where disabled forever. (Thanks to Chris
+% Rowley for pointing this out.) I removed this misbehaviour and at
+% the same time decided to allow at least floats spanning all
+% columns, e.g., generated by the |figure*| environment. You can
+% see the new functionality in table~\ref{tab:newcmds} which was
+% inserted at this very point.
+% \begin{table*}
+% \small
+% \setlength{\multicolsep}{0pt}
+% \begin{quote}
+% \begin{multicols}{2}
+% |\setemergencystretch|: This is a hook for people who like
+% to play around. It is supposed to set the
+% |\emergencystretch| \meta{dimen} register provided in the
+% new \TeX{} 3.0. The first argument is the number of columns and
+% the second one is the current |\hsize|. At the moment the
+% default definition is $4\mbox{\tt pt} \times |#1|$, i.e.\ the
+% |\hsize| isn't used at all. But maybe there are better
+% formulae.
+%
+% \setlength{\emergencystretch}{20pt} |\set@floatcmds|: This is
+% the hook for the experts who like to implement a full float
+% mechanism for the \mc{} environment. The |@| in the name
+% should signal that this might not be easy.
+% \end{multicols}
+% \end{quote}
+% \vspace*{-1ex}
+% \vspace*{-0ex}
+% \caption[]{The new commands of {\sf multicol.sty} version 1.2.
+% Both commands might be removed if good solutions to these
+% open problems are found. I hope that these commands will
+% prevent that nearly identical style files derived from
+% this one are floating around.}
+% \label{tab:newcmds}
+% \end{table*}
+% However single column floats are still forbidden and I don't think
+% I will have time to tackle this problem in the near future. As an
+% advice for all who want to try: wait for \TeX{} 3.0. It has a few
+% features which will make life much easier in multi-column
+% surroundings. Nevertheless we are working here at the edge of
+% \TeX{}s capabilities, really perfect solutions would need a
+% different approach than it was done in \TeX{}s page builder.
+%
+% The text below is nearly unchanged, I only added documentation at
+% places where new code was added.
+% \end{multicols}
+%
+% \changes{v1.5l}{1996/01/13}{Try hard to explain unresolved reference
+% that happens if \cs{OnlyDescription} is used}
+%
+% \StopEventually{\PrintIndex \PrintChanges
+% \ifx\Finale\relax
+% \typeout{**********************************}
+% \typeout{* Info: Typesetting this document with
+% \protect\OnlyDescription\space will}
+% \typeout{* Info: result in one unresolved
+% reference to `sec:v14'.}
+% \typeout{* Info: --- tough, it's just not there in this case!}
+% \typeout{**********************************}
+% \fi
+% }
+%
+%
+% \begin{multicols}{2}[\section{The Implementation}
+% We are now switching to two-column output to show the
+% abilities of this environment (and bad layout decisions).
+% \subsection{The documentation driver file}
+% ][10\baselineskip]
+%
+% \hbadness=10000
+%
+%
+% 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 {\tt
+% docstrip} program.
+% Since this is the first code in this file one can produce the
+% documentation
+% simply by running \LaTeX{} on the \texttt{.dtx} file.
+% \begin{macrocode}
+%<*driver>
+\documentclass{ltxdoc}
+% \end{macrocode}
+% We use the \texttt{balancingshow} option when loading \mc{} so
+% that full tracing is produced. This has to be done before the
+% \texttt{doc} package is loaded, since \texttt{doc} otherwise
+% requires \mc{} without any options.
+% \begin{macrocode}
+\usepackage{multicol}[1999/05/25]
+\usepackage{doc}
+% \end{macrocode}
+% First we set up the page layout suitable for
+% this article.
+% \begin{macrocode}
+\setlength{\textwidth}{39pc}
+\setlength{\textheight}{54pc}
+\setlength{\parindent}{1em}
+\setlength{\parskip}{0pt plus 1pt}
+\setlength{\oddsidemargin}{0pc}
+\setlength{\marginparwidth}{0pc}
+\setlength{\topmargin}{-2.5pc}
+\setlength{\headsep}{20pt}
+\setlength{\columnsep}{1.5pc}
+% \end{macrocode}
+% We want a rule between columns.
+% \begin{macrocode}
+\setlength\columnseprule{.4pt}
+% \end{macrocode}
+% We also want to ensure that a new \mc{} environment finds enough
+% space at the bottom of the page.
+% \begin{macrocode}
+\setlength\premulticols{6\baselineskip}
+% \end{macrocode}
+% When balancing columns we disregard solutions that
+% are too bad. Also, if the last column is too bad
+% we typeset it without stretch.
+% \begin{macrocode}
+\setcounter{columnbadness}{7000}
+\setcounter{finalcolumnbadness}{7000}
+% \end{macrocode}
+% The index is supposed to come out in four columns.
+% And we don't show macro names in the margin.
+% \begin{macrocode}
+\setcounter{IndexColumns}{4}
+\let\DescribeMacro\SpecialUsageIndex
+\let\DescribeEnv\SpecialEnvIndex
+\renewcommand\PrintMacroName[1]{}
+\CodelineIndex
+%\DisableCrossrefs % Partial index
+\RecordChanges % Change log
+% \end{macrocode}
+% Line numbers are very small for this article.
+% \begin{macrocode}
+\renewcommand{\theCodelineNo}
+ {\scriptsize\rm\arabic{CodelineNo}}
+\settowidth\MacroIndent{\scriptsize\rm 00\ }
+
+\begin{document}
+ \typeout
+ {****************************************
+ ^^J* Expect some Under- and overfull boxes.
+ ^^J****************************************}
+ \DocInput{multicol.dtx}
+\end{document}
+%</driver>
+% \end{macrocode}
+%
+%
+% \end{multicols}
+%
+% \begin{multicols}{2}[\subsection{Identification and
+% option processing}]
+%
+%
+% We start by identifying the package. Since it makes use of features
+% only available in \LaTeXe{} we ensure that this format is available.
+% (Now this is done earlier in the file.)
+% \begin{macrocode}
+%<*package>
+% \NeedsTeXFormat{LaTeX2e}
+% \ProvidesPackage{multicol}[..../../..
+% v... multicolum formatting]
+% \end{macrocode}
+%
+%^^A \subsection{Option processing}
+%
+% Next we declare options supported by \mc{}. Twocolumn mode
+% and \mc{} do not work together so we warn about possible
+% problems. However, since you can revert to |\onecolumn|
+% in which case \mc{} does work, we don't make this an error.
+% \begin{macrocode}
+\DeclareOption{twocolumn}
+ {\PackageWarning{multicol}{May not work
+ with the twocolumn option}}
+% \end{macrocode}
+% Tracing is done using a counter. However
+% it is also possible to invoke the tracing
+% using the options declared below.
+% \begin{macrocode}
+\newcount\c@tracingmulticols
+\DeclareOption{errorshow}
+ {\c@tracingmulticols\z@}
+\DeclareOption{infoshow}
+ {\c@tracingmulticols\@ne}
+\DeclareOption{balancingshow}
+ {\c@tracingmulticols\tw@}
+\DeclareOption{markshow}
+ {\c@tracingmulticols\thr@@}
+\DeclareOption{debugshow}
+ {\c@tracingmulticols5\relax}
+% \end{macrocode}
+% The next option is intended for typesetting on a |\baselineskip|
+% grid. Right now it doesn't do anything other than warning if it
+% thinks that the grid got lost.
+% \changes{v1.6a}{2003/03/15}{New option grid}
+% \begin{macrocode}
+\let\mc@gridwarn\maxdimen
+\DeclareOption{grid}{\def\mc@gridwarn{\maxdepth}}
+\ProcessOptions
+% \end{macrocode}
+%
+%
+% \end{multicols}
+%
+% \begin{multicols}{2}[\subsection{Starting and
+% Ending the \mc{} Environment}]
+%
+% \begin{macro}{\multicols}
+% As mentioned before, the \mc{} environment has one mandatory
+% argument (the number of columns) and up to two optional ones. We
+% start by reading the number of columns into the |\col@number|
+% register.
+% \begin{macrocode}
+\def\multicols#1{\col@number#1\relax
+% \end{macrocode}
+% If the user forgot the argument, \TeX{} will complain about a
+% missing number at this point. The error recovery mechanism will
+% then use zero, which isn't a good choice in this case. So we
+% should now test whether everything is okay. The minimum is two
+% columns at the moment.
+% \changes{v1.3b}{1990/10/09}{Minimum of two columns}
+% \begin{macrocode}
+ \ifnum\col@number<\tw@
+ \PackageWarning{multicol}%
+ {Using `\number\col@number'
+ columns doesn't seem a good idea.^^J
+ I therefore use two columns instead}%
+ \col@number\tw@ \fi
+% \end{macrocode}
+% We have only enough box registers for ten columns, so we need to
+% check that the user hasn't asked for more.
+% \changes{v1.4k}{1992/06/27}{Maximum of 5 columns (temp)}
+% \changes{v1.5a}{1992/11/04}{Allow 10 columns again}
+% \begin{macrocode}
+ \ifnum\col@number>10
+ \PackageError{multicol}%
+ {Too many columns}%
+ {Current implementation doesn't
+ support more than 10 columns.%
+ \MessageBreak
+ I therefore use 10 columns instead}%
+ \col@number10 \fi
+% \end{macrocode}
+% Within the environment we need a special version of the
+% kernel |\@footnotetext| command since the original sets the
+% the |\hsize| to |\columnwidth| which is not correct in the
+% multicol environment. Here |\columnwidth| refers to the width of
+% the individual column and the footnote should be in |\textwidth|.
+% Since |\@footnotetext| has a different definition inside a
+% minipage environment we do not redefine it directly. Instead we
+% locally set |\columnwidth| to |\textwidth| and call the original
+% (current) definition stored in |\orig@footnotetext|.
+% \changes{v1.5p}{1997/12/14}{Redefinition of \cs{@footnotetext}
+% only within env pr/2689.}
+% \changes{v1.5r}{1998/08/17}{Use \cs{@footnotetext} but with
+% local change to \cs{columnwidth}.}
+% \changes{v1.5w}{1999/10/21}{Make \cs{@footnotetext} long to allow
+% multi-paragraph footnotes.}
+% If the \mc{} environment is nested inside another \mc{}
+% environment then the redefinition has already happened. So be
+% better test for this situation. Otherwise, we will get a \TeX{}
+% stack overflow as this would generate a self-referencing definition.
+% \changes{v1.6e}{2004/02/14}{Avoid self-referencing definition of
+% \cs{@footnotetext} (pr/3618)}.
+% \begin{macrocode}
+ \ifx\@footnotetext\mult@footnotetext\else
+ \let\orig@footnotetext\@footnotetext
+ \let\@footnotetext\mult@footnotetext
+ \fi
+% \end{macrocode}
+% Now we can safely look for the optional arguments.
+% \begin{macrocode}
+ \@ifnextchar[\mult@cols{\mult@cols[]}}
+% \end{macrocode}
+% \end{macro}
+%
+%
+%
+% \begin{macro}{\mult@footnotetext}
+%
+% \begin{macrocode}
+\long\def\mult@footnotetext#1{\begingroup
+ \columnwidth\textwidth
+ \orig@footnotetext{#1}\endgroup}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\mult@cols}
+% The |\mult@cols| macro grabs the first optional argument
+% (if any) and looks for the second one.
+% \begin{macrocode}
+\def\mult@cols[#1]{\@ifnextchar[%
+% \end{macrocode}
+% This argument should be a \meta{dimen} denoting the minimum free
+% space needed on the current page to start the environment. If the
+% user didn't supply one, we use |\premulticols| as a
+% default.
+% \begin{macrocode}
+ {\mult@@cols{#1}}%
+ {\mult@@cols{#1}[\premulticols]}}
+% \end{macrocode}
+% \end{macro}
+%
+%
+% \begin{macro}{\mult@@cols}
+% After removing all arguments from the input we are able
+% to start with |\mult@@cols|.
+% \begin{macrocode}
+\def\mult@@cols#1[#2]{%
+% \end{macrocode}
+% First thing we do is to decide whether or not this is an
+% unbounded multicols environment, i.e. one that may split across
+% pages, or one that has to be typeset into a box. If we are in
+% \TeX's ``inner'' mode (e.g., inside a box already) then we have a
+% boxed version of multicols therefore we set the |@boxedmulticols|
+% switch to true. The \mc{} should start in vertical mode. If we
+% are not already there we now force it with |\par| since otherwise
+% the test for ``inner'' mode wouldn't show if we are in a box.
+% \changes{v1.4f}{1992/04/28}{\cs{par} added to allow for correct inner test}
+% \begin{macrocode}
+ \par
+ \ifinner \@boxedmulticolstrue
+% \end{macrocode}
+% Otherwise we check |\doublecol@number|. This counter is zero
+% outside a multicols environment but positive inside (this happens
+% a little later on). In the second case we need to process the
+% current multicols also in ``boxed mode'' and so change the switch
+% accordingly.
+% \begin{macrocode}
+ \else
+ \ifnum \doublecol@number>\z@
+ \@boxedmulticolstrue
+ \fi
+ \fi
+% \end{macrocode}
+% Then we look to see if statistics are requested:
+% \begin{macrocode}
+ \mult@info\z@
+ {Starting environment with
+ \the\col@number\space columns%
+% \end{macrocode}
+% In boxed mode we add some more info.
+% \changes{v1.4f}{1992/04/28}{\cs{on@line} added to tracing info}
+% \begin{macrocode}
+ \if@boxedmulticols\MessageBreak
+ (boxed mode)\fi
+ }%
+% \end{macrocode}
+% Then we measure the current page to see whether a useful portion
+% of the multicolumn environment can be typeset. This routine
+% might start a new page.
+% \changes{v1.4a}{1992/02/14}{Forgotten braces added}
+% \begin{macrocode}
+ \enough@room{#2}%
+% \end{macrocode}
+% Now we output the first argument and produce vertical space
+% above the columns. (Note that this argument corresponds to the
+% first optional argument of the {\sf multicols} environment.)
+% For many releases this argument was typeset in a group to get
+% a similar effect as |\twocolumn[..]| where the argument is
+% also implicitly surrounded by braces. However, this conflicts
+% with local changes done by things like sectioning commands (which
+% account for the majority of commands used in that argument)
+% messing up vertical spacing etc.\ later in the document so that
+% from version v1.5q on this argument is again typeset at the outer
+% level.
+% \changes{v1.4e}{1992/03/16}{Typeset optional arg inside group}
+% \changes{v1.5q}{1998/01/19}{And removed the group again six years later}
+% \begin{macrocode}
+ #1\par\addvspace\multicolsep
+% \end{macrocode}
+% When the last line of a paragraph had a positive depth then this
+% depth normally taken into account by the baselineskip calculation
+% for the next line. However, the columns produced by a following
+% \texttt{multicol} are rigid and thus the distance from the
+% baseline of a previous text line to the first line in a
+% \texttt{multicol} would differ depending on the depth of the
+% previous line. To account for this we add a negative space unless
+% the depth is \texttt{-1000pt} which signals something special to
+% \TeX and is not supposed to be a real depth.
+% \changes{v1.5z1}{2003/02/17}{Add a kern to cancel potential depth of
+% previous line}
+% \begin{macrocode}
+ \ifdim \prevdepth = -\@m\p@
+ \else
+% \end{macrocode}
+% The actual generation of this corrective space is a little bit
+% more complicated as it doesn't make sense to always back up to
+% the previous baseline (in case an object with a very large depth
+% was placed there, e.g., a centered tabular). So we only back up
+% to the extend that we are within the |\baselineskip| grid. We
+% know that the box produced by \mc{} has |\topskip| at its top so
+% that also needs to be taken into account.
+% \changes{v1.6a}{2003/03/15}{Adjust spacing}
+% \begin{macrocode}
+ \@tempcnta\prevdepth
+ \@tempcntb\baselineskip
+ \divide\@tempcnta\@tempcntb
+ \advance\@tempcnta\@ne
+ \dimen@\prevdepth
+ \advance\dimen@ -\@tempcnta\baselineskip
+ \advance\dimen@ \topskip
+ \kern-\dimen@
+ \fi
+% \end{macrocode}
+% We start a new grouping level to hide all subsequent changes
+% (done in |\prepare@multicols| for example).
+% \begin{macrocode}
+ \begingroup
+ \prepare@multicols
+% \end{macrocode}
+% If we are in boxed mode we now open a box to typeset all material
+% from the multicols body into it, otherwise we simply go ahead.
+% \changes{v1.4g}{1992/05/07}{\cs{global} was probably wrong but at least
+% unnecessary}
+% \begin{macrocode}
+ \if@boxedmulticols
+ \setbox\mult@box\vbox\bgroup
+% \end{macrocode}
+% \changes{v1.5?}{1994/?/?}{Penalty moved to later point}
+% We may have to reset some parameters at this point,
+% perhaps |\@parboxrestore|
+% would be the right action but I leave it for the moment.
+% \changes{v1.4l}{1992/08/17}{\cs{@totalleftmargin} now in \cs{prepare@multicols}}
+% \begin{macrocode}
+ \fi
+% \end{macrocode}
+% We finish by suppressing initial spaces.
+% \begin{macrocode}
+ \ignorespaces}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\if@boxedmulticols}
+% Here is the switch and the box for ``boxed'' multicols code.
+% \begin{macrocode}
+\newif\if@boxedmulticols
+\@boxedmulticolsfalse
+\newbox\mult@box
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\enough@room}
+% \changes{v1.0c}{1989/05/12}{Penalty 0 added to empty the contribution
+% list.}
+% The |\enough@room| macro used
+% above isn't perfect but works reasonably well in this context. We
+% measure the free space on the current page by subtracting
+% |\pagetotal| from |\pagegoal|. This isn't entirely
+% correct since it doesn't take the `shrinking' (i.e.\
+% |\pageshrink|) into account. The `recent contribution list'
+% might be nonempty so we start with |\par| and an explicit
+% |\penalty|.\footnote{See the documentation of
+% \cs{endmulticols} for further details.}
+% Actually, we use |\addpenalty| to ensure that a following
+% |\addvspace| will `see' the vertical space that might be
+% present.
+% The use of |\addpenalty| will have the effect that all items from
+% the recent contributions will be moved to the main vertical list
+% and the |\pagetotal| value will be updated correctly. However,
+% the penalty will be placed in front of any dangling glue item
+% with the result that the main vertical list may already be
+% overfull even if \TeX{} is not invoking the output routine.
+% \changes{v1.3b}{1990/10/09}{Do \cs{penalty} with \cs{addpenalty}}
+% \changes{v1.4e}{1992/03/16}{But ignore \cs{@nobreak} in \cs{addpenalty}}
+% \begin{macrocode}
+\def\enough@room#1{%
+% \end{macrocode}
+% Measuring makes only sense when we are not in ``boxed mode'' so
+% the routine does nothing if the switch is true.
+% \begin{macrocode}
+ \if@boxedmulticols\else
+ \par
+% \end{macrocode}
+% \label{mac:enoughroom}
+% To empty the contribution list the first release contained a
+% penalty zero but this had the result that |\addvspace| couldn't
+% detect preceding glue. So this was changed to |\addpenalty|. But
+% this turned out to be not enough as |\addpenalty| will not add a
+% penalty when |@nobreak| is true. Therefore we force this switch
+% locally to false. As a result there may be a break between
+% preceding text and the start of a multicols environment, but this
+% seems acceptable since there is the optional argument for exactly
+% this reason.
+% \begin{macrocode}
+ \bgroup\@nobreakfalse\addpenalty\z@\egroup
+ \page@free \pagegoal
+ \advance \page@free -\pagetotal
+% \end{macrocode}
+% To be able to output the value we need to assign it to a register
+% first since it might be a register (default) in which case we
+% need to use |\the| or it might be a plain value in which case
+% |\the| would be wrong.
+% \changes{v1.5e}{1994/05/26}{Assign arg to skip register to be able
+% to output value}
+% \begin{macrocode}
+ \@tempskipa#1\relax
+% \end{macrocode}
+% Now we test whether tracing information is required:
+% \begin{macrocode}
+ \mult@info\z@
+ {Current page:\MessageBreak
+ height=%
+ \the\pagegoal: used \the\pagetotal
+ \space -> free=\the\page@free
+ \MessageBreak
+ needed \the\@tempskipa
+ \space(for #1)}%
+% \end{macrocode}
+% Our last action is to force a page break if there isn't enough
+% room left.
+% \begin{macrocode}
+ \ifdim \page@free <#1\newpage \fi
+ \fi}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\prepare@multicols}
+% When preparing for multicolumn output several things must
+% be done.
+% \begin{macrocode}
+\def\prepare@multicols{%
+% \end{macrocode}
+% We start saving the current |\@totalleftmargin| and then
+% resetting the |\parshape| in case we are inside some list
+% environment. The correct indentation for the \mc{} environment in
+% such a case will be produced by moving the result to the right by
+% |\multicol@leftmargin| later on. If we would use the value of of
+% |\@totalleftmargin| directly then lists inside the \mc{}
+% environment could cause a shift of the output.
+% \changes{v1.4l}{1992/08/17}{saved \cs{@totalleftmargin}}
+% \begin{macrocode}
+ \multicol@leftmargin\@totalleftmargin
+ \@totalleftmargin\z@
+ \parshape\z@
+% \end{macrocode}
+% We also set the register |\doublecol@number| for later use. This
+% register should contain $2\times |\col@number|$. This is also an
+% indicator that we are within a \mc{} environment as mentioned
+% above.
+% \changes{v1.5a}{1992/11/04}{Add offset to \cs{doublecolnumber}}
+% \begin{macrocode}
+ \doublecol@number\col@number
+ \multiply\doublecol@number\tw@
+ \advance\doublecol@number\mult@rightbox
+% \end{macrocode}
+%
+% \begin{macrocode}
+ \if@boxedmulticols
+ \let\l@kept@firstmark\kept@firstmark
+ \let\l@kept@botmark\kept@botmark
+ \global\let\kept@firstmark\@empty
+ \global\let\kept@botmark\@empty
+ \else
+% \end{macrocode}
+% We add an empty box to the main vertical list to ensure that we
+% catch any insertions (held over or inserted at the top of the
+% page). Otherwise it might happen that the |\eject| is discarded
+% without calling the output routine. Inside the output routine we
+% remove this box again. Again this code applies only if we are on
+% the main vertical list and not within a box.
+% However, it is not enough to turn off interline spacing, we also
+% have to clear |\topskip| before adding this box, since |\topskip|
+% is always inserted before the first box on a page which would
+% leave us with an extra space of |\topskip| if \mc{} start on a
+% fresh sheet.
+% \changes{v1.3c}{1991/03/03}{\cs{null} inserted and removed in output}
+% \changes{v1.4a}{1992/02/11}{Conditional code for boxed mode added.}
+% \changes{v1.4o}{1992/11/22}{\cs{topskip} locally zeroed.}
+% \begin{macrocode}
+ \nointerlineskip {\topskip\z@\null}%
+ \output{%
+ \global\setbox\partial@page\vbox
+ {%
+% \end{macrocode}
+% Now we have to make sure that we catch one special situation which
+% may result in loss of text! If the user has a huge amount of
+% vertical material within the first optional argument that is larger
+% then |\premulticols| and we are near the bottom of the page then it
+% can happen that not the |\eject| is triggering this special output
+% routine but rather the overfull main vertical list. In that case
+% we get another breakpoint through the |\eject| penalty. As a result
+% this special output routine would be called twice and the contents
+% of |\partial@page|, i.e.\ the material before the \mc{}
+% environment gets lost. There are several solutions to avoid this
+% problem, but for now we will simply detect this and inform the user
+% that he/she has to enlarge the |\premulticols| by using a suitable
+% value for the second argument.
+% \changes{v1.4a}{1992/02/11}{Checking for text losses.}
+% \begin{macrocode}
+%<*check>
+ \ifvoid\partial@page\else
+ \PackageError{multicol}%
+ {Error saving partial page}%
+ {The part of the page before
+ the multicols environment was
+ nearly full with^^Jthe result
+ that starting the environment
+ will produce an overfull
+ page. Some^^Jtext may be lost!
+ Please increase \premulticols
+ either generally or for this%
+ ^^Jenvironment by specifying a
+ suitable value in the second
+ optional argument to^^Jthe
+ multicols environment.}
+ \unvbox\partial@page
+ \box\last@line
+ \fi
+%</check>
+ \unvbox\@cclv
+ \global\setbox\last@line\lastbox
+ }%
+% \end{macrocode}
+% Finally we need to record the marks that are present within the
+% |\partial@page| so that we can construct correct first and bottom
+% marks later on. This is done by the following code.
+% \changes{v1.4a}{1992/02/14}{kept marks initiated}
+% \begin{macrocode}
+ \prep@keptmarks
+% \end{macrocode}
+% Finally we have to initialize |\kept@topmark| which should
+% ideally be initialized with the mark that is current on ``top''
+% of this page. Unfortunately we can't use |\topmark| because this
+% register will not always contain what its name promises because
+% \LaTeX{} sometimes calls the output routine for float
+% management.\footnote{During such a call the \cs{botmark}
+% gets globally copied to \cs{topmark} by the \TeX{}
+% program.} Therefore we use the second best solution by
+% initializing it with |\firstmark|. In fact, for our purpose this
+% doesn't matter as we use |\kept@topmark| only to initialize
+% |\firstmark| and |\botmark| of a following page if we don't find
+% any marks on the current one.
+% \changes{v1.4i}{1992/06/18}{\cs{kept@topmark} initialized.}
+% \begin{macrocode}
+ \global\let\kept@topmark\firstmark
+ }\eject
+% \end{macrocode}
+% The next thing to do is to assign a new value to |\vsize|.
+% \LaTeX{} maintains the free room on the page (i.e.\ the page
+% height without the space for already contributed floats) in the
+% register |\@colroom|. We must subtract the height of
+% |\partial@page| to put the actual free room into this
+% variable.
+% \begin{macrocode}
+ \advance\@colroom-\ht\partial@page
+% \end{macrocode}
+% Then we have to calulate the |\vsize| value to use during column
+% assembly. |\set@mult@vsize| takes an argument which allows to
+% make the setting local (|\relax|) or global (|\global|). The
+% latter variant is used inside the output routine below. At this
+% point here we have to make a local change to |\vsize| because we
+% want to get the original value for |\vsize| restored in case
+% this \mc{} environment ends on the same page where it has started.
+% \changes{v1.4p}{1992/11/26}{Use different \cs{vsize} setting}
+% \changes{v1.4p}{1992/11/26}{Code moved to \cs{set@mult@vsize}}
+% \begin{macrocode}
+ \set@mult@vsize\relax
+% \end{macrocode}
+% Now we switch to a new |\output| routine which will be used
+% to put the gathered column material together.
+% \begin{macrocode}
+ \output{\multi@column@out}%
+% \end{macrocode}
+% Finally we handle the footnote insertions. We have to multiply
+% the magnification factor and the extra skip by the number of
+% columns since each footnote reduces the space for every column
+% (remember that we have pagewide footnotes). If, on the other
+% hand, footnotes are typeset at the very end of the document, our
+% scheme still works since |\count\footins| is zero then, so it
+% will not change.
+% To allow even further customization the setting of the |\footins|
+% parameters is done in a separate macro.
+% \changes{v1.5?}{1994/?/?}{Use \cs{init@mult@footins}}
+% \begin{macrocode}
+ \init@mult@footins
+% \end{macrocode}
+% For the same reason (pagewide footnotes), the \meta{dimen}
+% register controlling the maximum space used for footnotes isn't
+% changed. Having done this, we must reinsert all the footnotes
+% which are already present (i.e.\ those encountered when the
+% material saved in |\partial@page| was first processed). This
+% will reduce the free space (i.e.\ |\pagetotal|) by the
+% appropriate amount since we have changed the magnification
+% factor, etc.\ above.
+% \begin{macrocode}
+ \reinsert@footnotes
+% \end{macrocode}
+% All the code above was only necessary for the unrestricted \mc{}
+% version, i.e.\ the one that allows page breaks. If we are within
+% a box there is no point in setting up special output routines or
+% |\vsize|, etc.
+% \begin{macrocode}
+ \fi
+% \end{macrocode}
+% But now we are coming to code that is necessary in all cases. We
+% assign new values to |\vbadness|, |\hbadness| and |\tolerance|
+% since it's rather hard for \TeX{} to produce `good' paragraphs
+% within narrow columns.
+% \changes{v1.2a}{1990/02/05}{\cs{vbadness} 10001 now.}
+% \begin{macrocode}
+ \vbadness\@Mi \hbadness5000
+ \tolerance\multicoltolerance
+% \end{macrocode}
+% Since nearly always the first pass will fail we ignore it
+% completely telling \TeX{} to hyphenate directly. In fact, we now
+% use another register to keep the value for the multicol
+% pre-tolerance, so that a designer may allow to use
+% |\pretolerance|.
+% \changes{v1.2a}{1990/02/05}{\cs{pretolerance} -1 because it nearly never
+% succeeds.}
+% \changes{v1.4e}{1992/03/20}{Using}
+% \begin{macrocode}
+ \pretolerance\multicolpretolerance
+% \end{macrocode}
+% For use with the new \TeX{} we set |\emergencystretch| to
+% $|\col@number| \times 4pt$. However this is only a guess
+% so at the moment this is done in a macro
+% |\setemergencystretch| which gets the current |\hsize|
+% and the number of columns as arguments. Therefore users are able
+% to figure out their own formula.
+% \changes{v1.2a}{1990/02/05}{\cs{setemergencystretch} added.}
+% \begin{macrocode}
+ \setemergencystretch\col@number\hsize
+% \end{macrocode}
+% Another hook to allow people adding their own extensions without
+% making a new package is |\set@floatcmds| which handles any
+% redefinitions of \LaTeX{}s internal float commands to work with
+% the \mc{} environment. At the moment it is only used to redefine
+% |\@dblfloat| and |\end@dblfloat|.
+% \changes{v1.2a}{1990/02/05}{\cs{set@floatcmds} added.}
+% \begin{macrocode}
+ \set@floatcmds
+% \end{macrocode}
+% Additionally, we advance |\baselineskip| by
+% |\multicolbaselineskip| to allow corrections for narrow
+% columns.
+% \begin{macrocode}
+ \advance\baselineskip\multicolbaselineskip
+% \end{macrocode}
+% \changes{v1.0e}{1989/06/21}{\cs{textwidth} changed to \cs{linewidth}.}
+% \changes{v1.0e}{1989/06/21}{So this file will
+% work with the `twocolumn' command.}
+% The |\hsize| of the columns is given by the formula:
+% \[
+% { |\linewidth| - (|\col@number|-1)
+% \times
+% |\columnsep|
+% \over
+% |\col@number|}
+% \]
+% The formula above has changed from release to release. We now
+% start with the current value of |\linewidth| so that the column
+% width is properly calculated when we are inside a minipage or a
+% list or some other environment.
+% This will be achieved with:
+% \begin{macrocode}
+ \hsize\linewidth \advance\hsize\columnsep
+ \advance\hsize-\col@number\columnsep
+ \divide\hsize\col@number
+% \end{macrocode}
+% We also set |\linewidth| and |\columnwidth| to |\hsize| In the past
+% |\columnwidth| was left unchanged. This is inconsistent,
+% but |\columnwidth| is used only by floats (which
+% aren't allowed in their current implementation) and by the
+% |\footnote| macro. Since we want pagewide
+% footnotes\footnote{I'm not sure that I really want pagewide
+% footnotes. But balancing of the last page can
+% only be achieved with this approach or with a
+% multi-path algorithm which is complicated and
+% slow. But it's a challenge to everybody to
+% prove me wrong! Another possibility is to
+% reimplement a small part of the {\it
+% fire\_up\/} procedure in \TeX{} (the program).
+% I think that this is the best solution if you
+% are interested in complex page makeup, but it
+% has the disadvantage that the resulting
+% program cannot be called \TeX{} thereafter.}
+% this simple trick saved us from rewriting the |\footnote|
+% macros. However, some applications refered to |\columnwidth| as
+% the ``width of the current column'' to typeset displays
+% (the \texttt{amsmath} package, for example) and to allow the use
+% of such applications together with \texttt{multicol} this is now
+% changed.
+%
+% Before we change |\linewidth| to the new value we record its old
+% value in some register called |\full@width|. This value is
+% used later on when we package all columns together.
+% \changes{v1.0e}{1989/06/21}{Setting of \cs{columnwidth} removed.}
+% \changes{v1.5o}{1997/11/16}{Setting of \cs{columnwidth} added again
+% pr/2664.}
+% \begin{macrocode}
+ \full@width\linewidth
+ \linewidth\hsize
+ \columnwidth\hsize
+}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\init@mult@footins}
+% This macro is used to set up the parameters associated
+% with footnote floats. It can be redefined by applications that
+% require different amount of spaces when typesetting footnotes.
+% \begin{macrocode}
+\def\init@mult@footins{%
+ \multiply\count\footins\col@number
+ \multiply\skip \footins\col@number
+}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\set@mult@vsize}
+%
+% Since we have to set |\col@umber| columns on one page,
+% each with a height of |\@colroom|, we have to assign
+% $
+% |\vsize| = |\col@number| \times |\@colroom|
+% $
+% in order to collect enough material before entering the
+% |\output| routine again. In fact we have to add another
+% $
+% (|\col@number|-1) \times (|\baselineskip|-|\topskip|)
+% $
+% if you think about it.
+% \changes{v1.4p}{1992/11/26}{Macro added.}
+% \begin{macrocode}
+\def\set@mult@vsize#1{%
+ \vsize\@colroom
+ \@tempdima\baselineskip
+ \advance\@tempdima-\topskip
+ \advance\vsize\@tempdima
+ \vsize\col@number\vsize
+ \advance\vsize-\@tempdima
+% \end{macrocode}
+% But this might not be enough since we use |\vsplit| later to
+% extract the columns from the gathered material. Therefore we add
+% some `extra lines,' one for each column plus a corrective action
+% depending on the value of the `\texttt{collectmore}' counter.
+% The final value is assigned globally if |#1| is |\global| because
+% we want to use this macro later inside the output routine too.
+% \changes{v1.6c}{2003/04/08}{Collect one line per column more}
+% \begin{macrocode}
+ \advance\vsize\col@number\baselineskip
+ #1\advance\vsize
+ \c@collectmore\baselineskip}
+% \end{macrocode}
+% \end{macro}
+%
+%
+% \begin{macro}{\multicol@leftmargin}
+% Here is the dimen register we need for saving away the outer
+% value of |\@totalleftmargin|.
+% \begin{macrocode}
+\newdimen\multicol@leftmargin
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\endmulticols}
+% When the end of the \mc{} environment is sensed we have to
+% balance the gathered material. Depending on whether or not we are
+% inside a boxed multicol different things must happen. But first
+% we end the current paragraph with a |\par| command.
+% \begin{macrocode}
+\def\endmulticols{\par
+ \if@boxedmulticols
+% \end{macrocode}
+% In boxed mode we have to close the box in which we have gathered
+% all material for the columns.
+% \begin{macrocode}
+ \egroup
+% \end{macrocode}
+% Now we call |\balance@columns| the routine that balances material
+% stored in the box |\mult@box|.
+% \changes{v1.5?}{1994/?/?}{Splitting off zero box moved to \cs{balance@columns}}
+% \begin{macrocode}
+ \balance@columns
+% \end{macrocode}
+% After balancing the result has to be returned by the command
+% |\page@sofar|. But before we do this we reinsert any marks found
+% in box |\mult@box|.
+% \begin{macrocode}
+ \return@nonemptymark{first}%
+ \kept@firstmark
+ \return@nonemptymark{bot}%
+ \kept@botmark
+ \page@sofar
+% \end{macrocode}
+%
+% \begin{macrocode}
+ \global\let\kept@firstmark
+ \l@kept@firstmark
+ \global\let\kept@botmark
+ \l@kept@botmark
+%<*marktrace>
+ \mult@info\tw@
+ {Restore kept marks to\MessageBreak
+ first: \meaning\kept@firstmark
+ \MessageBreak bot\space\space:
+ \meaning\kept@botmark }%
+%</marktrace>
+% \end{macrocode}
+% This finishes the code for the ``boxed'' case.
+% \begin{macrocode}
+ \else
+% \end{macrocode}
+% If there was a |\columnbreak| on the very last line all material
+% will have been moved to the |\colbreak@box|. Thus the the galley
+% will be ampty and no output routine gets called so that the text
+% is lost. To avoid this problem (though unlikely) we check if the
+% current galley is empty and the |\colbreak@box| contains text and
+% if so return that to the galley. If the galley is non-empty any
+% material in |\colbreak@box| is added in the output routine since
+% it needs to be put in front.
+% \changes{v1.6d}{2003/04/17}{Catch problem with \cs{columnbreak} in
+% last line}
+% \begin{macrocode}
+%<*colbreak>
+ \ifdim\pagegoal=\maxdimen
+ \ifvoid\colbreak@box\else
+ \mult@info\@ne{Re-adding forced
+ break(s) for splitting}%
+ \unvbox\colbreak@box\fi
+ \fi
+%</colbreak>
+% \end{macrocode}
+%
+% If we are in an unrestricted \mc{} environment we end the current
+% paragraph above with |\par| but this isn't sufficient since \TeX{}s
+% {\it page\_builder} will not totally empty the contribution
+% list.\footnote{This once caused a puzzling bug where some of the
+% material was balanced twice, resulting in some overprints. The
+% reason was the \cs{eject} which was placed at the end of
+% the contribution list. Then the {\it page\_builder} was called
+% (an explicit \cs{penalty} will empty the contribution
+% list), but the line with the \cs{eject} didn't fit onto
+% the current page. It was then reconsidered after the output
+% routine had ended, causing a second break after one line.}
+% Therefore we must also add an explicit |\penalty|. Now the
+% contribution list will be emptied and, if its material doesn't
+% all fit onto the current page then the output routine will be
+% called before we change it.
+% \changes{v1.3b}{1990/10/09}{Do \cs{penalty} with \cs{addpenalty}}
+% \changes{v1.4e}{1992/03/16}{But ignore \cs{@nobreak} in \cs{addpenalty}}
+% \changes{v1.5c}{1993/04/18}{Again use \cs{penalty}}
+% At this point we need to use |\penalty| not |\addpenalty| to
+% ensure that a) the recent contributions are emptied and b) that
+% the very last item on the main vertical list is a valid break
+% point so that \TeX{} breaks the page in case it is overfull.
+% \begin{macrocode}
+ \penalty\z@
+% \end{macrocode}
+% The processed material might consist of a last line with a
+% decender in which case the |\prevdepth| will be
+% non-zero. However, this material is getting reformatted now so
+% that this value is likely to be wrong. We therefore normalize the
+% situation by pretending that the depth is zero and arrange later
+% that the box containing the assembled columns has in fact this property.
+% \changes{v1.6a}{2003/03/15}{Adjusting \cs{prevdepth}}
+% \begin{macrocode}
+ \prevdepth\z@
+% \end{macrocode}
+% Now it's safe to change the output routine in order to balance
+% the columns.
+% \begin{macrocode}
+ \output{\balance@columns@out}\eject
+% \end{macrocode}
+% If the \mc{} environment body was completely empty or if a
+% multi-page \mc{} just ends at a page boundary we have the unusual
+% case that the |\eject| will have no effect (since the main
+% vertical list is empty)---thus no output routine is called at
+% all. As a result the material preceding the \mc{} (stored in
+% |\partial@page| will get lost if we don't take of this by hand.
+% \changes{v1.4m}{1992/09/04}{Check \cs{partial@page} being emptied}
+% \begin{macrocode}
+ \ifvbox\partial@page
+ \unvbox\partial@page\fi
+% \end{macrocode}
+% After the output routine has acted we restore
+% the kept marks to their initial value.
+% \begin{macrocode}
+ \global\let\kept@firstmark\@empty
+ \global\let\kept@botmark\@empty
+%<*marktrace>
+ \mult@info\tw@
+ {Make kept marks empty}%
+%</marktrace>
+ \fi
+% \end{macrocode}
+% The output routine above will take care of the |\vsize| and
+% reinsert the balanced columns, etc. But it can't reinsert the
+% |\footnotes| because we first have to restore the
+% |\footins| parameter since we are returning to one column
+% mode. This will be done in the next line of code; we simply close
+% the group started in |\multicols|.
+%
+% To fix an obscure bug which is the result of the current
+% definition of the |\begin| \ldots\ |\end| macros, we check that
+% we are still (logically speaking) in the \mc{} environment. If,
+% for example, we forget to close some environment inside the
+% \mc{} environment, the following |\endgroup| would be
+% incorrectly considered to be the closing of this environment.
+% \changes{v1.3c}{1991/03/14}{Check closing env.}
+% \begin{macrocode}
+ \@checkend{multicols}%
+ \endgroup
+% \end{macrocode}
+% We also set the `{\sf unbalance}' counter to its default. This is
+% done globally since \LaTeX{} counters are always changed this
+% way.\footnote{Actually, we are still in a group started by the
+% \cs{begin} macro, so \cs{global} must be used
+% anyway.}
+% \begin{macrocode}
+ \global\c@unbalance\z@
+% \end{macrocode}
+% Now it's time to return any footnotes if we are in unrestricted
+% mode:
+% \begin{macrocode}
+ \if@boxedmulticols\else
+ \reinsert@footnotes
+% \end{macrocode}
+% We also take a look at the amount of free space on the current
+% page to see if it's time for a page break. The vertical space
+% added thereafter will vanish if |\enough@room| starts a new
+% page.
+%
+% But there is one catch. If the |\end{multicols}| is at the top of
+% which can happen if there is a break point just before it (such
+% as end ending environment) which was chosen. In that case we
+% would do the next page using the internal |\vsize| for multicol
+% collection which is a desaster. So we better catch this
+% case. Fortunately we can detect it by looking at |\pagegoal|.
+% \changes{v1.5x}{2000/05/05}{Detect and fix problem if a multicols
+% ends at the top of a page}
+% \begin{macrocode}
+ \ifdim \pagegoal=\maxdimen
+ \global\vsize\@colroom
+ \else
+ \enough@room\postmulticols
+ \fi
+ \fi
+ \addvspace\multicolsep
+% \end{macrocode}
+% If statistics are required we finally report that we have
+% finished everything.
+% \begin{macrocode}
+ \mult@info\z@
+ {Ending environment
+ \if@boxedmulticols
+ \space(boxed mode)\fi
+ }}
+% \end{macrocode}
+% \end{macro}
+%
+%
+% \begin{macro}{\c@unbalance}
+% \SpecialMainIndex{\c@collectmore}
+% \SpecialMainIndex{\col@number}
+% \SpecialMainIndex{\doublecol@number}
+% \SpecialMainIndex{\premulticols}
+% \SpecialMainIndex{\multicoltolerance}
+% \SpecialMainIndex{\multicolpretolerance}
+% \SpecialMainIndex{\page@free}
+% \SpecialMainIndex{\premulticols}
+% \SpecialMainIndex{\postmulticols}
+% \SpecialMainIndex{\multicolsep}
+% \SpecialMainIndex{\multicolbaselineskip}
+% \SpecialMainIndex{\partial@page}
+% Let us end this section by allocating all the registers used so
+% far.
+% \begin{macrocode}
+\newcount\c@unbalance
+\newcount\c@collectmore
+% \end{macrocode}
+% In the new \LaTeX{} release |\col@number| is already allocated by
+% the kernel, so we don't allocate it again.
+% \begin{macrocode}
+%\newcount\col@number
+\newcount\doublecol@number
+\newcount\multicoltolerance
+\newcount\multicolpretolerance
+\newdimen\full@width
+\newdimen\page@free
+\newdimen\premulticols
+\newdimen\postmulticols
+\newskip\multicolsep
+\newskip\multicolbaselineskip
+\newbox\partial@page
+\newbox\last@line
+% \end{macrocode}
+% And here are their default values:
+% \begin{macrocode}
+\c@unbalance = 0
+\c@collectmore = 0
+% \end{macrocode}
+% To allow checking whether some macro is used within the \mc{}
+% environment the counter |\col@number| gets a default of |1|
+% outside the the environment.
+% \changes{v1.3d}{1991/10/23}{\cs{col@number} set to one}
+% \begin{macrocode}
+\col@number = 1
+\multicoltolerance = 9999
+\multicolpretolerance = -1
+\premulticols = 50pt
+\postmulticols= 20pt
+\multicolsep = 12pt plus 4pt minus 3pt
+\multicolbaselineskip=0pt
+% \end{macrocode}
+% \end{macro}
+%
+% \end{multicols}
+%
+% \begin{multicols}{2}[\subsection{The output routines}]
+%
+% We first start with some simple macros. When typesetting the page we
+% save the columns either in the box registers 0, 2, 4,\ldots\
+% (locally) or 1, 3, 5,\ldots\ (globally). This is \PlainTeX{} policy
+% to avoid an overflow of the save stack.
+%
+% \begin{macro}{\process@cols}
+% Therefore we define a |\process@cols| macro to help us in
+% using these registers in the output routines below. It has two
+% arguments: the first one is a number; the second one is the
+% processing information. It loops starting with |\count@=#1|
+% (|\count@| is a scratch register defined in \PlainTeX),
+% processes argument |#2|, adds two to |\count@|,
+% processes argument |#2| again, etc.\ until |\count@| is
+% higher than |\doublecol@number|. It might be easier to
+% understand it through an example, so we define it now and
+% explain its usage afterwards.
+% \begin{macrocode}
+\def\process@cols#1#2{\count@#1\relax
+ \loop
+%<*debug>
+ \typeout{Looking at box \the\count@}
+%</debug>
+ #2%
+ \advance\count@\tw@
+ \ifnum\count@<\doublecol@number
+ \repeat}
+% \end{macrocode}
+% \end{macro}
+%
+%
+% \begin{macro}{\page@sofar}
+% We now define |\page@sofar| to give an example of the
+% |\process@cols| macro. |\page@sofar| should output everything
+% prepared by the balancing routine |\balance@columns|.
+% \begin{macrocode}
+\def\page@sofar{%
+% \end{macrocode}
+% |\balance@columns| prepares its output in the even numbered
+% scratch box registers.
+% Now we output the columns gathered assuming that they are saved
+% in the box registers 2 (left column), 4 (second column), \ldots\
+% However, the last column (i.e.\ the right-most) should be saved in
+% box register 0.\footnote{You will see the reason for this numbering
+% when we look at the output routines
+% \cs{multi@column@out} and
+% \cs{balance@columns@out}.}
+% First we ensure that the columns have equal width. We use
+% |\process@cols| for this purpose, starting with
+% $|\count@|=|\mult@rightbox|$. Therefore |\count@| loops through
+% |\mult@rightbox|, $|\mult@rightbox| + 2$,\ldots
+% (to |\doublecol@number|).
+% \changes{v1.5a}{1992/11/04}{New box mechanism}
+% \begin{macrocode}
+ \process@cols\mult@rightbox
+% \end{macrocode}
+% We have to check if the box in question is void, because the
+% operation |\wd|\meta{number} on a void box will \emph{not} change
+% its dimension (sigh).
+% \changes{v1.5h}{1994/08/26}{Check for void boxes}
+% \changes{v1.5i}{1994/10/02}{But don't remove original code.}
+% \begin{macrocode}
+ {\ifvoid\count@
+ \setbox\count@\hbox to\hsize{}%
+ \else
+ \wd\count@\hsize
+ \fi}%
+% \end{macrocode}
+% Now we give some tracing information.
+% \changes{v1.4l}{1992/08/17}{use \cs{multicol@leftmargin} instead of
+% \cs{@totalleftmargin}}
+% \changes{v1.6b}{2003/03/15}{Different info display}
+% \begin{macrocode}
+ \count@\col@number \advance\count@\m@ne
+ \mult@info\z@
+ {Column spec: \the\full@width\space = indent
+ + columns + sep =\MessageBreak
+ \the\multicol@leftmargin\space
+ + \the\col@number\space
+ x \the\hsize\space
+ + \the\count@\space
+ x \the\columnsep
+ }%
+% \end{macrocode}
+% At this point we should always be in vertical mode.
+% \begin{macrocode}
+\ifvmode\else\errmessage{Multicol Error}\fi
+% \end{macrocode}
+% Now we put all columns together in an |\hbox| of width
+% |\full@width| (shifting it by |\multicol@leftmargin| to the right
+% so that it will be placed correctly if we are within a list
+% environment)
+% \changes{v1.4l}{1992/08/17}{use \cs{multicol@leftmargin} instead of
+% \cs{@totalleftmargin}}
+%
+% The box containing the columns has a large height and thus will
+% always result in using |\lineskip| if the normal |\baselineskip|
+% calculations are used. We therefore better cancel that process.
+% \changes{v1.5z1}{2003/02/17}{Suppress interline glue at this point}
+% \begin{macrocode}
+ \nointerlineskip
+% \end{macrocode}
+% As mentioned earlier we want to have the reference point of the
+% box we put on the page being at the baseline of the last line of
+% the columns but we also want to ensure that the box has no depth
+% so that any following skip is automatically starting from that
+% baseline.
+% We achieve this by recording the depths of all columns and then
+% finally backing up by the maximum. (perhaps a simpler method
+% would be to assemble the box in a register and set the depth of
+% that box to zero (not checked).
+%
+% We need a global scratch register for this; using standard \TeX{}
+% conventions we choose |\dimen2| and initialize it with the depth
+% of the character ``p'' since that is one of the depths that
+% compete for the maximum.
+% \changes{v1.6a}{2003/03/15}{Preparing for adjusting \cs{prevdepth}}
+% \begin{macrocode}
+ \setbox\z@\hbox{p}\global\dimen\tw@\dp\z@
+ \moveright\multicol@leftmargin
+ \hbox to\full@width{%
+% \end{macrocode}
+% and separating the columns with a rule if desired.
+% \changes{v1.5a}{1992/11/04}{New box mechanism}
+% \changes{v1.5z}{2000/07/10}{Ensure that column rule has always
+% \cs{normalcolor}}
+% \begin{macrocode}
+ \process@cols\mult@gfirstbox{%
+% \end{macrocode}
+% If the depth of the current box is larger than the maximum found
+% so far in |\dimen2| we update that register.
+% \changes{v1.6a}{2003/03/15}{Preparing for adjusting \cs{prevdepth}}
+% \begin{macrocode}
+ \ifdim\dp\count@>\dimen\tw@
+ \global\dimen\tw@\dp\count@ \fi
+ \box\count@
+ \hss{\normalcolor\vrule
+ \@width\columnseprule}\hss}%
+% \end{macrocode}
+% As you will have noticed, we started with box register
+% |\mult@gfirstbox| (i.e.\
+% the left column). So this time |\count@| looped through 2,
+% 4,\ldots\ (plus the appropriate offset).
+% Finally we add box 0 and close the |\hbox|.
+% \changes{v1.5a}{1992/11/04}{New box mechanism}
+% \changes{v1.6a}{2003/03/15}{Preparing for adjusting \cs{prevdepth}}
+% Again we may have to update |\dimen\tw@|.
+% \begin{macrocode}
+ \ifdim\dp\mult@rightbox>\dimen\tw@
+ \global\dimen\tw@\dp\mult@rightbox \fi
+ \box\mult@rightbox
+% \end{macrocode}
+% The depths of the columns depend on their last lines. To ensure
+% that we will always get a similar look as far as the rules are
+% concerned we force the depth at least the depth of a letter~`p'.
+% \begin{macrocode}
+ \rlap{\phantom p}%
+ }%
+% \end{macrocode}
+% Now after typesetting the box we mack up to its baseline by using
+% the value stored in |\dimen2|.
+% \changes{v1.6a}{2003/03/15}{Now adjusting \cs{prevdepth}}
+% \begin{macrocode}
+ \kern-\dimen\tw@
+% \end{macrocode}
+% However, in case of of the columns was unusually deep \TeX{} may
+% have tried some corrective actions in which case backing up by
+% the ahve value will not bring us back to the baseline. A good
+% indication for this is a depth of |\maxdepth| though it is not an
+% absolute proof. If the option \texttt{grid} is used
+% |\mc@gridwarn| will expand to this, otherwise to |\maxdimen| in
+% which case this warning will not show up.
+% \begin{macrocode}
+ \ifdim\dimen\tw@ = \mc@gridwarn
+ \PackageWarning{multicol}%
+ {Very deep columns!\MessageBreak
+ Grid alignment might be broken}%
+ \fi
+}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\reinsert@footnotes}
+% Before we tackle the bigger output routines we define just one
+% more macro which will help us to find our way through the
+% mysteries later. |\reinsert@footnotes| will do what its name
+% indicates: it reinserts the footnotes present in
+% |\footinbox| so that they will be reprocessed by \TeX{}'s
+% {\it page\_builder}.
+%
+% Instead of actually reinserting the footnotes we insert an empty
+% footnote. This will trigger insertion mechanism as well and since
+% the old footnotes are still in their box and we are on a fresh page
+% |\skip| |footins| should be correctly taken into account.
+% \changes{v1.3c}{1990/03/03}{\cs{unbox}ing avoided.}
+% \begin{macrocode}
+\def\reinsert@footnotes{\ifvoid\footins\else
+ \insert\footins{}\fi}
+% \end{macrocode}
+% \end{macro}
+%
+%
+% \begin{macro}{\multi@column@out}
+% Now we can't postpone the difficulties any longer. The
+% |\multi@column@out| routine will be called in two situations.
+% Either the page is full (i.e.\ we have collected enough material
+% to generate all the required columns) or a float or marginpar (or
+% a |\clearpage| is
+% sensed. In the latter case the |\outputpenalty| is less
+% than $-10000$, otherwise the penalty which triggered the output
+% routine is higher. Therefore it's easy to distinguish both
+% cases: we simply test this register.
+% \changes{v1.5c}{1993/04/18}{Support \cs{clearpage}}
+% \begin{macrocode}
+\def\multi@column@out{%
+ \ifnum\outputpenalty <-\@M
+% \end{macrocode}
+% If this was a |\clearpage|, a float or a marginpar we call
+% |\speci@ls|
+% \begin{macrocode}
+ \speci@ls \else
+% \end{macrocode}
+% otherwise we construct the final page.
+% \changes{v1.5u}{1999/05/25}{Support \cs{columnbreak}}
+% \changes{v1.5v}{1999/07/18}{Added debug statements for
+% column break support}
+% For the next block of code see comments in section~\ref{sec:colbreak}.
+% \begin{macrocode}
+%<*colbreak>
+ \ifvoid\colbreak@box\else
+ \mult@info\@ne{Re-adding forced
+ break(s) for splitting}%
+ \setbox\@cclv\vbox{%
+ \unvbox\colbreak@box
+ \penalty-\@Mv\unvbox\@cclv}%
+ \fi
+%</colbreak>
+% \end{macrocode}
+% Let us now consider the
+% normal case. We have to |\vsplit| the columns from the
+% accumulated material in box 255. Therefore we first assign
+% appropriate values to |\splittopskip| and |\splitmaxdepth|.
+% \begin{macrocode}
+ \splittopskip\topskip
+ \splitmaxdepth\maxdepth
+% \end{macrocode}
+% Then we calculate the current column height (in |\dimen@|).
+% Note that the height of |\partial@page| is already
+% subtracted from |\@colroom| so we can use its value as a
+% starter.
+% \begin{macrocode}
+ \dimen@\@colroom
+% \end{macrocode}
+% But we must also subtract the space occupied by footnotes on the
+% current page. Note that we first have to reset the skip register
+% to its normal value.
+% Again, the actual action is carried out in a utility macro, so that
+% other applications can modify it.
+% \changes{v1.5?}{1994/?/?}{Use \cs{leave@mult@footins}}
+% \begin{macrocode}
+ \divide\skip\footins\col@number
+ \ifvoid\footins \else
+ \leave@mult@footins
+ \fi
+% \end{macrocode}
+% Now we are able to |\vsplit| off all but the last column.
+% Recall that these columns should be saved in the box registers 2,
+% 4,\ldots\ (plus offset).
+% \changes{v1.5a}{1992/11/04}{New box mechanism}
+% \begin{macrocode}
+ \process@cols\mult@gfirstbox{%
+ \setbox\count@
+ \vsplit\@cclv to\dimen@
+% \end{macrocode}
+% After splitting we update the kept marks.
+% \begin{macrocode}
+ \set@keptmarks
+% \end{macrocode}
+% If |\raggedcolumns| is in force we add a |vfill| at the bottom by
+% unboxing the split box.
+% \changes{v1.3c}{1990/03/03}{\cs{unbox}ing avoided.}
+% \begin{macrocode}
+ \ifshr@nking
+ \setbox\count@
+ \vbox to\dimen@
+ {\unvbox\count@\vfill}%
+ \fi
+ }%
+% \end{macrocode}
+% Then the last column follows.
+% \changes{v1.5a}{1992/11/04}{New box mechanism}
+% \begin{macrocode}
+ \setbox\mult@rightbox
+ \vsplit\@cclv to\dimen@
+ \set@keptmarks
+ \ifshr@nking
+ \setbox\mult@rightbox\vbox to\dimen@
+ {\unvbox\mult@rightbox\vfill}%
+ \fi
+% \end{macrocode}
+% Having done this we hope that box 255 is emptied. If not, we
+% reinsert its contents.
+% \begin{macrocode}
+ \ifvoid\@cclv \else
+ \unvbox\@cclv
+ \penalty\outputpenalty
+% \end{macrocode}
+% In this case a footnote that happens to fall into the leftover
+% bit will be typeset on the wrong page. Therefore we warn the user
+% if the current page contains footnotes. The older versions of
+% \mc{} produced this warning regardless of whether or not
+% footnotes were present, resulting in many unnecessary warnings.
+% \changes{v1.3c}{1991/02/17}{Check if footnotes are actually present
+% before issuing a warning.}
+% \begin{macrocode}
+ \ifvoid\footins\else
+ \PackageWarning{multicol}%
+ {I moved some lines to
+ the next page.\MessageBreak
+ Footnotes on page
+ \thepage\space might be wrong}%
+ \fi
+% \end{macrocode}
+% If the `{\sf tracingmulticols}' counter is 4 or higher we also
+% add a rule.
+% \begin{macrocode}
+ \ifnum \c@tracingmulticols>\thr@@
+ \hrule\allowbreak \fi
+ \fi
+% \end{macrocode}
+% To get a correct marks for the current page we have to (locally
+% redefine |\firstmark| and |\botmark|.
+% If |\kept@firstmark| is non-empty then |\kept@botmark| must be
+% non-empty too so we can use their values. Otherwise we use the
+% value of |\kept@topmark| which was first initialized when we
+% gathered the |\partical@page| and later on was updated to the
+% |\botmark| for the preceding page
+%
+% \changes{v1.4a}{1992/02/14}{\cs{botmark} set to \cs{splitbotmark}}
+% \begin{macrocode}
+ \ifx\@empty\kept@firstmark
+ \let\firstmark\kept@topmark
+ \let\botmark\kept@topmark
+ \else
+ \let\firstmark\kept@firstmark
+ \let\botmark\kept@botmark
+ \fi
+% \end{macrocode}
+% We also initalize |\topmark| with |\kept@topmark|. This will make
+% this mark okay for all middle pages of the \mc{} environment.
+% \changes{v1.5d}{1993/09/15}{reinit \cs{topmark}}
+% \begin{macrocode}
+ \let\topmark\kept@topmark
+%<*marktrace>
+ \mult@info\tw@
+ {Use kept top mark:\MessageBreak
+ \meaning\kept@topmark
+ \MessageBreak
+ Use kept first mark:\MessageBreak
+ \meaning\kept@firstmark
+ \MessageBreak
+ Use kept bot mark:\MessageBreak
+ \meaning\kept@botmark
+ \MessageBreak
+ Produce first mark:\MessageBreak
+ \meaning\firstmark
+ \MessageBreak
+ Produce bot mark:\MessageBreak
+ \meaning\botmark
+ \@gobbletwo}%
+%</marktrace>
+% \end{macrocode}
+% With a little more effort we could have done better. If we had,
+% for example, recorded the shrinkage of the material in
+% |\partial@page| it would be now possible to try higher
+% values for |\dimen@| (i.e.\ the column height) to overcome
+% the problem with the nonempty box 255. But this would make the
+% code even more complex so I skipped it in the current
+% implementation.
+%
+% Now we use \LaTeX{}'s standard output
+% mechanism.\footnote{This will produce a lot of overhead since both
+% output routines are held in memory. The correct
+% solution would be to redesign the whole output
+% routine used in \LaTeX.}
+% Admittedly this is a funny way to do it.
+%
+% \begin{macrocode}
+ \setbox\@cclv\vbox{\unvbox\partial@page
+ \page@sofar}%
+% \end{macrocode}
+% The macro |\@makecol| adds all floats assigned for the current
+% page to this page. |\@outputpage| ships out the resulting box.
+% Note that it is just possible that such floats are present even
+% if we do not allow any inside a \mc{} environment.
+% \begin{macrocode}
+ \@makecol\@outputpage
+% \end{macrocode}
+% After the page is shipped out we have to prepare the kept marks
+% for the following page. |\kept@firstmark| and |\kept@botmark|
+% reinitilized by setting them to |\@empty|. The value of
+% |\botmark| is then assigned to |\kept@topmark|.
+% \changes{v1.4g}{1992/06/03}{Only change \cs{kept@topmark} if
+% \cs{kept@botmark} non-empty}
+% \changes{v1.4i}{1992/06/18}{Set \cs{kept@topmark} to \cs{botmark}}
+% \begin{macrocode}
+ \global\let\kept@topmark\botmark
+ \global\let\kept@firstmark\@empty
+ \global\let\kept@botmark\@empty
+%<*marktrace>
+ \mult@info\tw@
+ {(Re)Init top mark:\MessageBreak
+ \meaning\kept@topmark
+ \@gobbletwo}%
+%</marktrace>
+% \end{macrocode}
+% Now we reset |\@colroom| to |\@colht| which is \LaTeX's
+% saved value of |\textheight|.
+% \begin{macrocode}
+ \global\@colroom\@colht
+% \end{macrocode}
+% Then we process deferred floats waiting for their chance to be
+% placed on the next page.
+% \begin{macrocode}
+ \process@deferreds
+ \@whilesw\if@fcolmade\fi{\@outputpage
+ \global\@colroom\@colht
+ \process@deferreds}%
+% \end{macrocode}
+% If the user is interested in statistics we inform him about the
+% amount of space reserved for floats.
+% \begin{macrocode}
+ \mult@info\@ne
+ {Colroom:\MessageBreak
+ \the\@colht\space
+ after float space removed
+ = \the\@colroom \@gobble}%
+% \end{macrocode}
+% Having done all this we must prepare to tackle the next page.
+% Therefore we assign a new value to |\vsize|. New, because
+% |\partial@page| is now empty and |\@colroom| might be
+% reduced by the space reserved for floats.
+% \changes{v1.4p}{1992/11/26}{Use different \cs{vsize} setting}
+% \begin{macrocode}
+ \set@mult@vsize \global
+% \end{macrocode}
+% The |\footins| skip register will be adjusted when the output
+% group is closed.
+% \changes{v1.3c}{1991/03/03}{Unnecessary code removed}
+% \begin{macrocode}
+ \fi}
+% \end{macrocode}
+% \end{macro}
+%
+%
+%
+% \begin{macro}{\leave@mult@footins}
+% This macro is used to subtract the amount of space
+% occupied by footnotes for the current space from the
+% space available for the current column. The space current column
+% is stored in |\dimen@|. See above for the description of the default
+% action.
+% \changes{v1.5?}{1994/?/?}{Macro added}
+% \begin{macrocode}
+\def\leave@mult@footins{%
+ \advance\dimen@-\skip\footins
+ \advance\dimen@-\ht\footins
+}
+% \end{macrocode}
+% \end{macro}
+%
+%
+%
+% \begin{macro}{\speci@ls}
+% We left out two macros: |\process@deferreds| and
+% |\speci@ls|.
+% \changes{v1.5c}{1993/04/18}{Support \cs{clearpage}}
+% \begin{macrocode}
+\def\speci@ls{%
+ \ifnum\outputpenalty <-\@Mi
+% \end{macrocode}
+% If the document ends in the middle of a multicols environment, e.g.,
+% if the user forgot the |\end{multicols}|, \TeX{} adds a very
+% negative penalty to the end of the galley which is intended to signal
+% the output routine that it is time to prepare for shipping out
+% everything remaining. Since inside multicols the output routine of
+% \LaTeX{} is disabled sometimes we better check for this case: if we
+% find a very negative penalty we produce an error message and run
+% the default output routine for this case.
+% \changes{v1.5s}{1998/09/10}{check for \cs{stop} penalty pr/2873}
+% \begin{macrocode}
+ \ifnum \outputpenalty<-\@MM
+ \PackageError{multicol}{Document end
+ inside multicols environment}\@ehd
+ \@specialoutput
+ \else
+% \end{macrocode}
+% \changes{v1.5u}{1999/05/25}{Support \cs{columnbreak}}
+% \changes{v1.5v}{1999/07/18}{Added debug statements for
+% column break support}
+% For the next block of code see comments in section~\ref{sec:colbreak}.
+% \begin{macrocode}
+%<*colbreak>
+ \ifnum\outputpenalty = -\@Mv
+ \mult@info\@ne{Forced column
+ break seen}%
+ \global\advance\vsize-\pagetotal
+ \global\setbox\colbreak@box
+ \vbox{\ifvoid\colbreak@box
+ \else
+ \unvbox\colbreak@box
+ \penalty-\@Mv
+ \fi
+ \unvbox\@cclv}
+ \reinsert@footnotes
+ \else
+%</colbreak>
+% \end{macrocode}
+% If we encounter a float or a marginpar in the current
+% implementation we simply warn the user that this is not allowed.
+% Then we reinsert the page and its footnotes.
+% \begin{macrocode}
+ \PackageWarningNoLine{multicol}%
+ {Floats and marginpars not
+ allowed inside `multicols'
+ environment!}
+ \unvbox\@cclv\reinsert@footnotes
+% \end{macrocode}
+% Additionally we empty the |\@currlist| to avoid later error
+% messages when the \LaTeX{} output routine is again in force.
+% But first we have to place the boxes back onto the
+% |\@freelist|. (|\@elt|s default is |\relax| so
+% this is possible with |\xdef|.)
+% \changes{v1.2a}{1990/02/05}{Float boxes freed.}
+% \begin{macrocode}
+ \xdef\@freelist{\@freelist\@currlist}%
+ \gdef\@currlist{}%
+%<*colbreak>
+ \fi
+%</colbreak>
+ \fi
+% \end{macrocode}
+% If the penalty is $-10001$ it will come from a |\clearpage| and
+% we will execute |\@doclearpage| to get rid of any deferred
+% floats.
+% \begin{macrocode}
+ \else \@doclearpage \fi
+}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\process@deferreds}
+% |\process@deferreds| is a simplified version of \LaTeX{}'s
+% |\@startpage|. We first call the macro
+% |\@floatplacement| to save the current user parameters in
+% internal registers. Then we start a new group and save the
+% |\@deferlist| temporarily in the macro |\@tempb|.
+% \begin{macrocode}
+\def\process@deferreds{%
+ \@floatplacement
+ \@tryfcolumn\@deferlist
+ \if@fcolmade\else
+ \begingroup
+ \let\@tempb\@deferlist
+% \end{macrocode}
+% Our next action is to (globally) empty |\@deferlist| and
+% assign a new meaning to |\@elt|. Here |\@scolelt| is a
+% macro that looks at the boxes in a list to decide whether they
+% should be placed on the next page (i.e.\ on |\@toplist| or
+% |\@botlist|) or should wait for further processing.
+% \begin{macrocode}
+ \gdef\@deferlist{}%
+ \let\@elt\@scolelt
+% \end{macrocode}
+% Now we call |\@tempb| which has the form
+% \begin{center}
+% |\@elt|\meta{box register}|\@elt|^^A
+% \meta{box register}\ldots{}
+% \end{center}
+% So |\@elt| (i.e.\ |\@scolelt|) will distribute the
+% boxes to the three lists.
+% \begin{macrocode}
+ \@tempb \endgroup
+ \fi}
+% \end{macrocode}
+% \end{macro}
+%
+%
+%
+% \begin{macro}{ifshr@nking}
+% \begin{macro}{\raggedcolumns}
+% \begin{macro}{\flushcolumns}
+% \changes{v1.1a}{1989/09/20}{\cs{flushedcolumns} renamed to \cs{flushcolumns}.}
+% The |\raggedcolumns| and |\flushcolumns|
+% declarations are defined with the help of a new |\if...|
+% macro.
+% \begin{macrocode}
+\newif\ifshr@nking
+% \end{macrocode}
+% The actual definitions are simple: we just switch to {\sf true}
+% or {\sf false} depending on the desired action. To avoid extra
+% spaces in the output we enclose these changes in
+% |\@bsphack|\ldots{}\allowbreak|\@esphack|.
+% \begin{macrocode}
+\def\raggedcolumns{%
+ \@bsphack\shr@nkingtrue\@esphack}
+\def\flushcolumns{%
+ \@bsphack\shr@nkingfalse\@esphack}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+%
+% \begin{macro}{\balance@columns@out}
+% Now for the last part of the show: the column balancing output
+% routine. Since this code is called with an explicit penalty
+% (|\eject|) there is no need to check for something special (eg
+% floats). We start by balancing the material gathered.
+% \begin{macrocode}
+\def\balance@columns@out{%
+% \end{macrocode}
+% For this we need to put the contents of box 255 into |\mult@box|.
+% \begin{macrocode}
+%<-colbreak> \setbox\mult@box
+%<-colbreak> \vbox{\unvbox\@cclv}%
+% \end{macrocode}
+% \changes{v1.5u}{1999/05/25}{Support \cs{columnbreak}}
+% \changes{v1.5v}{1999/07/18}{Added debug statements for
+% column break support}
+% For the next block of code see comments in section~\ref{sec:colbreak}.
+% \begin{macrocode}
+%<*colbreak>
+ \setbox\mult@box\vbox{%
+ \ifvoid\colbreak@box\else
+ \unvbox\colbreak@box\break
+ \mult@info\@ne{Re-adding
+ forced break(s) in balancing}%
+ \fi
+ \unvbox\@cclv}%
+%</colbreak>
+ \balance@columns
+% \end{macrocode}
+% This will bring us into the position to apply |\page@sofar|.
+% But first we have to set |\vsize| to a value suitable for
+% one column output.
+% \begin{macrocode}
+ \global\vsize\@colroom
+ \global\advance\vsize\ht\partial@page
+% \end{macrocode}
+% Then we |\unvbox| the |\partial@page| (which may be void if we
+% are not prcessing the first page of this \mc{} environment.
+% \begin{macrocode}
+ \unvbox\partial@page
+% \end{macrocode}
+% Then we return the first and bottom mark and the gathered
+% material to the main vertical list.
+% \begin{macrocode}
+ \return@nonemptymark{first}\kept@firstmark
+ \return@nonemptymark{bot}\kept@botmark
+ \page@sofar
+% \end{macrocode}
+% We need to add a penalty at this point which allows to break at
+% this point since calling the output routine may have removed the
+% only permissible break point thereby ``glueing'' any following
+% skip to the balanced box. In case there are any weird settings
+% for |\multicolsep| etc. this could produce funny results.
+% \changes{v1.5c}{1993/04/18}{added penalty at output routine exit}
+% \begin{macrocode}
+ \penalty\z@
+}
+% \end{macrocode}
+% As we already know, reinserting of footnotes will be done in the
+% macro |\endmulticols|.
+% \end{macro}
+%
+%
+% \begin{macro}{\balance@columns}
+% This macro now does the actual balancing.
+% \begin{macrocode}
+\def\balance@columns{%
+% \end{macrocode}
+% We start by setting the kept marks by updating them with any
+% marks from this box. This has to be done \emph{before} we add a
+% penalty of $-10000$ to the top of the box, otherwise only an
+% empty box will be considered.
+% \changes{v1.5h}{1994/08/26}{Get kept marks first}
+% \begin{macrocode}
+ \get@keptmarks\mult@box
+% \end{macrocode}
+% We then contine by resetting trying to remove any discardable
+% stuff at the end of |\mult@box|. This is rather experimental. We
+% also add a forced break point at the very beginning, so that we
+% can split the box to height zero later on, thereby adding a known
+% |\splittopskip| glue at the beginning.
+% \begin{macrocode}
+ \setbox\mult@box\vbox{%
+ \penalty-\@M
+ \unvbox\mult@box
+ \remove@discardable@items
+ }%
+% \end{macrocode}
+% Then follow values assignments to get the |\vsplit|ting right.
+% We use the natural part of |\topskip| as the natural part for
+% |\splittopskip| and allow for a bit of undershoot and overshoot
+% by adding some stretch and shrink.
+% \changes{v1.5?}{1994/?/?}{Allow columns to come out a bit long or short}
+% \begin{macrocode}
+ \@tempdima\topskip
+ \splittopskip\@tempdima
+ \@plus\multicolundershoot
+ \@minus\multicolovershoot
+ \splitmaxdepth\maxdepth
+% \end{macrocode}
+% The next step is a bit tricky: when \TeX{} assembles material in
+% a box, the first line isn't preceded by interline glue, i.e.
+% there is no parameter like |\boxtopskip| in \TeX{}. This means
+% that the baseline of the first line in our box is at some
+% unpredictable point depending on the height of the largest
+% character in this line. But of course we want all columns to
+% align properly at the baselines of their first lines. For this
+% reason we have opened |\mult@box| with a |\penalty| {\sf -10000}.
+% This will now allow us to split off from |\mult@box| a tiny bit
+% (in fact nothing since the first possible break-point is the
+% first item in the box). The result is that |\splittopskip| is
+% inserted at the top of |\mult@box| which is exactly what we like
+% to achieve.
+% \changes{v1.5?}{1994/?/?}{Do splitting to zero here}
+% \begin{macrocode}
+ \setbox\@tempboxa\vsplit\mult@box to\z@
+% \end{macrocode}
+% Next we try to find a suitable starting point for the calculation
+% of the column height. It should be less than the height finally
+% chosen, but large enough to reach this final value in only a few
+% iterations. The formula which is now implemented will try to
+% start with the nearest value which is a multiple of
+% |\baselineskip|. The coding is slightly tricky in \TeX{} and
+% there are perhaps better ways \ldots
+% \changes{v1.4d}{1992/03/04}{New algorithm for start height}
+% \begin{macrocode}
+ \@tempdima\ht\mult@box
+ \advance\@tempdima\dp\mult@box
+ \divide\@tempdima\col@number
+% \end{macrocode}
+% The code above sets |\@tempdima| to the length of a column if we
+% simply divide the whole box into equal pieces. To get to the next
+% lower multiple of |\baselineskip| we convert this dimen to a
+% number (the number of scaled points) then divide this by
+% |\baselineskip| (also in scaled points) and then multiply this
+% result with |\baselineskip| assigning the result to |\dimen@|.
+% This makes |\dimen@| $\leq$ to |\@tempdimena|.
+% \begin{macrocode}
+ \count@\@tempdima
+ \divide\count@\baselineskip
+ \dimen@\count@\baselineskip
+% \end{macrocode}
+% Next step is to correct our result by taking into account the
+% difference between |\topskip| and |\baselineskip|. We start by
+% adding |\topskip|; if this makes the result too large then we
+% have to subtract one |\baselineskip|.
+% \begin{macrocode}
+ \advance\dimen@\topskip
+ \ifdim \dimen@ >\@tempdima
+ \advance\dimen@-\baselineskip
+ \fi
+% \end{macrocode}
+% At the user's request we start with a higher value (or lower, but
+% this usually only increases the number of tries).
+% \begin{macrocode}
+ \advance\dimen@\c@unbalance\baselineskip
+% \end{macrocode}
+% We type out statistics if we were asked to do so.
+% \changes{v1.4f}{1992/04/28}{\cs{on@line} added to tracing info}
+% \begin{macrocode}
+ \mult@info\@ne
+ {Balance columns\on@line:
+ \ifnum\c@unbalance=\z@\else
+ (off balance=\number\c@unbalance)\fi
+ \@gobbletwo}%
+% \end{macrocode}
+% But we don't allow nonsense values for a start.
+% \begin{macrocode}
+ \ifnum\dimen@<\topskip
+ \mult@info\@ne
+ {Start value
+ \the\dimen@ \space ->
+ \the\topskip \space (corrected)}%
+ \dimen@\topskip
+ \fi
+% \end{macrocode}
+% Now we try to find the final column height. We start by setting
+% |\vbadness| to infinity (i.e.\ $10000$) to suppress
+% underfull box reports while we are trying to find an acceptable
+% solution. We do not need to do it in a group since at the end of
+% the output routine everything will be restored. The setting of
+% the final columns will nearly always produce underfull boxes with
+% badness $10000$ so there is no point in warning the user about
+% it.
+% \changes{v1.2a}{1990/02/05}{Group around main loop removed.}
+% \begin{macrocode}
+ \vbadness\@M
+% \end{macrocode}
+% We also allow for overfull boxes while we trying to split the
+% columns.
+% \begin{macrocode}
+ \vfuzz \col@number\baselineskip
+% \end{macrocode}
+% The variable |\last@try| will hold the dimension used in the
+% previous trial splitting. We initialize it with a negative value.
+% \changes{v1.5?}{1994/?/?}{Initialize \cs{last@try}}
+% \begin{macrocode}
+ \last@try-\p@
+ \loop
+% \end{macrocode}
+% In order not to clutter up \TeX{}'s valuable main memory with
+% things that are no longer needed, we empty all globally used box
+% registers. This is necessary if we return to this point after an
+% unsuccessful trial. We use |\process@cols| for this purpose,
+% starting with |\mult@grightbox|. Note the extra braces around
+% this macro call. They are needed since \PlainTeX{}'s
+% |\loop|\ldots{}\allowbreak|\repeat| mechanism cannot be nested on
+% the same level of grouping.
+% \changes{v1.5a}{1992/11/04}{New box mechanism}
+% \begin{macrocode}
+ {\process@cols\mult@grightbox
+ {\global\setbox\count@
+ \box\voidb@x}}%
+% \end{macrocode}
+% The contents of box |\mult@box| are now copied globally to
+% box~|\mult@grightbox|. (This will be the right-most column, as
+% we shall see later.)
+% \begin{macrocode}
+ \global\setbox\mult@grightbox
+ \copy\mult@box
+% \end{macrocode}
+% We start with the assumption that the trial will be successful.
+% If we end up with a solution that is too bad we set
+% |too@bad| to \texttt{true}.
+% \changes{v1.5b}{1992/11/05}{New badness mechanism}
+% \begin{macrocode}
+%<*badness>
+ \global\too@badfalse
+%</badness>
+% \end{macrocode}
+% Using |\vsplit| we extract the other columns from box register
+% |\mult@grightbox|. This leaves box register |\mult@box|
+% untouched so that we can start over again if this trial was
+% unsuccessful.
+% \begin{macrocode}
+ {\process@cols\mult@firstbox{%
+ \global\setbox\count@
+ \vsplit\mult@grightbox to\dimen@
+% \end{macrocode}
+% After every split we check the badness of the resulting column,
+% normally the amount of extra white in the column.
+% \begin{macrocode}
+%<*badness>
+ \ifnum\c@tracingmulticols>\@ne
+ \@tempcnta\count@
+ \advance\@tempcnta-\mult@grightbox
+ \divide\@tempcnta \tw@
+ \message{^^JColumn
+ \number\@tempcnta\space
+ badness: \the\badness\space}%
+ \fi
+% \end{macrocode}
+% If this badness is larger than the allowed column badness
+% we reject this solution by setting |too@bad| to \texttt{true}.
+% \begin{macrocode}
+ \ifnum\badness>\c@columnbadness
+ \ifnum\c@tracingmulticols>\@ne
+ \message{too bad
+ (>\the\c@columnbadness)}%
+ \fi
+ \global\too@badtrue
+ \fi
+%</badness>
+ }}%
+% \end{macrocode}
+% There is one subtle point here: while all other constructed boxes
+% have a depth that is determined by |\splitmaxdepth| the last box
+% will get a natural depth disregarding the original setting and
+% the value of |\splitmaxdepth| or |\boxmaxdepth|. This means that
+% we may end up with a very large depth in box |\mult@grightbox|
+% which would
+% make the result of the testing incorrect. So we change the value
+% by unboxing the box into itself.
+% \begin{macrocode}
+ \boxmaxdepth\maxdepth
+ \global\setbox\mult@grightbox
+ \vbox{\unvbox\mult@grightbox}%
+% \end{macrocode}
+% We also save a copy |\mult@firstbox| at its ``natural'' size
+% for later use.
+% \begin{macrocode}
+ \setbox\mult@nat@firstbox
+ \vbox{\unvcopy\mult@firstbox}%
+% \end{macrocode}
+% After |\process@cols| has done its job we have the following
+% situation:
+% \begin{center}
+% \begin{tabular}{r@{$\:\:\longleftarrow\:\:$}l}
+% box |\mult@rightbox| & all material \\
+% box |\mult@gfirstbox| & first column \\
+% box |\mult@gfirstbox|${}+2$ & second column \\
+% \multicolumn{1}{c}{$\vdots$} &
+% \multicolumn{1}{c}{$\vdots$} \\
+% box |\mult@grightbox| & last column
+% \end{tabular}
+% \end{center}
+% We report the height of the first column, in brackets
+% the natural size is given.
+% \changes{v1.5?}{1994/?/?}{Show natural size}
+% \begin{macrocode}
+ \ifnum\c@tracingmulticols>\@ne
+ \message{^^JFirst column
+ = \the\dimen@\space
+ (\the\ht\mult@nat@firstbox)}\fi
+% \end{macrocode}
+% If |\raggedcolumns| is in force older releases of this file also
+% shrank the first column to its natural height at this point.
+% This was done so that the first column doesn't run short compared
+% to later columns but it is actually producing incorrect results
+% (overprinting of text) in boundary cases, so since version v1.5q
+% |\raggedcolumns| means allows for all columns to run slightly short.
+% \changes{v1.5q}{1998/01/19}{Do not reset \cs{mult@firstbox} (pr2739)}
+% \begin{macrocode}
+% \ifshr@nking
+% \global\setbox\mult@firstbox
+% \copy\mult@nat@firstbox
+% \fi
+% \end{macrocode}
+% Then we give information about the last column.\footnote{With
+% \TeX{} version 3.141 it is now possible to use \LaTeX's
+% \cs{newlinechar} in the \cs{message} command, but
+% people with older \TeX{} versions will now get
+% \texttt{\string^\string^J} instead of a new line on the screen.}
+% \changes{v1.4a}{1992/02/12}{Changed to proper \cs{endlinechar} in\cs{message}}
+% \begin{macrocode}
+ \ifnum\c@tracingmulticols>\@ne
+ \message{<> last column =
+ \the\ht\mult@grightbox^^J}%
+% \end{macrocode}
+% Some tracing code that we don't compile into the production version
+% unless asked for. It will produce huge listings of the boxes
+% involved in balancing in the transcript file.
+% \begin{macrocode}
+%<*debug>
+ \ifnum\c@tracingmulticols>4
+ {\showoutput
+ \batchmode
+ \process@cols\@ne
+ {\showbox\count@}}%
+ \errorstopmode
+ \fi
+%</debug>
+ \fi
+% \end{macrocode}
+% We check whether our trial was successful. The test used is very
+% simple: we merely compare the first and the last column. Thus
+% the intermediate columns may be longer than the first if
+% |\raggedcolumns| is used. If the right-most column is
+% longer than the first then we start over with a larger value for
+% |\dimen@|.
+% \changes{v1.3c}{1991/03/03}{\cs{global}\cs{advance} left over from older code}
+% \begin{macrocode}
+ \ifdim\ht\mult@grightbox >\dimen@
+% \end{macrocode}
+% If the height of the last box is too large we mark this trial as
+% unsuccessful.
+% \changes{v1.5v}{1999/07/18}{Added tracing statements for
+% trial unsuccesful}
+% \begin{macrocode}
+%<*badness>
+ \too@badtrue
+ \ifnum\c@tracingmulticols>\@ne
+ \typeout{Rejected: last
+ column too large!}%
+ \fi
+ \else
+% \end{macrocode}
+% \changes{v1.5v}{1999/07/18}{Check last column if it contains forced
+% break and reject trial if that is the case}
+%
+% To ensure that there isn't a forced break in the last column we
+% try to split off a box of size |\maxdimen| from |\mult@grightbox|
+% (or rather from a copy of it). This should result in a void box
+% after the split, unless there was a forced break somewhere within
+% the column in which case the material after the break would have
+% stayed in the box.
+% \begin{macrocode}
+%<*colbreak>
+ \setbox\@tempboxa
+ \copy\mult@grightbox
+ \setbox\z@\vsplit\@tempboxa to\maxdimen
+ \ifvoid\@tempboxa
+%</colbreak>
+% \end{macrocode}
+% Thus if |\@tempboxa| is void we have a valid solution.
+% In this case we take a closer
+% look at the last column to decide if this column should be made
+% as long as all other columns or if it should be allowed to be
+% shorter.
+% For this we first have to rebox the column into a box of the
+% appropriate height. If tracing is enabled we then display the
+% badness for this box.
+% \begin{macrocode}
+ \global\setbox\mult@grightbox
+ \vbox to\dimen@
+ {\unvbox\mult@grightbox}%
+ \ifnum\c@tracingmulticols>\@ne
+ \message{Final badness:
+ \the\badness}%
+ \fi
+% \end{macrocode}
+% We then compare this badness with the allowed badness for the final
+% column. If it does not exceed this value we use the box, otherwise
+% we rebox it once more and add some glue at the bottom.
+% \begin{macrocode}
+ \ifnum\badness>\c@finalcolumnbadness
+ \global\setbox\mult@grightbox
+ \vbox to\dimen@
+ {\unvbox\mult@grightbox\vfill}%
+ \ifnum\c@tracingmulticols>\@ne
+ \message{ setting natural
+ (> \the\c@finalcolumnbadness)}%
+ \fi
+ \fi
+% \end{macrocode}
+% If |\@tempboxa| above was not void our trial was unsuccessful and
+% we report this fact and try again.
+% \begin{macrocode}
+%<*colbreak>
+ \else
+ \too@badtrue
+ \ifnum\c@tracingmulticols>\@ne
+ \typeout{Rejected: unprocessed
+ forced break(s) in last column!}%
+ \fi
+ \fi
+ \fi
+%</colbreak>
+% \end{macrocode}
+% If the natural height of the first box is smaller than the
+% current trial size but is larger than the previous trial size it
+% is likely that we have missed a potientially better
+% solution. (This could have happened if for some reason our first
+% trial size was too high.) In that case we dismiss this trial and
+% restart using the natural height for the next trial.
+% \begin{macrocode}
+ \ifdim\ht\mult@nat@firstbox<\dimen@
+ \ifdim\ht\mult@nat@firstbox>\last@try
+ \too@badtrue
+ \ifnum\c@tracingmulticols>\@ne
+ \typeout{Retry: using natural
+ height of first column!}%
+ \fi
+ \dimen@\ht\mult@nat@firstbox
+ \last@try\dimen@
+ \advance\dimen@-\p@
+ \fi
+ \fi
+% \end{macrocode}
+% Finally the switch |too@bad| is tested. If it was made true
+% either earlier on or due to a rightmost column being too large
+% we try again with a slightly larger value for |\dimen@|.
+% \begin{macrocode}
+ \iftoo@bad
+%</badness>
+ \advance\dimen@\p@
+ \repeat
+% \end{macrocode}
+% At that point |\dimen@| holds the height that was determined by
+% the balancing loop.
+% If that height for the columns turns out to be larger
+% than the available space (which is |\@colroom|) we sqeeze the
+% columns into the space assuming that they will have enough
+% shrinkability to allow this.\footnote{This might be wrong, since
+% the shrinkability that accounts for the amount of material might
+% be present only in some columns. But it is better to try then to
+% give up directly.}
+% However, this squeezing should only be done if we are balancing
+% columns on the main galley and \emph{not} if we are building a
+% boxed multicol (in the latter case the current |\@colroom| is
+% irrelevant since the produced box might be moved anywhere at a
+% later stage).
+% \changes{v1.3c}{1991/03/03}{Limit column height to \cs{@colroom}}
+% \changes{v1.5q}{1998/01/19}{Removed setting \cs{dimen@} (pr2739)}
+% \changes{v1.5y}{2000/06/10}{Limit column height only in unrestricted
+% mode (pr/3212)}
+% \begin{macrocode}
+ \if@boxedmulticols\else
+ \ifdim\dimen@>\@colroom
+ \dimen@\@colroom
+ \fi
+ \fi
+% \end{macrocode}
+% Then we move the contents of the odd-numbered box registers to
+% the even-numbered ones, shrinking them if requested.
+% We have to use |\vbox| not |\vtop| (as it was done in
+% the first versions) since otherwise the resulting boxes will have
+% no height (\TB\/ page 81). This would mean that extra
+% |\topskip| is added when the boxes are returned to the
+% page-builder via |\page@sofar|.
+% \changes{v1.3a}{1990/05/20}{Changed \cs{vtop} to \cs{vbox}.}
+% \begin{macrocode}
+ \process@cols\mult@rightbox
+ {\@tempcnta\count@
+ \advance\@tempcnta\@ne
+ \setbox\count@\vbox to\dimen@
+ {%
+% \end{macrocode}
+%
+% \begin{macrocode}
+ \vskip \z@
+ \@plus-\multicolundershoot
+ \@minus-\multicolovershoot
+ \unvbox\@tempcnta
+ \ifshr@nking\vfill\fi}}%
+}
+% \end{macrocode}
+% \end{macro}
+%
+% \end{multicols}
+%
+% \begin{multicols}{2}[\subsection{The box allocations}]
+%
+% \begin{macro}{\mult@rightbox}
+% \begin{macro}{\mult@grightbox}
+% \begin{macro}{\mult@firstbox}
+% \begin{macro}{\mult@gfirstbox}
+% Early releases of these macros used the first box registers
+% 0, 2, 4,\ldots\ for global boxes and 1, 3, 5,\ldots\ for the
+% corresponding local boxes. (You might still find some traces
+% of this setup in the documentation, sigh.) This produced a problem
+% at the moment we had more than 5 columns because then officially
+% allocated boxes were overwritten by the algorithm.
+% The new release now uses private box registers
+% \begin{macrocode}
+\newbox\mult@rightbox
+\newbox\mult@grightbox
+\newbox\mult@gfirstbox
+\newbox\mult@firstbox
+\newbox\@tempa\newbox\@tempa
+\newbox\@tempa\newbox\@tempa
+\newbox\@tempa\newbox\@tempa
+\newbox\@tempa\newbox\@tempa
+\newbox\@tempa\newbox\@tempa
+\newbox\@tempa\newbox\@tempa
+\newbox\@tempa\newbox\@tempa
+\newbox\@tempa\newbox\@tempa
+\newbox\@tempa
+\let\@tempa\relax
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+%
+% \end{multicols}
+%
+%
+% \begin{multicols}{2}[\section{New macros and hacks for version 1.2}]
+%
+% \begin{macro}{\emergencystretch}
+% \begin{macro}{\setemergencystretch}
+% If we don't use \TeX{} 3.0 |\emergencystretch| is undefined
+% so in this case we simply add it as an unused \meta{dimen}
+% register.
+% \changes{v1.4j}{1992/06/25}{Setting of \cs{emergencystretch} on top
+% removed.}
+% \begin{macrocode}
+\@ifundefined{emergencystretch}
+ {\newdimen\emergencystretch}{}
+% \end{macrocode}
+% \changes{v1.2a}{1990/02/05}{Macro added.}
+% My tests showed that the following formula worked pretty well.
+% Nevertheless the |\setemergencystretch| macro also gets
+% |\hsize| as second argument to enable the user to try
+% different formulae.
+% \begin{macrocode}
+\def\setemergencystretch#1#2{%
+ \emergencystretch 4pt
+ \multiply\emergencystretch#1}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+
+
+% \begin{macro}{\set@floatcmds}
+% \changes{v1.2a}{1990/02/05}{Macro added.}
+% \changes{v1.5g}{1994/06/07}{Updated since floats have changed}
+% \changes{v1.5j}{1994/06/07}{Updated since floats have changed again}
+% \changes{v1.5l}{1995/10/19}{Added \cmd{@largefloatcheck}}
+% Even if this should be used as a hook we use a |@| in the
+% name since it is more for experts.
+% \begin{macrocode}
+\def\set@floatcmds{%
+ \let\@dblfloat\@dbflt
+ \def\end@dblfloat{\par
+ \vskip\z@
+ \egroup
+ \color@endbox
+ \@largefloatcheck
+ \outer@nobreak
+% \end{macrocode}
+% This is cheap (defering the floats until after the current page)
+% but any other solution would go deep into \LaTeX's output
+% routine and I don't like to work on it until I know which parts
+% of the output routine have to be reimplemented anyway for
+% \LaTeX3.
+% \begin{macrocode}
+ \ifnum\@floatpenalty<\z@
+% \end{macrocode}
+% We have to add the float to the |\@deferlist| because we assume
+% that outside the \mc{} environment we are in one column mode.
+% This is not entirely correct, I already used the \mc{}
+% environment inside of \LaTeX{}s |\twocolumn| declaration but it
+% will do for most applications.
+% \begin{macrocode}
+ \@cons\@deferlist\@currbox
+ \fi
+ \ifnum\@floatpenalty=-\@Mii
+ \@Esphack
+ \fi}}
+% \end{macrocode}
+% \end{macro}
+%
+% \end{multicols}
+%
+% \begin{multicols}{2}[\subsection{Maintaining the mark registers}]
+% \label{sec:v14}
+%
+% This section contains the routines that set the marks so that they
+% will be handled correctly. They have been introduced with version~1.4.
+%
+% \begin{macro}{\kept@topmark}
+% \changes{v1.4h}{1992/06/04}{Init to double brace pair}
+% \begin{macro}{\kept@firstmark}
+% \begin{macro}{\kept@botmark}
+% First thing we do is to reserve three macro names to hold the
+% replacement text for \TeX's primitives |\firstmark|, |\botmark| and
+% |\topmark|. We initialize the first two to be empty and
+% |\kept@topmark| to contain two empty pair of braces. This is
+% necessary since |\kept@topmark| is supposed to contain the last
+% mark from a preceding page and in \LaTeX{} any ``real'' mark must
+% contain two parts representing left and right mark information.
+% \begin{macrocode}
+\def\kept@topmark{{}{}}
+\let\kept@firstmark\@empty
+\let\kept@botmark\@empty
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+%
+% \begin{macro}{\return@nonemptymark}
+% Sometimes we want to return the value of a ``kept'' mark into a
+% |\mark| node on the main vertical list. This is done by the
+% function |\return@nonemptymark|. As the name suggests it only acts
+% if the replacement text of the kept mark is non-empty. This is done
+% to avoid adding an empty mark when no mark was actually present. If
+% we would nevertheless add such a mark it would be regarded as a
+% valid |\firstmark| later on.
+% \begin{macrocode}
+\def\return@nonemptymark#1#2{%
+ \ifx#2\@empty
+ \else
+% \end{macrocode}
+% For debugging purposes we take a look at the value of the kept mark
+% that we are about to return. This code will get stripped out for
+% production.
+% \begin{macrocode}
+%<*marktrace>
+ \mult@info\tw@
+ {Returned #1 mark:\MessageBreak
+ \meaning#2}%
+% \nobreak
+% \fi
+%</marktrace>
+% \end{macrocode}
+% Since the contents of the mark may be arbitrary \LaTeX{} code we
+% better make sure that it doesn't get expanded any further. (Some
+% expansion have been done already during the execution of
+% |\markright| or |\markboth|.) We therefore use the usual mechanism
+% of a toks register to prohibit expansion.\footnote{Due to the
+% current definition of \cs{markright} etc.\ it wouldn't
+% help to define the \cs{protect} command to prohibit
+% expansion as any \cs{protect} has already vanished due to
+% earlier expansions.}
+% \changes{v1.4n}{1992/09/10}{Make marks robust}
+% \changes{v1.5t}{1999/03/22}{re-add \cs{mark} command which was commented out
+% by mistake at some point in 1998 (pr/2978)}
+% \begin{macrocode}
+ \toks@\expandafter{#2}%
+ \mark{\the\toks@}%
+% \end{macrocode}
+% We don't want any breakpoint between such a returned mark and the
+% following material (which is usually just the box where the mark
+% came from).
+% \begin{macrocode}
+ \nobreak
+ \fi}
+% \end{macrocode}
+% \end{macro}
+%
+%
+% \begin{macro}{\get@keptmarks}
+% If we have some material in a box register we may want to get the
+% first and the last mark out of this box. This can be done with
+% |\get@keptmarks| which takes one argument: the box register number
+% or its nick name defined by |\newbox|.
+% \begin{macrocode}
+\def\get@keptmarks#1{%
+% \end{macrocode}
+% For debugging purposes we take a look at the current dimensions
+% of the box since in earlier versions of the code I made some
+% mistakes in this area.
+% \begin{macrocode}
+%<*debug>
+ \typeout{Mark box #1 before:
+ ht \the\ht#1, dp \the\dp#1}%
+%</debug>
+% \end{macrocode}
+% Now we open a new group an locally copy the box to itself. As a
+% result any operation, i.e.\ |\vsplit|, will only have a local
+% effect. Without this trick the box content would get lost up to
+% the level where the last assignment to the box register was done.
+% \begin{macrocode}
+ \begingroup
+ \vbadness\@M
+ \setbox#1\copy#1%
+% \end{macrocode}
+% Now we split the box to the maximal possible dimension. This
+% should split off the full contents of the box so that effectively
+% everything is split off. As a result |\splitfirstmark| and
+% |\splitbotmark| will contain the first and last mark in the box
+% respectively.
+% \begin{macrocode}
+ \setbox#1\vsplit#1to\maxdimen
+% \end{macrocode}
+% Therefore we can now set the kept marks which is a global
+% operation and afterwards close the group. This will restore the
+% original box contents.
+% \begin{macrocode}
+ \set@keptmarks
+ \endgroup
+% \end{macrocode}
+% For debugging we take again a look at the box dimension which
+% shouldn't have changed.
+% \begin{macrocode}
+%<*debug>
+ \typeout{Mark box #1 \space after:
+ ht \the\ht#1, dp \the\dp#1}%
+%</debug>
+}
+% \end{macrocode}
+% \end{macro}
+%
+%
+% \begin{macro}{\set@keptmarks}
+% The macro |\set@keptmarks| is responsible for setting
+% |\kept@firstmark| and |\kept@botmark|, by checking the current
+% values for |\splitfirstmark| and |\splitbotmark|.
+% \begin{macrocode}
+\def\set@keptmarks{%
+% \end{macrocode}
+% If |\kept@firstmark| is empty we assume that it isn't set. This
+% is strictly speaking not correct as we loose the ability to have
+% marks that are explicitly empty, but for standard \LaTeX{}
+% application it is sufficient. If it is non-empty we don't change
+% the value---within the output routines it will then be restored
+% to |\@empty|.
+% \begin{macrocode}
+ \ifx\kept@firstmark\@empty
+% \end{macrocode}
+% We now put the contents of |\splitfirstmark| into
+% |\kept@firstmark|. In the case that there wasn't any mark at all
+% |\kept@firstmark| will not change by that operation.
+% \begin{macrocode}
+ \expandafter\gdef\expandafter
+ \kept@firstmark
+ \expandafter{\splitfirstmark}%
+% \end{macrocode}
+% When debugging we show the assignment but only when something
+% actually happened.
+% \begin{macrocode}
+%<*marktrace>
+ \ifx\kept@firstmark\@empty\else
+ \mult@info\tw@
+ {Set kept first mark:\MessageBreak
+ \meaning\kept@firstmark%
+ \@gobbletwo}%
+ \fi
+%</marktrace>
+ \fi
+% \end{macrocode}
+% We always try to set the bottom mark to the |\splitbotmark| but
+% of course only when there has been a |\splitbotmark| at all.
+% Again, we assume that an empty |\splitbotmark| means that the
+% split off box part didn't contain any marks at all.
+% \begin{macrocode}
+ \expandafter\def\expandafter\@tempa
+ \expandafter{\splitbotmark}%
+ \ifx\@tempa\@empty\else
+ \global\let\kept@botmark\@tempa
+%<*marktrace>
+ \mult@info\tw@
+ {Set kept bot mark:\MessageBreak
+ \meaning\kept@botmark%
+ \@gobbletwo}%
+%</marktrace>
+ \fi}%
+% \end{macrocode}
+% \end{macro}
+%
+%
+% \begin{macro}{\prep@keptmarks}
+% The |\prep@keptmarks| function is used to initialize the kept
+% marks from the contents of |\partial@page|, i.e.\ the box that
+% holds everything from the top of the current page prior to
+% starting the \mc{} environment. However, such a box is only
+% available if we are not producing a boxed \mc{}.
+% \begin{macrocode}
+\def\prep@keptmarks{%
+ \if@boxedmulticols \else
+ \get@keptmarks\partial@page
+ \fi}
+% \end{macrocode}
+% \end{macro}
+%
+%
+% \begin{macro}{\remove@discardable@items}
+%
+% \begin{macrocode}
+\def\remove@discardable@items{%
+%<*debug>
+ \edef\@tempa{s=\the\lastskip,
+ p=\the\lastpenalty,
+ k=\the\lastkern}%
+ \typeout\@tempa
+%</debug>
+ \unskip\unpenalty\unkern
+%<*debug>
+ \edef\@tempa{s=\the\lastskip,
+ p=\the\lastpenalty,
+ k=\the\lastkern}%
+ \typeout\@tempa
+%</debug>
+ \unskip\unpenalty\unkern
+%<*debug>
+ \edef\@tempa{s=\the\lastskip,
+ p=\the\lastpenalty,
+ k=\the\lastkern}%
+ \typeout\@tempa
+%</debug>
+ \unskip\unpenalty\unkern
+%<*debug>
+ \edef\@tempa{s=\the\lastskip,
+ p=\the\lastpenalty,
+ k=\the\lastkern}%
+ \typeout\@tempa
+%</debug>
+ \unskip\unpenalty\unkern
+}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macrocode}
+%<*badness>
+\newif\iftoo@bad
+% \end{macrocode}
+%
+% \begin{macro}{\c@columnbadness}
+% \begin{macro}{\c@finalcolumnbadness}
+% \begin{macrocode}
+\newcount\c@columnbadness
+\c@columnbadness=10000
+\newcount\c@finalcolumnbadness
+\c@finalcolumnbadness=9999
+
+\newdimen\last@try
+
+% \end{macrocode}
+%
+% \changes{v1.5z1}{2003/02/17}{Change wrong default for
+% \cs{multicolovershoot} to zero (pr/3465).}
+% \begin{macrocode}
+\newdimen\multicolovershoot
+\newdimen\multicolundershoot
+\multicolovershoot=0pt
+\multicolundershoot=2pt
+\newbox\mult@nat@firstbox
+%</badness>
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\mult@info}
+% A helper for producing info messages
+% \begin{macrocode}
+\def\mult@info#1#2{%
+ \ifnum\c@tracingmulticols>#1%
+ \GenericWarning
+ {(multicol)\@spaces\@spaces}%
+ {Package multicol: #2}%
+ \fi
+}
+% \end{macrocode}
+% \end{macro}
+%
+% \end{multicols}
+%
+%
+% \begin{multicols}{2}[\section{Fixing the
+% \cs{columnwidth}}]
+%
+% \begin{macro}{\@footnotetext}
+% \changes{v1.5o}{1997/11/16}{Redefinition added pr/2664.}
+% \changes{v1.5r}{1998/08/17}{Use \cs{@footnotetext} but with
+% local change to \cs{columnwidth}.}
+% \begin{macro}{\mult@footnotetext}
+% \changes{v1.5r}{1998/08/17}{Macro removed again.}
+% If we store the current column width in |\columnwidth| we have
+% to redefine the internal |\@footnotetext| macro to use |\textwidth|
+% for the width of the footnotes rather then using the original
+% definition.
+%
+% Starting with version v1.5r this is now done in a way that the original
+% definition is still used, execpt that locally |\columnwidth| is set to
+% |\textwidth|.
+%
+% This solves two problems: first redefinitions of |\@footnotetext|
+% done by a class will correctly survive and second if multicols is
+% used inside a minipage environment the special definition of
+% |\@footnotetext| in that environment will be picked up and not the
+% one for the main galley (the latter would result in all footnotes
+% getting lost in that case).
+%
+% See the definition of the |\multicols| command further up for the exact
+% code.
+% \end{macro}
+% \end{macro}
+% \end{multicols}
+%
+%
+% \begin{multicols*}{2}[\section{Further extensions}]
+%
+% This section does contain code for extensions added to this package
+% over time. Not all of them may be active, some might sit dormant and
+% wait for being activated in some later release.
+%
+% \subsection{Not balancing the columns}
+%
+% This is fairly trivial to implement. we just have to disable the
+% balancing output routine and replace it by the one that ships out
+% the other pages.
+%
+% \begin{macro}{\multicols*}
+% \changes{v1.5q}{1998/01/19}{Macro added}
+% The code for this environment was suggested by Matthias Clasen.
+% \begin{macrocode}
+%<*nobalance>
+ \@namedef{multicols*}{%
+% \end{macrocode}
+% If we are not on the main galley, i.e., inside a box of some
+% sort, that approach will not work since we don't have a vertical
+% size for the box so we better warn that we balance anyway.
+% \begin{macrocode}
+ \ifinner
+ \PackageWarning{multicol}%
+ {multicols* inside a box does
+ not make sense.\MessageBreak
+ Going to balance anyway}%
+ \else
+ \let\balance@columns@out
+ \multi@column@out
+ \fi
+ \begin{multicols}
+}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\endmulticols*}
+% When ending the environment we simply end the inner
+% \texttt{multicols} environment, except that we better also stick
+% in some stretchable vertical glue so that the last column still
+% containing text is not vertically stretched out.
+% \changes{v1.5q}{1998/01/19}{Macro added}
+% \begin{macrocode}
+ \@namedef{endmulticols*}{\vfill
+ \end{multicols}}
+%</nobalance>
+% \end{macrocode}
+% \end{macro}
+%
+%
+% \subsection{Manual column breaking} \label{sec:colbreak}
+%
+% The problem with manual page breaks within \mc{} is the fact that
+% during collection of material for all columns a page-forcing penalty
+% (i.e. -10000 or higher) would stop the collecting pass which is not
+% quite what is desired. On the other hand, using a penalty like -9999
+% would mean that there would be occasions where the |\vsplit|ing
+% operations within \mc{} would ignore that penalty and still choose a
+% different break point.
+%
+% For this reason the current implementation
+% uses a completely different approach. In a nutshell it extends the \LaTeX{}
+% output routine handling by introducing an additional penalty flag
+% (i.e., a penalty which is forcing but higher than -10000 so that the
+% output routine can look at this value and thus knows why it has been
+% called).
+%
+% Inside the output routine we test for this value and if it appears
+% we do two things: save the galley up to this point in a special box
+% for later use and reduce the |\vsize| by the height of the material
+% seen. This way the forcing penalty is now hidden in that box and we
+% can restart the collection process for the remaining
+% columns. (This is done in |\speci@ls| above.)
+%
+% In the output routines that do the |\vsplit|ting either for
+% balancing or for a full page we simply combine box~255 with the
+% saved box thus getting a single box for splitting which now
+% contains forcing breaks in the right positions.
+%
+%
+% \begin{macro}{\columnbreak}
+% \changes{v1.5u}{1999/05/25}{Macro added}
+% |\columnbreak| is modelled after |\pagebreak| except that we
+% generate a penalty -10005.
+% \begin{macrocode}
+%<*colbreak>
+\mathchardef\@Mv=10005
+\def\columnbreak{%
+% \end{macrocode}
+% We have to ensure that it is only used within a \mc{}
+% environment since if that penalty would be seen by the unmodified
+% \LaTeX{} output routine strange things would happen.
+% \begin{macrocode}
+ \ifnum\col@number<\tw@
+ \PackageError{multicol}%
+ {\noexpand\columnbreak outside multicols}%
+ {This command can only be used within
+ a multicols or multicols* environment.}%
+ \else
+ \ifvmode
+ \penalty -\@Mv\relax
+ \else
+ \@bsphack
+ \vadjust{\penalty -\@Mv\relax}%
+ \@esphack
+ \fi
+ \fi}
+% \end{macrocode}
+% \end{macro}
+%
+%
+% \begin{macro}{\colbreak@box}
+% \changes{v1.5u}{1999/05/25}{Macro added}
+% Need a box to collect the galley up to the column break.
+% \begin{macrocode}
+\newbox\colbreak@box
+%</colbreak>
+%</package>
+% \end{macrocode}
+% \end{macro}
+%
+% \end{multicols*}
+%
+% \Finale
+%
+\endinput
diff --git a/Master/texmf-dist/source/latex/tools/rawfonts.dtx b/Master/texmf-dist/source/latex/tools/rawfonts.dtx
new file mode 100644
index 00000000000..b34e5a2d6cd
--- /dev/null
+++ b/Master/texmf-dist/source/latex/tools/rawfonts.dtx
@@ -0,0 +1,218 @@
+% \iffalse meta-comment
+%
+% Copyright 1993 1994 1995 1996 1997 1998 1999 2000 2001 2002 2003
+% The LaTeX3 Project and any individual authors listed elsewhere
+% in this file.
+%
+% This file is part of the Standard LaTeX `Tools Bundle'.
+% -------------------------------------------------------
+%
+% It 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.3 or later is part of all distributions of LaTeX
+% version 2003/12/01 or later.
+%
+% The list of all files belonging to the LaTeX `Tools Bundle' is
+% given in the file `manifest.txt'.
+%
+% \fi
+% \title{The \textsf{rawfonts} package}
+% \date{v0.01}
+% \author{Alan Jeffrey}
+% \maketitle
+%
+% \CheckSum{286}
+%
+% \section*{Overview}
+%
+% The |rawfonts| \LaTeXe{} package is used to provide emulation
+% of \LaTeX~2.09 documents which used low-level commands such as
+% |\tenrm|. If you say:
+% \begin{verbatim}
+% \usepackage{rawfonts}
+% \end{verbatim}
+% then over sixty fonts such as |\tenrm| will be loaded into \LaTeX.
+% This has a large overhead, for example this document uses:
+% \begin{verbatim}
+% 8221 words of font info for 30 fonts
+% \end{verbatim}
+% but when run with the |rawfonts| package it uses:
+% \begin{verbatim}
+% 19294 words of font info for 73 fonts
+% \end{verbatim}
+% That is |rawfonts| can cause your document to load twice as many
+% fonts. (This overhead is why \LaTeXe{} does not define |\tenrm| and
+% friends by default.)
+%
+% If you want to only load a small
+% number of fonts, you can use the |only|
+% option, for example to only load |\tenrm| and |\tensf|:
+% \begin{verbatim}
+% \usepackage[only,tenrm,tensf]{rawfonts}
+% \end{verbatim}
+% The |rawfonts| package is intended mainly for use with \LaTeX~2.09
+% documents, and you might want to have the package loaded every time
+% you use \LaTeXe{} in compatibility mode. In this case, you should add
+% the line:
+% \begin{verbatim}
+% \RequirePackage{rawfonts}
+% \end{verbatim}
+% to your |latex209.cfg| \LaTeX~2.09 compatibility configuration file.
+%
+% \StopEventually{}
+%
+% \section*{Implementation}
+%
+% The driver for the documentation you're now reading.
+% \begin{macrocode}
+%<*driver>
+\documentclass{ltxdoc}
+\begin{document}
+\DocInput{rawfonts.dtx}
+\end{document}
+%</driver>
+% \end{macrocode}
+% This is a \LaTeXe{} package.
+% \begin{macrocode}
+%<*package>
+\NeedsTeXFormat{LaTeX2e}
+\ProvidesPackage{rawfonts}
+ [1994/05/08 Low-level LaTeX 2.09 font compatibility]
+% \end{macrocode}
+% The |rawfonts| package uses the |somedefs| package.
+% \begin{macrocode}
+\RequirePackage{somedefs}
+% \end{macrocode}
+% By default, all the fonts are loaded, but the |only| option says
+% that only the ones specified as options should be.
+% \begin{macrocode}
+\UseAllDefinitions
+\DeclareOption{only}{\UseSomeDefinitions}
+\DeclareOption*{\UseDefinition{\CurrentOption}}
+\ProcessOptions
+% \end{macrocode}
+% The rest of the code loads fonts. Five point:
+% \begin{macrocode}
+\ProvidesDefinition{\DeclareFixedFont{\fivrm}{OT1}{cmr}{m}{n}{\@vpt}}
+\ProvidesDefinition{\DeclareFixedFont{\fivmi}{OML}{cmm}{m}{it}{\@vpt}}
+\ProvidesDefinition{\DeclareFixedFont{\fivsy}{OMS}{cmsy}{m}{n}{\@vpt}}
+\ProvidesDefinition{\DeclareFixedFont{\fivly}{U}{lasy}{m}{n}{\@vpt}}
+% \end{macrocode}
+% Six point:
+% \begin{macrocode}
+\ProvidesDefinition{\DeclareFixedFont{\sixrm}{OT1}{cmr}{m}{n}{\@vipt}}
+\ProvidesDefinition{\DeclareFixedFont{\sixmi}{OML}{cmm}{m}{it}{\@vipt}}
+\ProvidesDefinition{\DeclareFixedFont{\sixsy}{OMS}{cmsy}{m}{n}{\@vipt}}
+\ProvidesDefinition{\DeclareFixedFont{\sixly}{U}{lasy}{m}{n}{\@vipt}}
+% \end{macrocode}
+% Seven point:
+% \begin{macrocode}
+\ProvidesDefinition{\DeclareFixedFont{\sevrm}{OT1}{cmr}{m}{n}{\@viipt}}
+\ProvidesDefinition{\DeclareFixedFont{\sevmi}{OML}{cmm}{m}{it}{\@viipt}}
+\ProvidesDefinition{\DeclareFixedFont{\sevsy}{OMS}{cmsy}{m}{n}{\@viipt}}
+\ProvidesDefinition{\DeclareFixedFont{\sevit}{OT1}{cmr}{m}{it}{\@viipt}}
+\ProvidesDefinition{\DeclareFixedFont{\sevly}{U}{lasy}{m}{n}{\@viipt}}
+% \end{macrocode}
+% Eight point:
+% \begin{macrocode}
+\ProvidesDefinition{\DeclareFixedFont{\egtrm}{OT1}{cmr}{m}{n}{\@viiipt}}
+\ProvidesDefinition{%
+ \DeclareFixedFont{\egtmi}{OML}{cmm}{m}{it}{\@viiipt}}
+\ProvidesDefinition{%
+ \DeclareFixedFont{\egtsy}{OMS}{cmsy}{m}{n}{\@viiipt}}
+\ProvidesDefinition{%
+ \DeclareFixedFont{\egtit}{OT1}{cmr}{m}{it}{\@viiipt}}
+\ProvidesDefinition{\DeclareFixedFont{\egtly}{U}{lasy}{m}{n}{\@viiipt}}
+% \end{macrocode}
+% Nine point:
+% \begin{macrocode}
+\ProvidesDefinition{\DeclareFixedFont{\ninrm}{OT1}{cmr}{m}{n}{\@ixpt}}
+\ProvidesDefinition{\DeclareFixedFont{\ninmi}{OML}{cmm}{m}{it}{\@ixpt}}
+\ProvidesDefinition{\DeclareFixedFont{\ninsy}{OMS}{cmsy}{m}{n}{\@ixpt}}
+\ProvidesDefinition{\DeclareFixedFont{\ninit}{OT1}{cmr}{m}{it}{\@ixpt}}
+\ProvidesDefinition{\DeclareFixedFont{\ninbf}{OT1}{cmr}{bx}{n}{\@ixpt}}
+\ProvidesDefinition{\DeclareFixedFont{\nintt}{OT1}{cmtt}{m}{n}{\@ixpt}}
+\ProvidesDefinition{\DeclareFixedFont{\ninly}{U}{lasy}{m}{n}{\@ixpt}}
+% \end{macrocode}
+% Ten point:
+% \begin{macrocode}
+\ProvidesDefinition{\DeclareFixedFont{\tenrm}{OT1}{cmr}{m}{n}{\@xpt}}
+\ProvidesDefinition{\DeclareFixedFont{\tenmi}{OML}{cmm}{m}{it}{\@xpt}}
+\ProvidesDefinition{\DeclareFixedFont{\tensy}{OMS}{cmsy}{m}{n}{\@xpt}}
+\ProvidesDefinition{\DeclareFixedFont{\tenit}{OT1}{cmr}{m}{it}{\@xpt}}
+\ProvidesDefinition{\DeclareFixedFont{\tensl}{OT1}{cmr}{m}{sl}{\@xpt}}
+\ProvidesDefinition{\DeclareFixedFont{\tenbf}{OT1}{cmr}{bx}{n}{\@xpt}}
+\ProvidesDefinition{\DeclareFixedFont{\tentt}{OT1}{cmtt}{m}{n}{\@xpt}}
+\ProvidesDefinition{\DeclareFixedFont{\tensf}{OT1}{cmss}{m}{n}{\@xpt}}
+\ProvidesDefinition{\DeclareFixedFont{\tenly}{U}{lasy}{m}{n}{\@xpt}}
+\ProvidesDefinition{\DeclareFixedFont{\tenex}{OMX}{cmex}{m}{n}{\@xpt}}
+% \end{macrocode}
+% Eleven point:
+% \begin{macrocode}
+\ProvidesDefinition{\DeclareFixedFont{\elvrm}{OT1}{cmr}{m}{n}{\@xipt}}
+\ProvidesDefinition{\DeclareFixedFont{\elvmi}{OML}{cmm}{m}{it}{\@xipt}}
+\ProvidesDefinition{\DeclareFixedFont{\elvsy}{OMS}{cmsy}{m}{n}{\@xipt}}
+\ProvidesDefinition{\DeclareFixedFont{\elvit}{OT1}{cmr}{m}{it}{\@xipt}}
+\ProvidesDefinition{\DeclareFixedFont{\elvsl}{OT1}{cmr}{m}{sl}{\@xipt}}
+\ProvidesDefinition{\DeclareFixedFont{\elvbf}{OT1}{cmr}{bx}{n}{\@xipt}}
+\ProvidesDefinition{\DeclareFixedFont{\elvtt}{OT1}{cmtt}{m}{n}{\@xipt}}
+\ProvidesDefinition{\DeclareFixedFont{\elvsf}{OT1}{cmss}{m}{n}{\@xipt}}
+\ProvidesDefinition{\DeclareFixedFont{\elvly}{U}{lasy}{m}{n}{\@xipt}}
+% \end{macrocode}
+% Twelve point:
+% \begin{macrocode}
+\ProvidesDefinition{\DeclareFixedFont{\twlrm}{OT1}{cmr}{m}{n}{\@xiipt}}
+\ProvidesDefinition{\DeclareFixedFont{\twlmi}{OML}{cmm}{m}{it}{\@xiipt}}
+\ProvidesDefinition{\DeclareFixedFont{\twlsy}{OMS}{cmsy}{m}{n}{\@xiipt}}
+\ProvidesDefinition{\DeclareFixedFont{\twlit}{OT1}{cmr}{m}{it}{\@xiipt}}
+\ProvidesDefinition{\DeclareFixedFont{\twlsl}{OT1}{cmr}{m}{sl}{\@xiipt}}
+\ProvidesDefinition{\DeclareFixedFont{\twlbf}{OT1}{cmr}{bx}{n}{\@xiipt}}
+\ProvidesDefinition{\DeclareFixedFont{\twltt}{OT1}{cmtt}{m}{n}{\@xiipt}}
+\ProvidesDefinition{\DeclareFixedFont{\twlsf}{OT1}{cmss}{m}{n}{\@xiipt}}
+\ProvidesDefinition{\DeclareFixedFont{\twlly}{U}{lasy}{m}{n}{\@xiipt}}
+% \end{macrocode}
+% Fourteen point:
+% \begin{macrocode}
+\ProvidesDefinition{\DeclareFixedFont{\frtnrm}{OT1}{cmr}{m}{n}{\@xivpt}}
+\ProvidesDefinition{%
+ \DeclareFixedFont{\frtnmi}{OML}{cmm}{m}{it}{\@xivpt}}
+\ProvidesDefinition{%
+ \DeclareFixedFont{\frtnsy}{OMS}{cmsy}{m}{n}{\@xivpt}}
+\ProvidesDefinition{%
+ \DeclareFixedFont{\frtnbf}{OT1}{cmr}{bx}{n}{\@xivpt}}
+\ProvidesDefinition{\DeclareFixedFont{\frtnly}{U}{lasy}{m}{n}{\@xivpt}}
+% \end{macrocode}
+% Seventeen point:
+% \begin{macrocode}
+\ProvidesDefinition{%
+ \DeclareFixedFont{\svtnrm}{OT1}{cmr}{m}{n}{\@xviipt}}
+\ProvidesDefinition{%
+ \DeclareFixedFont{\svtnmi}{OML}{cmm}{m}{it}{\@xviipt}}
+\ProvidesDefinition{%
+ \DeclareFixedFont{\svtnsy}{OMS}{cmsy}{m}{n}{\@xviipt}}
+\ProvidesDefinition{%
+ \DeclareFixedFont{\svtnbf}{OT1}{cmr}{bx}{n}{\@xviipt}}
+\ProvidesDefinition{\DeclareFixedFont{\svtnly}{U}{lasy}{m}{n}{\@xviipt}}
+% \end{macrocode}
+% Twenty point:
+% \begin{macrocode}
+\ProvidesDefinition{\DeclareFixedFont{\twtyrm}{OT1}{cmr}{m}{n}{\@xxpt}}
+\ProvidesDefinition{\DeclareFixedFont{\twtymi}{OML}{cmm}{m}{it}{\@xxpt}}
+\ProvidesDefinition{\DeclareFixedFont{\twtysy}{OMS}{cmsy}{m}{n}{\@xxpt}}
+\ProvidesDefinition{\DeclareFixedFont{\twtyly}{U}{lasy}{m}{n}{\@xxpt}}
+% \end{macrocode}
+% Twenty-five point:
+% \begin{macrocode}
+\ProvidesDefinition{\DeclareFixedFont{\twfvrm}{OT1}{cmr}{m}{n}{\@xxvpt}}
+% \end{macrocode}
+% That's it.
+% \begin{macrocode}
+%</package>
+% \end{macrocode}
+%
+% \Finale
+%
+% \endinput
diff --git a/Master/texmf-dist/source/latex/tools/showkeys.dtx b/Master/texmf-dist/source/latex/tools/showkeys.dtx
new file mode 100644
index 00000000000..e64dbda0956
--- /dev/null
+++ b/Master/texmf-dist/source/latex/tools/showkeys.dtx
@@ -0,0 +1,796 @@
+% \iffalse meta-comment
+%
+% Copyright 1993 1994 1995 1996 1997 1998 1999 2000 2001 2002 2003
+% The LaTeX3 Project and any individual authors listed elsewhere
+% in this file.
+%
+% This file is part of the Standard LaTeX `Tools Bundle'.
+% -------------------------------------------------------
+%
+% It 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.3 or later is part of all distributions of LaTeX
+% version 2003/12/01 or later.
+%
+% The list of all files belonging to the LaTeX `Tools Bundle' is
+% given in the file `manifest.txt'.
+%
+% \fi
+% \iffalse
+%% File: showkeys.dtx Copyright (C) 1992-1997 David Carlisle
+%
+%<*dtx>
+ \ProvidesFile{showkeys.dtx}
+%</dtx>
+%<package>\NeedsTeXFormat{LaTeX2e}
+%<package>\ProvidesPackage{showkeys}
+%<driver> \ProvidesFile{showkeys.drv}
+% \fi
+% \ProvidesFile{showkeys.dtx}
+ [1997/06/12 v3.12 Show cite and label keys (DPC)]
+%
+% \iffalse
+%<*driver>
+\documentclass{ltxdoc}
+\usepackage
+% [notcite,notref,color]
+ {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{516}
+%
+%
+% \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} option, the packages
+% in the AMS-\LaTeX\ collection, and the \textsf{varioref},
+% \textsf{natbib} and \textsf{harvard} packages.
+%
+% \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).
+%
+% If you find the printed keys distracting, but don't want to use the
+% above options to stop them altogether you may use:
+% \begin{description}
+% \item[color] Print the keys in a distinguishing colour. The default
+% value is a light grey.
+% \end{description}
+% The colours may be changed by redefining the following two colours
+% after the package is loaded.
+% |refkey| (also used for |\cite|) and
+% |labelkey| (also used for |\bibitem|).
+% The defaults are:
+%\begin{verbatim}
+% \definecolor{refkey}{gray}{.75}
+% \definecolor{labelkey}{gray}{.75}
+%\end{verbatim}
+%
+% If this option is used the \textsf{color} package will be loaded.
+%
+% The package accepts two further options.
+% \begin{description}
+% \item[final] to supress the action of this package, for `final'
+% versions.
+% \item[draft] the normal behaviour of this package.
+% \end{description}
+% 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.
+%
+% \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 cannot 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}[ht]
+% 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, \emph{showlabels.sty},
+% Undated package, similar to this one, but shows labels
+% inline, affecting the formating of the document.
+%
+% \bibitem{anon:sk}
+% Annonymous, \emph{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, \emph{\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 their `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}
+% \end{macrocode}
+%
+% \begin{macro}{\SK@refcolor}
+% \begin{macro}{\SK@labelcolor}
+% Colour commands. Normally no-op.
+% \begin{macrocode}
+\let\SK@refcolor\relax
+\let\SK@labelcolor\relax
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+% \changes{v3.11}{1996/11/01}
+% {Colour support added, inspired by tools/2297}
+% |color| option loads the \textsf{color} package and defines the
+% colours. Delayed to the end of the package as package loading not
+% allowed in this option section.
+% \begin{macrocode}
+\DeclareOption{color}{\AtEndOfPackage{%
+ \RequirePackage{color}%
+ \definecolor{refkey}{gray}{.75}%
+ \definecolor{labelkey}{gray}{.75}%
+ \def\SK@refcolor{\color{refkey}}%
+ \def\SK@labelcolor{\color{labelkey}}}}
+% \end{macrocode}
+%
+% \changes{v3.04}{1995/10/30}
+% {final and draft options handling.}
+% Allow |final| to be specified in the document class options
+% to supress the loading of this package.
+% \begin{macrocode}
+\DeclareOption{final}{\endinput}
+\DeclareOption{draft}{}
+% \end{macrocode}
+%
+% \begin{macrocode}
+\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}
+% \changes{v3.09}{1996/08/30}
+% {Add extra group so brace hack works. Donald Arseneau tools/2147}
+% The new definition, print the argument, and then do the old
+% definition.
+% \begin{macrocode}
+\def\label#1{%
+ \@bsphack
+ \SK@\SK@@label{#1}%
+ \begingroup
+ \SK@label{#1}%
+ \endgroup
+ \@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}
+% \end{macrocode}
+%
+% \begin{macrocode}
+\def\@lbibitem[#1]#2{%
+ \SK@lbibitem[#1]{#2}\SK@\SK@@label{#2}\ignorespaces}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\SK@}
+% \changes{v3.07}{1996/05/17}
+% {use \cs{protected@edef} for tools/2147}
+% 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{%
+ \protected@edef\@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{\SK@labelcolor\fbox{%
+ \normalfont\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}
+%
+% \begin{macrocode}
+ \else
+% \end{macrocode}
+% \changes{v3.10}{1996/09/06}
+% {Save prevdepth and restore later}
+% If we insert a box into the main vertical list, do not want to
+% change |\prevdepth| as that would afect vertical spacing in the
+% document. (The box itself should not cause any difference in break
+% points as there is a node there anyway coming from the |\write| to
+% the aux file.
+% \begin{macrocode}
+ \dimen@\prevdepth
+ \nointerlineskip
+% \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}
+ \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 (but perhaps not
+% now that |\prevdepth| is restored.)
+% \changes{v3.00}{1994/09/07}
+% {Back up over a previous skip because of the new
+% \cs{belowcaptionskip}}
+% \changes{v3.04}{1995/10/30}
+% {\cs{advance} added, to total two successive skips.}
+% \changes{v3.04}{1995/10/30}
+% {\cs{nointerlineskip} called before \cs{ifvoid} test, not just
+% void case}
+% \changes{v3.04}{1995/10/30}
+% {\cs{marginparskip} added in inner vmode case}
+% \begin{macrocode}
+ \advance\skip@\lastskip\unskip
+ \setbox\z@\lastbox
+% \end{macrocode}
+% \changes{v3.10}{1996/09/06}
+% {Inner vertical mode case, put it in the margin.}
+% \begin{macrocode}
+ \ifvoid\z@
+ \llap{\SK@lab\SK@lab@relax\kern\marginparsep}%
+ \else
+ \hbox{\box\z@\kern\marginparsep\SK@labx}%
+ \fi
+ \vskip\skip@
+ \else
+% \end{macrocode}
+% In outer vertical mode, previously used a |\vadjust| at the start of
+% the next paragraph (and before that used |\marginpar|). These
+% methods sometimes cause extra space, eg if paragraph starts with a
+% math display, so now just insert the box directly, taking care not
+% to change |\prevdepth|.
+% \changes{v3.02}{1995/03/17}
+% {Use \cs{vadjust} instead of \cs{marginpar}}
+% \changes{v3.10}{1996/09/06}
+% {Insert the box directly}
+% \begin{macrocode}
+ \llap{\SK@lab\SK@lab@relax\kern\marginparsep}%
+ \fi
+% \end{macrocode}
+% Restore |\prevdepth|.
+% \begin{macrocode}
+ \prevdepth\dimen@
+% \end{macrocode}
+%
+% \begin{macrocode}
+ \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
+% \end{macrocode}
+% \changes{v3.08}{1996/07/10}{Missing percent added. /2215}
+% \begin{macrocode}
+ \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@eqnarray}
+% 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
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\eqnarray}
+% \changes{v3.09}{1996/08/30}
+% {Fix eqnarray AMS incompatibility. tools/2252}
+% When the AMS packages are loaded |showkeys| assumes environments
+% work `The AMS way' However |eqnarray| (unlike |equation|) is not
+% redefined, so here we need to remove some of the AMS hacks.
+% \begin{macrocode}
+\toks@\expandafter{\eqnarray}
+\edef\eqnarray{\let\noexpand\tagform@\noexpand\SK@tagform@\the\toks@}
+% \end{macrocode}
+% \end{macro}
+%
+% \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 AMS environments
+% \begin{macrocode}
+\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}
+%
+% \begin{macro}{\SK@def}
+% \changes{v3.05}{1995/11/09}
+% {Macro added}
+% This macro redefines a command |#1|. The new definition can make use
+% of the old definition as |\SK@|\emph{old name}. If |#1| is really a
+% |\protect|'ed command with the real definition in a `\emph{space}'
+% command then the `space' version is used as the old definition.
+% Need to test this for each command as some package may have changed
+% the status of a command to being `protected'.
+% The new definition is made as if with |\DeclareRobustCommand|, but
+% with |\def| syntax for the argument specification.
+% \begin{macrocode}
+\def\SK@def#1{%
+ \edef\@tempa{\expandafter\@gobble\string#1}%
+ \@ifundefined{\@tempa\space}%
+ {\expandafter\let\csname SK@\@tempa\endcsname#1}%
+ {\expandafter\let\csname SK@\@tempa\expandafter\endcsname
+ \csname\@tempa\space\endcsname}%
+ \expandafter\def\expandafter#1\expandafter{%
+ \expandafter\protect\csname\@tempa\space\endcsname}%
+ \expandafter\def\csname\@tempa\space\endcsname}
+% \end{macrocode}
+% \end{macro}
+%
+% The next section redefines |\ref| and |\pageref| (unless the
+% \texttt{notref} option was given).
+% \begin{macrocode}
+\ifx\SK@ref\@empty
+% \end{macrocode}
+% Even if \texttt{notref} option is used, need to fudge the
+% \textsf{varioref} commands as they use |\label| internally.
+% \changes{v3.04}{1995/10/30}
+% {improve varioref support in notref option case, for tools/1744}
+% \begin{macrocode}
+\AtBeginDocument{%
+ \ifx\vpageref\@undefined\else
+ \SK@def\@@vpageref#1[#2]#3{{%
+ \let\label\SK@label
+ \SK@@@vpageref#1[#2]{#3}}}%
+ \DeclareRobustCommand\vref[1]{%
+ \unskip~\ref{#1}%
+ {\let\label\SK@label
+ \SK@@@vpageref\unskip[\unskip\space]{#1}}}%
+ \fi}
+\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{%
+ \SK@def\ref#1{\SK@\SK@@ref{#1}\SK@ref{#1}}%
+ \SK@def\pageref#1{\SK@\SK@@ref{#1}\SK@pageref{#1}}%
+ \ifx\vpageref\@undefined\else
+% \end{macrocode}
+% varioref support.
+% \begin{macrocode}
+ \SK@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
+% \end{macrocode}
+% \changes{v3.06}{1995/11/22}
+% {Fix \cs{harvarditem} support}
+% \begin{macrocode}
+\AtBeginDocument{%
+ \ifx\HAR@checkdef\@undefined\else
+ \expandafter\let\expandafter
+ \SK@HAR@bi\csname\string\harvarditem\endcsname
+ \expandafter\def\csname\string\harvarditem\endcsname[#1]#2#3#4{%
+ \SK@HAR@bi[#1]{#2}{#3}{#4}\SK@\SK@@label{#4}}%
+ \fi}
+\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
+% \textsf{natbib} and \textsf{cite}.
+% \changes{v3.01}{1994/09/09}
+% {Add \cs{citefullauthor}}
+% \changes{v3.12}{1997/06/12}
+% {Support cite package. tools/2490}
+%
+% If \textsf{cite} or \textsf{overcite} is being used, redefine |\citen|
+% rather than |\cite| so as not to spoil the space and punctuation
+% calculations done by those packages.
+% \begin{macrocode}
+ \ifx\citen\@undefined
+ \SK@def\cite#1#{\SK@citea{#1}}%
+ \else
+ \SK@def\citen#1{\SK@\SK@@ref{#1}\SK@citen{#1}}%
+ \fi
+ \SK@def\citeauthor#1{\SK@\SK@@ref{#1}\SK@citeauthor{#1}}%
+ \SK@def\citefullauthor#1{\SK@\SK@@ref{#1}\SK@citefullauthor{#1}}%
+ \SK@def\citeyear#1{\SK@\SK@@ref{#1}\SK@citeyear{#1}}%
+ \else
+% \end{macrocode}
+% In the \textsf{harvard} style do \emph{not} redefine individual cite
+% commands. Just redefine one internal command that is used in all the
+% citation forms.
+% \begin{macrocode}
+ \SK@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
+% \end{macrocode}
+% \changes{v3.06}{1995/11/22}
+% {Fix \cs{harvarditem} support}
+% \begin{macrocode}
+ \expandafter\def\csname\string\harvarditem\endcsname[#1]#2#3#4{%
+ \SK@HAR@bi[#1]{#2}{#3}{#4}\SK@\SK@@label{#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
+ \SK@refcolor
+ \rlap{\vrule\raise .75em%
+ \hbox{\underbar{\normalfont\footnotesize\ttfamily#2}}}}}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macrocode}
+%</package>
+% \end{macrocode}
+%
+% \Finale
+%
diff --git a/Master/texmf-dist/source/latex/tools/somedefs.dtx b/Master/texmf-dist/source/latex/tools/somedefs.dtx
new file mode 100644
index 00000000000..80fa373498d
--- /dev/null
+++ b/Master/texmf-dist/source/latex/tools/somedefs.dtx
@@ -0,0 +1,171 @@
+% \iffalse meta-comment
+%
+% Copyright 1993 1994 1995 1996 1997 1998 1999 2000 2001 2002 2003
+% The LaTeX3 Project and any individual authors listed elsewhere
+% in this file.
+%
+% This file is part of the Standard LaTeX `Tools Bundle'.
+% -------------------------------------------------------
+%
+% It 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.3 or later is part of all distributions of LaTeX
+% version 2003/12/01 or later.
+%
+% The list of all files belonging to the LaTeX `Tools Bundle' is
+% given in the file `manifest.txt'.
+%
+% \fi
+% \title{The \textsf{somedefs} toolkit package}
+% \date{long time ago in a different century\ldots}
+% \author{Alan Jeffrey}
+% \maketitle
+%
+% \CheckSum{56}
+%
+% \changes{v0.03}{1994/06/01}{Use new style error commands. DPC}
+% \changes{v0.02}{1994/05/10}{Added a \cmd\relax, to stop arguments to
+% \cmd\newcommand\ being unbraced by \cmd\ProvidesCommand. Added
+% an error message for commands which are requested but never
+% defined. Spotted by DPC.}
+%
+% \section*{Overview}
+%
+% This is an example `programmers toolkit' package, for use by package
+% writers. It allows package writers to provide options which switch
+% definitions on and off. For example, a package |fred| might define a
+% large number of commands, including |\foo| and |\baz|, so:
+% \begin{verbatim}
+% \usepackage{fred}
+% \end{verbatim}
+% would use a lot of memory, even if |\foo| and |\baz| were the only
+% commands needed. However, if the author of |fred| used the |somedefs|
+% package, then the user would be able to say:
+% \begin{verbatim}
+% \usepackage[only,foo,baz]{fred}
+% \end{verbatim}
+% and only the commands |\foo| and |\baz| would be defined.
+%
+% To use the |somedefs| package in your own packages or classes, you
+% say:
+% \begin{verbatim}
+% \RequirePackage{somedefs}
+% \end{verbatim}
+% You can then use four new commands:
+% \begin{flushleft}\begin{itemize}
+% \item |\UseAllDefinitions| which says that all the commands in the
+% file should be defined.
+% \item |\UseSomeDefinitions| which says that only the commands
+% specified by |\UseDefinition| should be defined.
+% \item |\UseDefinition{|\meta{name}|}| which says that the command
+% |\name| should be defined.
+% \item |\ProvidesDefinition{|\meta{definition}|}| which provides one
+% definition, of the form |\definingcommand{\command}...|
+% \end{itemize}\end{flushleft}
+% For example, the package |fred| could say:
+% \begin{verbatim}
+% \RequirePackage{somedefs}
+% \UseAllDefinitions
+% \DeclareOption{only}{\UseSomeDefinitions}
+% \DeclareOption*{\UseDefinition{\CurrentOption}}
+% \ProcessOptions
+% \ProvidesDefinition{\newcommand{\foo}{...}}
+% \ProvidesDefinition{\newcommand{\baz}{...}}
+% \end{verbatim}
+% One of the commands |\UseAllDefinitions| or |\UseSomeDefinitions|
+% should always be used. You may have some commands which need other
+% commands, in which case you have to declare the options by hand. For
+% example, if the command |\bar| needs the command |\foo|, you could
+% say:
+% \begin{verbatim}
+% \DeclareOption{bar}{\UseDefinition{bar}\UseDefinition{foo}}
+% \end{verbatim}
+% For a longer example of the use of the |somedefs| package, look at the
+% |rawfonts| package.
+%
+% \StopEventually{}
+%
+% \section*{Implementation}
+%
+% The driver for the documentation you're now reading.
+% \begin{macrocode}
+%<*driver>
+\documentclass{ltxdoc}
+\begin{document}
+\DocInput{somedefs.dtx}
+\end{document}
+%</driver>
+% \end{macrocode}
+% This is a \LaTeXe{} package.
+% \begin{macrocode}
+%<*package>
+\NeedsTeXFormat{LaTeX2e}
+\ProvidesPackage{somedefs}[1994/06/01 v0.03 Toolkit for optional definitions]
+% \end{macrocode}
+% \begin{macro}{\UseSomeDefinitions}
+% \begin{macro}{\UseAllDefinitions}
+% \begin{macro}{\UseDefinition}
+% \begin{macro}{\ProvidesDefinition}
+% \begin{macro}{\@providesdefinition}
+% \begin{macro}{\@provides@definition}
+% \begin{macro}{\@unprovided@definition}
+% The package works by having |\UseDefinition{|\meta{name}|}| define
+% |\name| to be |\@unprovided@definition|.
+% If |\UseSomeDefinitions| has been called,
+% then |\ProvidesDefinition| looks to see if |\name|
+% is |\@unprovided@definition|. If
+% |\UseAllDefinitions| has been called, then |\ProvidesDefinition|
+% does nothing. If neither has been called, then
+% |\ProvidesDefinition| produces an error message.
+% \begin{macrocode}
+\def\UseSomeDefinitions{%
+ \let\ProvidesDefinition\@providesdefinition
+}
+\def\UseAllDefinitions{%
+ \let\ProvidesDefinition\@firstofone
+}
+\def\UseDefinition#1{%
+ \expandafter\let\csname#1\endcsname\@unprovided@definition
+}
+\def\ProvidesDefinition#1{%
+ \PackageError{somedefs}%
+ {No \noexpand\UseSomeDefinitions or \string\UseAllDefinitions}%
+ {The package which used the `somedefs' package has an error.}%
+}
+\def\@providesdefinition#1{\@provides@definition#1\relax
+ \@provides@definition}
+\def\@provides@definition#1#2#3\@provides@definition{%
+ \ifx#2\@unprovided@definition
+ #1#2#3%
+ \fi
+}
+\def\@unprovided@definition{%
+ \PackageError{somedefs}%
+ {Package `somedefs' error: this command was never defined}%
+ {You have requested a command which does not exist.}%
+}
+\@onlypreamble\UseSomeDefinitions
+\@onlypreamble\UseAllDefinitions
+\@onlypreamble\UseDefinition
+\@onlypreamble\ProvidesDefinition
+\@onlypreamble\@providesdefinition
+\@onlypreamble\@provides@definition
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% That's it!
+% \begin{macrocode}
+%</package>
+% \end{macrocode}
+%
+% \Finale
+%
+% \endinput
diff --git a/Master/texmf-dist/source/latex/tools/tabularx.dtx b/Master/texmf-dist/source/latex/tools/tabularx.dtx
new file mode 100644
index 00000000000..502ca409970
--- /dev/null
+++ b/Master/texmf-dist/source/latex/tools/tabularx.dtx
@@ -0,0 +1,896 @@
+% \iffalse meta-comment
+%
+% Copyright 1993 1994 1995 1996 1997 1998 1999 2000 2001 2002 2003
+% The LaTeX3 Project and any individual authors listed elsewhere
+% in this file.
+%
+% This file is part of the Standard LaTeX `Tools Bundle'.
+% -------------------------------------------------------
+%
+% It 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.3 or later is part of all distributions of LaTeX
+% version 2003/12/01 or later.
+%
+% The list of all files belonging to the LaTeX `Tools Bundle' is
+% given in the file `manifest.txt'.
+%
+% \fi
+% \iffalse
+%% File: tabularx.dtx Copyright (C) 1991-1999 David Carlisle
+%
+%<*dtx>
+ \ProvidesFile{tabularx.dtx}
+%</dtx>
+%<package>\NeedsTeXFormat{LaTeX2e}
+%<package>\ProvidesPackage{tabularx}
+%<driver> \ProvidesFile{tabularx.drv}
+% \fi
+% \ProvidesFile{tabularx.dtx}
+ [1999/01/07 v2.07 `tabularx' package (DPC)]
+% \iffalse
+%<*driver>
+\documentclass{ltxdoc}
+\usepackage[infoshow]{tabularx}
+\begin{document}
+ \DocInput{tabularx.dtx}
+\end{document}
+%</driver>
+% \fi
+%
+% \changes{v1.00}{1992/01/30}{Initial version.}
+% \changes{v1.01}{1992/07/07}{Re-issue for the new doc and docstrip.}
+% \changes{v1.02}{1992/07/17}{Added some support for \cmd\verb}
+% \changes{v1.03}{1992/08/17}
+% {Added \cs{ifnum0}!=`\{\cs{fi}\} brackets after report by
+% Andreas Maassen}
+% \changes{v1.04}{1992/09/02}
+% {fixed \cmd\verb, and support footnotes.}
+% \changes{v1.05}{1992/11/06}
+% {preserve all LaTeX counters}
+% \changes{v1.06}{1993/08/02}
+% {(Martin Schroeder) Support the optional [t] or [b] argument.
+% Also now works with delarray.sty.}
+% \changes{v1.07}{1993/08/27}
+% {Modifications to make this style compatible with calc.sty.}
+% \changes{v2.00}{1994/03/14}
+% {Update to LaTeX2e}
+% \changes{v2.01}{1994/05/22}
+% {New Tracing format.}
+%
+%
+% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%
+%
+% \CheckSum{456}
+%
+% \GetFileInfo{tabularx.dtx}
+% \title{The \textsf{tabularx} package\thanks{This file
+% has version number \fileversion, last
+% revised \filedate.}}
+% \author{David Carlisle}
+% \date{\filedate}
+% \maketitle
+% \DeleteShortVerb{\|}
+% \MakeShortVerb{\"}
+%
+% \begin{abstract}
+% A new environment, {\ttfamily tabularx}, is defined, which takes the
+% same arguments as {\ttfamily tabular*}, but modifies the widths of
+% certain columns, rather than the inter column space, to set a table
+% with the requested total width. The columns that may stretch are
+% marked with the new token {\ttfamily X} in the preamble argument.
+%
+% This package requires the {\ttfamily array} package.
+% \end{abstract}
+%
+% \section{Introduction}
+% This package implements a version of the {\ttfamily tabular}
+% environment in which the widths of certain columns are calculated so
+% that the table is is a specified width. Requests for such an
+% environment seem to occur quite regularly in {\ttfamily
+% comp.text.tex}.
+%
+% \DescribeEnv{tabularx}
+% "\begin{tabularx}{"\meta{width}"}{"\meta{preamble}"}"\\
+% The arguments of "tabularx" are essentially the same as those of
+% the standard "tabular*" environment. However rather than adding space
+% between the columns to achieve the desired width, it adjusts the
+% widths of some of the columns. The columns which are affected by the
+% {\ttfamily tabularx} environment should be denoted with the letter
+% {\ttfamily X} in the preamble argument. The {\ttfamily X} column
+% specification will be converted to "p{"\meta{some value}"}" once the
+% correct column width has been calculated.
+%
+% \section{Examples}
+%
+% The following table is set with
+% "\begin{tabularx}{250pt}{|c|X|c|X|} ...".
+%
+% \begin{center}
+% \begin{tabularx}{250pt}{|c|X|c|X|}
+% \hline
+% \multicolumn{2}{|c|}{Multicolumn entry!}&
+% THREE&
+% FOUR\\
+% \hline
+% one&
+% \raggedright\arraybackslash The width of this column depends on the
+% width of the table.\footnote
+% {You can now use {\ttfamily \bslash footnote} inside {\ttfamily
+% tabularx}!}&
+% three&
+% \raggedright\arraybackslash Column four will act in the same way as
+% column two, with the same width.\\
+% \hline
+% \end{tabularx}
+% \end{center}
+% If we change the first line to "\begin{tabularx}{300pt}{|c|X|c|X|}" we
+% get:
+% \begin{center}
+% \begin{tabularx}{300pt}{|c|X|c|X|}
+% \hline
+% \multicolumn{2}{|c|}{Multicolumn entry!}&
+% THREE&
+% FOUR\\
+% \hline
+% one&
+% \raggedright\arraybackslash The width of this column depends on the
+% width of the table.&
+% three&
+% \raggedright\arraybackslash Column four will act in the same way as
+% column two, with the same width.\\
+% \hline
+% \end{tabularx}
+% \end{center}
+%
+% \edef\mytt{\expandafter\noexpand\csname
+% mdseries\endcsname\noexpand\ttfamily}
+% \section{Differences between {\mytt tabularx} and {\mytt tabular*}}
+% These two environments take the same arguments, to produce a table of
+% a specified width. The main differences between them are:
+% \begin{itemize}
+% \item {\ttfamily tabularx} modifies the widths of the \emph{columns},
+% whereas {\ttfamily tabular*} modifies the widths of the inter-column
+% \emph{spaces}.
+% \item {\ttfamily tabular} and {\ttfamily tabular*} environments may be
+% nested with no restriction, however if one {\ttfamily tabularx}
+% environment occurs inside another, then the inner one {\em must\/} be
+% enclosed by "{ }".
+% \item The body of the {\ttfamily tabularx} environment is in fact the
+% argument to a command, and so certain constructions which are not
+% allowed in command arguments (like "\verb") may not be used.\footnote
+% {Since Version 1.02, {\ttfamily\bslash verb and \ttfamily\bslash
+% verb*} may be used, but they may treat spaces incorrectly, and the
+% argument can not contain an unmatched {\ttfamily\char`\{} or
+% {\ttfamily\char`\}}, or a {\ttfamily\char`\%} character.}
+% \item {\ttfamily tabular*} uses a primitive capability of \TeX\ to
+% modify the inter column space of an alignment. {\ttfamily tabularx}
+% has to set the table several times as it searches for the best column
+% widths, and is therefore much slower. Also the fact that the body is
+% expanded several times may break certain \TeX\ constructs.
+% \end{itemize}
+%
+% \section{Customising the behaviour of {\mytt tabularx}}
+%
+% \subsection{Terminal output}
+% \DescribeMacro{\tracingtabularx}
+% If this declaration is made, say in the document preamble, then all
+% following {\ttfamily tabularx} environments will print information
+% about column widths as they repeatedly re-set the tables to find the
+% correct widths.
+%
+% As an alternative to using the "\tracingtabularx" declaration, either
+% of the options "infoshow" or "debugshow" may be given, either in the
+% "\usepackage" command that loads "tabularx", or as a global option
+% in the "\documentclass" command.
+%
+% \subsection{The environment used to typeset the {\mytt X} columns}
+% By default the {\ttfamily X} specification is turned into
+% "p{"\meta{some value}"}". Such narrow columns often
+% require a special format, this may be achieved using the ">" syntax
+% of {\ttfamily array.sty}. So for example you may give a specification
+% of ">{\small}X". Another format which is useful in narrow columns is
+% ragged right, however \LaTeX's "\raggedright" macro redefines
+% "\\" in a way which conflicts with its use in a tabular or array
+% environments.
+%\DescribeMacro{\arraybackslash}
+% For this reason this package introduces the command "\arraybackslash",
+% this may be used after a "\raggedright", "\raggedleft" or
+% "\centering" declaration. Thus a {\ttfamily tabularx} preamble may
+% specify\\
+% ">{\raggedright\arraybackslash}X".
+%
+% \DescribeMacro{\newcolumntype}
+% These preamble specifications may of course be saved using the
+% command, "\newcolumntype", defined in {\ttfamily array.sty}. Thus we
+% may say\\
+% "\newcolumntype{Y}{>{\small\raggedright\arraybackslash}X}"\\
+% and then use {\ttfamily Y} in the {\ttfamily tabularx} preamble
+% argument.
+%
+% \DescribeMacro{\tabularxcolumn}
+% The {\ttfamily X} columns are set using the {\ttfamily p} column which
+% corresponds to "\parbox[t]". You may want them set using, say, the
+% {\ttfamily m} column, which corresponds to "\parbox[c]". It is not
+% possible to change the column type using the ">" syntax, so another
+% system is provided. "\tabularxcolumn" should be defined to be a macro
+% with one argument, which expands to the {\ttfamily tabular} preamble
+% specification that you want to correspond to {\ttfamily X}. The
+% argument will be replaced by the calculated width of a column.
+%
+% The default is "\newcommand{\tabularxcolumn}[1]{p{#1}}". So we may
+% change this with a command such as:\\
+% "\renewcommand{\tabularxcolumn}[1]{>{\small}m{#1}}"
+%
+% \subsection{Column widths}
+% Normally all {\ttfamily X} columns in a single table are set to the
+% same width, however it is possible to make {\ttfamily tabularx} set
+% them to different widths.
+% A preamble argument of "{>{\hsize=.5\hsize}X>{\hsize=1.5\hsize}X}"
+% specifies two columns, the second will be three times as wide as the
+% first. However if you want to play games like this you should follow
+% the following two rules.
+% \begin{itemize}
+% \item Make sure that the sum of the widths of all the {\ttfamily X}
+% columns is unchanged. (In the above example, the new widths still add
+% up to twice the default width, the same as two standard {\ttfamily X}
+% columns.)
+% \item Do not use "\multicolumn" entries which cross any {\ttfamily X}
+% column.
+% \end{itemize}
+% As with most rules, these may be broken if you know what you are
+% doing.
+%
+% \subsection{If the algorithm fails\ldots}
+% It may be that the widths of the `normal' columns of the table
+% already total more than the requested total
+% width. \textsf{tabularx} refuses to set the
+% \texttt{X} columns to a negative width, so in this case you get a
+% warning ``X Columns too narrow (table too wide)''.
+%
+% The \texttt{X} columns will in this case be set to a width of 1em
+% and so the table itself will be wider than the requested total width
+% given in the argument to the environment.
+% This behaviour of the package can be customised slightly
+% as noted in the documentation of the code section.
+%
+% \StopEventually{}
+%
+% \section{The Macros}
+%
+% \begin{macrocode}
+%<*package>
+% \end{macrocode}
+%
+% \changes{v2.00}{1994/02/07}
+% {New Option Handling}
+% \begin{macrocode}
+\DeclareOption{infoshow}{\AtEndOfPackage\tracingtabularx}
+\DeclareOption{debugshow}{\AtEndOfPackage\tracingtabularx}
+\ProcessOptions
+% \end{macrocode}
+%
+% This requires {\ttfamily array.sty}.
+% \changes{v2.00}{1994/02/07}
+% {Use LaTeX2e's \cmd{\RequirePackage} to load array}
+% \begin{macrocode}
+\RequirePackage{array}[1994/02/03]
+% \end{macrocode}
+%
+% First some registers etc.\ that we need.
+% \begin{macrocode}
+\newdimen\TX@col@width
+\newdimen\TX@old@table
+\newdimen\TX@old@col
+\newdimen\TX@target
+\newdimen\TX@delta
+\newcount\TX@cols
+\newif\ifTX@
+% \end{macrocode}
+%
+% Now a trick to get the body of an environment into a token register,
+% without doing any expansion. This does not do any real checking of
+% nested environments, so if you should need to nest one {\ttfamily
+% tabularx} inside another, the inner one must be surrounded by "{ }".
+%
+% \begin{macro}{\tabularx}
+% Prior to v1.06, this macro took two arguments, which were saved in
+% separate registers before the table body was saved by "\TX@get@body".
+% Unfortunatly this disables the "[t]" optional argument. Now just save
+% the width specification separately, then clear the token register
+% "\toks@".
+% Finally call "\TX@get@body" to begin saving the body of the table.
+% The "{\ifnum0=`}\fi" was added at v1.03, to allow "tabularx" to appear
+% inside a "\halign".^^A
+% \setbox0=\hbox{\footnotesize"\iffalse{\fi\ifnum0=`}\fi"}^^A
+% \setbox2=\hbox{\footnotesize"\ifnum0=`{}\fi"}^^A
+% \footnote{This adds an extra level of grouping,
+% which is not really needed. Instead, I could use \box0\ here, and
+% \box2\ below, however the code here would then have to be moved after
+% the first line, because of the footnote to page 386 of the \TeX{}Book,
+% and I do not think I should be writing code that is so obscure as to
+% be documented in a footnote in an appendix called ``Dirty Tricks''!}
+%
+% This mechanism of grabbing an environment body does have the
+% disadvantage (shared with the AMS alignment environments) that you
+% can not make extension environments by code such as
+%\begin{verbatim}
+%\newenvironment{foo}{\begin{tabularx}{XX}}{\end{tabularx}}
+%\end{verbatim}
+% as the code is looking for a literal string "\end{tabularx}" to stop
+% scanning. Since version 2.02, one may avoid this problem by using
+% "\tabularx" and "\endtabularx" directly in the definition:
+%\begin{verbatim}
+%\newenvironment{foo}{\tabularx{XX}}{\endtabularx}
+%\end{verbatim}
+% The scanner now looks for the end of the current environment ("foo" in
+% this example.) There are some restrictions on this usage, the
+% principal one being that "\endtabularx" is the \emph{first} token of
+% the `end code' of the environment.
+% \begin{macrocode}
+\def\tabularx#1{%
+% \end{macrocode}
+% \changes{v2.02}{1995/03/20}
+% {New local setting of \cs{TX@}}
+% \changes{v4.09}{1998/05/13}
+% {Use \cs{setlength}, so that calc extensions apply. tools/2793}
+% Allow "\tabularx" "\endtabularx" (but not "\begin{tabularx}"
+% "\end{tabularx}") to be used in "\newenvironment" definitions.
+% \begin{macrocode}
+\edef\TX@{\@currenvir}%
+ {\ifnum0=`}\fi
+% \end{macrocode}
+% "\relax" added at v1.05 so that non-expandable length tokens, like
+% "\textwidth" do not generate an extra space, and an overfull box.
+% "\relax" removed again at v4.09 in favour of "\setlength" so if you
+% use the calc package you can use a width of "(\textwidth-12pt)/2".
+% \begin{macrocode}
+ \setlength\TX@target{#1}%
+ \TX@typeout{Target width: #1 = \the\TX@target.}%
+ \toks@{}\TX@get@body}
+% \end{macrocode}
+% \end{macro}
+%
+
+% \begin{macro}{\endtabularx}
+% This does not do very much\ldots
+% \changes{v2.02}{1995/03/20}
+% {Macro added}
+% \begin{macrocode}
+\let\endtabularx\relax
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\TX@get@body}
+% Place all tokens as far as the first "\end" into a token register.
+% Then call "\TX@find@end" to see if we are at "\end{tabularx}".
+% \begin{macrocode}
+\long\def\TX@get@body#1\end
+ {\toks@\expandafter{\the\toks@#1}\TX@find@end}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\TX@find@end}
+% If we are at "\end{tabularx}", call "\TX@endtabularx", otherwise
+% add "\end{...}" to the register, and call "\TX@get@body" again.
+% \begin{macrocode}
+\def\TX@find@end#1{%
+ \def\@tempa{#1}%
+ \ifx\@tempa\TX@\expandafter\TX@endtabularx
+ \else\toks@\expandafter
+ {\the\toks@\end{#1}}\expandafter\TX@get@body\fi}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\TX@}
+% The string {\ttfamily tabularx} as a macro for testing with "\ifx".
+% \begin{macrocode}
+\def\TX@{tabularx}
+% \end{macrocode}
+% \end{macro}
+%
+% Now that all the parts of the table specification are stored in
+% registers, we can begin the work of setting the table.
+%
+% The algorithm for finding the correct column widths is as follows.
+% Firstly set the table with each {\ttfamily X} column the width of the
+% final table. Assuming that there is at least one {\ttfamily X} column,
+% this will produce a table that is too wide. Divide the excess width by
+% the number of {\ttfamily X} columns, and reduce the column width by
+% this amount. Reset the table. If the table is not now the correct
+% width, a "\multicolumn" entry must be `hiding' one of the {\ttfamily
+% X} columns, and so there is one less {\ttfamily X} column affecting
+% the width of the table. So we reduce by 1 the number of X columns and
+% repeat the process.
+%
+% \begin{macro}{\TX@endtabularx}
+% Although I have tried to make {\ttfamily tabularx} look like an
+% environment, it is in fact a command, all the work is done by this
+% macro.
+% \begin{macrocode}
+\def\TX@endtabularx{%
+% \end{macrocode}
+% Define the {\ttfamily X} column, with an internal version of the
+% "\newcolumntype" command. The "\expandafter" commands enable
+% "\NC@newcol" to get the {\em expansion} of\\
+% "\tabularxcolumn{\TX@col@width}" as its
+% argument. This will be the definition of an {\ttfamily X} column, as
+% discussed in section 4.
+% \begin{macrocode}
+ \expandafter\TX@newcol\expandafter{\tabularxcolumn{\TX@col@width}}%
+% \end{macrocode}
+% Initialise the column width, and the number of {\ttfamily X} columns.
+% The number of {\ttfamily X} columns is set to one, which means that
+% the initial count will be one too high, but this value is decremented
+% before it is used in the main loop.
+%
+% Since v1.02, switch the definition of "\verb".
+% \begin{macrocode}
+ \let\verb\TX@verb
+% \end{macrocode}
+% Since v1.05, save the values of all \LaTeX\ counters, the list
+% "\cl@@ckpt" contains the names of all the \LaTeX\ counters that have
+% been defined so far. We expand "\setcounter" at this point, as it
+% results in fewer tokens being stored in "\TX@ckpt", but the actual
+% resetting of the counters occurs when "\TX@ckpt" is expanded after
+% each trial run.
+% Actually since v1.07, use something equivalent to the expansion of the
+% original definition of "\setcounter", so that "tabularx" works in
+% conjunction with "calc.sty".
+% \begin{macrocode}
+ \def\@elt##1{\global\value{##1}\the\value{##1}\relax}%
+ \edef\TX@ckpt{\cl@@ckpt}%
+ \let\@elt\relax
+ \TX@old@table\maxdimen
+ \TX@col@width\TX@target
+ \global\TX@cols\@ne
+% \end{macrocode}
+% Typeout some headings (unless this is disabled).
+% \begin{macrocode}
+ \TX@typeout@
+ {\@spaces Table Width\@spaces Column Width\@spaces X Columns}%
+% \end{macrocode}%
+% First attempt. Modify the {\ttfamily X} definition to count {\ttfamily
+% X} columns.
+% \begin{macrocode}
+ \TX@trial{\def\NC@rewrite@X{%
+ \global\advance\TX@cols\@ne\NC@find p{\TX@col@width}}}%
+% \end{macrocode}
+% Repeatedly decrease column width until table is the correct width,
+% or stops shrinking, or the columns become two narrow.
+% If there are no multicolumn entries, this will only take one attempt.
+% \begin{macrocode}
+ \loop
+ \TX@arith
+ \ifTX@
+ \TX@trial{}%
+ \repeat
+% \end{macrocode}
+% One last time, with warnings back on (see appendix D)
+% use {\ttfamily tabular*} to put it in a box of the right size, in case
+% the algorithm failed to find the correct size.
+%
+% Since v1.04, locally make "\footnotetext" save its argument in a token
+% register.
+% Since v1.06, "\toks@" contains the preamble specification,
+% and possible optional argument, as well as the table body.
+% \begin{macrocode}
+ {\let\@footnotetext\TX@ftntext\let\@xfootnotenext\TX@xftntext
+ \csname tabular*\expandafter\endcsname\expandafter\TX@target
+ \the\toks@
+ \csname endtabular*\endcsname}%
+% \end{macrocode}
+% Now the alignment is finished, and the "}" has restored the original
+% meaning of "\@footnotetext" expand the register "\TX@ftn" which will
+% execute a series of\\
+% "\footnotetext["\meta{num}"]{"\meta{note}"}"\\
+% commands. We need to be careful about clearing the register as we may
+% be inside a nested {\ttfamily tabularx}.
+% \begin{macrocode}
+ \global\TX@ftn\expandafter{\expandafter}\the\TX@ftn
+% \end{macrocode}
+% Now finish off the {\ttfamily tabularx} environment. Note that we need
+% "\end{tabularx}" here as the "\end{tabularx}" in the user's
+% file is never expanded. Now use "\TX@" rather than "tabularx".
+% \changes{v2.02}{1995/03/20}
+% {Close the environment \cs{TX@} rather than `tabularx'}
+%
+% We also need to finish off the group started by "{\ifnum0=`}\fi" in
+% the macro "\tabularx".
+% \begin{macrocode}
+ \ifnum0=`{\fi}%
+ \expandafter\end\expandafter{\TX@}}
+% \end{macrocode}
+% \end{macro}
+%
+%
+% \begin{macro}{\TX@arith}
+% Calculate the column width for the next try, setting the flag
+% "\ifTX@" to false if the loop should be aborted.
+% \begin{macrocode}
+\def\TX@arith{%
+ \TX@false
+ \ifdim\TX@old@table=\wd\@tempboxa
+% \end{macrocode}
+% If we have reduced the column width, but the table width has not
+% changed, we stop the loop, and output the table (which will cause an
+% over-full alignment) with the previous value of "\TX@col@width".
+% \begin{macrocode}
+ \TX@col@width\TX@old@col
+ \TX@typeout@{Reached minimum width, backing up.}%
+ \else
+% \end{macrocode}
+% Otherwise calculate the amount by which the current table is too wide.
+% \begin{macrocode}
+ \dimen@\wd\@tempboxa
+ \advance\dimen@ -\TX@target
+ \ifdim\dimen@<\TX@delta
+% \end{macrocode}
+% If this amount is less than "\TX@delta", stop. ("\TX@delta"
+% should be non-zero otherwise we may miss the target due to rounding
+% error.)
+% \begin{macrocode}
+ \TX@typeout@{Reached target.}%
+ \else
+% \end{macrocode}
+% Reduce the number of effective {\ttfamily X} columns by one. (Checking
+% that we do not get 0, as this would produce an error later.) Then
+% divide excess width by the number of effective columns, and calculate
+% the new column width. Temporarily store this value (times $-1$) in
+% "\dimen@".
+% \begin{macrocode}
+ \ifnum\TX@cols>\@ne
+ \advance\TX@cols\m@ne
+ \fi
+ \divide\dimen@\TX@cols
+ \advance\dimen@ -\TX@col@width
+ \ifdim \dimen@ >\z@
+% \end{macrocode}
+% If the new width would be too narrow, abort the loop. At the moment
+% too narrow, means less than 0\,pt!
+%
+% Prior to v2.03, if the loop was aborted here, the X columns were left
+% with the width of the previous run, but this may make the table far
+% too wide as initial guesses are always too big. Now force to
+% "\TX@error@width" which defaults to be 1em. If you want to
+% get the old behaviour stick\\
+% "\renewcommand\TX@error@width{\TX@col@width}"\\
+% in a package file loaded after \textsf{tabularx}.
+% \changes{v2.03}{1997/02/20}{Improve warning message and force to 1em.}
+% \begin{macrocode}
+ \PackageWarning{tabularx}%
+ {X Columns too narrow (table too wide)\MessageBreak}%
+ \TX@col@width\TX@error@width\relax
+ \else
+% \end{macrocode}
+% Otherwise save the old settings, and set the new column width. Set the
+% flag to true so that the table will be set, and the loop will be
+% executed again.
+% \begin{macrocode}
+ \TX@old@col\TX@col@width
+ \TX@old@table\wd\@tempboxa
+ \TX@col@width-\dimen@
+ \TX@true
+ \fi
+ \fi
+ \fi}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\TX@error@width}
+% \changes{v2.03}{1997/02/20}{macro added.}
+% \changes{v2.04}{1997/02/26}{spurious brace removed.}
+% If the calculated width is negative, use this instead.
+% \begin{macrocode}
+\def\TX@error@width{1em}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\TX@delta}
+% Accept a table that is within "\hfuzz" of the correct width.
+% \begin{macrocode}
+\TX@delta\hfuzz
+% \end{macrocode}
+% \end{macro}
+%
+% Initialise the {\ttfamily X} column. The definition can be empty here,
+% as it is set for each {\ttfamily tabularx} environment.
+% \begin{macrocode}
+\newcolumntype{X}{}
+% \end{macrocode}
+%
+% \begin{macro}{\tabularxcolumn}
+% The default definition of {\ttfamily X} is "p{#1}".
+% \begin{macrocode}
+\def\tabularxcolumn#1{p{#1}}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\TX@newcol}
+% A little macro just used to cut down the number of "\expandafter"
+% commands needed.
+% \begin{macrocode}
+\def\TX@newcol{\newcol@{X}[0]}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\TX@trial}
+% Make a test run.
+% \begin{macrocode}
+\def\TX@trial#1{%
+ \setbox\@tempboxa\hbox{%
+% \end{macrocode}
+% Any extra commands. This is used on the first run to count the number
+% of {\ttfamily X} columns.
+% \begin{macrocode}
+ #1\relax
+% \end{macrocode}
+% Since v1.04, make "\footnotetext" gobble its arguments. Also locally
+% clear "\TX@vwarn" so that the warning is generated by the {\ttfamily
+% final} run, and does not appear in the middle of the table if
+% "\tracingtabularx".
+% \begin{macrocode}
+ \let\@footnotetext\TX@trial@ftn
+ \let\TX@vwarn\@empty
+% \end{macrocode}
+% Do not nest {\ttfamily tabularx} environments during trial runs. This
+% would waste time, and the global setting of "\TX@cols" would break the
+% algorithm.
+% \begin{macrocode}
+ \expandafter\let\expandafter\tabularx\csname tabular*\endcsname
+ \expandafter\let\expandafter\endtabularx\csname endtabular*\endcsname
+% \end{macrocode}
+% Added at v1.05: dissable "\write"s during a trial run. This trick is
+% from the \TeX{}Book.\footnote{Actually the \TeX{}Book trick does
+% not work correctly, so changed for v2.05.}
+% \changes{v2.05}{1997/09/18}
+% {New \cs{write} trick. tools/2607}
+% \changes{v2.07}{1999/01/07}
+% {Newer \cs{write} trick. tools/2792}
+% \begin{macrocode}
+ \def\write{\begingroup
+ \def\let{\afterassignment\endgroup\toks@}%
+ \afterassignment\let\count@}%
+% \end{macrocode}
+% Turn off warnings (see appendix D). Also prevent them being turned
+% back on by setting the parameter names to be registers.
+% \begin{macrocode}
+ \hbadness\@M
+ \hfuzz\maxdimen
+ \let\hbadness\@tempcnta
+ \let\hfuzz\@tempdima
+% \end{macrocode}
+% Make the table, and finish the hbox.
+% Since v1.06, "\toks@" contains the preamble specification,
+% and possible optional argument, as well as the table body.
+% \begin{macrocode}
+ \expandafter\tabular\the\toks@
+ \endtabular}%
+% \end{macrocode}
+% Since v1.05 reset all \LaTeX\ counters, by executing "\TX@ckpt".
+% \begin{macrocode}
+ \TX@ckpt
+% \end{macrocode}
+% Print some statistics.
+% Added "\TX@align" in v1.05, to line up the columns.
+% \begin{macrocode}
+ \TX@typeout@{\@spaces
+ \expandafter\TX@align
+ \the\wd\@tempboxa\space\space\space\space\space\@@
+ \expandafter\TX@align
+ \the\TX@col@width\space\space\space\space\space\@@
+ \@spaces\the\TX@cols}}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\TX@align}
+% Macro added at v1.05, to improve the printing of the tracing info.
+% \begin{macrocode}
+\def\TX@align#1.#2#3#4#5#6#7#8#9\@@{%
+ \ifnum#1<10 \space\fi
+ \ifnum#1<100 \space\fi
+ \ifnum#1<\@m\space\fi
+ \ifnum#1<\@M\space\fi
+ #1.#2#3#4#5#6#7#8\space\space}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\arraybackslash}
+% "\\" hack.
+% \begin{macrocode}
+\def\arraybackslash{\let\\\@arraycr}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\tracingtabularx}
+% Print statistics on column and table widths.
+% \begin{macrocode}
+\def\tracingtabularx{%
+ \def\TX@typeout{\PackageWarningNoLine{tabularx}}%
+ \def\TX@typeout@##1{\typeout{(tabularx) ##1}}}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\TX@typeout}
+% The default is to be to be quiet
+% \begin{macrocode}
+\let\TX@typeout\@gobble
+\let\TX@typeout@\@gobble
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\TX@ftn}
+% A token register for saving footnote texts.
+% \begin{macrocode}
+\newtoks\TX@ftn
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\TX@ftntext}
+% \begin{macro}{\TX@xftntext}
+% Inside the alignment just save up the footnote text in a token
+% register.
+% \begin{macrocode}
+\long\def\TX@ftntext#1{%
+ \edef\@tempa{\the\TX@ftn\noexpand\footnotetext
+ [\the\csname c@\@mpfn\endcsname]}%
+ \global\TX@ftn\expandafter{\@tempa{#1}}}%
+\long\def\TX@xftntext[#1]#2{%
+ \global\TX@ftn\expandafter{\the\TX@ftn\footnotetext[#1]{#2}}}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\TX@trial@ftn}
+% On trial runs, gobble footnote texts.
+% \begin{macrocode}
+\long\def\TX@trial@ftn#1{}
+% \end{macrocode}
+% \end{macro}
+%
+% This last section was added at Version 1.02. Previous versions
+% documentented the fact that "\verb" did not work inside {\ttfamily
+% tabularx}, but that did not stop people using it! This usually put
+% \LaTeX\ into an irrecoverable error position, with error messages that
+% did not mention the cause of the error. The `poor man's "\verb"' (and
+% "\verb*") defined here is based on page 382 of the \TeX{}Book. As
+% explained there, doing verbatim this way means that spaces are not
+% treated correctly, and so "\verb*" may well be useless, however I
+% consider this section of code to be error-recovery, rather than a real
+% implementation of verbatim.
+%
+% The mechanism is quite general, and any macro which wants to allow a
+% form of "\verb" to be used within its argument may
+% "\let\verb=\TX@verb". (Making sure to restore the real definition
+% later!)
+%
+% "\verb" and "\verb*" are subject to the following restictions:
+% \begin{enumerate}
+% \item Spaces in the argument are not read verbatim, but may be skipped
+% according to \TeX's usual rules.
+% \item Spaces will be added to the output after control words, even if
+% they were not present in the input.
+% \item Unless the argument is a single space, any trailing space,
+% whether in the original argument, or added as in (2),
+% will be omitted.
+% \item The argument must not end with "\", so "\verb|\|" is not
+% allowed, however, because of (3), "\verb|\ |" produces
+% "\".
+% \item The argument must be balanced with respect to "{" and "}". So
+% "\verb|{|" is not allowed.
+% \item A comment character like "%" will not appear verbatim. It will
+% act as usual, commenting out the rest of the input line!
+% \item The combinations "?`" and "!`" will appear as
+% {\ttfamily?`} and {\ttfamily!`} if the {\ttfamily cmtt} font is
+% being used.
+% \end{enumerate}
+%
+% \begin{macro}{\TX@verb}
+% The internal definition of "\verb". Spaces will be replaced by "~", so
+% for the star-form, "\let" "~" be \verb*| |, which we obtain as
+% "\uppercase{*}". Use "{\ifnum0=`}\fi" rather than "\bgroup" to allow
+% "&" to appear in the argument.
+% \begin{macrocode}
+{\uccode`\*=`\ %
+\uppercase{\gdef\TX@verb{%
+ \leavevmode\null\TX@vwarn
+ {\ifnum0=`}\fi\ttfamily\let\\\ignorespaces
+ \@ifstar{\let~*\TX@vb}{\TX@vb}}}}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\TX@vb}
+% Get the `almost verbatim' text using "\meaning". The `"!"' is added to
+% the front of the user supplied text, to ensure that the whole argument
+% does not consist of a single "{ }" group. \TeX\ would strip the outer
+% braces from such a group. The `"!"' will be removed later.
+%
+% Originally I followed Knuth, and had "\def\@tempa{##1}", however this
+% did not allow "#" to appear in the argument. So in v1.04, I changed
+% this to to use a token register, and "\edef". This allows "#" appear,
+% but makes each one appear twice!, so later we loop through, replacing
+% "##" by "#".
+% \begin{macrocode}
+\def\TX@vb#1{\def\@tempa##1#1{\toks@{##1}\edef\@tempa{\the\toks@}%
+ \expandafter\TX@v\meaning\@tempa\\ \\\ifnum0=`{\fi}}\@tempa!}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\TX@v}
+% Strip the initial segment of the "\meaning", including the `"!"'
+% added earlier.
+% \begin{macrocode}
+\def\TX@v#1!{\afterassignment\TX@vfirst\let\@tempa= }
+% \end{macrocode}
+% \end{macro}
+%
+% As explained above we are going to replace "##" pairs by "#". To do
+% this we need non-special "#" tokens. Make "*" into a parameter
+% token so that we can define macros with arguments. The normal meanings
+% will be restored by the "\endgroup" later.
+% \begin{macrocode}
+\begingroup
+\catcode`\*=\catcode`\#
+\catcode`\#=12
+% \end{macrocode}
+%
+% \begin{macro}{\TX@vfirst}
+% As a special case, prevent the first character from being dropped.
+% This makes "\verb*| |" produce \verb*| |. Then call "\TX@v@".
+% This is slightly tricky since v1.04, as I have to ensure that an
+% actual "#" rather than a command "\let" to "#" is passed on if the
+% first character is "#".
+% \begin{macrocode}
+\gdef\TX@vfirst{%
+ \if\@tempa#%
+ \def\@tempb{\TX@v@#}%
+ \else
+ \let\@tempb\TX@v@
+ \if\@tempa\space~\else\@tempa\fi
+ \fi
+ \@tempb}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\TX@v@}
+% Loop through the "\meaning", replacing all spaces by "~". If the last
+% charcter is a space it is dropped, so that "\verb*|\LaTeX|" produces
+% "\LaTeX" not \verb*|\LaTeX |. The rewritten tokens are then further
+% processed to replace "##" pairs.
+% \begin{macrocode}
+\gdef\TX@v@*1 *2{%
+ \TX@v@hash*1##\relax\if*2\\\else~\expandafter\TX@v@\fi*2}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\TX@v@hash}
+% The inner loop, replacing "##" by "#".
+% \begin{macrocode}
+\gdef\TX@v@hash*1##*2{*1\ifx*2\relax\else#\expandafter\TX@v@hash\fi*2}
+% \end{macrocode}
+% \end{macro}
+%
+% As promised, we now restore the normal meanings of "#" and "*".
+% \begin{macrocode}
+\endgroup
+% \end{macrocode}
+%
+% \begin{macro}{\TX@vwarn}
+% Warn the user the first time this "\verb" is used.
+% \begin{macrocode}
+\def\TX@vwarn{%
+ \@warning{\noexpand\verb may be unreliable inside tabularx}%
+ \global\let\TX@vwarn\@empty}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macrocode}
+%</package>
+% \end{macrocode}
+%
+% \Finale
+\endinput
diff --git a/Master/texmf-dist/source/latex/tools/theorem.dtx b/Master/texmf-dist/source/latex/tools/theorem.dtx
new file mode 100644
index 00000000000..a117647fadb
--- /dev/null
+++ b/Master/texmf-dist/source/latex/tools/theorem.dtx
@@ -0,0 +1,1163 @@
+% \iffalse meta-comment
+%
+% Copyright 1993 1994 1995 1996 1997 1998 1999 2000 2001 2002 2003
+% The LaTeX3 Project and any individual authors listed elsewhere
+% in this file.
+%
+% This file is part of the Standard LaTeX `Tools Bundle'.
+% -------------------------------------------------------
+%
+% It 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.3 or later is part of all distributions of LaTeX
+% version 2003/12/01 or later.
+%
+% The list of all files belonging to the LaTeX `Tools Bundle' is
+% given in the file `manifest.txt'.
+%
+% \fi
+%
+% \CheckSum{467}
+%% \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 \~}
+%%
+%
+%
+\def\FMithmInfo{1995/11/23 v2.2c Theorem extension package (FMi)}
+%
+% \ProvidesFile{theorem.dtx}[\FMithmInfo]
+%\iffalse % this is a METACOMMENT !
+%%
+%% Package `theorem' to use with LaTeX2e
+%% Copyright (C) 1989-1995 Frank Mittelbach, all rights reserved.
+%<+package>\@ifundefined{theorem@style}{}{\endinput}
+%<+package>\NeedsTeXFormat{LaTeX2e}[1995/06/01]
+%<+package>\ProvidesPackage{theorem}
+%<+package> [\FMithmInfo]
+%
+% \fi
+%
+% \changes{v1.0}{87/05/07}{First draft.}
+% \changes{v1.0a}{87/05/07}{`thistheoremstyle' added.}
+% \changes{v1.1a}{87/07/29}{New concept: redefine the internal
+% \protect\LaTeX{} commands `@xnthm' etc.}
+% \changes{v1.1b}{87/07/31}{`theoremfont' used to specify font.}
+% \changes{v1.2a}{88/01/08}{`@endtheorem' now globally defined.}
+% \changes{v1.2b}{88/01/11}{`newtheorem' only allowed in the preamble.}
+% \changes{v1.3a}{88/02/14}{`theoremfont' now a toks register.}
+%
+% \changes{v2.0a}{88/11/16}{New implementation and new documentation.}
+% \changes{v2.0a}{88/11/16}{No layout changes but internal modifications
+% old substyles won't work.}
+% \changes{v2.0b}{89/01/30}{`global' used for all definitions.}
+% \changes{v2.0c}{89/06/15}{Documentation translated to English.
+% Thanks to LLL and Nina}
+% \changes{v2.1a}{90/02/15}{Support for new font selection.}
+% \changes{v2.2a}{94/02/03}{Cleanup for LaTeX2e}
+%
+% \DoNotIndex{\@endparenv,\@ifdefinable,\@ifnextchar,\@ifundefined}
+% \DoNotIndex{\@namedef,\@nameuse,\@spaces,\@tempa,\@warning}
+% \DoNotIndex{\ }
+% \DoNotIndex{\begingroup,\bfseries}
+% \DoNotIndex{\csname}
+% \DoNotIndex{\def,\do,\docdate}
+% \DoNotIndex{\endcsname,\endgroup,\endinput,\endtrivlist,\expandafter}
+% \DoNotIndex{\filedate,\fileversion}
+% \DoNotIndex{\gdef,\global}
+% \DoNotIndex{\hbox,\hskip}
+% \DoNotIndex{\ignorespaces,\input,\itshape,\item}
+% \DoNotIndex{\labelsep,\let,\llap}
+% \DoNotIndex{\makeatletter}
+% \DoNotIndex{\noexpand}
+% \DoNotIndex{\refstepcounter,\relax,\rlap}
+% \DoNotIndex{\setlength,\slshape,\space,\string,\strut}
+% \DoNotIndex{\the,\trivlist,\typeout}
+% \DoNotIndex{\vbox}
+% \DoNotIndex{\xdef}
+%
+% \def\deflabel#1{\ttfamily #1\hfill}
+% \def\deflist#1{\begin{list}{}{\settowidth\labelwidth{\ttfamily #1}%
+% \setlength\leftmargin\labelwidth
+% \addtolength\leftmargin\labelsep
+% \let\makelabel\deflabel}}
+% \def\enddeflist{\end{list}}
+% \def\envfont{\normalfont\ttfamily}
+%
+% \MakeShortVerb{\|}
+%
+% \newcommand{\TUB}{{\sl TUGboat\/}}
+%
+% \GetFileInfo{theorem.dtx}
+% \title{An Extension of the
+% \LaTeX{} theorem environment\thanks{This file
+% has version number \fileversion, last
+% revised \filedate.}}
+% \author{Frank Mittelbach\\
+% Electronic Data Systems\\
+% (Deutschland) GmbH\\
+% Eisenstra\ss e 56\\
+% D-65424 R\"usselsheim\\
+% Federal Republic of Germany}
+%
+% \maketitle
+%
+% \begin{abstract}
+% The macros described in this paper yield an extension of the
+% \LaTeX{} theorem mechanism. It is designed is to satisfy the
+% different requirements of various journals. Thus, the
+% layout of the ``theorems'' can be manipulated by determining a
+% ``style''. This article describes not only the use, but
+% also the definition, of the necessary macros.
+% \end{abstract}
+%
+% \section*{Preface to version 2.2}
+%
+% For \LaTeXe{} this package did not need any fundamental changes. I
+% only modified the messages generated so that theorem layout styles
+% will show up with the |\listfiles| command and cleaned the section
+% on the New Font Selection Scheme since this is now included in
+% \LaTeX.
+%
+% \section*{Preface to version 2.1}
+%
+% This version is identical to 2.0g described in \TUB\ 10\#3 except
+% for some internal defaults which are now set depending on the used
+% font selection scheme.
+%
+% This was done to avoid unpleasant surprises if the new font selection
+% scheme is in force. For further details see
+% section~\ref{sec:newfonts} and \cite{bk:GMS94}.
+%
+% \section{Introduction}
+%
+% For our purposes here, ``theorems'' are labelled enunciations,
+% often set off from the main text by extra space and a font change.
+% Theorems, corollaries, conjectures, definitions, and remarks
+% are all instances of ``theorems''. The ``header'' of these structures
+% is composed of a label (such as \textsc{Theorem} or \textsc{Remark})
+% and a number which serializes an item in the sequence of items
+% with the same label.
+%
+% Shortly after the introduction of \LaTeX{} at the Fachbereich
+% Mathematik in Mainz, the desire to manipulate the layout of
+% ``theorems'' arose. In Mainz, the following two conventions came
+% into general use:
+% \begin{enumerate}
+% \item The number of the theorem is shown in the margin.
+% \item There is a line break at
+% the end of the theorem header.
+% \end{enumerate}
+%
+% Additionally, some journals require different formats which depend on
+% the ``sort of theorem'': e.g.\ often remarks and definitions are set
+% in |\upshape|, while |\itshape| is employed for main theorems.
+%
+% Confronted with these requirements, a theorem environment was
+% developed in Mainz which allows separate determination of the
+% layout of the ``theorems sets'', comparable to |\pagestyle|.
+%
+%
+% \section{The user interface}
+% \subsection{Defining new theorem sets}
+%
+% \DescribeMacro\newtheorem
+% As in the original \LaTeX{} version, the command |\newtheorem|
+% defines a new ``theorem set'' or ``theorem-like structure''.
+% Two required arguments name the new environment and give the text
+% to be typeset with each instance of the new ``set'', while
+% an optional argument determines how
+% the ``set'' is enumerated:
+% \begin{description}
+% \item[\ttfamily \bslash newtheorem\{foo\}\{bar\}]
+% The theorem set {\envfont foo} (whose name is \texttt{bar})
+% uses its own counter.
+% \item[\ttfamily \bslash newtheorem\{foo2\}{[foo]}\{bar2\}]
+% The theorem set {\envfont foo2} (printed name \texttt{bar2})
+% uses the same counter as the theorem set \texttt{foo}.
+% \item[\ttfamily \bslash newtheorem\{foo3\}\{bar3\}{[section]}]
+% The theorem set {\envfont foo3} (printed name \texttt{bar3}) is
+% enumerated within the counter \texttt{section}, i.e.\ with every
+% new |\section| the enumeration begins again with 1, and
+% the enumeration is composed from the section-number and the
+% theorem counter itself.
+% \end{description}
+%
+% \DescribeMacro\theoremstyle
+% Additionally, the command |\theoremstyle| can define the layout
+% of various, or all, theorem sets. It should be noted that any
+% theorem set defined by |\newtheorem| is typeset in the
+% |\theoremstyle| that is current at the time of the definition.
+% Thus, the following
+% \begin{verbatim}
+% \theoremstyle{break} \newtheorem{Cor}{Corollary}
+% \theoremstyle{plain} \newtheorem{Exa}{Example}[section]
+%\end{verbatim} ^^A No blank at line start
+% leads to the result that the set {\envfont Cor} is formatted in the
+% style \texttt{break}, while the set {\envfont Exa} and all the
+% following ones are formatted in the style \texttt{plain}, unless
+% another |\theoremstyle| follows. Since the definitions installed by
+% |\newtheorem| are global, one also can limit |\theoremstyle| locally
+% by grouping braces.
+%
+% \DescribeMacro\theorembodyfont
+% The choice of the font for the theorem body is completely
+% independent of the chosen |\theoremstyle|; this has proven to
+% be very advantageous. For example,
+% \begin{verbatim}
+% {\theorembodyfont{\upshape} \newtheorem{Rem}{Remark}}
+%\end{verbatim}
+% defines a theorem set {\envfont Rem}, which will be set in
+% |\upshape| in the current layout (which in our example is
+% \texttt{plain}). As with |\theoremstyle|, the |\theorembodyfont|
+% chosen is that current at the time of |\newtheorem|. If
+% |\theorembodyfont| is not specified or one defines
+% |\theorembodyfont{}|, then the font used will be that defined by the
+% |\theoremstyle|.
+%
+% \DescribeMacro\theoremheaderfont It is also possible to customize
+% the font used for the theorem headers. This is, however, a global
+% declaration, and therefore there should be at most one
+% |\theoremheaderfont| declaration in the preamble.\footnote{If it is
+% actually necessary to have different header fonts, one has to define
+% new theorem styles (substituting the desired font) or specify the
+% information directly in the \texttt{\bslash newtheorem} declaration
+% (the unclean variant).}
+%
+% \DescribeMacro\theorempreskipamount
+% \DescribeMacro\theorempostskipamount Two additional parameters
+% affect the vertical space around the theorem environments:
+% |\theorempreskipamount| and |\theorempostskipamount| define,
+% respectively, the spacing before and after such an environment.
+% These parameters apply for all theorem sets and can be manipulated
+% with the ordinary length macros. They are rubber lengths,
+% (`\textsf{skips}'), and therefore can contain \texttt{plus} and
+% \texttt{minus} parts.
+%
+% Since the definition of theorem sets should---most sensibly---be
+% placed in the preamble, we only allow installation there.
+% It is therefore possible to release the memory used here after
+% |\begin{document}|, in order to make room for other
+% applications.
+%
+%
+% \subsection{Existing theorem styles}
+%
+% The following theorem styles exist to date:
+% \begin{deflist}{marginbreak}
+% \item[plain]
+% This theorem style emulates the original \LaTeX{} definition,
+% except that additionally the parameters
+% |\theorem...skipamount| are used.
+% \item[break]
+% In this style, the theorem header is followed by a line
+% break.
+% \item[marginbreak]
+% The theorem number is set in the margin, and there is a line
+% break as in \texttt{break}.
+% \item[changebreak]
+% Like \texttt{break}, but with header number and text
+% interchanged.
+% \item[change]
+% Header number and text are interchanged, without a line break.
+% \item[margin]
+% The number is set in the left margin, without a line break.
+% \end{deflist}
+% All styles (except \texttt{plain}) select |\slshape| as the default
+% |\theorembodyfont|.
+%
+%
+% \subsection{Examples}
+%
+% Given the above theorem sets {\envfont Cor}, {\envfont Exa}
+% and {\envfont Rem},
+% suppose that the preamble also contains the declarations:
+% \begin{verbatim}
+% \theoremstyle{marginbreak} \newtheorem{Lem}[Cor]{Lemma}
+% \theoremstyle{change}
+% \theorembodyfont{\itshape} \newtheorem{Def}[Cor]{Definition}
+%
+% \theoremheaderfont{\scshape}
+%\end{verbatim}
+% Then the following are some typical examples of the typeset output
+% resulting from their use.
+%
+% \begin{Cor}
+% This is a sentence typeset in the theorem environment {\envfont
+% Cor}.
+% \end{Cor}
+%
+% \begin{Exa}
+% This is a sentence typeset in the theorem environment {\envfont
+% Exa}.
+% \end{Exa}
+%
+% \begin{Rem}
+% This is a sentence typeset in the theorem environment {\envfont
+% Rem}.
+% \end{Rem}
+%
+% \begin{Lem}[Ben User]
+% This is a sentence typeset in the theorem environment {\envfont
+% Lem}.
+% \end{Lem}
+%
+% \begin{Def}[Very impressive Definition]
+% This is a sentence typeset in the theorem environment {\envfont
+% Def}.
+% \end{Def}
+%
+% The last two examples show the effect of the optional argument to
+% a theorem environment (it is the text typeset in parentheses).
+%
+%
+% \section{Special Considerations}
+% \label{sec:newfonts}
+%
+% Theoremheader and body are implemented as a unit. This means that
+% the |\theoremheaderfont| will inherit characteristics of the
+% |\theorembodyfont| in \LaTeXe. Thus, if for example
+% |\theorembodyfont| is |\itshape| and |\theoremheaderfont|
+% is |\bfseries| the font selected for the header will have the
+% characteristics `bold extended italic'. If this is not desired one
+% should set the |\theoremheaderfont| to something like
+% \begin{verbatim}
+% \theoremheaderfont{\normalfont\bfseries}
+%\end{verbatim}
+% i.e.\ supplying all necessary font informations explicitly.
+%
+%
+%
+% \section{Acknowledgements}
+%
+% The publication of this set of macros was only possible with the
+% help of Christina Busse (translating the manuscript into English),
+% Joachim Pense (playing the r\^ole of typist), Chris Rowley
+% (looking everything over) and many others providing useful
+% suggestions.
+%
+% \StopEventually{%
+% \begin{thebibliography}{9}
+% \bibitem{bk:GMS94} \textsc{M.~Goossens}, \textsc{F.~Mittelbach}
+% and \textsc{A.~Samarin}.
+% \newblock The \LaTeX{} Companion.
+% \newblock
+% Addison-Wesley, Reading, Massachusetts, 1994.
+% \bibitem{latex:source} \textsc{Lamport, Leslie.} \newblock
+% \texttt{latex.tex}, version 2.09, date
+% Feb. 1990.
+% \end{thebibliography}
+% \PrintIndex
+% \PrintChanges}
+%
+%
+% \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} program. Since it is the first code in the file
+% one can alternatively process this file directly with \LaTeXe{} to
+% obtain the documentation.
+%
+% \begin{macrocode}
+%<*driver>
+\documentclass{ltxdoc}
+
+\usepackage{theorem}
+
+%<+driver>% The next few lines define theorem sets which are used
+%<+driver>% in the example section of the documentation.
+
+\theoremstyle{break} \newtheorem{Cor}{Corollary}
+\theoremstyle{plain} \newtheorem{Exa}{Example}[section]
+{\theorembodyfont{\upshape}\newtheorem{Rem}{Remark}}
+\theoremstyle{marginbreak} \newtheorem{Lem}[Cor]{Lemma}
+\theoremstyle{change}
+\theorembodyfont{\itshape} \newtheorem{Def}[Cor]{Definition}
+
+\theoremheaderfont{\scshape}
+
+\RecordChanges
+
+\begin{document}
+ \DocInput{theorem.dtx}
+\end{document}
+%</driver>
+% \end{macrocode}
+%
+% \section{Definition of the Macros}
+%
+% If the file has been loaded before, we abort immediately. If not the
+% package announces itself (this is actually done at the very top if
+% the file---the way it is done isn't good style so don't copy it).
+% \changes{v2.0e}{89/07/19}{Spaces removed from `typeout'.}
+% \changes{v2.2b}{95/11/19}{Announce moved to top of file}
+% \begin{macrocode}
+%<*package>
+%\@ifundefined{theorem@style}{}{\endinput}
+%\def\FMithmInfo{1995/11/19 v2.2b Theorem extension package (FMi)}
+%\ProvidesPackage{theorem}[\FMithmInfo]
+% \end{macrocode}
+%
+%
+% \subsection{Definition of theorem styles and fonts}
+%
+% All the definitions in this file are done globally to allow
+% inputting this file inside a group.
+%
+% \begin{macro}{\theoremstyle}
+% Before a theorem style can be installed, the chosen style must be
+% known. For that reason, we must test to see that
+% |\th@|\meta{style} is known or, more precisely, that it is
+% different from |\relax|. If the style is not known then
+% |\th@plain| is used.
+% \begin{macrocode}
+\gdef\theoremstyle#1{%
+ \@ifundefined{th@#1}{\@warning
+ {Unknown theoremstyle `#1'. Using `plain'}%
+ \theorem@style{plain}}%
+% \end{macrocode}
+% We save the theorem style to be used in the token register
+% |\theorem@style|.
+% \begin{macrocode}
+ {\theorem@style{#1}}%
+% \end{macrocode}
+% Now we ``evaluate'' the theorem style: this means, we call the
+% macro |\th@|\meta{style} which will activate the relevant
+% definitions which are contained in a separate file. This is done
+% in a group to suppress changes to the current font. This could
+% otherwise pose problems together with the new font selection
+% scheme\footnote{When I printed the original article using the new
+% font selection scheme I ended with a document with slanted
+% typefaces (text headings and all) simply because one of the
+% theorem styles used \texttt{\bslash sl} at toplevel.} if the
+% |\th@|\meta{style} is evaluated a second time.
+% \changes{v2.1a}{90/02/15}{Group added around `th@..}
+% \changes{v2.1a}{90/02/15}{Reseting of `..@begintheorem removed.}
+% \begin{macrocode}
+ \begingroup
+ \csname th@\the\theorem@style \endcsname
+ \endgroup}
+% \end{macrocode}
+% \end{macro}
+%
+%
+% \begin{macro}{\@begintheorem}
+% \changes{v2.1a}{90/02/15}{Relaxed at toplevel.}
+% \begin{macro}{\@opargbegintheorem}
+% \changes{v2.1a}{90/02/15}{Relaxed at toplevel.}
+% We reset |\@begintheorem| and |\@opargbegintheorem| to
+% |\relax| since these commands are no longer necessary at
+% toplevel. This will save a few tokens.
+% \begin{macrocode}
+\global\let\@begintheorem\relax
+\global\let\@opargbegintheorem\relax
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\theorem@style}
+% Obviously the \textsf{token} register used above has to be
+% allocated. To assure the utmost compatibility with the
+% original \LaTeX{} definition, we set the default theorem style to
+% \texttt{plain}, which implements the usual \LaTeX{} convention.
+% \changes{v2.0f}{89/07/20}{Unnecessary `global' removed.}
+% \begin{macrocode}
+\newtoks\theorem@style
+\global\theorem@style{plain}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\theorembodyfont}
+% \begin{macro}{\theorem@bodyfont}
+% If the |\theorembodyfont| is set by the user then it should not
+% interact with the default font set in the theorem style. When the
+% new font selection is in force this may happen if, for example,
+% the default is |\itshape| and the new |\theorembodyfont| is
+% |\sffamily|. So we add a |\reset@font| command in front of the
+% user definition.
+% \changes{v2.0f}{89/07/20}{Unnecessary `global' removed.}
+% \changes{v2.0g}{89/09/19}{`theoremfont to `theorembodyfont.}
+% \changes{v2.1c}{92/06/22}{`reset@font added and logic changed.}
+% \changes{v2.1d}{92/10/28}{Reset to empty if arg is empty}
+% \begin{macrocode}
+\gdef\theorembodyfont#1{%
+% \end{macrocode}
+% We check if the argument supplied is empty and if so put nothing
+% into the |\theorem@bodyfont| token register to allow for
+% |\theorembodyfont{}| as a mean of using the default of the
+% current |\theoremstyle|.
+% \begin{macrocode}
+ \def\@tempa{#1}%
+ \ifx\@tempa\@empty
+ \theorem@bodyfont{}%
+ \else
+ \theorem@bodyfont{\reset@font#1}%
+ \fi
+ }
+\newtoks\theorem@bodyfont
+\global\theorem@bodyfont{}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+%
+% \begin{macro}{\theoremheaderfont}
+% \changes{v2.0g}{89/09/19}{Macro added.}
+% The font for the theorem headers is handled differently because
+% this definition applies to all theorem styles.
+% \begin{macrocode}
+\gdef\theoremheaderfont#1{\gdef\theorem@headerfont{#1}%
+% \end{macrocode}
+% After using the macro once it is redefined to produce an error
+% message.
+% \begin{macrocode}
+ \gdef\theoremheaderfont##1{%
+ \typeout{\string\theoremheaderfont\space should be used
+ only once.}}}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\theorem@headerfont}
+% \changes{v2.0g}{89/09/19}{Macro added.}
+% To set the |\theorem@headerfont| default we first test if
+% the new fontselection scheme is in force.
+% \changes{v2.1a}{90/02/15}{Support for new font selection.}
+% \begin{macrocode}
+\ifx\upshape\undefined
+% \end{macrocode}
+% If not we define it to expand into |\bfseries|. We don't use
+% |\let| just in case a following style option redefines this
+% macro.
+% \begin{macrocode}
+\gdef\theorem@headerfont{\bfseries}
+% \end{macrocode}
+% Otherwise we reset the current shape before calling |\bfseries|.
+% \begin{macrocode}
+\else \gdef\theorem@headerfont{\normalfont\bfseries}\fi
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\th@plain}
+% \begin{macro}{\th@break}
+% \begin{macro}{\th@marginbreak}
+% \begin{macro}{\th@changebreak}
+% \begin{macro}{\th@change}
+% \begin{macro}{\th@margin}
+% The different styles are defined in macros such as
+% |\th@plain|. Since memory space is precious in
+% ``non-Big-versions'', we have to avoid offering too many unused
+% definitions. Therefore we define these styles in separate files
+% that can be loaded on demand. Thus the commands themselves only
+% load these files. We use |\@input@| a \LaTeXe{} internal command
+% that ensures that the file will be listed with |\listfiles|
+% \changes{v2.2a}{94/02/02}{Use `@input@ to load theorem layout files}
+% \begin{macrocode}
+\gdef\th@plain{\@input@{thp.sty}}
+\gdef\th@break{\@input@{thb.sty}}
+\gdef\th@marginbreak{\@input@{thmb.sty}}
+\gdef\th@changebreak{\@input@{thcb.sty}}
+\gdef\th@change{\@input@{thc.sty}}
+\gdef\th@margin{\@input@{thm.sty}}
+% \end{macrocode}
+% This list will be expanded when new styles become
+% available. For testing, just append new theorem substyles
+% as document options.
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+%
+%
+% \subsection{Definition of a new theorem set}
+%
+% As already pointed out, a new theorem environment can be defined in
+% three different ways:
+% \begin{verbatim}
+% \newtheorem{Lem}{Lemma}
+% \newtheorem{Lem}{Lemma}[section]
+% \newtheorem{Lem}[Theorem]{Lemma}
+%\end{verbatim}
+% The function of the macro |\newtheorem| is to recognize these cases
+% and then to branch into one of the three macros |\@ynthm|, |\@xnthm|
+% or |\@othm|. This mechanism is adopted unchanged from
+% \cite{latex:source}; the essential point here is that, for example,
+% in the second case, the arguments \texttt{Lem}, \texttt{Lemma} and
+% \texttt{section} are passed over to the macro |\@xnthm|.
+%
+% We inspect this case first because the others present fewer problems,
+% and thus are easily derived from this one.
+%
+% \begin{macro}{\@xnthm}
+% For our example arguments, the macro |\@xnthm| must fulfill
+% the following:
+% \begin{itemize}
+% \item
+% Define a new \LaTeX-counter `Lem'
+% \item
+% reset this counter within a |\section|
+% \item
+% define the macro |\theLem|
+% \item
+% define the environment macros |\Lem| and
+% |\endLem| using the current
+% |\theoremstyle| and |\theorem@bodyfont|.
+% \end{itemize}
+% Obviously, all this should happen only if the first argument
+% of |\@xnthm| (i.e.\ \texttt{Lem} in our example) is chosen so
+% as not to conflict with any previously defined commands or
+% environments. This test is performed by the \LaTeX{} macro
+% |\@ifdefinable|.
+% \begin{macrocode}
+\gdef\@xnthm#1#2[#3]{\expandafter\@ifdefinable\csname #1\endcsname
+% \end{macrocode}
+% Therefore, the first argument of |\@ifdefinable| is the
+% expansion (in the example, |\Lem|) of
+% |\csname||#1\endcsname|. The second argument is
+% executed only if the test has been completed successfully.
+% \begin{macrocode}
+ {%
+% \end{macrocode}
+% Now we define the new counter. The names of the \LaTeX{}
+% macros employed should speak for themselves:
+% \changes{v2.2b}{1995/10/07}{Use \cs{@newctr}}
+% \changes{v2.2c}{1995/11/23}{Use \cs{@newctr} properly.}
+% \begin{macrocode}
+ \@definecounter{#1}\@newctr{#1}[#3]%
+% \end{macrocode}
+% Using |\@newctr| will give a proper error message if the counter
+% in |#3| is not defined.
+% In defining `|\theLem|' we must generate the desired macro
+% name by use of |\expandafter| and |\csname|.
+% \begin{macrocode}
+ \expandafter\xdef\csname the#1\endcsname
+% \end{macrocode}
+% An |\xdef| is used in order to make the definition global,
+% and to ensure that it contains the replacement texts of
+% |\@thmcountersep| and |\@thmcounter|.\footnote{These
+% two macros can be defined by the document style. Their default
+% values produce a `\texttt{.}' as separation and an arabic
+% representation of the number.} However, not everything should be
+% expanded. For example, it saves space to use |\thesection|
+% instead of its---at times---lengthy expansion.
+% \begin{macrocode}
+ {\expandafter \noexpand \csname the#3\endcsname
+ \@thmcountersep \@thmcounter{#1}}%
+% \end{macrocode}
+% Thus with the defaults of \LaTeX{}, |\theLem| would be
+% replaced by the command sequence |\thesection.\arabic{Lem}|.
+%
+% We will now look at the definition of the macro which is executed
+% at the beginning of the actual environment (in our example this
+% macro is |\Lem|). It should be noted that we use an
+% ``|\expandafter| trick'' to expand only certain parts of the
+% replacement text at the time of the definition.
+% \begin{macrocode}
+ \def\@tempa{\global\@namedef{#1}}%
+ \expandafter \@tempa \expandafter{%
+% \end{macrocode}
+% First, the macro that contains the current definitions of
+% |\@begintheorem| and |\@opargtheorem| should be called
+% up. The name of this macro---as is already known---has the form
+% |\th@|\meta{theorem\ style}; therefore, it must be called by
+% \begin{macrocode}
+ \csname th@\the \theorem@style
+% \end{macrocode}
+% In addition the default theorem font should be changeable, i.e.\
+% we have to insert the contents of |\theorem@bodyfont|. For
+% that reason, we expand even further, beyond |\endcsname|,
+% and thus insert the contents of the \textsf{token} register
+% |\theorem@bodyfont| in the replacement text.
+% \begin{macrocode}
+ \expandafter \endcsname \the \theorem@bodyfont
+% \end{macrocode}
+% Now it is time to call the macro |\@thm| which takes over
+% the further processing. It has two arguments: the current
+% counter name (in our example, \texttt{Lem}), and the text of the
+% label (in our example, \texttt{Lemma}).
+% \begin{macrocode}
+ \@thm{#1}{#2}}%
+% \end{macrocode}
+% With this, the `sub-definition' is complete. The macro
+% |\@endtheorem| ends a theorem environment and is, so far, nothing
+% but an |\endtrivlist|. (Hence it is defined globally, and not
+% within the theorem styles.\footnote{This has to be changed as
+% soon as theorem styles that change \texttt{\bslash @endtheorem}
+% exist. In such a case, all existing styles must be changed as
+% well since they will have to reset the macro.}) Therefore, we can
+% set it equivalent to the macro that ends the theorem set (in our
+% example, |\endLem|). However, if some day theorem styles exist
+% that do change |\@endtheorem|, we would have to use the
+% commented-out line instead.
+% \begin{macrocode}
+ \global \expandafter \let \csname end#1\endcsname \@endtheorem
+% \global\@namedef{end#1}{\@endtheorem}%
+% \end{macrocode}
+% With these commands all the required definitions are employed,
+% unless the test |\@ifdefinable| has failed. Therefore, we
+% end the second argument of this macro and with it the definition
+% of |\@xnthm|.
+% \begin{macrocode}
+ }}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\@ynthm}
+% The definition of |\@ynthm| is completely analogous. In
+% this case the new counter that is defined is not reset within
+% another counter; thus the definition of |\the...|
+% is simplified:
+% \begin{macrocode}
+\gdef\@ynthm#1#2{\expandafter\@ifdefinable\csname #1\endcsname
+ {\@definecounter{#1}%
+ \expandafter\xdef\csname the#1\endcsname{\@thmcounter{#1}}%
+% \end{macrocode}
+% The rest of the definition corresponds literally to that of
+% |\@xnthm|:
+% \begin{macrocode}
+ \def\@tempa{\global\@namedef{#1}}\expandafter \@tempa
+ \expandafter{\csname th@\the \theorem@style \expandafter
+ \endcsname \the\theorem@bodyfont \@thm{#1}{#2}}%
+ \global \expandafter \let \csname end#1\endcsname \@endtheorem}}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\@othm}
+% The definition of |\@othm| does not contain anything new.
+% \begin{macrocode}
+\gdef\@othm#1[#2]#3{%
+% \end{macrocode}
+% \changes{v2.2b}{95/10/07}{Build in check for counter defined}
+% We do not define a new counter but instead use one that has
+% already been defined. Thus the only definition we need is that
+% of this pseudo-counter (i.e.\ |\the|\meta{env.\ name}).
+% First we check if |#2| corresponds to a known counter name.
+% \begin{macrocode}
+ \expandafter\ifx\csname c@#2\endcsname\relax
+ \@nocounterr{#2}%
+ \else
+ \expandafter\@ifdefinable\csname #1\endcsname
+ {\expandafter \xdef \csname the#1\endcsname
+ {\expandafter \noexpand \csname the#2\endcsname}%
+% \end{macrocode}
+% All other parts of the definition can be adopted from
+% |\@xnthm|. We have to remember, though, that in this case
+% the name of the current counter and the theorem label have moved
+% to the second and third arguments.
+% \begin{macrocode}
+ \def\@tempa{\global\@namedef{#1}}\expandafter \@tempa
+ \expandafter{\csname th@\the \theorem@style \expandafter
+ \endcsname \the\theorem@bodyfont \@thm{#2}{#3}}%
+ \global \expandafter \let \csname end#1\endcsname \@endtheorem}%
+ \fi}
+% \end{macrocode}
+% \end{macro}
+%
+% \subsection{Macros that are employed in a {\envfont theorem}
+% environment}
+%
+% \begin{macro}{\@thm}
+% The macro |\@thm| has to increase the current counter. Then,
+% depending on whether the environment has (or does not have) an
+% optional argument, it has to branch into either |\@begintheorem|
+% or |\@opargtheorem|.
+% \begin{macrocode}
+\gdef\@thm#1#2{\refstepcounter{#1}%
+% \end{macrocode}
+% Now we start a {\envfont trivlist} environment, and give
+% |\@topsep| and |\@topsepadd| the values of the \textsf{skip}
+% registers |\theorempreskipamount| and |\theorempostskipamount|.
+% The value in |\@topsep| is the vertical space that is inserted by
+% the first (and only) |\item| in our |\trivlist| whilst
+% |\@topsepadd| is inserted by |\@endparenv| at the end of that
+% {\envfont trivlist} environment. By using these registers, we
+% obtain the desired space around a {\envfont theorem} environment.
+% \begin{macrocode}
+ \trivlist
+ \@topsep \theorempreskipamount % used by first \item
+ \@topsepadd \theorempostskipamount % used by \@endparenv
+% \end{macrocode}
+% Now we have to test whether an optional argument has been given.
+% \changes{v2.0d}{89/07/18}{Forgotten percent added.}
+% \begin{macrocode}
+ \@ifnextchar [%
+% \end{macrocode}
+% If there is an optional argument, we will call |\@ythm|, and
+% move the arguments read back into the input stream.
+% \begin{macrocode}
+ {\@ythm{#1}{#2}}%
+% \end{macrocode}
+% If not, we call |\@begintheorem|. Its first argument is the
+% name of the theorem set (hence the second argument of
+% |\@thm|). Its second argument is the macro that produces the
+% current number.
+% \begin{macrocode}
+ {\@begintheorem{#2}{\csname the#1\endcsname}\ignorespaces}}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\@xthm}
+% \begin{macro}{\@ythm}
+% Both these macros were originally called by |\@thm|. We do
+% not need |\@xthm| anymore, hence we reset it to
+% |\relax|. The definition of |\@ythm| has not changed at
+% all from its definition in \LaTeX. In order to make the macros
+% easier to understand, we will
+% nevertheless present it (commented out).
+% \begin{macrocode}
+\global\let\@xthm\relax
+% \def\@ythm#1#2[#3]{\@opargbegintheorem{#2}{\csname
+% the#1\endcsname}{#3}\ignorespaces}
+%</package>
+% \end{macrocode}
+% The primitive |\ignorespaces| in |\@ythm| and
+% |\@thm| is needed to remove the spaces between the
+% |\begin{...}| and the actual text.
+% \end{macro}
+% \end{macro}
+%
+%
+% \subsection{Definition of the theorem substyles}
+%
+% As already pointed out, the theorem substyles, defined below, are
+% only loaded when necessary. Note that all these substyles, except
+% \texttt{plain}, have |\slshape| as the default body font.
+%
+% \subsubsection{The \texttt{plain} style}
+%
+% \label{dok:th@plain} As the following macros use |@|, we have
+% to locally set the |\catcode| of this symbol to ``letter''.
+% This happens within a group, so that we do not have to worry about
+% which |\catcode| that symbol had before.
+% \begin{macrocode}
+%<*thp>
+\begingroup \makeatletter
+% \end{macrocode}
+% Since we are now within a group, we must make all definitions
+% globally. First we make sure that \texttt{theorem.sty} is loaded.
+% This will allow us to use this file as a document style option
+% without having to call \texttt{theorem} itself as an option. At the
+% same time, we assure that at least version 2 is loaded, since
+% |\theorem@style| was not defined in earlier versions.
+% \begin{macrocode}
+\@ifundefined{theorem@style}{\input{theorem.sty}}{}
+\ProvidesFile{thp.sty}
+ [\FMithmInfo]
+% \end{macrocode}
+%
+%
+% \begin{macro}{\th@plain}
+% \begin{macro}{\@begintheorem}
+% \begin{macro}{\@opargbegintheorem}
+% |\theoremstyle{plain}| corresponds to the original
+% definition, except that the distances to the surrounding text are
+% determined by the parameters |\theorempreskipamount| and
+% |\theorempostskipamount|.
+% First we set the default body font.
+% \begin{macrocode}
+\gdef\th@plain{\normalfont\itshape
+% \end{macrocode}
+% Then we define |\@begintheorem| and
+% |\@opargbegintheorem|. These two macros define how the
+% header of a theorem is typeset. |\@opargbegintheorem| will
+% be called if a \textsf{theorem} environment with an optional
+% argument is encountered; otherwise, the header is constructed by
+% calling |\@begintheorem|. If one of these macros is
+% executed, we are within a \textsf{trivlist} environment started by
+% |\@thm|. So the theorem header is produced with an
+% |\item| command.
+%
+% Instead of specifying the header font directly, all standard
+% theorem styles use the |\theorem@headerfont| macro to allow
+% customization. The extra space (|\labelsep|) is necessary
+% because of problems in the \textsf{trivlist} environment.
+% \begin{macrocode}
+ \def\@begintheorem##1##2{%
+ \item[\hskip\labelsep \theorem@headerfont ##1\ ##2]}%
+% \end{macrocode}
+% The definition of |\@opargbegintheorem| is completely
+% analogous. The only difference is the fact that there exists a
+% third argument (which is the optional parameter of the
+% environment and contains additional information about the
+% theorem). Customarily we enclose it in parentheses.
+% \begin{macrocode}
+\def\@opargbegintheorem##1##2##3{%
+ \item[\hskip\labelsep \theorem@headerfont ##1\ ##2\ (##3)]}}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+% \noindent
+% We conclude with an |\endgroup| to restore the
+% |\catcode| of |@|.
+% \begin{macrocode}
+\endgroup
+%</thp>
+% \end{macrocode}
+%
+%
+% \subsubsection{The \texttt{break} style}
+%
+% This style option is stored in the file |thb.sty|.
+% For the next two lines see the documentation for |\th@plain| on
+% page~\pageref{dok:th@plain}.
+% \begin{macrocode}
+%<*thb>
+\begingroup \makeatletter
+\@ifundefined{theorem@style}{\input{theorem.sty}}{}
+\ProvidesFile{thb.sty}
+ [\FMithmInfo]
+% \end{macrocode}
+%
+% \begin{macro}{\th@break}
+% |\theoremstyle{break}| produces a line break after the name
+% of the theorem. The font is |\slshape|. Hence, we define
+% |\th@break| as follows:
+% \begin{macrocode}
+\gdef\th@break{\normalfont\slshape
+ \def\@begintheorem##1##2{\item[%
+% \end{macrocode}
+% We run into the following problem: it is not possible to create
+% the header with |\item[|\meta{title}|]| and then start
+% a new line by, for example, |\mbox{}\\|. Such a definition
+% will fail whenever a list environment follows immediately. With
+% the above construction, the |\mbox{}| causes the switch
+% |@inlabel| (cf.\ definition of |\list| and
+% |\trivlist| in \cite{latex:source}) to be set to \texttt{false}
+% and so the following list will insert additional vertical
+% space (|\topskip|). This is quite annoying. Therefore, we
+% create the line break within the |\item|. In order to ensure
+% that the text will begin at the proper position in the following
+% line, we simply pretend that the label does not take any
+% room.\footnote{This will lead to problems whenever very high
+% symbols occurring in the line tower into the
+% heading. So, something else has to be done here sometime.}
+% \begin{macrocode}
+ \rlap{\vbox{\hbox{\hskip \labelsep\theorem@headerfont ##1\ ##2}%
+ \hbox{\strut}}}]}%
+% \end{macrocode}
+% Again, the definition of |\@opargbegintheorem| is
+% completely analogous.
+% \begin{macrocode}
+\def\@opargbegintheorem##1##2##3{%
+ \item[\rlap{\vbox{\hbox{\hskip \labelsep \theorem@headerfont
+ ##1\ ##2\ (##3)}%
+ \hbox{\strut}}}]}}
+\endgroup
+%</thb>
+% \end{macrocode}
+% \end{macro}
+%
+%
+% \subsubsection{The \texttt{changebreak} style}
+%
+% \begin{macrocode}
+% This style option is stored in the file |thcb.sty|.
+% \begin{macrocode}
+%<*thcb>
+\begingroup \makeatletter
+\@ifundefined{theorem@style}{\input{theorem.sty}}{}
+\ProvidesFile{thcb.sty}
+ [\FMithmInfo]
+% \end{macrocode}
+%
+% \begin{macro}{\th@changebreak}
+% The \texttt{change-break} theorem style is like \texttt{break}
+% but with interchange of theorem name and theorem number. Thus we
+% define |\th@changebreak| as follows:
+% \begin{macrocode}
+\gdef\th@changebreak{\normalfont\slshape
+ \def\@begintheorem##1##2{\item
+ [\rlap{\vbox{\hbox{\hskip\labelsep \theorem@headerfont ##2\ ##1}%
+ \hbox{\strut}}}]}%
+\def\@opargbegintheorem##1##2##3{%
+ \item[\rlap{\vbox{\hbox{\hskip\labelsep \theorem@headerfont
+ ##2\ ##1\ (##3)}%
+ \hbox{\strut}}}]}}
+\endgroup
+%</thcb>
+% \end{macrocode}
+% \end{macro}
+%
+%
+% \subsubsection{The \texttt{change} style}
+%
+% This style option is stored in the file |thc.sty|.
+% \begin{macrocode}
+%<*thc>
+\begingroup \makeatletter
+\@ifundefined{theorem@style}{\input{theorem.sty}}{}
+\ProvidesFile{thc.sty}
+ [\FMithmInfo]
+% \end{macrocode}
+%
+% \begin{macro}{\th@change}
+% The \texttt{change} theorem style corresponds to the
+% \texttt{change break} style without a linebreak after the header.
+% To say it in another way, it's the same as the \texttt{plain}
+% style but with number and name interchanged and |\slshape| as the
+% default font.
+% \begin{macrocode}
+\gdef\th@change{\normalfont\slshape
+ \def\@begintheorem##1##2{\item
+ [\hskip\labelsep \theorem@headerfont ##2\ ##1]}%
+\def\@opargbegintheorem##1##2##3{%
+ \item[\hskip\labelsep \theorem@headerfont ##2\ ##1\ (##3)]}}
+\endgroup
+%</thc>
+% \end{macrocode}
+% \end{macro}
+%
+%
+% \subsubsection{The \texttt{marginbreak} style}
+%
+% This style option is the one used most often at Mainz. It is saved
+% in the file |thmb.sty|.
+% \begin{macrocode}
+%<*thmb>
+\begingroup \makeatletter
+\@ifundefined{theorem@style}{\input{theorem.sty}}{}
+\ProvidesFile{thmb.sty}
+ [\FMithmInfo]
+% \end{macrocode}
+%
+% \begin{macro}{\th@marginbreak}
+% The \texttt{margin break} style is nearly the same as the
+% \texttt{change break} style. The only difference is the placement
+% of the theorem number. We use |\llap| to place it in the left
+% margin.
+%
+% In this style |\labelsep| denotes the separation between the
+% number and the text.
+% \begin{macrocode}
+\gdef\th@marginbreak{\normalfont\slshape
+ \def\@begintheorem##1##2{\item
+ [\rlap{\vbox{\theorem@headerfont
+ \hbox{\llap{##2}\hskip\labelsep ##1}%
+ \hbox{\strut}}}]}%
+\def\@opargbegintheorem##1##2##3{%
+ \item[\rlap{\vbox{\theorem@headerfont
+ \hbox{\llap{##2}\hskip\labelsep ##1\ (##3)}%
+ \hbox{\strut}}}]}}
+\endgroup
+%</thmb>
+% \end{macrocode}
+% \changes{v2.1c}{90/02/17}{`endgroup outside macrocode env.}
+% \end{macro}
+%
+%
+%
+% \subsubsection{The \texttt{margin} style}
+%
+% This style option is stored in the file |thm.sty|.
+% \begin{macrocode}
+%<*thm>
+\begingroup \makeatletter
+\@ifundefined{theorem@style}{\input{theorem.sty}}{}
+\ProvidesFile{thm.sty}
+ [\FMithmInfo]
+% \end{macrocode}
+%
+% \begin{macro}{\th@margin}
+% Again this is only a variant of the theorem styles described
+% above without any new ideas.
+% \begin{macrocode}
+\gdef\th@margin{\normalfont\slshape
+ \def\@begintheorem##1##2{\item
+ [\theorem@headerfont \llap{##2}\hskip\labelsep ##1]}%
+\def\@opargbegintheorem##1##2##3{%
+ \item[\theorem@headerfont \llap{##2}\hskip\labelsep ##1\ (##3)]}}
+\endgroup
+%</thm>
+% \end{macrocode}
+% \end{macro}
+%
+%
+%
+%
+% \subsection{Final Definitions}
+%
+% \begin{macro}{\theorempreskipamount}
+% \begin{macro}{\theorempostskipamount}
+% The \textsf{skip} parameters that regulate the vertical empty space
+% before and after the {\envfont theorem} environment have
+% to be allocated as well.
+% \changes{v2.0f}{89/07/20}{Unnecessary `global' removed.}
+% \begin{macrocode}
+%<*package>
+\newskip\theorempreskipamount
+\newskip\theorempostskipamount
+% \end{macrocode}
+% Since we have used the same values for all theorem sets, we now can
+% assign them.
+% \begin{macrocode}
+\global\setlength\theorempreskipamount{12pt plus 5pt minus 3pt}
+\global\setlength\theorempostskipamount{8pt plus 3pt minus 1.5pt}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+%
+% \begin{macro}{\@endtheorem}
+% The same holds for the macro |\@endtheorem|, which ends a
+% {\envfont theorem} environment. Since it is the same for all
+% theorem sets, it is removed from the macros |\th@|\meta{style}.
+% It simply ends the {\envfont trivlist} environment, which was
+% begun in |\@thm|.
+% \begin{macrocode}
+\global\let\@endtheorem=\endtrivlist
+% \end{macrocode}
+% \end{macro}
+%
+%
+%
+% \begin{macro}{\@preamblecmds}
+% All macros defined above are to be used only in the preamble.
+% Therefore, we insert them in |\@preamblecmds| which will disable
+% them at begin document. This is done by the internal \LaTeXe{}
+% command |\@onlypreamble|.
+% \changes{v2.0g}{89/09/19}{`theoremheaderfont and `theorembodyfont
+% added.}
+% \changes{v2.2a}{94/02/03}{Use \LaTeXe{} interface}
+% \begin{macrocode}
+\@onlypreamble\@xnthm
+\@onlypreamble\@ynthm
+\@onlypreamble\@othm
+\@onlypreamble\newtheorem
+\@onlypreamble\theoremstyle
+\@onlypreamble\theorembodyfont
+\@onlypreamble\theoremheaderfont
+% \end{macrocode}
+% \end{macro}
+%
+% Finally we declare the \texttt{plain} theorem style to be the default.
+% \changes{v2.1b}{90/06/04}{Fixed missing `item by declaring default
+% style.}
+% \begin{macrocode}
+\theoremstyle{plain}
+%</package>
+% \end{macrocode}
+%
+% \Finale
+
+\endinput
diff --git a/Master/texmf-dist/source/latex/tools/tools.ins b/Master/texmf-dist/source/latex/tools/tools.ins
new file mode 100644
index 00000000000..b01195e3426
--- /dev/null
+++ b/Master/texmf-dist/source/latex/tools/tools.ins
@@ -0,0 +1,208 @@
+%%
+%% This file will generate fast loadable files and documentation
+%% driver files from the doc files in this package when run through
+%% LaTeX or TeX.
+%%
+%% Copyright 1993 1994 1995 1996 1997 1998 1999 2000 2001 2002 2003
+%% The LaTeX3 Project and any individual authors listed elsewhere
+%% in this file.
+%%
+%% This file is part of the Standard LaTeX `Tools Bundle'.
+%% -------------------------------------------------------
+%%
+%% It 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.3 or later is part of all distributions of LaTeX
+%% version 2003/12/01 or later.
+%%
+%% In particular, NO PERMISSION is granted to modify the contents of this
+%% file since it contains the legal notices that are placed in the files
+%% it generates.
+%%
+%% The list of all files belonging to the `Tools Bundle' is
+%% given in the file `manifest.txt'.
+%%
+%%
+%% --------------- start of docstrip commands ------------------
+%%
+\input docstrip
+
+\def\SimplePackage#1{%
+ \generate{\file{#1.sty}{\from{#1.dtx}{package}}}}
+
+\keepsilent
+
+\usedir{tex/latex/tools}
+
+\preamble
+
+This is a generated file.
+
+Copyright 1993 1994 1995 1996 1997 1998 1999 2000 2001 2002 2003
+The LaTeX3 Project and any individual authors listed elsewhere
+in this file.
+
+This file was generated from file(s) of the Standard LaTeX `Tools Bundle'.
+--------------------------------------------------------------------------
+
+It 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.3 or later is part of all distributions of LaTeX
+version 2003/12/01 or later.
+
+This file may only be distributed together with a copy of the LaTeX
+`Tools Bundle'. You may however distribute the LaTeX `Tools Bundle'
+without such generated files.
+
+The list of all files belonging to the LaTeX `Tools Bundle' is
+given in the file `manifest.txt'.
+
+\endpreamble
+
+% Array files
+%%%%%%%%%%%%%
+\generate{\file{array.sty}{\from{array.dtx}{package,ncols}}}
+
+\SimplePackage{delarray}
+
+\SimplePackage{tabularx}
+
+\SimplePackage{dcolumn}
+
+\SimplePackage{hhline}
+
+\SimplePackage{longtable}
+
+% Multicolumn
+%%%%%%%%%%%%%
+\generate{\file{multicol.sty}{%
+ \from{multicol.dtx}{package,badness,check,marktrace,nobalance,colbreak}}}
+
+
+% Bold Math Symbols
+%%%%%%%%%%%%%%%%%%%
+\SimplePackage{bm}
+
+% Footnote Right
+%%%%%%%%%%%%%%%
+\SimplePackage{ftnright}
+
+% Theorem files
+%%%%%%%%%%%%%%%
+\generate{%
+ \file{theorem.sty}{\from{theorem.dtx}{package}}
+ \file{thb.sty}{\from{theorem.dtx}{thb}}
+ \file{thcb.sty}{\from{theorem.dtx}{thcb}}
+ \file{thc.sty}{\from{theorem.dtx}{thc}}
+ \file{thp.sty}{\from{theorem.dtx}{thp}}
+ \file{thmb.sty}{\from{theorem.dtx}{thmb}}
+ \file{thm.sty}{\from{theorem.dtx}{thm}}}
+
+% Verbatim
+%%%%%%%%%%
+\generate{%
+ \file{verbatim.sty}{\from{verbatim.dtx}{package}}
+ \file{verbtest.tex}{\from{verbatim.dtx}{testdriver}}}
+
+% Smart Page references
+%%%%%%%%%%%%%%%%%%%%%%%
+\SimplePackage{varioref}
+
+% External references
+%%%%%%%%%%%%%%%%%%%%%
+\SimplePackage{xr}
+
+% Smart Space command
+%%%%%%%%%%%%%%%%%%%%%
+\SimplePackage{xspace}
+
+% Show \label \ref keys
+%%%%%%%%%%%%%%%%%%%%%%%
+\SimplePackage{showkeys}
+
+% Load fonts under old names
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\SimplePackage{rawfonts}
+
+% Selective Option handling
+%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\SimplePackage{somedefs}
+
+
+% Font sample
+%%%%%%%%%%%%%
+\generate{%
+ \file{fontsmpl.sty}{\from{fontsmpl.dtx}{package}}
+ \file{fontsmpl.tex}{\from{fontsmpl.dtx}{document}}}
+
+% After Page Package
+%%%%%%%%%%%%%%%%%%%%
+\SimplePackage{afterpage}
+
+
+% Enumerate Package
+%%%%%%%%%%%%%%%%%%%%
+\SimplePackage{enumerate}
+
+
+% Indent first paragraphs
+%%%%%%%%%%%%%%%%%%%
+\SimplePackage{indentfirst}
+
+
+% Show the layout of a document class
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\SimplePackage{layout}
+
+
+% Infix Arithmetic
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\SimplePackage{calc}
+
+% Debugging
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\SimplePackage{trace}
+
+% File-Error files
+%%%%%%%%%%%%%%%%%%
+\generate{%
+ \file{h.tex}{\from{fileerr.dtx}{help}}
+ \file{s.tex}{\from{fileerr.dtx}{scroll}}
+ \file{e.tex}{\from{fileerr.dtx}{edit}}
+ \file{q.tex}{\from{fileerr.dtx}{batch}}
+ \file{r.tex}{\from{fileerr.dtx}{run}}
+ \file{x.tex}{\from{fileerr.dtx}{exit}}}
+
+
+\Msg{***********************************************************}
+\Msg{*}
+\Msg{* To finish the installation you have to move the following}
+\Msg{* files into a directory searched by TeX:}
+\Msg{*}
+\Msg{* All the files with extension `.sty' and `.tex'}
+\Msg{* Note there also may be a file .tex which is `invisible'}
+\Msg{* on some operating systems.}
+\Msg{*}
+\Msg{* To produce the documentation run the .dtx files through LaTeX.}
+\Msg{*}
+\Msg{* Happy TeXing}
+\Msg{***********************************************************}
+
+
+\Msg{}
+\Msg{* Finally trying to make a file `.tex'.}
+\Msg{* (Placed at the end of this run, as this}
+\Msg{* may fail on some operating systems.)}
+
+\let\oldopenout\openout
+\def\openout{\batchmode\immediate\oldopenout}
+
+\generate{\file{.tex}{\from{fileerr.dtx}{return}}}
+
+\endbatchfile
diff --git a/Master/texmf-dist/source/latex/tools/trace.dtx b/Master/texmf-dist/source/latex/tools/trace.dtx
new file mode 100644
index 00000000000..71c3494d773
--- /dev/null
+++ b/Master/texmf-dist/source/latex/tools/trace.dtx
@@ -0,0 +1,708 @@
+% \iffalse meta-comment
+%
+% Copyright 1993 1994 1995 1996 1997 1998 1999 2000 2001 2002 2003
+% The LaTeX3 Project and any individual authors listed elsewhere
+% in this file.
+%
+% This file is part of the Standard LaTeX `Tools Bundle'.
+% -------------------------------------------------------
+%
+% It 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.3 or later is part of all distributions of LaTeX
+% version 2003/12/01 or later.
+%
+% The list of all files belonging to the LaTeX `Tools Bundle' is
+% given in the file `manifest.txt'.
+%
+% \fi
+% \iffalse
+%%
+%% $Id: trace.dtx,v 3.2 2003/06/29 14:44:49 mittelba Exp $
+%%
+%% (C) Copyright 1999-2001 Frank Mittelbach
+%% All rights reserved.
+%%
+%<*dtx>
+ \ProvidesFile{trace.dtx}
+%</dtx>
+%<package>\NeedsTeXFormat{LaTeX2e}
+%<package>\ProvidesPackage{trace}
+%<driver>\ProvidesFile{trace.drv}
+% \fi
+% \ProvidesFile{trace.dtx}
+ [2003/04/30 v1.1c trace LaTeX code]
+%
+% \iffalse
+%<*driver>
+\documentclass{ltxdoc}
+\usepackage{doc}
+\setcounter{StandardModuleDepth}{1}
+
+\usepackage{shortvrb}
+\MakeShortVerb\|
+
+\DeclareRobustCommand\eTeX{\ensuremath{\varepsilon}-\kern-.125em\TeX}
+
+\begin{document}
+\DocInput{trace.dtx}
+\end{document}
+%</driver>
+% \fi
+%
+% \CheckSum{237}
+%
+% \GetFileInfo{trace.dtx}
+%
+% \title{The \textsf{trace} package\thanks{This file
+% has version number \fileversion, last
+% revised \filedate.}}
+% \author{Frank Mittelbach\\
+% \LaTeX3 project\\
+% \texttt{frank.mittelbach@latex-project.org}}
+% \date{\filedate}
+% \maketitle
+%
+%
+%
+% \section{Introduction}
+%
+% When writing new macros one often finds that they do not work as
+% expected (at least I do :-). If this happens and one can't
+% immediately figure out why there is a problem one has to start doing
+% some serious debugging. \TeX{} offers a lot of bells and whistles to
+% control what is being traced but often enough I find myself applying
+% the crude command |\tracingall| which essentially means ``give me
+% whatever tracing information is available''.
+%
+% In fact I normally use \eTeX{} in such a case, since that \TeX{}
+% extension offers me a number of additional tracing possibilities
+% which I find extremely helpful. The most important ones are
+% |\tracingassigns|, which will show you changes to register values
+% and changes to control sequences when they happen, and
+% |\tracinggroups|, which will tell you what groups are entered
+% or left (very useful if your grouping got out of sync).
+%
+% So what I really write is
+%\begin{verbatim}
+% \tracingassigns=1\tracinggroups=1\tracingall
+%\end{verbatim}
+% That in itself is already a nuisance (since it is a mouthful) but
+% there is a worse catch: when using |\tracingall| you do get a awful
+% lot of information and some of it is really useless.
+%
+% For example, if \LaTeX{} has to load a new font it enters some
+% internal routines of NFSS which scan font definition tables etc.
+% And 99.9\% of the time you are not at all interested in that part of the
+% processing but in the two lines before and the five lines
+% after. However, you have to scan through a few hundred lines of
+% output to find the lines you need.
+%
+% Another example is the \texttt{calc} package. A simple statement
+% like |\setlength| |\linewidth| |{1cm}| inside your macro will result
+% in
+%
+% \renewcommand\MacroFont{\fontencoding\encodingdefault
+% \fontfamily\ttdefault
+% \fontseries\mddefault
+% \fontshape\updefault
+% \footnotesize}%
+%\begin{verbatim}
+% \setlength ->\protect \setlength
+% {\relax}
+%
+% \setlength ->\calc@assign@skip
+%
+% \calc@assign@skip ->\calc@assign@generic \calc@Askip \calc@Bskip
+%
+% \calc@assign@generic #1#2#3#4->\let \calc@A #1\let \calc@B #2\expandafter \calc
+% @open \expandafter (#4!\global \calc@A \calc@B \endgroup #3\calc@B
+% #1<-\calc@Askip
+% #2<-\calc@Bskip
+% #3<-\linewidth
+% #4<-1cm
+% {\let}
+% {\let}
+% {\expandafter}
+% {\expandafter}
+%
+% \calc@open (->\begingroup \aftergroup \calc@initB \begingroup \aftergroup \calc
+% @initB \calc@pre@scan
+% {\begingroup}
+% {\aftergroup}
+% {\begingroup}
+% {\aftergroup}
+%
+% \calc@pre@scan #1->\ifx (#1\expandafter \calc@open \else \ifx \widthof #1\expan
+% dafter \expandafter \expandafter \calc@textsize \else \calc@numeric \fi \fi #1
+% #1<-1
+% {\ifx}
+% {false}
+% {\ifx}
+% {false}
+%
+% \calc@numeric ->\afterassignment \calc@post@scan \global \calc@A
+% {\afterassignment}
+% {\global}
+% {\fi}
+% {\fi}
+%
+% \calc@post@scan #1->\ifx #1!\let \calc@next \endgroup \else \ifx #1+\let \calc@
+% next \calc@add \else \ifx #1-\let \calc@next \calc@subtract \else \ifx #1*\let
+% \calc@next \calc@multiplyx \else \ifx #1/\let \calc@next \calc@dividex \else \i
+% fx #1)\let \calc@next \calc@close \else \calc@error #1\fi \fi \fi \fi \fi \fi \
+% calc@next
+% #1<-!
+% {\ifx}
+% {true}
+% {\let}
+% {\else}
+% {\endgroup}
+% {restoring \calc@next=undefined}
+%
+% \calc@initB ->\calc@B \calc@A
+% {\skip44}
+% {\global}
+% {\endgroup}
+% {restoring \skip44=0.0pt}
+%
+% \calc@initB ->\calc@B \calc@A
+% {\skip44}
+% {\dimen27}
+%\end{verbatim}
+%
+% \noindent Do you still remember what I was talking about?
+%
+% No? We're trying to find a problem in macro code without having to scan
+% too many uninteresting lines. To make this possible we have to
+% redefine a number of key commands to turn tracing off temporarily in
+% the hope that this will reduce the amount of noise during the
+% trace. For example, if we change one of the \texttt{calc} internals
+% slightly, the above tracing output can be reduced to:
+%
+%\begin{verbatim}
+% \setlength ->\protect \setlength
+% {\relax}
+%
+% \setlength ->\calc@assign@skip
+%
+% \calc@assign@skip ->\calc@assign@generic \calc@Askip \calc@Bskip
+%
+% \calc@assign@generic #1#2#3#4->\let \calc@A #1\let \calc@B #2\expandafter \calc
+% @open \expandafter (#4!\global \calc@A \calc@B \endgroup #3\calc@B
+% #1<-\calc@Askip
+% #2<-\calc@Bskip
+% #3<-\linewidth
+% #4<-1cm
+% {\let}
+% {\let}
+% {\expandafter}
+% {\expandafter}
+%
+% \calc@open (->\begingroup \conditionally@traceoff \aftergroup \calc@initB \begi
+% ngroup \aftergroup \calc@initB \calc@pre@scan
+% {\begingroup}
+%
+% \conditionally@traceoff ->\tracingrestores \z@ \tracingcommands \z@ \tracingpag
+% es \z@ \tracingmacros \z@ \tracingparagraphs \z@
+% {\tracingrestores}
+% {\tracingcommands}
+% {restoring \tracingrestores=1}
+%
+% \calc@initB ->\calc@B \calc@A
+% {\skip44}
+% {\dimen27}
+%\end{verbatim}
+%
+% \noindent\label{conttraceoffexample}
+% Still a lot of noise but definitely preferable to the
+% original case.
+%
+% I redefined those internals that I found most annoyingly
+% noisy. There are probably many others that could be treated in a
+% similar fashion, so if you think you found one worth adding please
+% drop me a short note.
+%
+% \[ * \quad * \quad * \]
+%
+% \DescribeMacro\traceon
+% \DescribeMacro\traceoff
+% The package defines the two macros |\traceon| and |\traceoff| to
+% unconditionally turn tracing on or off, respectively. |\traceon| is
+% like |\tracingall| but additionally adds |\tracingassigns| and
+% |\tracinggroups| if the \eTeX{} program (in extended mode) is
+% used. And |\traceoff| will turn tracing off again, a command which
+% is already badly missing in plain \TeX{}, since it is often not
+% desirable to restrict the tracing using extra groups in the
+% document.
+%
+% \DescribeMacro\conditionally@traceon
+% \DescribeMacro\conditionally@traceoff
+% There are also two internal macros that turn tracing on and off, but
+% only if the user requested tracing in the first place. These are the
+% ones that are used internally within the code below.
+%
+% Since the package overwrites some internals of other packages you
+% should load it as the last package in your preamble using
+% |\usepackage{trace}|.
+%
+% The package offers the option \texttt{logonly} that suppresses
+% terminal output during tracing (unless |\tracingall| is used). This
+% is useful if the \TeX{} implementation used gets rather slow when
+% writing a lot of information to the terminal.
+%
+% It also offers the option \texttt{full} in which case |\traceon|
+% will trace all parts of the code, i.e., essentially work like
+% |\tracingall|.
+%
+% \section{A sample file}
+%
+% The following small test file shows the benefits of the
+% \texttt{trace} package. If one uncomments the line loading the
+% package, the amount of tracing data will be drastically reduced.
+% Without the \texttt{trace} package we get 6594 lines in the log
+% file; adding the package will reduce this to 1618 lines.
+%
+%\begin{verbatim}
+% \documentclass{article}
+% \usepackage{calc}
+% %\usepackage{trace} % uncomment to see difference
+%
+% \begin{document}
+% \ifx\traceon\undefined \tracingall \else \traceon \fi
+%
+% \setlength\linewidth{1cm}
+%
+% $foo=\bar a$
+%
+% \small \texttt{\$} \stop
+%\end{verbatim}
+%
+% \StopEventually{}
+%
+% \section{Implementation}
+%
+% \renewcommand\MacroFont{\fontencoding\encodingdefault
+% \fontfamily\ttdefault
+% \fontseries\mddefault
+% \fontshape\updefault
+% \small}
+%
+% This package is for use with \LaTeX{} (though something similar
+% could be produced for other formats).
+% \begin{macrocode}
+%<*package>
+\NeedsTeXFormat{LaTeX2e}[1998/12/01]
+% \end{macrocode}
+%
+% The package has a option that suppresses tracing on the
+% terminal, i.e., if used will not set |\tracingonline| to
+% one. This has been added in version 1.1a since some \TeX{}
+% implementations get rather slow when outputting to a terminal.
+% \begin{macrocode}
+\DeclareOption{logonly}
+ {\let\tracingonline@p\z@}
+% \end{macrocode}
+% The default is showing the tracing information on the terminal.
+% \begin{macrocode}
+\let\tracingonline@p\@ne
+% \end{macrocode}
+%
+% If the option |full| is selected then all code should be traced,
+% i.e., the commands |\conditionally@traceoff| and
+% |\conditionally@traceon| should do nothing. We set them to
+% |\@empty| not |\relax| since the latter might produce a math ord
+% in certain circumstances. We also have to make sure that
+% |\traceon| (as defined further down) is not redfining
+% |\conditionally@traceoff| again. To make this all work these
+% redefinitions have to wait until the end of the package.
+% \changes{v1.1c}{2003/04/30}{Option ``full'' added}
+% \begin{macrocode}
+\DeclareOption{full}
+ {\AtEndOfPackage{\let\conditionally@traceoff\@empty
+ \let\conditionally@traceon\@empty
+ \let\traceon\tr@ce@n
+ }}
+% \end{macrocode}
+%
+% \begin{macrocode}
+\ProcessOptions\relax
+% \end{macrocode}
+%
+%
+%
+% \begin{macro}{\if@tracing}
+% We need a switch to determine if we want any tracing at
+% all. Otherwise, if we use |\traceoff|\ldots|\traceon|
+% internally, we would unconditionally turn on tracing even when no
+% tracing was asked for in the first place.
+% \begin{macrocode}
+\newif\if@tracing
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\traceon}
+% This macro ensures that |\conditionally@traceoff| is actually
+% turning off switches (since |\tracinall| might have disabled it)
+% and then calls |\tr@ce@n| to setup tracing.
+% \begin{macrocode}
+\def\traceon{\let\conditionally@traceoff\unconditionally@traceoff
+ \tr@ce@n}
+% \end{macrocode}
+% \end{macro}
+
+% \begin{macro}{\tr@ce@n}
+% \changes{v1.1c}{2003/04/30}{Macro added}
+% \begin{macro}{\conditionally@traceoff}
+% As stated in the introduction, the amount of tracing being done
+% should depend on the formatter we use. So we first test if we are
+% running with \eTeX{} in extended mode. In the latter case the command
+% |\tracinggroups| is defined.\footnote{If some package writer has defined
+% that command name for some reason---too bad---then we make the
+% wrong deduction from this fact and as a result the package will fail.}
+% \begin{macrocode}
+\ifx\tracinggroups\undefined
+% \end{macrocode}
+%
+% If we are using standard \TeX{} then |\tr@ce@n| is more or less
+% another name for |\tracingall|. The only differences are that we
+% set the above |@tracing| switch to true and reorder the
+% assignments within it somewhat so that it will output no tracing
+% information about itself. In contrast, |\tracingall| itself produces
+%
+%\begingroup
+% \renewcommand\MacroFont{\fontencoding\encodingdefault
+% \fontfamily\ttdefault
+% \fontseries\mddefault
+% \fontshape\updefault
+% \footnotesize}%
+%\begin{verbatim}
+% {vertical mode: \tracingstats}
+% {\tracingpages}
+% {\tracinglostchars}
+% {\tracingmacros}
+% {\tracingparagraphs}
+% {\tracingrestores}
+% {\errorcontextlines}
+%
+% \showoutput ->\tracingoutput \@ne \showboxbreadth \maxdimen \showboxdepth \maxd
+% imen \errorstopmode \showoverfull
+% {\tracingoutput}
+% {\showboxbreadth}
+% {\showboxdepth}
+% {\errorstopmode}
+%
+% \showoverfull ->\tracingonline \@ne
+% {\tracingonline}
+%\end{verbatim}
+%\endgroup
+%
+% \noindent Which is quite a lot given that none of it is of any
+% help to the task at hand. In contrast |\tr@ce@n| will produce
+% nothing whatsoever since the noise generating switches are set at
+% the very end.
+% \begin{macrocode}
+ \def\tr@ce@n{%
+% \end{macrocode}
+% We start by setting the |@tracing| switch to signal that tracing
+% is asked for. This is then followed by setting the various
+% tracing primitives of \TeX.
+% \begin{macrocode}
+ \@tracingtrue
+ \tracingstats\tw@
+ \tracingpages\@ne
+ \tracinglostchars\@ne
+ \tracingparagraphs\@ne
+ \errorcontextlines\maxdimen
+ \tracingoutput\@ne
+ \showboxbreadth\maxdimen
+ \showboxdepth\maxdimen
+ \errorstopmode
+ \tracingmacros\tw@
+ \tracingrestores\@ne
+ \tracingcommands\tw@
+% \end{macrocode}
+% The setting of |\tracingonline| depends on the option
+% \texttt{logonly}:
+% \begin{macrocode}
+ \tracingonline\tracingonline@p
+ }
+% \end{macrocode}
+%
+% Now what should |\conditionally@traceoff| do in this case? Should
+% it revert all settings changed by |\tr@ce@n|? It should not, since
+% our goal is to shorten the trace output, thus setting all of the
+% uninteresting values back makes the output unnecessarily
+% longer. Therefore we restrict ourself to those |\tracing...|
+% internals that really contribute to listings like the above.
+%
+% And one additional point is worth mentioning. The order in which
+% we turn the tracing internals off has effects on the output we
+% see. So what needs to be turned off first? Either
+% |\tracingrestores| or |\tracingcommands|; it makes no difference
+% which, as long as they both come first. This is because those two
+% are the only tracing switches that produce output while tracing
+% the command |\conditionally@traceoff| itself (see example on
+% page~\pageref{conttraceoffexample}).
+%
+% In principle we would need to test the |@tracing| switch to see
+% if there is anything to turn off; after all, this is the
+% conditional trace off. However this would lead to
+% extra output if we are currently tracing so we skip the test and
+% instead accept that in case we are not doing any tracing we
+% unnecessarily set the tracing primitives back to zero (i.e., the
+% value they already have).
+% \changes{v1.1c}{2003/04/30}{Turn off \cs{tracingoutput}}
+% \begin{macrocode}
+ \def\conditionally@traceoff{%
+ \tracingrestores\z@
+ \tracingcommands\z@
+ \tracingpages\z@
+ \tracingmacros\z@
+ \tracingparagraphs\z@
+ \tracingoutput\z@
+ \showboxbreadth\m@ne
+ \showboxdepth\m@ne
+% \end{macrocode}
+%
+% As remarked above there are more tracing switches set by
+% |\tr@ce@n|, however there is no point in resetting
+% |\tracinglostchars| so we leave it alone.
+% \changes{v1.1c}{2003/04/30}{Reset \cs{tracingstats} to one}
+% \begin{macrocode}
+ \tracingstats\@ne
+% \tracinglostchars\z@
+% \end{macrocode}
+% Since this is the command that only conditionally turns off
+% tracing we do not touch the |@tracing| switch. This way a
+% |\conditionally@traceon| will be able to turn the tracing on
+% again.
+% \begin{macrocode}
+ }
+% \end{macrocode}
+%
+% That covers the case for the standard \TeX{} program. If
+% |\tracingsgroups| was defined we assume that we are running with
+% \eTeX{} in extended mode.
+% \begin{macrocode}
+\else
+% \end{macrocode}
+%
+% In that case |\tr@ce@n| does more than |\tracingall|: it also
+% turns on tracing of assignments and tracing of
+% grouping.\footnote{These are my personal preference settings;
+% \eTeX{} does in fact offer some more tracing switches and perhaps
+% one or or more of them should be added here as well.}
+% To keep tracing at a minimum |\tracingassigns| should be turned
+% on last (in fact like before we disassemble |\tracingall|
+% and reorder it partially).
+% \begin{macrocode}
+ \def\tr@ce@n{%
+ \@tracingtrue
+ \tracingstats\tw@
+ \tracingpages\@ne
+ \tracinglostchars\@ne
+ \tracingparagraphs\@ne
+ \errorcontextlines\maxdimen
+ \tracingoutput\@ne
+ \showboxbreadth\maxdimen
+ \showboxdepth\maxdimen
+ \errorstopmode
+ \tracingmacros\tw@
+ \tracinggroups\@ne
+ \tracingrestores\@ne
+ \tracingcommands\tw@
+ \tracingassigns\@ne
+ \tracingonline\tracingonline@p
+ }
+% \end{macrocode}
+%
+% When turning tracing off again we now also have to turn off those
+% additional tracing switches. But what to turn off in what order?
+% Since |\tracingassigns| is quite noisy (two lines of output per
+% assignment) and the whole command expansion consists of
+% assignments, we had best start with this switch and follow it again
+% by |\tracingrestores| and |\tracingcommands|. The rest can be in
+% any order, it doesn't make a difference.
+%
+% With the same reasoning as before we omit testing for the
+% |@tracing| switch and always set the primitives back to zero.
+% \changes{v1.1c}{2003/04/30}{Turn off \cs{tracingoutput}}
+% \changes{v1.1c}{2003/04/30}{Reset \cs{tracingstats} to one}
+% \begin{macrocode}
+ \def\conditionally@traceoff{%
+ \tracingassigns\z@
+ \tracingrestores\z@
+ \tracingcommands\z@
+ \tracingpages\z@
+ \tracingmacros\z@
+ \tracingoutput\z@
+ \showboxbreadth\m@ne
+ \showboxdepth\m@ne
+ \tracingstats\@ne
+ \tracingparagraphs\z@
+ \tracinggroups\z@
+ }
+% \end{macrocode}
+%
+% This concludes the part that depends on the formatter being
+% used.
+% \begin{macrocode}
+\fi
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+%
+% \begin{macro}{\unconditionally@traceoff}
+% \changes{v1.1c}{2003/04/30}{Macro added}
+% A saved version of whatever |\conditionally@traceoff| was defined
+% to be. We need this since the latter might get disabled by
+% |\tracingall| or by the \texttt{full} option.
+% \begin{macrocode}
+\let\unconditionally@traceoff\conditionally@traceoff
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\tracingall}
+% \changes{v1.1c}{2003/04/30}{Macro added}
+% We redefine |\tracingall| to trace the same stuff than |\tr@ce@n| (i.e.,
+% more when \eTeX{} is being used) and ensure that everything gets
+% traced by disabling |\conditionally@traceoff|. And, of course,
+% |\tracingall| should always report on the terminal.
+% \begin{macrocode}
+\def\tracingall{\let\conditionally@traceoff\@empty
+ \let\tracingonline@p\@ne
+ \tr@ce@n
+}
+% \end{macrocode}
+% \end{macro}
+%
+%
+% \begin{macro}{\traceoff}
+% \begin{macro}{\conditionally@traceon}
+% Above we have defined |\conditionally@traceoff| and |\traceon| so
+% now we have to define their counterparts.
+%
+% To stop tracing unconditionally we call
+% |\unconditionally@traceoff| and then reset the |@tracing| switch
+% to false.
+% \begin{macrocode}
+\def\traceoff{\unconditionally@traceoff \@tracingfalse}
+% \end{macrocode}
+%
+% Now the |\conditionally@traceon| command will look at the
+% |@tracing| switch and if it is true it will call |\traceon| to
+% restart tracing (note that the latter command unnecessarily sets
+% the switch to true as well). The reason for the |\expandafter| is
+% to get rid of the |\fi| primitive which would otherwise show up in
+% the tracing output (and perhaps puzzle somebody).
+% \begin{macrocode}
+\def\conditionally@traceon{\if@tracing \expandafter \traceon \fi}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+%
+% The rest of the package now consists of redefinitions of certain
+% commands to make use of |\conditionally@traceoff|.
+%
+% \subsection{Taming \texttt{calc}}
+%
+% \begin{macro}{\calc@open}
+% Near the start of parsing a calc expression the macro |\calc@open|
+% is called. Since it already involves a group it is perfectly
+% suitable for our task---we don't even have to restart the tracing as
+% this is done automatically for us.
+% \begin{macrocode}
+\def\calc@open({\begingroup
+ \conditionally@traceoff
+ \aftergroup\calc@initB
+ \begingroup\aftergroup\calc@initB
+ \calc@pre@scan}
+% \end{macrocode}
+% \end{macro}
+%
+%
+% \subsection{Making NFSS less noisy}
+%
+% \begin{macro}{\define@newfont}
+% Whenever NFSS determines that the font currently asked for is not
+% already loaded, it will start looking through font definition
+% files and then load the font. This results in a very large number
+% of tracing lines which are not normally of interest (unless there
+% is a bug in that area---something we hope should have been found
+% by now). Again the code already contains its own group so we only
+% have to turn the tracing off.
+% \begin{macrocode}
+\def\define@newfont{%
+ \begingroup
+ \conditionally@traceoff
+ \let\typeout\@font@info
+ \escapechar\m@ne
+ \expandafter\expandafter\expandafter
+ \split@name\expandafter\string\font@name\@nil
+ \try@load@fontshape % try always
+ \expandafter\ifx
+ \csname\curr@fontshape\endcsname \relax
+ \wrong@fontshape\else
+ \extract@font\fi
+ \endgroup}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\frozen@everymath}
+% \begin{macro}{\frozen@everydisplay}
+% At the beginning of every math formula NFSS will check whether or
+% not the math fonts are properly set up and if not will load
+% whatever is needed. So we surround that part of the code
+% with |\conditionally@traceoff| and |\conditionally@traceon|
+% thereby avoiding all this uninteresting output.
+% \begin{macrocode}
+\frozen@everymath =
+ {\conditionally@traceoff \check@mathfonts \conditionally@traceon
+ \the\everymath}
+\frozen@everydisplay =
+ {\conditionally@traceoff \check@mathfonts \conditionally@traceon
+ \the\everydisplay}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+%
+%
+% \section{Checking for italic corrections}
+%
+% \begin{macro}{\maybe@ic@}
+% When executing |\textit| or its friends, \LaTeX{} looks ahead to
+% determine whether or not to add an italic correction at the
+% end. This involves looping through the |\nocorrlist| which
+% outputs a lot of tracing lines we are normally not interested
+% in. So we disable tracing for this part of the processing.
+% \begin{macrocode}
+\def \maybe@ic@ {%
+ \ifdim \fontdimen\@ne\font>\z@
+ \else
+ \conditionally@traceoff
+ \@tempswatrue
+ \expandafter\@tfor\expandafter\reserved@a\expandafter:\expandafter=%
+ \nocorrlist
+ \do \t@st@ic
+ \if@tempswa \sw@slant \fi
+ \conditionally@traceon
+ \fi
+}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macrocode}
+%</package>
+% \end{macrocode}
+%
+%
+% \Finale
+%
+% \endinput
diff --git a/Master/texmf-dist/source/latex/tools/varioref.dtx b/Master/texmf-dist/source/latex/tools/varioref.dtx
new file mode 100644
index 00000000000..1a30d6742d3
--- /dev/null
+++ b/Master/texmf-dist/source/latex/tools/varioref.dtx
@@ -0,0 +1,1903 @@
+% \iffalse meta-comment
+%
+% Copyright 1993 1994 1995 1996 1997 1998 1999 2000 2001 2002 2003
+% The LaTeX3 Project and any individual authors listed elsewhere
+% in this file.
+%
+% This file is part of the Standard LaTeX `Tools Bundle'.
+% -------------------------------------------------------
+%
+% It 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.3 or later is part of all distributions of LaTeX
+% version 2003/12/01 or later.
+%
+% The list of all files belonging to the LaTeX `Tools Bundle' is
+% given in the file `manifest.txt'.
+%
+% \fi
+% \iffalse
+%% Package varioref to use with LaTeX2e
+%% Copyright (C) 1992-2004 Frank Mittelbach, all rights reserved.
+%%
+%% For additions or updates to the language options please contact
+%% the author at
+%%
+%% frank.mittelbach@latex-project.org
+%%
+%% In case of bugs, please use "latexbug.tex" (category tools) to report them.
+%%
+%
+%<package>\NeedsTeXFormat{LaTeX2e}[1995/05/16]
+%<package>\ProvidesPackage{varioref}
+%<package> [2004/02/27 v1.4i package for extended references (FMi)]
+% \fi
+%
+% \CheckSum{1683}
+%% \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 \~}
+%%
+%
+%
+% \changes{v1.0a}{1993/12/06}{Upgrade to LaTeX2e}
+% \changes{v1.0g}{1994/05/27}{Use \cmd\DeclareRobustCommand}
+%
+%
+% \title{The \texttt{varioref} package\thanks{This file
+% has version number \fileversion, last
+% revised \filedate.}}
+% \author{Frank Mittelbach}
+% \date{\filedate}
+%
+% \maketitle
+%
+%
+% \begin{abstract}
+% This package defines the commands |\vref|, |\vpageref|,
+% |\vrefrange|, and |\vpagerefrange| for
+% \LaTeXe. |\vref| is similar to |\ref| but adds an additional
+% page reference, like `on the facing page' or `on page 27' whenever
+% the corresponding |\label| is not on the same page. The command
+% |\vpageref| is a variation to |\pageref| with a similar
+% functionality. The |\v...range| commands take two labels as arguments
+% and produce strings which depend on whether or not these labels
+% fall onto a single page or on different pages.
+% Generated strings are customizable so that these
+% commands are usable with various languages.
+% \end{abstract}
+%
+% \section{Introduction}
+%
+% In many cases it is helpful when refering to a figure or table to
+% put both a |\ref| and a |\pageref| command into the document
+% especially when there are one or more pages between the reference
+% and the object. Therefore some people use a command like
+% \begin{verbatim}
+% \newcommand{\fullref}[1]{\ref{#1} on page~\pageref{#1}}
+%\end{verbatim}
+% which reduces the number of key strokes, necessary to make such a
+% complete reference. But since one never knows where the referenced
+% object finally falls, using such a device may result in a page
+% reference to the current page which is disturbing and therefore
+% should be avoided.
+%
+%
+%
+% \section{The user interface}
+%
+%\DescribeMacro\vref The implementation of |\vref| below produces only
+% a |\ref| when reference and |\label| are on the same page. It will
+% additionally produce one of the strings `on the facing page', `on
+% the preceding page', or `on the following page', if label and
+% reference differ by one and it will produce both |\ref| and
+% |\pageref| when the difference is larger. The word `facing' is used
+% when label and reference both fall onto a double spread. However,
+% if a special page numbering scheme is used instead of the usual
+% arabic numbering (e.g., |\pagenumbering{roman}|) then there will be
+% no distinction between one or many pages off.
+%
+%\DescribeMacro\vpageref Sometimes one wants to refer only to page
+% number and again such a reference should normally be suppressed if
+% we are refering to the current page. For this purpose the package
+% defines the |\vpageref| command. It will produce the same strings as
+% |\vref| except that it doesn't start with the |\ref| and except that
+% it will produce the string that is saved in |\reftextcurrent| if
+% label and reference fall onto the same page. By defining
+% |\reftextcurrent| to produce ``on this page'' or something similar,
+% we can avoid that
+% \begin{verbatim}
+% ... see the example \vpageref{ex:foo} which shows ...
+%\end{verbatim}
+% comes out as ``\ldots~see the example which shows~\ldots'', which
+% could be misleading.
+%
+% You can put a space in front of |\vpageref| it will be ignored if
+% the command doesn't produce any text at all.
+%
+% But in fact |\vpageref| allows even more control. If has two
+% optional arguments. With the first one, one can specify the text
+% that should be used if label and reference fall on the same page.
+% This is very helpful if both are near to each other, so that they
+% may or may not be separated by a page break. In such a case we
+% usually know (!) whether the reference is before or after the label
+% so that we can say something like
+% \begin{verbatim}
+% ... see the example \vpageref[above]{ex:foo} which shows ...
+%\end{verbatim}
+% which will then come out as ``\ldots~see the example above which
+% shows~\ldots'' if we are still on the same page, but as ``\ldots~see
+% the example on the page before which shows~\ldots'' (or something
+% similar depending on the settings of the |\reftext..before|
+% commands) when there was a page break in the meantime. One warning
+% however, if you use |\vpageref| with the optional argument to refer
+% to a figure or table, keep in mind that depending on the float
+% placement parameters the float may show up on top of the current
+% page and therefore before the reference even if it came after it in
+% the source file.
+%
+% But maybe you prefer to say ``\ldots~see the above example'' if
+% example and reference fall onto the same page, i.e., reverse the
+% word order. In fact, in some languages the word order automatically
+% changes in that case. To allow for this variation the second
+% optional argument can be used. It specifies the text preceding the
+% generated reference if object and reference do not fall onto the
+% same page. Thus one would write
+% \begin{verbatim}
+% ... see the \vpageref[above example][example]{ex:foo}
+% which shows ...
+%\end{verbatim}
+% to achieve the desired effect.
+%
+%
+% \subsection{Additions in 1998}
+%
+% \DescribeMacro\vrefrange This command is similar to |\vref| but it
+% takes two mandatory arguments denoting a range to refer to (e.g., a
+% sequences of figures or a sequence of equations, etc.). So if
+% |fig:a| is your first figure in the sequence and |fig:c| your last
+% you can write
+%\begin{verbatim}
+% ... see figures \vrefrange{fig:a}{fig:c} ...
+%\end{verbatim}
+% which would then be formatted as
+% \begin{quote}
+% \ldots\ see figures 3.4 to 3.6 on pages 23--24 \ldots
+% \end{quote}
+% or, if they happen to all fall onto the next page, as
+% \begin{quote}
+% \ldots\ see figures 3.4 to 3.6 on the following page \ldots
+% \end{quote}
+% i.e., the command is deciding what to say depending on where the two
+% labels are placed in relation to each other; it is essentially
+% implemented using |\vpagerefrange| described below.
+% The optional argument the command may take is the text to use in case
+% both labels are placed on the current page.
+%
+%
+% \DescribeMacro\vpagerefrange This command is similar to |\vpageref|
+% but takes two mandatory arguments which are two labels denoting a
+% range. If both labels fall onto the same page, the command acts
+% exactly like |\vpageref| (with a single label), otherwise it produces
+% something like ``on pages~15--18'' (see customization possibilities
+% below). The optional argument it may take is the text to use in case
+% both labels are placed on the current page.
+
+% \DescribeMacro\vrefpagenum This macro is provided to allow the user
+% to write their own small commands which implement functions similar
+% to those provided by the two previous commands. It takes two
+% arguments: the second is a label (i.e., as used in |\label| or
+% |\ref|) and the first is an arbitrary command name (make sure you
+% use our own) that receives the page number related to this label.
+% So if you have two (or more) labels you could retrieve their page
+% numbers, compare them and then decide what to print. For example,
+% the following not very serious definition (also using the
+% \texttt{ifthen} package)
+%\begin{verbatim}
+% \newcommand\amusingversion[2]{%
+% \vrefpagenum\firstnum{#1}%
+% \vrefpagenum\secondnum{#2}%
+% the definition%
+% \ifthenelse{\equal\firstnum\secondnum}%
+% {s of \ref{#1} and \ref{#2} \vpageref{#1}}%
+% { of \ref{#1} \vpageref{#1} and of \ref{#2} \vpageref{#2}}%
+% }
+%
+% ...\amusingversion{foo}{bar}
+%\end{verbatim}
+% will print something like
+% \begin{quote}
+% \ldots the definitions of 3 and 4 on the previous page
+% \end{quote}
+% in the case both labels are on the same page but something like
+% \begin{quote}
+% \ldots the definition of 3 on the next page and of 4 on page~13
+% \end{quote}
+% in case the are on different pages.
+%
+% \subsection{Additions in 2001}
+%
+% The user commands |\vref|, |\vpageref|, and |\vpagerefrange| all
+% work by first removing any space on their left and then inserting
+% some space of their own (|\vref|, for example, a nonbreakable
+% space). That seemed like a good idea back then, but it has the
+% disadvantage that you can't use these macros in situations where you
+% definitely do not want any space before the generated text. E.g., in
+% situations like |(\vref{foo} ...)| you end up with a space after the
+% open parenthesis.
+%
+% \DescribeMacro{\vref*}
+% \DescribeMacro{\vpageref*}
+% \DescribeMacro{\vpagerefrange*}
+% Since it is to late to change the default behaviour I've added star
+% versions of the macros which do not add any space before the
+% generated text (they do nevertheless remove space at the left).
+%
+%
+% \subsection{Additions in 2002}
+%
+% \DescribeMacro\labelformat
+% A reference via |\ref| produces by default the data associated with
+% the corresponding |\label| command (typically a number); any
+% additional formatting has to be provided by the user. If, for
+% example, references to equations are always to be typeset as
+% ``equation (\textit{number})'', one has to code
+% ``\verb=equation (\ref{=\textit{key}\verb=})=''. With |\labelformat|
+% the \texttt{varioref} package offers a possibility to generate such
+% frills automatically. The command takes two arguments: the first is
+% the name of a counter and the second is its representation when
+% referenced. This means that for a successful usage, one has to know
+% the counter name being used for generating the label, though in
+% practice this should not pose a problem. The current counter number
+% is picked up as an argument.
+% Here are two examples:
+%\begin{verbatim}
+% \labelformat{section}{section~#1}
+% \labelformat{equation}{equation~(#1)}}
+%\end{verbatim}
+%
+%
+% \DescribeMacro\Vref
+% \DescribeMacro\Ref
+% A side effect of using |\labelformat| is that, depending on the
+% defined formatting, it becomes impossible to use |\ref| at the
+% beginning of a sentence (if its replacement text starts with a
+% lowercase letter). To overcome this problem \texttt{varioref}
+% introduces the commands |\Ref| and |\Vref| that behave like
+% |\ref| and |\{vref| except that they uppercase the first token
+% of the generated string.
+%
+% To make |\Ref| or |\Vref| work properly the very first token in
+% the second argument of |\labelformat| has to be a simple \textsc{ascii}
+% letter, otherwise the capitalization will fail or worse, you will end
+% up with some error messages. If you actually need something more
+% complicated in this place (e.g., an accented letter)
+% you have to explicitly surround it with braces, to
+% identify the part that needs to be capitalized. For example, for
+% figure references in the Hungarian language you might want to write
+% |\labelformat{figure}{{\'a}bra~\thefigure}|.
+%
+% \DescribeMacro\vpagerefnum
+% If you like to have |\vref| suppress the page number on pages where
+% label and reference fall onto the same page, but prefer reference to
+% page numbers otherwise then |\vpagerefnum| can be used. This macro
+% hold the current page ``number" when |\vpageref| and friends are
+% executed. Thus, by defining, for example
+%\begin{verbatim}
+%\renewcommand\reftextfaceafter {on page~\thevpagerefnum}
+%\renewcommand\reftextfacebefore{on page~\thevpagerefnum}
+%\renewcommand\reftextafter {on page~\thevpagerefnum}
+%\renewcommand\reftextbefore {on page~\thevpagerefnum}
+%\end{verbatim}
+% textual references can be suppressed.
+%
+%
+% \section{Customization}
+%
+% The package supports all options defined by the babel package to
+% translate the fixed strings into other languages than English.
+% (Some languages need updating, however.)
+% It also supports languages currently not in babel;
+% check the section on options later on.
+% You can also modify some or all of the strings by redefining the
+% following commands.
+%\DescribeMacro\reftextbefore
+%\DescribeMacro\reftextfacebefore
+%\DescribeMacro\reftextafter
+%\DescribeMacro\reftextfaceafter Backward references use
+% |\reftextbefore| if the label is on the preceding page but invisible
+% and |\reftextfacebefore| if it is one the facing page (i.e., if the
+% current page number is odd). Similarily |\reftextafter| is used
+% when the label comes on the next page but one has to turn the page
+% and |\reftextfaceafter| if it is on the following but facing page.
+%
+% In fact, |\reftextface...| is used only if the user or the document
+% class specified two-sided printing.
+%
+%\DescribeMacro\reftextfaraway Finally we have |\reftextfaraway| which
+% is used whenever label and reference differ by more than one or when
+% they aren't numeric. This macro is a bit different because it takes
+% one argument, the symbolic reference string so that one cane make
+% use of |\pageref| in its replacement text.
+%
+%
+%\DescribeMacro\vreftextvario To allow a bit random variation in the
+% generated strings one can use the command |\reftextvario| inside the
+% string macros. It takes two arguments and selects one or the other
+% for printing depending on the number of already seens |\vref| or
+% |\vpageref| commands. As an example see the definitions of
+% |\reftextbefore| etc.\ \vpageref[below]{reftextbefore}.
+%
+%
+% \subsection{Additions in 1998}
+%
+% The commands |\vrefrange| and |\vpagerefrange| produce their text
+% using two macros described below. By redefining them one can modify
+% the results to accommodate special requirements.
+%
+%
+% They both take two mandatory arguments denoting the first and the
+% last label of the range.
+%
+%
+% \DescribeMacro\reftextpagerange This macro produces text that
+% describes the page range of the two labels, e.g., the default
+% for English is ``|on pages~\pageref{#1}--\pageref{#2}}|''.
+%
+%
+% \DescribeMacro\reftextlabelrange This macro produces text that
+% describes the range of figures, tables, or whatever the labels refer
+% to, the default for English is ``|\ref{#1} to~\ref{#2}|''.
+%
+%
+% \section{Options}
+%
+% As mentioned above the package supports all standard options offered
+% by the Babel system to customize the strings produced. In addition it
+% offers the option \texttt{draft} to turn error messages into warnings
+% during development. The defaul \texttt{final} produces error message
+% when a generated string falls onto a page boundary (see next section).
+%
+%
+% \section{A few warnings}
+%
+% Defining commands like the ones described above poses some
+% interesting problems. Suppose, for example, that a generated text
+% like `on the next page' gets broken across pages. If this happens it
+% is very difficult to find an acceptable solution and in fact can
+% even result in a document that will always change from one state to
+% another (i.e., inserting one string, finding that this is wrong,
+% inserting another string on the next run which makes the first
+% string correct again, inserting \ldots). The current implementation
+% of \texttt{varioref} therefore issues an error message whenever the
+% generated text is broken across page boundaries, e.g.,
+% \begin{quote}
+% table 5 on the current \meta{page break} page
+% \end{quote}
+% would would result in an error, which needs to be resolved by the
+% user by replacing the |\vref| command with an ordinary |\ref| just
+% before the final run. This is not
+% completely satisfactory but in such case no solution really is.
+% \DescribeMacro\vrefwarning
+% During document preparation, while one is still changing the text,
+% such error messages can be turned into warnings by placing a
+% |\vrefwarning| command in the preamble. This is equivalent to
+% specifying ``draft'' as an option to the package.
+% \DescribeMacro\vrefshowerrors
+% |\vrefshowerrors| ensures that varioref stops when detecting a
+% possible loop. This is the default and equivalent to specifying
+% ``final'' as an option.
+%
+% At the end final a warning: every use of |\vref| will internally
+% generate two macro names to keep track of the string positions
+% within the document. As a result you may run out of name space or
+% main memory if you make heavy use of this macro on a small \TeX{}
+% installation.
+%\DescribeMacro\fullref For this reason the primitive command
+% |\fullref| is also provided. This command can be used whenever you
+% know for sure that label and reference can't fall onto nearby pages.
+%
+% \StopEventually{\PrintIndex\PrintChanges}
+%
+%
+% \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} program.
+% \begin{macrocode}
+%<*driver>
+\documentclass{ltxdoc}
+\usepackage{varioref}
+\GetFileInfo{varioref.sty}
+\setlength\hfuzz{1pt} % ignore slight overfulls
+\EnableCrossrefs
+%\DisableCrossrefs % Say \DisableCrossrefs if index is ready
+
+\RecordChanges % Gather update information
+%\OnlyDescription % comment out for implementation details
+\begin{document}
+ \DocInput{varioref.dtx}
+\end{document}
+%</driver>
+% \end{macrocode}
+%
+%
+% \section{The implementation}
+%
+% The main implementation idea is to generate an internal label
+% command for every |\vpageref| and compare the page reference of this
+% label with the page reference of the user-requested label. Since
+% this means one additional macro name for each use of |\vpageref| or
+% |vref| (which is implemented in terms of |\vpageref|) the memory
+% requirements of this package may be high in terms of main and macro
+% name memory. Since the information held in the internal labels is
+% used only once one could envision a different scheme if suitable
+% primitives for this kind of ``one place information'' would be
+% provided by \LaTeX. This type of data structure is planned for
+% \LaTeX3 but for the moment we have to live with the memory
+% restrictions.
+%
+% We start by checking if this file was already loaded. If not we
+% identify the current version. This is actually done at the top
+% of the file, so we comment it out here
+% \changes{v0.1h}{1993/08/15}{Small documentation changes}
+% \begin{macrocode}
+%<*package>
+%\NeedsTeXFormat{LaTeX2e}[1994/06/01]
+%\ProvidesPackage{varioref}[\filedate\space\fileversion\space
+% LaTeX2e package for extended references (FMi)]
+% \end{macrocode}
+%
+%
+% \begin{macro}{\vref@addto}
+% \changes{v1.0b}{1994/01/31}{Avoid using babel `addto}
+% \changes{v1.0b}{1994/01/31}{The babel commands are starting
+% with extras}
+% To support the use of babel we want to add the additional strings
+% to the |\extras|\meta{language} commands. Since |\addto| in the
+% current implementation of babel has a bug that does not allow to
+% use arguments containing hashmarks we do this by hand.
+% \begin{macrocode}
+\def\vref@addto#1#2{%
+ #2%
+ \@temptokena{#2}%
+ \ifx#1\undefined
+ \edef#1{\the\@temptokena}%
+ \else
+ \toks@\expandafter{#1}%
+ \edef#1{\the\toks@\the\@temptokena}%
+ \fi
+ \@temptokena{}\toks@\@temptokena
+}
+\@onlypreamble\vref@addto
+% \end{macrocode}
+% \end{macro}
+%
+%
+% \subsection{Options}
+%
+% \begin{macro}{\vref@excuse}
+% Excuse that we don't know the strings for a certain language.
+% \changes{v1.0q}{1995/04/06}{Use `PackageWarning}
+% \begin{macrocode}
+\def\vref@excuse#1{%
+ \PackageWarningNoLine{varioref}{Sorry, language `#1'
+ not supported%
+ \MessageBreak
+ in this version.
+ English strings used by default.
+ \MessageBreak
+ Please modify \protect\reftext... commands manually.%
+ \MessageBreak\MessageBreak
+ If you can suggest translations for
+ this language,%
+ \MessageBreak
+ please mail them
+ to the author of this package}}
+\@onlypreamble\vref@excuse
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\vref@stringwarning}
+% And we sometimes just don't know some strings~\ldots
+% \changes{v1.2a}{1998/08/01}{Macro added}
+% \begin{macrocode}
+\def\vref@stringwarning#1{%
+ \PackageWarningNoLine{varioref}{Sorry, there is no proper
+ translation for the string\MessageBreak
+ produced by \protect#1\on@line.\MessageBreak
+ English string used instead.\MessageBreak
+ \MessageBreak
+ If you can suggest translations for
+ the current\MessageBreak
+ language, please mail them
+ to the author of this\MessageBreak package}}
+% \end{macrocode}
+% \end{macro}
+%
+%
+% \begin{macro}{\reftextfaceafter}
+% \begin{macro}{\reftextfacebefore}
+% \begin{macro}{\reftextafter}
+% \begin{macro}{\reftextbefore}
+% \begin{macro}{\reftextcurrent}
+% \label{reftextbefore} The options do set the the macros that
+% generate the textual strings. Note, that they do not start with a
+% space, the space is already added in the main macro below.
+% \changes{v1.2a}{1998/08/22}{Added american defaults for
+% \cs{reftextpagerange} and \cs{reftextlabelrange}}
+% \changes{v1.4d}{2002/11/11}{Changed default for \cs{reftextbefore}}
+%
+% Afrikaans option contributed by Danie Els
+% (\texttt{dnjels@sun.ac.za}).
+% \changes{v1.4g}{2003/03/29}{Added afrikaans option}
+% \begin{macrocode}
+\DeclareOption{afrikaans}
+ {\vref@addto\extrasafrikaans{%
+ \def\reftextfaceafter {op die \reftextvario{regterbladsy}%
+ {bladsy langsaan}}%
+ \def\reftextfacebefore{op die \reftextvario{linkerbladsy}%
+ {bladsy langsaan}}%
+ \def\reftextafter {op die \reftextvario{volgende bladsy}%
+ {bladsy hierna}}%
+ \def\reftextbefore {op die \reftextvario{vorige bladsy}%
+ {bladsy hiervoor}}%
+ \def\reftextcurrent {op \reftextvario{hierdie}%
+ {die huidige} bladsy}%
+ \def\reftextfaraway#1{op bladsy~\pageref{#1}}%
+ \def\reftextpagerange#1#2{op bladsye~\pageref{#1}--\pageref{#2}}%
+ \def\reftextlabelrange#1#2{\ref{#1} tot~\ref{#2}}%
+ }}
+% \end{macrocode}
+%
+% \begin{macrocode}
+\DeclareOption{american}
+ {\vref@addto\extrasamerican{%
+ \def\reftextfaceafter {on the \reftextvario{facing}{next} page}%
+ \def\reftextfacebefore{on the \reftextvario{facing}{preceding}
+ page}%
+ \def\reftextafter {on the \reftextvario{following}{next} page}%
+ \def\reftextbefore {on the \reftextvario{preceding}{previous} page}%
+ \def\reftextcurrent {on \reftextvario{this}{the current} page}%
+ \def\reftextfaraway#1{on page~\pageref{#1}}%
+ \def\reftextpagerange#1#2{on pages~\pageref{#1}--\pageref{#2}}%
+ \def\reftextlabelrange#1#2{\ref{#1} to~\ref{#2}}%
+ }}
+% \end{macrocode}
+% \changes{v1.2a}{1998/11/27}{Added austrian defaults (identical to german)}
+% The austrian defaults are the same as the german ones.
+% \begin{macrocode}
+\DeclareOption{austrian}
+ {\vref@addto\extrasaustrian{%
+ \def\reftextfaceafter {auf der n\"achsten Seite}%
+ \def\reftextfacebefore{auf der vorherigen Seite}%
+ \let\reftextafter \reftextfaceafter
+ \let\reftextbefore \reftextfacebefore
+ \def\reftextcurrent {auf dieser Seite}%
+ \def\reftextfaraway#1{auf Seite~\pageref{#1}}%
+ \def\reftextpagerange#1#2{auf Seiten~\pageref{#1}--\pageref{#2}}%
+ \def\reftextlabelrange#1#2{\ref{#1} bis~\ref{#2}}%
+ }}
+% \end{macrocode}
+% \changes{v1.2d}{2000/01/11}{Added naustrian defaults (identical to german)}
+% The naustrian defaults are the same but needed for ``Neue Rechtschreibung''.
+% \begin{macrocode}
+\DeclareOption{naustrian}
+ {\vref@addto\extrasnaustrian{%
+ \def\reftextfaceafter {auf der n\"achsten Seite}%
+ \def\reftextfacebefore{auf der vorherigen Seite}%
+ \let\reftextafter \reftextfaceafter
+ \let\reftextbefore \reftextfacebefore
+ \def\reftextcurrent {auf dieser Seite}%
+ \def\reftextfaraway#1{auf Seite~\pageref{#1}}%
+ \def\reftextpagerange#1#2{auf Seiten~\pageref{#1}--\pageref{#2}}%
+ \def\reftextlabelrange#1#2{\ref{#1} bis~\ref{#2}}%
+ }}
+% \end{macrocode}
+% Text for brazil defaults was contributed by
+% Alcino Dall Igna Junior\\
+% (|adij@di.ufpe.br|).
+% \changes{v1.0g}{1994/05/18}{Brazil defaults added.}
+% \begin{macrocode}
+\DeclareOption{brazil}
+ {\vref@addto\extrabrazil{%
+ \def\reftextfaceafter {na \reftextvario{p\'agina oposta}{pr\'oxima
+ p\'agina}}%
+ \def\reftextfacebefore{na p\'agina \reftextvario{oposta}{anterior}}%
+ \def\reftextafter {na \reftextvario{p\'agina seguinte}{pr\'oxima
+ p\'agina}}%
+ \def\reftextbefore{na p\'agina \reftextvario{anterior}{precedente}}%
+ \def\reftextcurrent {\reftextvario{nesta p\'agina}{na p\'agina
+ corrente}}%
+ \def\reftextfaraway#1{na p\'agina~\pageref{#1}}%
+ \def\reftextpagerange#1#2{\vref@stringwarning\reftextpagerange
+ on pages~\pageref{#1}--\pageref{#2}}%
+ \def\reftextlabelrange#1#2{\vref@stringwarning\reflabelpagerange
+ \ref{#1} to~\ref{#2}}%
+ }}
+% \end{macrocode}
+% Text for Breton defaults was contributed by
+% Christian ROLLAND\\
+% (|Christian.Rolland@univ-brest.fr|).
+% \changes{v1.0o}{1994/09/27}{Added defaults for breton}
+% \begin{macrocode}
+\DeclareOption{breton}
+ {\vref@excuse{breton}%
+ \vref@addto\extrasbreton{%
+ \def\reftextfaceafter {war ar bajenn \reftextvario{a-dal}{da heul}}%
+ \def\reftextfacebefore{war ar bajenn \reftextvario{a-dal}{a-raok}}%
+ \def\reftextafter {war ar bajenn da heul}%
+ \def\reftextbefore {war ar bajenn a-raok}%
+ \def\reftextcurrent {war ar \reftextvario{bajenn-ma\~n}%
+ {bajenn war-wel}}%
+ \def\reftextfaraway#1{war ar bajenn~\pageref{#1}}%
+ \def\reftextpagerange#1#2{\vref@stringwarning\reftextpagerange
+ on pages~\pageref{#1}--\pageref{#2}}%
+ \def\reftextlabelrange#1#2{\vref@stringwarning\reflabelpagerange
+ \ref{#1} to~\ref{#2}}%
+ }}
+% \end{macrocode}
+% Text for catalan defaults was contributed by Robert Fuster\\
+% (\verb=rfuster@mat.upv.es=).
+% \changes{v1.1c}{1997/06/12}{Added defaults for catalan}
+% \changes{v1.2g}{2000/08/22}{Updated defaults for catalan}
+% \begin{macrocode}
+\DeclareOption{catalan}
+ {\vref@addto\extrascatalan{%
+ \def\reftextfaceafter {a la p\`agina seg\"uent}%
+ \def\reftextfacebefore{a la p\`agina anterior}%
+ \let\reftextafter \reftextfaceafter
+ \let\reftextbefore \reftextfacebefore
+ \def\reftextcurrent {en aquesta p\`agina}%
+ \def\reftextfaraway#1{a la p\`agina~\pageref{#1}}%
+ \def\reftextpagerange#1#2{a les
+ p\`agines~\pageref{#1}--\pageref{#2}}%
+ \def\reftextlabelrange#1#2{\ref{#1} a~\ref{#2}}%
+ }}
+\DeclareOption{croatian}
+ {\vref@excuse{croatian}%
+ \vref@addto\extrascroatian{%
+ \def\reftextfaceafter {on the \reftextvario{facing}{next} page}%
+ \def\reftextfacebefore{on the \reftextvario{facing}{preceding}
+ page}%
+ \def\reftextafter {on the \reftextvario{following}{next} page}%
+ \def\reftextbefore {on the \reftextvario{preceding}{previous} page}%
+ \def\reftextcurrent {on \reftextvario{this}{the current} page}%
+ \def\reftextfaraway#1{on page~\pageref{#1}}%
+ \def\reftextpagerange#1#2{on pages~\pageref{#1}--\pageref{#2}}%
+ \def\reftextlabelrange#1#2{\ref{#1} to~\ref{#2}}%
+ }}
+% \end{macrocode}
+% Defaults for the Czech option provided by Milan Vancura
+% \verb=<milan@suse.cz>=.
+% \changes{v1.2e}{2000/04/04}{Added czech defaults}
+% \begin{macrocode}
+\DeclareOption{czech}
+ {%\vref@excuse{czech}%
+ \vref@addto\extrasczech{%
+ \def\reftextfaceafter {na n\'a\-sle\-du\-j\'\i c\'\i\ stran\v{e}}%
+ \def\reftextfacebefore{na p\v{r}ed\-choz\'\i\ stran\v{e}}%
+ \def\reftextafter {na n\'a\-sle\-du\-j\'\i c\'\i\ stran\v{e}}%
+ \def\reftextbefore {na p\v{r}ed\-choz\'\i\ stran\v{e}}%
+ \def\reftextcurrent {na t\'eto stran\v{e}}%
+ \def\reftextfaraway#1{na stran\v{e}~\pageref{#1}}%
+ \def\reftextpagerange#1#2{na stran\'ach~\pageref{#1}\--\pageref{#2}}%
+ \def\reftextlabelrange#1#2{\ref{#1} a\v{z}~\ref{#2}}%
+ }}
+% \end{macrocode}
+% Defaults for Danish provided by Torsten Martinsen
+% (\verb=tmar91@kom.auc.dk=). Further defaults by Ole Laursen
+% (\verb=olau@hardworking.dk=).
+% \changes{v1.0n}{1994/09/25}{Added Danish defaults}
+% \changes{v1.2h}{2000/12/30}{Updates to Danish defaults}
+% \begin{macrocode}
+\DeclareOption{danish}
+ {\vref@addto\extrasdanish{%
+ \def\reftextfaceafter {p\aa{} \reftextvario{modst\aa ende}%
+ {n\ae ste} side}%
+ \def\reftextfacebefore{p\aa{} \reftextvario{modst\aa ende}%
+ {forrige} side}%
+ \def\reftextafter {p\aa{} \reftextvario{den f\o lgende}%
+ {n\ae ste} side}%
+ \def\reftextbefore {p\aa{} \reftextvario{forrige side}
+ {foreg\aa ende side}}%
+ \def\reftextcurrent {p\aa{} denne side}%
+ \def\reftextfaraway#1{p\aa{} side~\pageref{#1}}%
+ \def\reftextpagerange#1#2{p\aa{} side~\pageref{#1}--\pageref{#2}}%
+ \def\reftextlabelrange#1#2{\ref{#1} til~\ref{#2}}%
+ }}
+% \end{macrocode}
+% Default string for dutch have been contributed by Frank Poppe
+% (\verb=POPPE@SWOV.NL=).
+% This option currently supports one additional string macro
+% |\refpagename| so that you can easily change to |bladzijde|
+% instead of |pagina| if you prefer this word for ``page''.
+% However, I will not guarantee that this will survive future
+% versions of this package, so use it on your own risk (you can
+% always update the full strings to be on the safe side).
+% \changes{v1.0l}{1994/07/07}{Added dutch defaults}
+% \changes{v1.2a}{1998/08/22}{Added dutch defaults for
+% \cs{reftextpagerange} and \cs{reftextlabelrange}}
+% \begin{macrocode}
+\DeclareOption{dutch}
+ {\vref@addto\extrasdutch{%
+ \def\refpagename{pagina}%
+ \def\reftextfaceafter {op de \reftextvario{rechter \refpagename}%
+ {\refpagename\ hiernaast}}%
+ \def\reftextfacebefore{op de \reftextvario{linker \refpagename}%
+ {\refpagename\ hiernaast}}%
+ \def\reftextafter {op de \reftextvario{volgende \refpagename}%
+ {\refpagename\ hierna}}%
+ \def\reftextbefore {op de \reftextvario{vorige \refpagename}%
+ {\refpagename\ hiervoor}}%
+ \def\reftextcurrent {op deze \refpagename}%
+ \def\reftextfaraway#1{op \refpagename~\pageref{#1}}%
+% \end{macrocode}
+% Concerning the next defaults I received the following comment by
+% Frederik Fouvry \texttt{<fouvry@coli.uni-sb.de>}:
+% ``In the Dutch options (where I can exert a proper language
+% judgement ;-), `t/m' is not used in formal (scientific) texts. I
+% would either use `--' or `tot en met' (the abbreviation written
+% out). ''
+% \changes{v1.4d}{2002/11/11}{Changed default for \cs{reftextlabelrange}}
+% \begin{macrocode}
+ \def\reftextpagerange#1#2{op pagina's~\pageref{#1}--\pageref{#2}}%
+ \def\reftextlabelrange#1#2{\ref#1--\ref{#2}}%
+ }}
+% \end{macrocode}
+% \changes{v1.2a}{1998/08/22}{Added english defaults for
+% \cs{reftextpagerange} and \cs{reftextlabelrange}}
+% \changes{v1.4d}{2002/11/11}{Changed default for \cs{reftextbefore}}
+% \begin{macrocode}
+\DeclareOption{english}
+ {\vref@addto\extrasenglish{%
+ \def\reftextfaceafter {on the \reftextvario{facing}{next} page}%
+ \def\reftextfacebefore{on the \reftextvario{facing}{preceding}
+ page}%
+ \def\reftextafter {on the \reftextvario{following}{next} page}%
+ \def\reftextbefore {on the \reftextvario{preceding}{previous} page}%
+ \def\reftextcurrent {on \reftextvario{this}{the current} page}%
+ \def\reftextfaraway#1{on page~\pageref{#1}}%
+ \def\reftextpagerange#1#2{on pages~\pageref{#1}--\pageref{#2}}%
+ \def\reftextlabelrange#1#2{\ref{#1} to~\ref{#2}}%
+ }}
+\DeclareOption{esperanto}
+ {\vref@excuse{esperanto}%
+ \vref@addto\extrasesperanto{%
+ \def\reftextfaceafter {on the \reftextvario{facing}{next} page}%
+ \def\reftextfacebefore{on the \reftextvario{facing}{preceding}
+ page}%
+ \def\reftextafter {on the \reftextvario{following}{next} page}%
+ \def\reftextbefore {on the \reftextvario{preceding}{previous} page}%
+ \def\reftextcurrent {on \reftextvario{this}{the current} page}%
+ \def\reftextfaraway#1{on page~\pageref{#1}}%
+ \def\reftextpagerange#1#2{on pages~\pageref{#1}--\pageref{#2}}%
+ \def\reftextlabelrange#1#2{\ref{#1} to~\ref{#2}}%
+ }}
+% \end{macrocode}
+% The finnish strings were suggested by Matti Rintala
+% (\verb=bitti@cs.tut.fi=).
+% \changes{v1.0m}{1994/09/23}{Added finnish strings}
+% \begin{macrocode}
+\DeclareOption{finnish}
+ {\vref@addto\extrasfinnish{%
+ \def\reftextfaceafter {\reftextvario{viereisell\"a}%
+ {seuraavalla} sivulla}%
+ \def\reftextfacebefore{\reftextvario{viereisell\"a}%
+ {edellisell\"a} sivulla}%
+ \def\reftextafter {seuraavalla sivulla}%
+ \def\reftextbefore {edellisell\"a sivulla}%
+ \def\reftextcurrent {t\"all\"a sivulla}%
+ \def\reftextfaraway#1{sivulla~\pageref{#1}}%
+ \def\reftextpagerange#1#2{\vref@stringwarning\reftextpagerange
+ on pages~\pageref{#1}--\pageref{#2}}%
+ \def\reftextlabelrange#1#2{\vref@stringwarning\reflabelpagerange
+ \ref{#1} to~\ref{#2}}%
+ }}
+% \end{macrocode}
+% French defaults are provided by Daniel Flippo
+% (\verb=Daniel.Flipo@univ-lille1.fr=).
+% \changes{v1.0j}{1994/06/21}{Added french defaults}
+% \changes{v1.2a}{1998/08/22}{Added french defaults for
+% \cs{reftextpagerange} and \cs{reftextlabelrange}}
+% \begin{macrocode}
+\DeclareOption{french}
+ {\vref@addto\extrasfrench{%
+ \def\reftextfaceafter {page \reftextvario{ci-contre}{suivante}}%
+ \def\reftextfacebefore{page \reftextvario{ci-contre}%
+ {pr\'ec\'edente}}%
+ \def\reftextafter {page suivante}%
+ \def\reftextbefore {page pr\'ec\'edente}%
+ \def\reftextcurrent {de la pr\'esente page}%
+ \def\reftextfaraway#1{page~\pageref{#1}}%
+ \def\reftextpagerange#1#2{pages~\pageref{#1}--\pageref{#2}}%
+ \def\reftextlabelrange#1#2{\ref{#1} \`a~\ref{#2}}%
+ }}
+% \end{macrocode}
+% Galician defaults are provided by Matthias Moebius\\
+% (\texttt{Matthias.Moebius@uni-konstanz.de}).
+% \changes{v1.1f}{1998/04/25}{Added galician defaults}
+% \begin{macrocode}
+\DeclareOption{galician}
+ {\vref@excuse{galician}%
+ \vref@addto\extrasgalician{%
+ \def\reftextfaceafter {na seguinte p\'axina}%
+ \def\reftextfacebefore{na p\'agina anterior}%
+ \let\reftextafter \reftextfaceafter
+ \let\reftextbefore \reftextfacebefore
+ \def\reftextcurrent {nesta p\'axina}%
+ \def\reftextfaraway#1{na p\'axina~\pageref{#1}}%
+ \def\reftextpagerange#1#2{\vref@stringwarning\reftextpagerange
+ on pages~\pageref{#1}--\pageref{#2}}%
+ \def\reftextlabelrange#1#2{\vref@stringwarning\reflabelpagerange
+ \ref{#1} to~\ref{#2}}%
+ }}
+% \end{macrocode}
+% There are no good variants for German (I think and still think but
+% this is a matter of taste :-).
+% \changes{v1.0b}{1994/01/31}{Replace in incorrect `def by `let}
+% The following definitions were recently suggested to me but since
+% the original are in for a long time i don't want to change them
+% now since that could make a lot of documents change their formatting.
+% If you fancy them, add a redefinition of the corresponding macro(s)
+% to the preamble of your document.
+%\begin{verbatim}
+% \def\reftextfaceafter {auf der \reftextvario
+% {gegen\"uberliegenden}{anderen} Seite}%
+% \def\reftextfacebefore {auf der \reftextvario
+% {gegen\"uberliegenden}{anderen} Seite}%
+% \def\reftextafter {auf der \reftextvario
+% {n\"achsten}{folgenden} Seite}%
+% \def\reftextbefore {auf der \reftextvario
+% {vorigen}{vorhergehenden} Seite}%
+% \def\reftextcurrent {\reftextvario
+% {auf dieser}{diese} Seite}%
+%\end{verbatim}
+% \begin{macrocode}
+\DeclareOption{german}
+ {\vref@addto\extrasgerman{%
+ \def\reftextfaceafter {auf der n\"achsten Seite}%
+ \def\reftextfacebefore{auf der vorherigen Seite}%
+ \let\reftextafter \reftextfaceafter
+ \let\reftextbefore \reftextfacebefore
+ \def\reftextcurrent {auf dieser Seite}%
+ \def\reftextfaraway#1{auf Seite~\pageref{#1}}%
+ \def\reftextpagerange#1#2{auf Seiten~\pageref{#1}--\pageref{#2}}%
+ \def\reftextlabelrange#1#2{\ref{#1} bis~\ref{#2}}%
+ }}
+% \end{macrocode}
+% \changes{v1.2d}{2000/01/11}{Added ngerman defaults (identical to german)}
+% The ngerman defaults are the same but needed for ``Neue Rechtschreibung''
+% (i.e., a different set of hyphenation patterns).
+% \begin{macrocode}
+\DeclareOption{ngerman}
+ {\vref@addto\extrasngerman{%
+ \def\reftextfaceafter {auf der n\"achsten Seite}%
+ \def\reftextfacebefore{auf der vorherigen Seite}%
+ \let\reftextafter \reftextfaceafter
+ \let\reftextbefore \reftextfacebefore
+ \def\reftextcurrent {auf dieser Seite}%
+ \def\reftextfaraway#1{auf Seite~\pageref{#1}}%
+ \def\reftextpagerange#1#2{auf Seiten~\pageref{#1}--\pageref{#2}}%
+ \def\reftextlabelrange#1#2{\ref{#1} bis~\ref{#2}}%
+ }}
+% \end{macrocode}
+% Defaults for greek suggested by Apostolos Syropoulos\\
+% (\verb=apostolo@obelix.ee.duth.gr=).
+% \changes{v1.2a}{1998/08/22}{Added defaults for greek}
+% \begin{macrocode}
+\DeclareOption{greek}
+ {\vref@addto\extrasgreek{%
+ \def\reftextfaceafter {sthn \reftextvario{paro'usa}%
+ {ep'omenh} sel'ida}%
+ \def\reftextfacebefore{sthn \reftextvario{paro'usa}{prohgo'umenh}
+ sel'ida}%
+ \def\reftextafter {sthn ep'omenh sel'ida}%
+ \def\reftextbefore {sthn prohgo'umenh sel'ida}%
+ \def\reftextcurrent {s'' aut'h th sel'ida}%
+ \def\reftextfaraway#1{sth sel'ida\nobreakspace\pageref{#1}}%
+ \def\reftextpagerange#1#2{stis sel'ides\nobreakspace
+ \pageref{#1}---\pageref{#2}}%
+ \def\reftextlabelrange#1#2{\ref{#1} ws\nobreakspace\ref{#2}}%
+ }}
+% \end{macrocode}
+% Defaults for Italian suggested by Giovanni Pensa
+% (\verb=pensa@dsi.unimi.it=) with i{\TeX}nici.
+% \changes{v1.1b}{1995/10/19}{Added defaults for Italian}
+% \changes{v1.2a}{1998/08/22}{Removed incorrect warning}
+% \begin{macrocode}
+\DeclareOption{italian}
+ {\vref@addto\extrasitalian{%
+ \def\reftextfaceafter {\reftextvario{a fronte}%
+ {nella pagina successiva}}%
+ \def\reftextfacebefore{\reftextvario{a fronte}%
+ {nella pagina precedente}}%
+ \def\reftextafter {nella pagina \reftextvario{seguente}%
+ {successiva}}%
+ \def\reftextbefore {nella pagina precedente}%
+ \def\reftextcurrent {in questa pagina}%
+ \def\reftextfaraway#1{a pagina~\pageref{#1}}%
+ \def\reftextpagerange#1#2{\vref@stringwarning\reftextpagerange
+ on pages~\pageref{#1}--\pageref{#2}}%
+ \def\reftextlabelrange#1#2{\vref@stringwarning\reflabelpagerange
+ \ref{#1} to~\ref{#2}}%
+ }}
+% \end{macrocode}
+% Defaults for Hungarian by Jeff Goldberg
+% (\verb=jeffrey@goldmark.org=).
+% There is a problem with the use of the definite article
+% \textit{a} or \textit{az} in Hungarian before expansions
+% of |\vref| or |\ref|. The problem is that the the word
+% should be \textit{az} if the number following would begin with
+% a vowel if spelled out, and \textit{a} if the number would begin
+% with a consonant.
+%
+% The option assumes that there is a command |\aza| defined which
+% helps resolving this problem.\footnote{This information is actually quite
+% old but unfortunately never made it into varioref. In case any work
+% has been undertaken to resolve this please inform the author about it.}
+% \changes{v1.2a}{1998/08/22}{Added defaults for magyar}
+% \begin{macrocode}
+\DeclareOption{magyar}
+ {\vref@addto\extrasmagyar{%
+ \def\reftextfaceafter {a k\"o\-vet\-kez\H{o} ol\-da\-lon}%
+ \def\reftextfacebefore{az el\H{o}\-z\H{o} ol\-da\-lon}%
+ \def\reftextfaceafter {\reftextvario{a t\'ul\-ol\-da\-lon}%
+ {a k\"o\-vet\-kez\H{o} ol\-da\-lon}}%
+ \def\reftextfacebefore{\reftextvario{a t\'ul\-ol\-da\-lon}%
+ {az el\H{o}\-z\H{o} ol\-da\-lon}}%
+ \def\reftextcurrent {ezen az ol\-da\-lon}%
+% \end{macrocode}
+% The following suggested patch has not been added yet (pending changes
+% in babel system).
+%\begin{verbatim}
+% \def\reftextfaraway#1{a~\csname @@magyar@az@lowxu\endcsname{\pageref{#1}}.~ol\-da\-lon}%
+% \def\reftextpagerange#1#2{a~\csname @@magyar@az@lowxu\endcsname{\pageref{#1}}%
+% --\pageref{#2}.~ol\-da\-la\-kon}%
+% \def\reftextlabelrange#1#2{{}\csname @@magyar@told\endcsname\ref{#1}+tol
+% \ref{#2}-ig}% Dat: `{}' is here for anti-\capitalize
+%\end{verbatim}
+% \begin{macrocode}
+ \def\reftextfaraway#1{\aza{\pageref{#1}} \pageref{#1}.~ol\-da\-lon}%
+ \def\reftextpagerange#1#2{\vref@stringwarning\reftextpagerange
+ on pages~\pageref{#1}--\pageref{#2}}%
+ \def\reftextlabelrange#1#2{\vref@stringwarning\reflabelpagerange
+ \ref{#1} to~\ref{#2}}%
+ }%
+% \end{macrocode}
+% The |\AtBeginDocument| needs to be executed when the option is
+% processed and not inside the babel interface.
+% \changes{v1.4i}{2004/02/27}{Moved \cs{AtBeginDocument}}
+% \begin{macrocode}
+ \AtBeginDocument{\providecommand\aza[1]{a/az%
+ \PackageError{varioref}{%
+ Proper definition for command \noexpand\aza missing}%
+ {You need to (re)define the command \noexpand\aza that
+ takes one argument (a number or a \noexpand\pageref command)
+ and produces the string `a' or `az' depending on the argument
+ value. It should also accept an optional argument (default `l')
+ to denote whether or not the string should be lowercase or
+ uppercase.}}}%
+ }
+% \end{macrocode}
+% The Norwegian and `nynorsk' translations have been provided by
+% Dag F Langmyhr \verb=<dag@ifi.uio.no>= and Karl Ove Hufthammer
+% \verb=<huftis@bigfoot.com>=.
+% \changes{v1.0q}{1995/04/06}{Added defaults for norsk}
+% \changes{v1.0q}{1995/04/06}{Added defaults for nynorsk}
+% \changes{v1.2a}{1998/08/22}{Updated defaults for norsk}
+% \changes{v1.2a}{1998/08/22}{Updated defaults for nynorsk}
+% \changes{v1.2a}{1998/08/22}{Added norsk defaults for
+% \cs{reftextpagerange} and \cs{reftextlabelrange}}
+% \changes{v1.2a}{1998/08/22}{Added nynorsk defaults for
+% \cs{reftextpagerange} and \cs{reftextlabelrange}}
+% \changes{v1.2i}{2001/01/12}{Updated nynorsk defaults}
+% \begin{macrocode}
+\DeclareOption{norsk}
+ {\vref@addto\extrasnorsk{%
+ \def\reftextfaceafter {p\aa{} neste side}%
+ \def\reftextfacebefore{p\aa{} forrige side}%
+ \def\reftextafter {p\aa{} neste side}%
+ \def\reftextbefore {p\aa{} forrige side}%
+ \def\reftextcurrent {p\aa{} denne siden}%
+ \def\reftextfaraway#1{p\aa{} side~\pageref{#1}}%
+ \def\reftextpagerange#1#2{p\aa{} side~\pageref{#1}--\pageref{#2}}%
+ \def\reftextlabelrange#1#2{\ref{#1} til~\ref{#2}}%
+ }}
+\DeclareOption{nynorsk}
+ {\vref@addto\extrasnynorsk{%
+ \def\reftextfaceafter {p\aa{} neste side}%
+ \def\reftextfacebefore{p\aa{} f\o{}rre side}%
+ \def\reftextafter {p\aa{} neste side}%
+ \def\reftextbefore {p\aa{} f\o{}rre side}%
+ \def\reftextcurrent {p\aa{} denne sida}%
+ \def\reftextfaraway#1{p\aa{} side~\pageref{#1}}%
+ \def\reftextpagerange#1#2{p\aa{} side~\pageref{#1}--\pageref{#2}}%
+ \def\reftextlabelrange#1#2{\ref{#1} til~\ref{#2}}%
+ }}
+% \end{macrocode}
+% The polish translations have been provided by
+% Tomasz Michniewski \\
+% \verb=<tomekm@ias.wat.waw.pl>=.
+% The use of the command \verb=\eob= and \verb=aob= etc.\
+% requires appropriate definitions as provided, for example, by
+% the babel system. This should probably be handled differently
+% but it would require modifications in babel's language support.
+% \changes{v1.1d}{1997/12/06}{Added defaults for polish}
+% \changes{v1.2a}{1998/08/22}{Added polish defaults for
+% \cs{reftextpagerange} and \cs{reftextlabelrange}}
+% \begin{macrocode}
+\DeclareOption{polish}
+ {\vref@addto\extraspolish{%
+ \def\reftextfaceafter {na \reftextvario{s\aob{}siedniej}%
+ {nast\eob{}pnej} stronie}%
+ \def\reftextfacebefore{na \reftextvario{s\aob{}siedniej}%
+ {poprzedniej} stronie}%
+ \def\reftextafter {na nast\eob{}pnej stronie}%
+ \def\reftextbefore {na poprzedniej stronie}%
+ \def\reftextcurrent {na \reftextvario{tej
+ samej}{bie\zkb{}\aob{}cej} stronie}%
+ \def\reftextfaraway#1{na \pageref{#1}~stronie}%
+ \def\reftextpagerange#1#2{na stronach~\pageref{#1}--\pageref{#2}}%
+ \def\reftextlabelrange#1#2{od~\ref{#1} do~\ref{#2}}%
+ }}
+% \end{macrocode}
+% The portuguese default text has been provided by
+% Jos\'e Carlos Oliveira Santos \verb=jcsantos@fc.up.pt=.
+% \changes{v1.2b}{1999/11/25}{Added portuguese defaults}
+% \changes{v1.2c}{1999/12/02}{Added more portuguese defaults}
+% \begin{macrocode}
+\DeclareOption{portuges}
+ {\vref@addto\extraportuges{%
+ \def\reftextfaceafter {na \reftextvario{p\'agina ao lado}{pr\'oxima
+ p\'agina}}%
+ \def\reftextfacebefore{na p\'agina \reftextvario{ao lado}{anterior}}%
+ \def\reftextafter {na \reftextvario{p\'agina seguinte}{pr\'oxima
+ p\'agina}}%
+ \def\reftextbefore{na p\'agina \reftextvario{anterior}{precedente}}%
+ \def\reftextcurrent {nesta p\'agina}%
+ \def\reftextfaraway#1{na p\'agina~\pageref{#1}}%
+ \def\reftextpagerange#1#2{nas p\'aginas~\pageref{#1}--\pageref{#2}}%
+ \def\reftextlabelrange#1#2{\ref{#1} a~\ref{#2}}%
+ }}
+\DeclareOption{romanian}
+ {\vref@excuse{romanian}%
+ \vref@addto\extrasromanian{%
+ \def\reftextfaceafter {on the \reftextvario{facing}{next} page}%
+ \def\reftextfacebefore{on the \reftextvario{facing}{preceding}
+ page}%
+ \def\reftextafter {on the \reftextvario{following}{next} page}%
+ \def\reftextbefore {on the \reftextvario{preceding}{previous} page}%
+ \def\reftextcurrent {on \reftextvario{this}{the current} page}%
+ \def\reftextfaraway#1{on page~\pageref{#1}}%
+ \def\reftextpagerange#1#2{on pages~\pageref{#1}--\pageref{#2}}%
+ \def\reftextlabelrange#1#2{\ref{#1} to~\ref{#2}}%
+ }}
+% \end{macrocode}
+% The text for russian was taken from the book in Russian by
+% I.~A.~Kotelnikov and P.~Z.~Chebotaev, and adapted
+% to the encoding-independent form by Vladimir Volovich
+% (\verb=vvv@vsu.ru=).
+% \changes{v1.2a}{1998/11/23}{Added russion strings}
+% \changes{v1.2a}{1998/11/24}{Added defaults for
+% \cs{reftextpagerange} and \cs{reftextlabelrange}}
+% \begin{macrocode}
+\DeclareOption{russian}
+ {\vref@addto\extrasrussian{%
+ \def\reftextfaceafter{\cyrn\cyra\ \reftextvario{\cyrp\cyrr\cyro
+ \cyrt\cyri\cyrv\cyro\cyrp\cyro\cyrl\cyro\cyrzh\cyrn\cyro\cyrishrt}%
+ {\cyrs\cyrl\cyre\cyrd\cyru\cyryu\cyrshch\cyre\cyrishrt}\ \cyrs\cyrt
+ \cyrr\cyra\cyrn\cyri\cyrc\cyre}%
+ \def\reftextfacebefore{\cyrn\cyra\ \reftextvario{\cyrp\cyrr\cyro
+ \cyrt\cyri\cyrv\cyro\cyrp\cyro\cyrl\cyro\cyrzh\cyrn\cyro\cyrishrt}%
+ {\cyrp\cyrr\cyre\cyrd\cyrery\cyrd\cyru\cyrshch\cyre\cyrishrt}\
+ \cyrs\cyrt\cyrr\cyra\cyrn\cyri\cyrc\cyre}%
+ \def\reftextafter{\cyrn\cyra\ \cyrs\cyrl\cyre\cyrd\cyru\cyryu\cyrshch
+ \cyre\cyrishrt\ \cyrs\cyrt\cyrr\cyra\cyrn\cyri\cyrc\cyre}%
+ \def\reftextbefore{\cyrn\cyra\ \reftextvario{\cyrp\cyrr\cyre\cyrd
+ \cyrsh\cyre\cyrs\cyrt\cyrv\cyru\cyryu\cyrshch\cyre\cyrishrt}%
+ {\cyrp\cyrr\cyre\cyrd\cyrery\cyrd\cyru\cyrshch\cyre\cyrishrt}%
+ \ \cyrs\cyrt\cyrr\cyra\cyrn\cyri\cyrc\cyre}%
+ \def\reftextcurrent{\cyrn\cyra\ \reftextvario{\cyrerev\cyrt\cyro
+ \cyrishrt}{\cyrd\cyra\cyrn\cyrn\cyro\cyrishrt}\ \cyrs\cyrt\cyrr
+ \cyra\cyrn\cyri\cyrc\cyre}%
+ \def\reftextfaraway#1{\cyrn\cyra\ \cyrs.~\pageref{#1}}%
+ \def\reftextpagerange#1#2{\cyrn\cyra\ \cyrs\cyrt\cyrr\cyra\cyrn
+ \cyri\cyrc\cyra\cyrh~\pageref{#1}--\pageref{#2}}%
+ \def\reftextlabelrange#1#2{\cyrs~\ref{#1}\ \cyrp\cyro~\ref{#2}}%
+ }}
+% \end{macrocode}
+% The text for slovak defaults was contributed by Miroslav Sedivy\\
+% (\verb=<miro@slovensko.com>=).
+% \changes{v1.4b}{2002/03/11}{Contributed defaults added}
+% \begin{macrocode}
+\DeclareOption{slovak}
+ {\vref@addto\extrasslovak{%
+ \def\reftextfaceafter {na \reftextvario{proti\v lahlej}%
+ {nasleduj\'ucej} strane}%
+ \def\reftextfacebefore{na \reftextvario{proti\v lahlej}%
+ {predch\'adzaj\'ucej} strane}%
+ \def\reftextafter {na \reftextvario{nasleduj\'ucej}%
+ {\v dal\v sej} strane}%
+ \def\reftextbefore {na \reftextvario{predch\'adzaj\'ucej}%
+ {predo\v slej} strane}%
+ \def\reftextcurrent {na tejto strane}%
+ \def\reftextfaraway#1{na strane~\pageref{#1}}%
+ \def\reftextpagerange#1#2{na stran\'ach~\pageref{#1}--\pageref{#2}}%
+ \def\reftextlabelrange#1#2{\ref{#1} a\v z~\ref{#2}}%
+ }}
+% \end{macrocode}
+% The text for slovene defaults was contributed by Roman Maurer\\
+% (\verb=<roman.maurer@amis.net>=).
+% \changes{v1.4a}{2002/03/05}{Contributed defaults added}
+% \begin{macrocode}
+\DeclareOption{slovene}
+ {\vref@addto\extrasslovene{%
+ \def\reftextfaceafter {na naslednji strani}%
+ \def\reftextfacebefore{na prej\v{s}nji strani}%
+ \let\reftextafter \reftextfaceafter
+ \let\reftextbefore \reftextfacebefore
+ \def\reftextcurrent {na \reftextvario{tej}{trenutni} strani}%
+ \def\reftextfaraway#1{na strani~\pageref{#1}}%
+ \def\reftextpagerange#1#2{na straneh~\pageref{#1}--\pageref{#2}}%
+ \def\reftextlabelrange#1#2{od~\ref{#1} do~\ref{#2}}%
+ }}
+% \end{macrocode}
+% Text for spanish defaults was contributed by Julio Sanchez
+% (\verb=jsanchez@gmv.es=) and Fernando Dobladez (\verb=<ferd@fuego.com>=).
+% \changes{v1.0f}{1994/03/16}{Inserted missing hash mark}
+% \changes{v1.0k}{1994/06/05}{Corrected misspelled cmd `extrasspanish}
+% \changes{v1.4a}{2002/03/05}{Missing defaults added}
+% \begin{macrocode}
+\DeclareOption{spanish}
+ {\vref@addto\extrasspanish{%
+ \def\reftextfaceafter {en la p\'agina siguiente}%
+ \def\reftextfacebefore{en la p\'agina anterior}%
+ \let\reftextafter \reftextfaceafter
+ \let\reftextbefore \reftextfacebefore
+ \def\reftextcurrent {en esta p\'agina}%
+ \def\reftextfaraway#1{en la p\'agina~\pageref{#1}}%
+ \def\reftextpagerange#1#2{en las p\'aginas~\pageref{#1}%
+ --\pageref{#2}}%
+ \def\reftextlabelrange#1#2{\ref{#1} a~\ref{#2}}%
+ }}
+% \end{macrocode}
+% The text for swedish was contributed by Mats Dahlgren
+% (\verb=matsd@sssk.se=).
+% \changes{v1.0p}{1995/01/10}{Added swedish strings}
+% \changes{v1.2a}{1998/08/22}{Added swedish defaults for
+% \cs{reftextpagerange} and \cs{reftextlabelrange}}
+% \begin{macrocode}
+\DeclareOption{swedish}
+ {\vref@addto\extrasswedish{%
+ \def\reftextfaceafter {p\aa\ \reftextvario{motst\aa ende}%
+ {n\"{a}sta} sida}%
+ \def\reftextfacebefore{p\aa\ \reftextvario{motst\aa ende}%
+ {f\"{o}reg\aa ende} sida}%
+ \def\reftextafter {p\aa\ \reftextvario{f\"{o}ljande}%
+ {n\"{a}sta} sida}%
+ \def\reftextbefore {p\aa\ f\"{o}reg\aa ende sida}%
+ \def\reftextcurrent {p\aa\ denna sida}%
+ \def\reftextfaraway#1{p\aa\ sidan~\pageref{#1}}%
+ \def\reftextpagerange#1#2{p\aa\
+ sidorna~\pageref{#1}--\pageref{#2}}%
+ \def\reftextlabelrange#1#2{\ref{#1} till~\ref{#2}}%
+ }}
+\DeclareOption{turkish}
+ {\vref@excuse{turkish}%
+ \vref@addto\extrasturkish{%
+ \def\reftextfaceafter {on the \reftextvario{facing}{next} page}%
+ \def\reftextfacebefore{on the \reftextvario{facing}{preceding}
+ page}%
+ \def\reftextafter {on the \reftextvario{following}{next} page}%
+ \def\reftextbefore {on the \reftextvario{preceding}{previous} page}%
+ \def\reftextcurrent {on \reftextvario{this}{the current} page}%
+ \def\reftextfaraway#1{on page~\pageref{#1}}%
+ \def\reftextpagerange#1#2{on pages~\pageref{#1}--\pageref{#2}}%
+ \def\reftextlabelrange#1#2{\ref{#1} to~\ref{#2}}%
+ }}
+% \end{macrocode}
+% We support francais as an alternative to french since people
+% might be used to it, but we discurrage it.
+% \begin{macrocode}
+\DeclareOption{francais}{%
+ \typeout{Please use `french' instead of `francais'}%
+ \ExecuteOptions{french}}
+\DeclareOption{germanb}{%
+ \typeout{Please use `german' instead of `germanb'}%
+ \ExecuteOptions{german}}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+% During document preparation errors due to |\vref| are usually of
+% not much interest. For this reason the draft option turns them into
+% warnings by issuing a |\vrefwarning| command. The final option
+% (default) stops with an error message when varioref detects a possible
+% loop.
+% \changes{v1.1h}{1998/08/01}{Added draft and final options}
+% \begin{macrocode}
+\DeclareOption{draft}{\AtEndOfPackage\vrefwarning}
+\DeclareOption{final}{\AtEndOfPackage\vrefshowerrors} % the default
+% \end{macrocode}
+%
+% After all options are declared we execute the default option
+% \texttt{english} to set up the defaults and then call
+% |\ProcessOptions*| to handle any option passed to the package.
+% The star form is used since we want to execute the options in the
+% order they are given (in case this isn't used together with the
+% \texttt{babel} package).
+% \begin{macrocode}
+\ExecuteOptions{english,final}
+\ProcessOptions*
+% \end{macrocode}
+%
+%
+% \subsection{Defining the main macros}
+%
+% \begin{macro}{\vr@cnt}
+% To generate new labels we use a counter and construct the
+% internal label names by prefixing the current counter value with
+% the string |vr@|. We need a \LaTeX{} counter to get |\include|s
+% handled correctly.
+% \changes{v0.1e}{1992/11/15}{use LaTeX counter}
+% \begin{macrocode}
+\newcounter{vrcnt}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\vpageref}
+% \changes{v1.3a}{2001/04/12}{Scan for star form}
+% \begin{macro}{\vp@geref}
+% The command |\vpageref| generates the appropriate string by first
+% parsing the optional arguments (if any) and then compares the
+% internal and the user label. This command should be robust since
+% the user might put it anywhere.
+%
+% We now start by scanning for a star which means: do not add a
+% space in front of the generated text---ever.
+% \begin{macrocode}
+\DeclareRobustCommand\vpageref{\@ifstar
+ {\let\vref@space\relax\vp@geref}%
+ {\let\vref@space\space\vp@geref}}
+% \end{macrocode}
+%
+% \begin{macrocode}
+\def\vp@geref{\@ifnextchar[%
+% \end{macrocode}
+% The default for the first optional argument is the string hidden
+% in the macro |\reftextcurrent|.
+% \begin{macrocode}
+ \@vpageref{\@vpageref[\reftextcurrent]}%
+}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\vref@space}
+% \changes{v1.4a}{2002/03/06}{Default added}
+% A default for |\vref@space|. This isn't really needed except in
+% the case that somebody has hooked into the \texttt{varioref}
+% interfaces at a lower level (which isn't really supported,
+% but\ldots). So giving a default will prevent an error message in
+% that case (and should hopefully produce the same behavior as before).
+% \begin{macrocode}
+\let\vref@space\space
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\@vpageref}
+% More parsing\ldots
+% \begin{macrocode}
+\def\@vpageref[#1]{\@ifnextchar[%
+% \end{macrocode}
+% The default for the second optional argument is a space which is
+% prefixed by |\unskip| to get rid of any leading space inserted
+% already.
+% \changes{v1.0h}{1994/06/11}{Pass first argument in both cases}
+% \changes{v1.0i}{1994/06/20}{Do it correctly}
+% \begin{macrocode}
+ {\@@vpageref{#1}}{\@@vpageref{#1}[\unskip\vref@space]}}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\@@vpageref}
+% The |\@@vpageref| macro finally generates the references by
+% comparing the value of an internal label with the value of the
+% user label.
+% \changes{v1.0h}{1994/06/11}{Change internal interface}
+% \begin{macrocode}
+\def\@@vpageref#1[#2]#3{%
+% \end{macrocode}
+% First it switches to horizontal mode if necessary and also
+% removes any leading space.
+% \begin{macrocode}
+ \leavevmode\unskip
+% \end{macrocode}
+% Then it advances the counter |\c@vrcnt| by one which is used to
+% generate internal label names.
+% \begin{macrocode}
+ \global\advance\c@vrcnt\@ne
+% \end{macrocode}
+% Then it checks if for the current value of |\c@vrcnt| a label
+% command was issued in the last run. If not it pretends that there
+% was one with the value |{??}{??}|. Thereafter it stores the the
+% pageref value for this label in the macro |\@tempa|.
+% \begin{macrocode}
+ \vref@pagenum\@tempa{\the\c@vrcnt @vr}%
+% \end{macrocode}
+% Here we check that the generated text is not going across a page
+% boundary.
+% \changes{v0.1f}{1993/01/01}{Add another label to catch cross-overs}
+% \begin{macrocode}
+ \vref@pagenum\@tempb{\the\c@vrcnt @xvr}%
+% \end{macrocode}
+% \changes{v1.0l}{1994/07/07}{Explicitly expand `label argument for
+% babel}
+% In version 1.0l the label string has been turned around so that
+% the number comes first. This was done to allow easy explicit
+% expansion of the number before it is passed to the |\label|
+% command. In the babel system the argument of |label| was not
+% expanded with the result that wrong label strings have been
+% generated. This is a general problem that might need a completely
+% different solution in babel but for now the change below (and in
+% some other places in the code) should solve the problem for this
+% special combination of packages.
+%
+% These days we actually use |\vref@label| instead of |\label| as
+% this avoids problems with Babel or \texttt{amsmath} redefining
+% the latter command.
+% \changes{v1.4e}{2003/01/08}{Use \cs{vref@label} instead of
+% \cs{label} (pr/3489)}
+% \begin{macrocode}
+ \vref@label{\the\c@vrcnt @xvr}%
+% \end{macrocode}
+% \changes{v1.1g}{1998/05/10}{Test if inside AMS display (pr2175)}
+% Inside displays of the \texttt{amsmath} package the |\label| command
+% is redefined which makes the test for loops incorrect if a |\vref|
+% is used in, say, |\intertext|. So we test this condition first and
+% only do the test if |\label| doesn't have a special meaning.
+% [This is no longer necessary as |\label| isn't used any more]
+% \begin{macrocode}
+% \ifx\label\label@in@display\else
+ \ifx\@tempa\@tempb\else
+% \end{macrocode}
+% If both points do not fall onto the same page with either issue
+% an error or a warning message.
+% \changes{v1.0g}{1994/05/27}{Looping pages shown in wrong order}
+% \begin{macrocode}
+ \vref@err{\noexpand\vref or \noexpand\vpageref at page boundary
+ \@tempb-\@tempa\space (may loop)%
+ }%
+ \fi
+% \fi
+% \end{macrocode}
+% Same game for the user requested label; this time the page
+% reference is saved in |\thevpagerefnum|.
+% \changes{v1.4c}{2002/06/14}{Use \cs{thevpagerefnum} instead of \cs{@tempb}}
+% \begin{macrocode}
+ \vrefpagenum\thevpagerefnum{#3}%
+% \end{macrocode}
+% Now after the internal label has served its purpose if would be
+% nice to free the memory it occupies by using something like
+% \begin{verbatim}
+% \global\expandafter\let
+% \csname r@\the\c@vrcnt @vr\endcsname\@empty
+%\end{verbatim}
+% But this is not possible because it would result in getting
+% `Labels may have changed\ldots' warnings for every run. Now we
+% are ready to produce the textual strings. Since we have removed
+% any leading space we now insert a space (unless this was the star
+% form of the command) and then compare the two
+% page references.
+% \begin{macrocode}
+ \vref@space
+ \ifx\@tempa\thevpagerefnum
+% \end{macrocode}
+% If they are the same we insert the first argument into the input
+% stream. Otherwise we insert the second argument. Recall that
+% those are the two optional arguments of |...|. However, if the
+% user explicitly requested an empty text string using the optional
+% argument we cancel any preceeding space.
+% \changes{v1.2f}{2000/07/07}{Don't output space if optional argument
+% empty (pr/3230)}
+% \begin{macrocode}
+ \def\@tempc{#1}%
+ \ifx\@tempc\@empty
+ \unskip
+ \else
+ #1%
+ \fi
+ \else
+ #2%
+% \end{macrocode}
+% Now we check if the page number of the referenced object (stored
+% in |\thevpagerefnum| is a single positive number.
+% \begin{macrocode}
+ \is@pos@number\thevpagerefnum
+ {%
+% \end{macrocode}
+% If so, we check if the current position (stored in |\@tempa|) is
+% a positive number. If this is the case we assign this number to
+% the counter register |\@tempcnta| and add one to it.
+% \begin{macrocode}
+ \is@pos@number\@tempa
+ {\@tempcnta\@tempa
+ \advance\@tempcnta\@ne
+ }%
+% \end{macrocode}
+% If it is not a positive number we assign the largest possible
+% number to |\@tempcnta| and thereby pretending that label and
+% reference are miles away from each other.
+% \begin{macrocode}
+ {\@tempcnta\maxdimen}%
+% \end{macrocode}
+% Now we are ready to check if reference and object are on nearby
+% pages. |\thevpagerefnum| will expand to the page number of the object
+% (and we know that this is a number) and |\@tempcnta| is either
+% one higher than the reference page or completely out of bounds.
+% So if both represend the same value then the object lies one page
+% after its reference.
+% \begin{macrocode}
+ \ifnum \thevpagerefnum =\@tempcnta
+% \end{macrocode}
+% Thus if the object falls onto an odd page then the reference is
+% on the facing even page (and so we insert |\reftextfaceafter|),
+% otherwise the object can not be seen from the reference (and we
+% in insert |\reftextafter|). Don't be surprised if we are not
+% using |\thevpagerefnum| in the check. Since |\@tempcnta| has the same
+% value it is faster to use the register instead of parsing the
+% macro contents anew.
+% \begin{macrocode}
+ \ifodd\@tempcnta
+% \end{macrocode}
+% In fact we are going to use |\reftextfaceafter| only if we are
+% doing two-sided printing, otherwise |\reftextafter| is always
+% used.
+% Since the value of |\if@twoside| is evaluated before reading in
+% packages we could do better (saving some tokens) by defining
+% the current macro in dependence of this boolean.
+% \begin{macrocode}
+ \if@twoside
+ \reftextfaceafter
+ \else
+ \reftextafter
+ \fi
+ \else
+ \reftextafter
+ \fi
+% \end{macrocode}
+% If the object is not on the page following the reference we check
+% if it is on the page before the reference. In \LaTeX{} this
+% situation is not too common, for example with floats it normally
+% does not occur, but of course it isn't impossible if you more
+% than one reference to the same object, or if you have back
+% references to sections, theorems, etc. To test this we now
+% substract two from the current value of |\@tempcnta| (which was
+% set to one higher as the reference page number). Note, that
+% substraction is also possible if the value was |\maxdimen| --- we
+% still get something that is much larger than any sensible page
+% number.
+% \begin{macrocode}
+ \else
+ \advance\@tempcnta-2
+% \end{macrocode}
+% If now |\thevpagerefnum| and |\@tempcnta| have the same value then the
+% object lies one page before the reference.
+% \begin{macrocode}
+ \ifnum \thevpagerefnum =\@tempcnta
+% \end{macrocode}
+% Again we have to check for odd or even pages to distinguish
+% between the facing and the non-facing situation.
+% \begin{macrocode}
+ \ifodd\@tempcnta
+ \reftextbefore
+ \else
+% \end{macrocode}
+% Again the |\reftextfacebefore| only if |@twoside| evaluates to
+% true.
+% \begin{macrocode}
+ \if@twoside
+ \reftextfacebefore
+ \else
+ \reftextbefore
+ \fi
+ \fi
+% \end{macrocode}
+% If the above test also returns false then we have object and
+% references on pages which are far away or don't contain simple
+% page numbers. Therefore we generate the |\reftextfaraway| string.
+% Recall that this is a macro which has the user label as an
+% argument.
+% \begin{macrocode}
+ \else
+ \reftextfaraway{#3}%
+ \fi
+ \fi
+ }%
+% \end{macrocode}
+% We do the same if our first test (that the page with the object
+% has a positive page number) turns out to be false.
+% \begin{macrocode}
+ {\reftextfaraway{#3}}%
+ \fi
+% \end{macrocode}
+% Finally we generate the internal label so that it can be check on
+% the next run. This means that we compare the position after the
+% string with the position of the referenced object. There is one
+% thing to note: to conserve space we locally make |\@currentlabel|
+% empty since we are only interested in the page number value of
+% this internal label.
+% \changes{v1.0l}{1994/07/07}{Explicitly expand \cs{label} argument for babel}
+%
+% These days we actually use |\vref@label| instead of |\label| as
+% this avoids problems with Babel or \texttt{amsmath} redefining
+% the latter command.
+% \changes{v1.4e}{2003/01/08}{Use \cs{vref@label} instead of
+% \cs{label} (pr/3489)}
+% \begin{macrocode}
+ \vref@label{\the\c@vrcnt @vr}%
+}
+% \end{macrocode}
+% \end{macro}
+%
+%
+% \begin{macro}{\vref@label}
+% \changes{v1.4e}{2003/01/08}{Macro added (pr/3489)}
+% This macro is like |\label| in the kernel but without passing on
+% |\@currentlabel|, ie useful if all we are interested in is the
+% page number. It also has the effect that it is uneffected by
+% \texttt{amsmath} or Babel redefining the |\label| command.
+% \begin{macrocode}
+\def\vref@label#1{\@bsphack
+ \protected@write\@auxout{}%
+ {\string\newlabel{#1}{{}{\thepage}}}%
+ \@esphack}
+% \end{macrocode}
+% \end{macro}
+%
+%
+% \begin{macro}{\vpagerefnum}
+% \changes{v1.4c}{2002/06/14}{Macro added}
+% This macro allows to define |\reftextafter| and friends to refer
+% to the page number rather than producing a textual reference.
+% \begin{macrocode}
+\let\thevpagerefnum\@empty
+% \end{macrocode}
+% \end{macro}
+%
+%
+% \begin{macro}{\vrefwarning}
+% \changes{v0.1g}{1993/02/14}{Macro added}
+% \begin{macro}{\vrefshowerrors}
+% \changes{v1.1h}{1998/08/01}{Macro added}
+% \begin{macro}{\vref@err}
+% \changes{v0.1g}{1993/02/14}{Macro added}
+% When the |\vref| command detects a possible crossing over a page
+% boundary it will call |\vref@err| to generate an error message.
+% During document preparation one can turn such errors into
+% warnings by issuing a |\vrefwarning| declaration.
+% \changes{v1.0g}{1993/02/14}{Macro added}
+% \begin{macrocode}
+\def\vrefwarning{\def\vref@err{\PackageWarning{varioref}}}
+% \end{macrocode}
+% \begin{macrocode}
+\def\vrefshowerrors{\def\vref@err##1{\PackageError{varioref}{##1}%
+ {Please check the pages in question. You might need to replace
+ the \string\vref\MessageBreak
+ or \noexpand\vpageref by a normal \noexpand\(page)ref to
+ stop LaTeX running forever.}}}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+%
+% \begin{macro}{\vref}
+% \changes{v1.3a}{2001/04/12}{Scan for star form}
+% We start by scanning for a star form in which case we do not put
+% any space before the generated text (only remove some).
+% \begin{macro}{\vr@f}
+% \begin{macrocode}
+\DeclareRobustCommand\vref{\@ifstar
+ {\let\vref@space\relax\vr@f}%
+ {\let\vref@space\nobreakspace\vr@f}}
+% \end{macrocode}
+% And now we do the real work\ldots
+% \changes{v1.3c}{2001/09/04}{Correct typo in name}
+% \begin{macrocode}
+\def\vr@f#1{%
+% \end{macrocode}
+% The use of|\nobreakspace| or |~| after the |\unskip| means that
+% this command will always produce a normal space while
+% something like |\nobreak\space| will
+% react to settings of |\nonfrenchspacing|.
+% Unfortunately the latter will also act in cases where one really
+% wants a normal space, e.g., in |Fig.~\vref{..}|, resulting in
+% a large extra space after the dot. For this reason the first solution
+% is used.
+% \changes{v1.1e}{1998/03/09}{Don't use \cs{nobreakspace} (pr/1866)}
+% \changes{v1.2a}{1998/11/27}{Use \cs{nobreakspace} (pr/2909)}
+% \changes{v1.2a}{1998/11/27}{Add \cs{leavevmode}}
+%
+% Above comments all refer to the earlier versions where there was
+% no posibility to suppress the space at all. By now we have
+% |\vref*| and |\vpageref*| to suppress the in internally generated
+% space by redefining |\vref@space| appropriately.
+% \begin{macrocode}
+ \leavevmode\unskip\vref@space
+ \ref{#1}%
+% \end{macrocode}
+% That means we have have to use |\vpageref| and not the internal
+% |\@vpageref| --- otherwise we would pick up the
+% ``current'' definition for |\vref@space| instead of setting it
+% back to |\space|.
+% \changes{v1.4c}{2002/06/18}{Use \cs{vpageref} not \cs{@vpageref} (pr/3403)}
+% \begin{macrocode}
+ \vpageref[\unskip]{#1}}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+%
+% \begin{macro}{\is@pos@number}
+% The utility macro |\is@pos@number| takes three arguments: a
+% string that is tested for being a valid integer and the actions
+% to be taken in case the test comes out true or false.
+%
+% We start by passing the string to the macro |\is@pos@num| after
+% prefixing it with a \texttt{0} and adding a space after it. To have
+% a well defined ending point we also add |\@nil| at the end.
+%\label{isposnumber}
+% \begin{macrocode}
+\def\is@pos@number#1{\is@pos@num0#1\space\@nil}
+% \end{macrocode}
+% Now we parse the enlarged string into a counter register. To get
+% control back after everything that is regarded by \TeX{} as a
+% number is put into that register we assign |\is@pos@num@| to the
+% |\afterassignment| token. Since the string started with 0, we
+% can be sure that the register assignment will be carried out
+% without an error message. In case of counter assignments leading
+% zeros are discarded.
+% \begin{macrocode}
+\def\is@pos@num{\afterassignment\is@pos@num@ \count@}
+% \end{macrocode}
+% Now we have to check whether or not the whole string was parsed
+% into that register or some remainder was left over. Since we have
+% added a |\@nil| token at the very end we can use that to delimit
+% the argument of |\is@pos@num@|. Note, that the added space in
+% |\is@pos@number| \vpageref[above]{isposnumber} gets parsed away
+% by the counter assignment. If it would be missing, and the full
+% string would consist of a number, \TeX{}would try to replace
+% |\@nil| by its definition to see if it would contain additional
+% digits and thus we would be in trouble at this point.
+% \begin{macrocode}
+\def\is@pos@num@#1\@nil{%
+% \end{macrocode}
+% Now we have to check if the argument is empty. We can do this
+% with an |\if| test (i.e., in an expandable way) since we know for
+% sure that it can not start with a digit
+% \begin{macrocode}
+ \if0#10%
+% \end{macrocode}
+% Depending on the result we execute the second or third argument
+% of the command |\is@pos@number| using a technique that removes
+% the |\else| or |\fi| from the input stream first, so that in
+% principle input stream parsing could be done from within the
+% arguments.
+% \begin{macrocode}
+ \expandafter\@firstoftwo \else
+ \expandafter\@secondoftwo \fi}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\reftextvario}
+% This macro gives a little bit of random variation in the text
+% because the outcome depends on the number of |\vref| commands
+% seen before.
+% \begin{macrocode}
+\def\reftextvario#1#2{\ifodd\c@vrcnt #1\else#2\fi}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\fullref}
+% And here is the primitive command that always produces a |\ref|
+% and a |\pageref|.
+% \begin{macrocode}
+\def\fullref#1{\ref{#1} \reftextfaraway{#1}}
+% \end{macrocode}
+% \end{macro}
+%
+%
+% \subsubsection{Supporting ranges}
+%
+% \begin{macro}{\vref@pagenum}
+% \changes{v1.2a}{1998/08/01}{Macro added}
+% This command takes a label as |#1| extracts the page number
+% associated with it and saves the result in a csname which is
+% passed as |#1|. If the label isn't associates with a page number
+% it essentially associates it with |??| for both the label number
+% and the page, thus defining the label this way. This means that
+% no label warning is generated for this label in case it is
+% undefined.
+% \begin{macrocode}
+\def\vref@pagenum#1#2{%
+ \@ifundefined{r@#2}{\@namedef{r@#2}{{??}{??}}}{}%
+ \edef#1{\expandafter\expandafter\expandafter
+ \@cdr\csname r@#2\endcsname
+ \@nil}%
+}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\vrefpagenum}
+% \changes{v1.2a}{1998/08/01}{Macro added}
+% Same as the above but this time we generate a warning for
+% undefined labels.
+% \begin{macrocode}
+\def\vrefpagenum#1#2{%
+ \@ifundefined{r@#2}%
+ {\G@refundefinedtrue
+ \@latex@warning{Reference `#2' on page \thepage \space
+ undefined}}{}%
+ \vref@pagenum{#1}{#2}}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\vpagerefrange}
+% \begin{macro}{\@vpagerefrange}
+% \begin{macro}{\@svpagerefrange}
+% \changes{v1.2a}{1998/08/01}{Macro added}
+% \changes{v1.3b}{2001/04/14}{Scan for star form}
+% If both labels refer to the same page then we produce a
+% |\vpageref|. Otherwise we produce the result of
+% |\reftextpagerange|.
+%
+% One could think of making this command even more clever by
+% producing a special string if the difference between the two page
+% number is one (but this is not done).
+%
+% We need two versions to implement a star form:
+% \begin{macrocode}
+\newcommand\@svpagerefrange[3][\reftextcurrent]{%
+ \vrefpagenum\@tempa{#2}%
+ \vrefpagenum\@tempb{#3}%
+ \ifx\@tempa\@tempb
+ \vpageref*[#1]{#2}%
+ \else
+ \reftextpagerange{#2}{#3}%
+ \fi
+}
+% \end{macrocode}
+% And the same but using |\vpageref|:
+% \begin{macrocode}
+\newcommand\@vpagerefrange[3][\reftextcurrent]{%
+ \vrefpagenum\@tempa{#2}%
+ \vrefpagenum\@tempb{#3}%
+ \ifx\@tempa\@tempb
+ \vpageref[#1]{#2}%
+ \else
+ \reftextpagerange{#2}{#3}%
+ \fi
+}
+% \end{macrocode}
+% And here we put things together.
+% \begin{macrocode}
+\newcommand\vpagerefrange{\@ifstar\@svpagerefrange\@vpagerefrange}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+%
+% \begin{macro}{\vrefrange}
+% \changes{v1.2a}{1998/08/01}{Macro added}
+% \begin{macrocode}
+\newcommand\vrefrange[3][\reftextcurrent]
+ {\reftextlabelrange{#2}{#3} \vpagerefrange[#1]{#2}{#3}}
+% \end{macrocode}
+% \end{macro}
+%
+%
+% \subsection{An extension of counter referencing}
+%
+% \begin{macro}{\refstepcounter}
+% \changes{v1.4a}{2002/02/24}{Macro redefined}
+%
+% At the moment a reference to a counter |foo| will generate the
+% equivalent of |\p@foo\thefoo| although not quite in this form. For
+% some applications it would be nice of one could have |\thefoo| being
+% an argument to |\p@foo| to be able to put material before and after
+% the number generated by |\thefoo|. This can be easily achieved with
+% a small change to one of the kernel commands as follows:
+% \begin{macrocode}
+\def\refstepcounter#1{\stepcounter{#1}%
+ \protected@edef\@currentlabel
+ {\csname p@#1\expandafter\endcsname\csname the#1\endcsname}%
+}
+% \end{macrocode}
+% The trick is to ensure that |\csname the#1\endcsname| is turned into
+% a single token before |\p@...| is expanded further. This way, if the
+% |\p@...| command is a macro with one argument it will receive
+% |\the...|. With the kernel code (i.e., without the |\expandafter|)
+% it will instead pick up |\csname| which would be disastrous.
+%
+% Using |\expandafter| instead of braces delimiting the argument is
+% better because, assuming that the |\p@...| command is not defined as
+% a macro with one argument, the braces will stay and prohibit kerning
+% that might otherwise happen between the glyphs generated by
+% |\the...| and surrounding glyphs.
+% \end{macro}
+%
+% \begin{macro}{\labelformat}
+% \changes{v1.4a}{2002/02/24}{Macro added}
+% A shortcut to set the |\p@...| macro for a counter. It will pick
+% up the counter representation as an argument so that it can be
+% specially formatted.
+% \begin{macrocode}
+\def\labelformat#1{\expandafter\def\csname p@#1\endcsname##1}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\Ref}
+% \changes{v1.4a}{2002/02/24}{Macro added}
+% This macro expands the result of |\ref| and then uppercases the
+% first token. Only useful if the label was generated via
+% |\labelformat| and contains some lower case letter at its start. If
+% the label starts with a complicated construct (e.g., an accented
+% letter) one has to surround everything that needs uppercasing in
+% a brace group in the definition of |\labelformat|.\footnote{There
+% is one problem with this approach: the braces are kept in a
+% normal \texttt{\textbackslash ref} which might spoil kerning.
+% Perhaps one day this needs redoing.}
+% \begin{macrocode}
+\DeclareRobustCommand\Ref[1]{\protected@edef\@tempa{\ref{#1}}%
+ \expandafter\MakeUppercase\@tempa}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\Vref}
+% \changes{v1.4a}{2002/02/24}{Macro added}
+% \begin{macro}{\Vr@f}
+% \changes{v1.4a}{2002/02/24}{Macro added}
+% |\Vref| is the counterpart to |\vref| with |\ref| replaced by
+% |\Ref| in its definition.
+% \begin{macrocode}
+\DeclareRobustCommand\Vref{\@ifstar
+ {\let\vref@space\relax\Vr@f}%
+ {\let\vref@space\nobreakspace\Vr@f}}
+\def\Vr@f#1{%
+ \leavevmode\unskip\vref@space
+ \Ref{#1}%
+ \@vpageref[\unskip]{#1}}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macrocode}
+%</package>
+% \end{macrocode}
+% \Finale
+%
+\endinput
+
diff --git a/Master/texmf-dist/source/latex/tools/verbatim.dtx b/Master/texmf-dist/source/latex/tools/verbatim.dtx
new file mode 100644
index 00000000000..29edcb61239
--- /dev/null
+++ b/Master/texmf-dist/source/latex/tools/verbatim.dtx
@@ -0,0 +1,1881 @@
+% \iffalse meta-comment
+%
+% Copyright 1993 1994 1995 1996 1997 1998 1999 2000 2001 2002 2003
+% The LaTeX3 Project and any individual authors listed elsewhere
+% in this file.
+%
+% This file is part of the Standard LaTeX `Tools Bundle'.
+% -------------------------------------------------------
+%
+% It 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.3 or later is part of all distributions of LaTeX
+% version 2003/12/01 or later.
+%
+% The list of all files belonging to the LaTeX `Tools Bundle' is
+% given in the file `manifest.txt'.
+%
+% \fi
+% \CheckSum{625}
+%
+%\iffalse % this is a METACOMMENT !
+%
+%
+%% Package `verbatim' to use with LaTeX2e
+%% Copyright (C) 1989--2003 by Rainer Schöpf. All rights reserved.
+%
+% Copying of this file is authorized only if either
+% (1) you make absolutely no changes to your copy, including name, or
+% (2) if you do make changes, you name it something other than
+% verbatim.dtx.
+% This restriction helps ensure that all styles developed here
+% remain identical.
+%
+%
+%
+% \section{Producing the documentation}
+%
+% We provide a short driver file that can be extracted by the
+% \textsf{DocStrip} program using the conditional `\textsf{driver}'.
+%
+% \begin{macrocode}
+%<*driver>
+\documentclass{ltxdoc}
+
+\pagestyle{myheadings}
+
+\title{A New Implementation of \LaTeX{}'s \\ \texttt{verbatim}
+ and \texttt{verbatim*} Environments.}
+\author{Rainer Sch\"opf\\
+ Internet: \texttt{Schoepf@Uni-Mainz.DE}
+ \and
+ Bernd Raichle\\
+ Stettener Str.~73\\
+ D-73732 W\"aldenbronn\\
+ Federal Republic of Germany\\
+ Internet: \texttt{raichle@azu.Informatik.Uni-Stuttgart.DE}
+ \and
+ Chris Rowley\\
+ The Open University\\
+ Parsifal College\\
+ Finchley Road\\
+ London NW3 7BG, UK\\
+ Internet: \texttt{C.A.Rowley@open.ac.uk}}
+\date{2001/03/12}
+\begin{document}
+\markboth{Verbatim style option}{Verbatim style option}
+\maketitle
+ \DocInput{verbatim.dtx}
+\end{document}
+%</driver>
+% \end{macrocode}
+%
+%
+%\fi
+%
+%
+% \changes{v1.5q}{2003/08/22}{Reintroduced \cs{@noligs}, by popular
+% request.}
+% \changes{v1.5i}{1996/06/04}{Move setting of verbatim font and
+% \cs{@noligs}.}
+% \changes{v1.5g}{1995/04/26}{Removed \cs{fileversion} and
+% \cs{filedate} from running head in
+% driver file, as these are no longer
+% defined.}
+% \changes{v1.5f}{1994/10/25}{Removed extra \cs{typeout} commands.}
+% \changes{v1.5e}{1994/06/10}{Added missing closing verbtest guard.}
+% \changes{v1.5d}{1994/05/30}{\cs{NeedsTeXFormat} and
+% \cs{ProvidesPackage} added.}
+% \changes{v1.5d}{1994/05/30}{\cs{addto@hook} removed, now in kernel.}
+% \changes{v1.5a}{1993/10/12}{Included \cs{newverbtext} command, as
+% written by Chris Rowley.}
+% \changes{v1.5}{1993/10/11}{Included vrbinput style option by Bernd
+% Raichle.}
+%
+% \changes{v1.4j}{1992/06/30}{Used \cs{lowercase}\{\cs{endgroup}
+% \ldots\} trick proposed by Bernd Raichle; changed all \cs{gdef}
+% to \cs{def} since no longer necessary.}
+% \changes{v1.4g}{1991/11/21}{Several improvements in the
+% documentation.}
+% \changes{v1.4f}{1991/08/05}{Corrected bug in documentation.
+% Found by Bernd Raichle.}
+% \changes{v1.4e}{1991/07/24}{Avoid reading this file twice.}
+% \changes{v1.4d}{1991/04/24}{\cs{penalty}\cs{interlinepenalty} added to
+% definition of \cs{par} in \cs{@verbatim}.
+% Necessary to avoid page breaks in
+% the scope of a \cs{samepage} declaration.}
+% \changes{v1.4c}{1990/10/18}{Added \cs{leavevmode} to definition of
+% backquote macro.}
+% \changes{v1.4b}{1990/07/14}{Converted nearly all \cs{verb}'s to
+% \texttt{\protect\string!|\ldots\protect\string!|}.}
+% \changes{v1.4a}{1990/04/04}{Added a number of percent characters
+% to suppress blank space at the end of some code lines.}
+% \changes{v1.4}{1990/03/07}{\cs{verb} rewritten.}
+%
+% \changes{v1.3a}{1990/02/04}{Removed \texttt{verbatimwrite} environment
+% from the code. Now only shown as an example.}
+%
+% \changes{v1.2g}{1990/02/01}{Revised documentation.}
+% \changes{v1.2e}{1990/01/15}{Added \cs{every@verbatim} hook.}
+% \changes{v1.2d}{1989/11/29}{Use token register \cs{@temptokena}
+% instead of macro \cs{@tempb}.}
+% \changes{v1.2d}{1989/11/29}{Use token register \cs{verbatim@line}
+% instead of macro \cs{@tempd}.}
+% \changes{v1.2b}{1989/10/25}{\cs{verbatimfile} renamed to
+% \cs{verbatiminput}. Suggested by Reinhard Wonneberger.}
+%
+% \changes{v1.1a}{1989/10/16}{\cs{verb} added.}
+% \changes{v1.1}{1989/10/09}{Made the code more modular (as suggested by
+% Chris Rowley): introduced
+% \cs{verbatim@addtoline}, etc. Added
+% \cs{verbatimwrite} environment.}
+%
+% \changes{v1.0e}{1989/07/17}{Fixed bug in \cs{verbatimfile} (*-form
+% handling, discovered by Dirk Kreimer).}
+% \changes{v1.0d}{1989/05/16}{Revised documentation, fixed silly bug
+% in \cs{verbatim@@@}.}
+% \changes{v1.0c}{1989/05/12}{Added redefinition of \cs{@sverb}, change
+% in end-of-line handling.}
+% \changes{v1.0b}{1989/05/09}{Change in \cs{verbatim@rescan}.}
+% \changes{v1.0a}{1989/05/07}{Change in \cs{verbatim@@testend}.}
+%
+%
+% \DoNotIndex{\ ,\!,\C,\[,\\,\],\^,\`,\{,\},\~}
+% \DoNotIndex{\@M,\@empty,\@flushglue,\@gobble,\@ifstar,\@ifundefined}
+% \DoNotIndex{\@namedef,\@spaces,\@tempa,\@tempb,\@tempc,\@tempd}
+% \DoNotIndex{\@temptokena,\@totalleftmargin,\@warning,\active}
+% \DoNotIndex{\aftergroup,\arabic,\begingroup,\catcode,\char,\closein}
+% \DoNotIndex{\csname,\def,\do,\docdate,\dospecials,\edef,\else}
+% \DoNotIndex{\endcsname,\endgraf,\endgroup,\endinput,\endlinechar}
+% \DoNotIndex{\endtrivlist,\expandafter,\fi,\filedate,\fileversion}
+% \DoNotIndex{\frenchspacing,\futurelet,\if,\ifcat,\ifeof,\ifnum}
+% \DoNotIndex{\ifx,\immediate,\item,\kern,\lccode,\leftskip,\let}
+% \DoNotIndex{\lowercase,\m@ne,\makeatletter,\makeatother,\newread}
+% \DoNotIndex{\newread,\next,\noexpand,\noindent,\openin,\parfillskip}
+% \DoNotIndex{\parindent,\parskip,\penalty,\read,\relax,\rightskip}
+% \DoNotIndex{\sloppy,\space,\string,\the,\toks@,\trivlist,\tt,\typeout}
+% \DoNotIndex{\vskip,\write,\z@}
+%
+% \begin{abstract}
+% This package reimplements the \LaTeX{} \texttt{verbatim} and
+% \texttt{verbatim*} environments.
+% In addition it provides a \texttt{comment} environment
+% that skips any commands or text between
+% |\begin{comment}|
+% and the next |\end{comment}|.
+% It also defines the command \texttt{verbatiminput} to input a whole
+% file verbatim.
+% \end{abstract}
+%
+% \section{Usage notes}
+%
+% \let\docDescribeMacro\DescribeMacro
+% \let\docDescribeEnv\DescribeEnv
+% \def\DescribeMacro#1{}
+% \def\DescribeEnv#1{}
+% \LaTeX's \texttt{verbatim} and \texttt{verbatim*} environments
+% have a few features that may give rise to problems. These are:
+% \begin{itemize}
+% \item
+% Due to the method used to detect the closing |\end{verbatim}|
+% (i.e.\ macro parameter delimiting) you cannot leave spaces
+% between the |\end| token and |{verbatim}|.
+% \item
+% Since \TeX{} has to read all the text between the
+% |\begin{verbatim}| and the |\end{verbatim}| before it can output
+% anything, long verbatim listings may overflow \TeX's memory.
+% \end{itemize}
+% Whereas the first of these points can be considered
+% only a minor nuisance the other one is a real limitation.
+%
+%
+% \DescribeEnv{verbatim}
+% \DescribeEnv{verbatim*}
+% This package file contains a reimplementation of the \texttt{verbatim}
+% and \texttt{verbatim*} environments which overcomes these
+% restrictions.
+% There is, however, one incompatibility between the old and the
+% new implementations of these environments: the old version
+% would treat text on the same line as the |\end{verbatim}|
+% command as if it were on a line by itself.
+% \begin{center}
+% \bf This new version will simply ignore it.
+% \end{center}
+% (This is the price one has to pay for the removal of the old
+% \texttt{verbatim} environment's size limitations.)
+% It will, however, issue a warning message of the form
+% \begin{verbatim}
+%LaTeX warning: Characters dropped after \end{verbatim*}!
+%\end{verbatim}
+% This is not a real problem since this text can easily be put
+% on the next line without affecting the output.
+%
+% This new implementation also solves the second problem mentioned
+% above: it is possible to leave spaces (but \emph{not} begin a new
+% line) between the |\end| and the |{verbatim}| or |{verbatim*}|:
+% \begin{verbatim}
+%\begin {verbatim*}
+% test
+% test
+%\end {verbatim*}
+%\end{verbatim}
+%
+% \DescribeEnv{comment}
+% Additionally we introduce a \texttt{comment} environment, with the
+% effect that the text between |\begin{comment}| and |\end{comment}|
+% is simply ignored, regardless of what it looks like.
+% At first sight this seems to be quite different from the purpose
+% of verbatim listing, but actually the implementation of these two
+% concepts turns out to be very similar.
+% Both rely on the fact that the text between |\begin{...}| and
+% |\end{...}| is read by \TeX{} without interpreting any commands or
+% special characters.
+% The remaining difference between \texttt{verbatim} and
+% \texttt{comment} is only that the text is to be typeset in the
+% first case and to be thrown away in the latter. Note that these
+% environments cannot be nested.
+%
+% \DescribeMacro{\verbatiminput}
+% |\verbatiminput| is a command with one argument that inputs a file
+% verbatim, i.e.\ the command |verbatiminput{xx.yy}|
+% has the same effect as\\[2pt]
+% \hspace*{\MacroIndent}|\begin{verbatim}|\\
+% \hspace*{\MacroIndent}\meta{Contents of the file \texttt{xx.yy}}\\
+% \hspace*{\MacroIndent}|\end{verbatim}|\\[2pt]
+% This command has also a |*|-variant that prints spaces as \verb*+ +.
+%
+%
+% \StopEventually{}
+%
+%
+% \section{Interfaces for package writers}
+%
+% The \texttt{verbatim} environment of \LaTeXe{} does not
+% offer a good interface to programmers.
+% In contrast, this package provides a simple mechanism to
+% implement similar features, the \texttt{comment} environment
+% implemented here being an example of what can be done and how.
+%
+%
+% \subsection{Simple examples}
+%
+% It is now possible to use the \texttt{verbatim} environment to define
+% environments of your own.
+% E.g.,
+%\begin{verbatim}
+% \newenvironment{myverbatim}%
+% {\endgraf\noindent MYVERBATIM:%
+% \endgraf\verbatim}%
+% {\endverbatim}
+%\end{verbatim}
+% can be used afterwards like the \texttt{verbatim} environment, i.e.
+% \begin{verbatim}
+%\begin {myverbatim}
+% test
+% test
+%\end {myverbatim}
+%\end{verbatim}
+% Another way to use it is to write
+% \begin{verbatim}
+%\let\foo=\comment
+%\let\endfoo=\endcomment
+%\end{verbatim}
+% and from that point on environment \texttt{foo} is the same as the
+% comment environment, i.e.\ everything inside its body is ignored.
+%
+% You may also add special commands after the |\verbatim| macro is
+% invoked, e.g.
+%\begin{verbatim}
+%\newenvironment{myverbatim}%
+% {\verbatim\myspecialverbatimsetup}%
+% {\endverbatim}
+%\end{verbatim}
+% though you may want to learn about the hook |\every@verbatim| at
+% this point.
+% \changes{v1.5h}{1995/09/21}{Clarified documentation on use of other
+% environments to define new verbatim-type ones.}
+% However, there are still a number of restrictions:
+% \begin{enumerate}
+% \item
+% You must not use the |\begin| or the |\end| command inside a
+% definition, e.g.~the following two examples will \emph{not} work:
+%\begin{verbatim*}
+%\newenvironment{myverbatim}%
+%{\endgraf\noindent MYVERBATIM:%
+% \endgraf\begin{verbatim}}%
+%{\end{verbatim}}
+%\newenvironment{fred}
+%{\begin{minipage}{30mm}\verbatim}
+%{\endverbatim\end{minipage}}
+%\end{verbatim*}
+% If you try these examples, \TeX{} will report a
+% ``runaway argument'' error.
+% More generally, it is not possible to use
+% |\begin|\ldots\allowbreak|\end|
+% or the related environments in the definition of the new
+% environment. Instead, the correct way to define this environment
+% would be
+% \begin{verbatim*}
+%\newenvironment{fred}
+%{\minipage{30mm}\verbatim}
+%{\endverbatim\endminipage}
+%\end{verbatim*}
+% \item
+% You can\emph{not} use the \texttt{verbatim} environment inside
+% user defined \emph{commands}; e.g.,
+% \changes{v1.4g}{1991/11/21}{Corrected wrong position of optional
+% argument to \cs{newcommand}. Discovered by Piet van Oostrum.}
+% \begin{verbatim*}
+%\newcommand{\verbatimfile}[1]%
+% {\begin{verbatim}\input{#1}\end{verbatim}}
+%\end{verbatim*}
+% does \emph{not} work; nor does
+% \begin{verbatim}
+%\newcommand{\verbatimfile}[1]{\verbatim\input{#1}\endverbatim}
+%\end{verbatim}
+% \item The name of the newly defined environment must not contain
+% characters with category code other than $11$ (letter) or
+% $12$ (other), or this will not work.
+% \end{enumerate}
+%
+%
+% \subsection{The interfaces}
+%
+% \DescribeMacro{\verbatim@font}
+% Let us start with the simple things.
+% Sometimes it may be necessary to use a special typeface for your
+% verbatim text, or perhaps the usual computer modern typewriter shape
+% in a reduced size.
+%
+% You may select this by redefining the macro |\verbatim@font|.
+% This macro is executed at the beginning of every verbatim text to
+% select the font shape.
+% Do not use it for other purposes; if you find yourself abusing this
+% you may want to read about the |\every@verbatim| hook below.
+%
+% By default, |\verbatim@font| switches to the typewriter font and
+% disables the ligatures contained therein.
+%
+%
+% \DescribeMacro{\every@verbatim}
+% \DescribeMacro{\addto@hook}
+% There is a hook (i.e.\ a token register) called |\every@verbatim|
+% whose contents are inserted into \TeX's mouth just before every
+% verbatim text.
+% Please use the |\addto@hook| macro to add something to this hook.
+% It is used as follows:\\[2pt]
+% \hspace*{\MacroIndent}|\addto@hook|\meta{name of the hook}^^A
+% |{|\meta{commands to be added}|}|
+% \vspace*{2pt}
+%
+%
+%
+% \DescribeMacro{\verbatim@start}
+% After all specific setup, like switching of category codes, has been
+% done, the |\verbatim@start| macro is called.
+% This starts the main loop of the scanning mechanism implemented here.
+% Any other environment that wants to make use of this feature should
+% execute this macro as its last action.
+%
+%
+% \DescribeMacro{\verbatim@startline}
+% \DescribeMacro{\verbatim@addtoline}
+% \DescribeMacro{\verbatim@processline}
+% \DescribeMacro{\verbatim@finish}
+% These are the things that concern the start of a verbatim
+% environment.
+% Once this (and other) setup has been done, the code in this package
+% reads and processes characters from the input stream in the
+% following way:
+% \begin{enumerate}
+% \item Before the first character of an input line is read, it
+% executes the macro |\verbatim@startline|.
+% \item After some characters have been read, the macro
+% |\verbatim@addtoline| is called with these characters as its only
+% argument.
+% This may happen several times per line (when an |\end| command is
+% present on the line in question).
+% \item When the end of the line is reached, the macro
+% |\verbatim@processline| is called to process the characters that
+% |\verbatim@addtoline| has accumulated.
+% \item Finally, there is the macro |\verbatim@finish| that is called
+% just before the environment is ended by a call to the |\end|
+% macro.
+% \end{enumerate}
+%
+%
+% To make this clear let us consider the standard \texttt{verbatim}
+% environment.
+% In this case the three macros above are defined as follows:
+% \begin{enumerate}
+% \item |\verbatim@startline| clears the character buffer
+% (a token register).
+% \item |\verbatim@addtoline| adds its argument to the character
+% buffer.
+% \item |\verbatim@processline| typesets the characters accumulated
+% in the buffer.
+% \end{enumerate}
+% With this it is very simple to implement the \texttt{comment}
+% environment:
+% in this case |\verbatim@startline| and |\verbatim@processline| are
+% defined to be
+% no-ops whereas |\verbatim@addtoline| discards its argument.
+%
+%
+% Let's use this to define a variant of the |verbatim|
+% environment that prints line numbers in the left margin.
+% Assume that this would be done by a counter called |VerbatimLineNo|.
+% Assuming that this counter was initialized properly by the
+% environment, |\verbatim@processline| would be defined in this case as
+% \begin{verbatim}
+%\def\verbatim@processline{%
+% \addtocounter{VerbatimLineNo}{1}%
+% \leavevmode
+% \llap{\theVerbatimLineNo\ \hskip\@totalleftmargin}%
+% \the\verbatim@line\par}
+%\end{verbatim}
+%
+% A further possibility is to define a variant of the |verbatim|
+% environment that boxes and centers the whole verbatim text.
+% Note that the boxed text should be less than a page otherwise you
+% have to change this example.
+%
+%\begin{verbatim}
+%\def\verbatimboxed#1{\begingroup
+% \def\verbatim@processline{%
+% {\setbox0=\hbox{\the\verbatim@line}%
+% \hsize=\wd0
+% \the\verbatim@line\par}}%
+% \setbox0=\vbox{\parskip=0pt\topsep=0pt\partopsep=0pt
+% \verbatiminput{#1}}%
+% \begin{center}\fbox{\box0}\end{center}%
+% \endgroup}
+%\end{verbatim}
+%
+% As a final nontrivial example we describe the definition of an
+% environment called \texttt{verbatimwrite}.
+% It writes all text in its body to a file whose name is
+% given as an argument.
+% We assume that a stream number called |\verbatim@out| has already
+% been reserved by means of the |\newwrite| macro.
+%
+% Let's begin with the definition of the macro |\verbatimwrite|.
+% \begin{verbatim}
+%\def\verbatimwrite#1{%
+%\end{verbatim}
+% First we call |\@bsphack| so that this environment does not influence
+% the spacing.
+% Then we open the file and set the category codes of all special
+% characters:
+% \begin{verbatim}
+% \@bsphack
+% \immediate\openout \verbatim@out #1
+% \let\do\@makeother\dospecials
+% \catcode`\^^M\active
+%\end{verbatim}
+% The default definitions of the macros
+% \begin{verbatim}
+% \verbatim@startline
+% \verbatim@addtoline
+% \verbatim@finish
+%\end{verbatim}
+% are also used in this environment.
+% Only the macro |\verbatim@processline| has to be changed before
+% |\verbatim@start| is called:
+% \begin{verbatim}
+% \def\verbatim@processline{%
+% \immediate\write\verbatim@out{\the\verbatim@line}}%
+% \verbatim@start}
+%\end{verbatim}
+% The definition of |\endverbatimwrite| is very simple:
+% we close the stream and call |\@esphack| to get the spacing right.
+% \begin{verbatim}
+%\def\endverbatimwrite{\immediate\closeout\verbatim@out\@esphack}
+%\end{verbatim}
+%
+% \section{The implementation}
+%
+% \let\DescribeMacro\docDescribeMacro
+% \let\DescribeEnv\docDescribeEnv
+%
+% \changes{v1.4e}{1991/07/24}{Avoid reading this file twice.}
+% The very first thing we do is to ensure that this file is not read
+% in twice. To this end we check whether the macro |\verbatim@@@| is
+% defined. If so, we just stop reading this file. The `package'
+% guard here allows most of the code to be excluded when extracting
+% the driver file for testing this package.
+% \begin{macrocode}
+%<*package>
+\NeedsTeXFormat{LaTeX2e}
+\ProvidesPackage{verbatim}
+ [2003/08/22 v1.5q LaTeX2e package for verbatim enhancements]
+\@ifundefined{verbatim@@@}{}{\endinput}
+% \end{macrocode}
+%
+% We use a mechanism similar to the one implemented for the
+% |\comment|\ldots\allowbreak|\endcomment| macro in \AmSTeX:
+% We input one line at a time and check if it contains the |\end{...}|
+% tokens.
+% Then we can decide whether we have reached the end of the verbatim
+% text, or must continue.
+%
+%
+% \subsection{Preliminaries}
+%
+% \begin{macro}{\every@verbatim}
+% The hook (i.e.\ token register) |\every@verbatim|
+% is initialized to \meta{empty}.
+% \begin{macrocode}
+\newtoks\every@verbatim
+\every@verbatim={}
+% \end{macrocode}
+% \end{macro}
+%
+%
+% \begin{macro}{\@makeother}
+% \changes{v1.1a}{1989/10/16}{\cs{@makeother} added.}
+% |\@makeother| takes as argument a character and changes
+% its category code to $12$ (other).
+% \begin{macrocode}
+\def\@makeother#1{\catcode`#112\relax}
+% \end{macrocode}
+% \end{macro}
+%
+%
+% \begin{macro}{\@vobeyspaces}
+% \changes{v1.5}{1993/10/11}{Changed definition to not use \cs{gdef}.}
+% \changes{v1.1a}{1989/10/16}{\cs{@vobeyspaces} added.}
+% The macro |\@vobeyspaces| causes spaces in the input
+% to be printed as spaces in the output.
+% \begin{macrocode}
+\begingroup
+ \catcode`\ =\active%
+ \def\x{\def\@vobeyspaces{\catcode`\ \active\let \@xobeysp}}
+ \expandafter\endgroup\x
+% \end{macrocode}
+% \end{macro}
+%
+%
+% \begin{macro}{\@xobeysp}
+% \changes{v1.1a}{1989/10/16}{\cs{@xobeysp} added.}
+% The macro |\@xobeysp| produces exactly one space in
+% the output, protected against breaking just before it.
+% (|\@M| is an abbreviation for the number $10000$.)
+% \begin{macrocode}
+\def\@xobeysp{\leavevmode\penalty\@M\ }
+% \end{macrocode}
+% \end{macro}
+%
+%
+% \begin{macro}{\verbatim@line}
+% \changes{v1.2d}{1989/11/29}{Introduced token register
+% \cs{verbatim@line}.}
+% We use a newly defined token register called |\verbatim@line|
+% that will be used as the character buffer.
+% \begin{macrocode}
+\newtoks\verbatim@line
+% \end{macrocode}
+% \end{macro}
+%
+% The following four macros are defined globally in a way suitable for
+% the \texttt{verbatim} and \texttt{verbatim*} environments.
+% \begin{macro}{\verbatim@startline}
+% \begin{macro}{\verbatim@addtoline}
+% \begin{macro}{\verbatim@processline}
+% |\verbatim@startline| initializes processing of a line
+% by emptying the character buffer (|\verbatim@line|).
+% \begin{macrocode}
+\def\verbatim@startline{\verbatim@line{}}
+% \end{macrocode}
+% |\verbatim@addtoline| adds the tokens in its argument
+% to our buffer register |\verbatim@line| without expanding
+% them.
+% \begin{macrocode}
+\def\verbatim@addtoline#1{%
+ \verbatim@line\expandafter{\the\verbatim@line#1}}
+% \end{macrocode}
+% Processing a line inside a \texttt{verbatim} or \texttt{verbatim*}
+% environment means printing it.
+% \changes{v1.2c}{1989/10/31}{Changed \cs{@@par} to \cs{par} in
+% \cs{verbatim@processline}. Removed \cs{leavevmode} and \cs{null}
+% (i.e.\ the empty \cs{hbox}).}
+% Ending the line means that we have to begin a new paragraph.
+% We use |\par| for this purpose. Note that |\par|
+% is redefined in |\@verbatim| to force \TeX{} into horizontal
+% mode and to insert an empty box so that empty lines in the input
+% do appear in the output.
+% \changes{v1.2f}{1990/01/31}{\cs{verbatim@startline} removed.}
+% \begin{macrocode}
+\def\verbatim@processline{\the\verbatim@line\par}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\verbatim@finish}
+% As a default, |\verbatim@finish| processes the remaining
+% characters.
+% When this macro is called we are facing the following problem:
+% when the |\end{verbatim}|
+% command is encountered |\verbatim@processline| is called
+% to process the characters preceding the command on the same
+% line. If there are none, an empty line would be output if we
+% did not check for this case.
+%
+% If the line is empty |\the\verbatim@line| expands to
+% nothing. To test this we use a trick similar to that on p.\ 376
+% of the \TeX{}book, but with |$|\ldots|$| instead of
+% the |!| tokens. These |$| tokens can never have the same
+% category code as a |$| token that might possibly appear in the
+% token register |\verbatim@line|, as such a token will always have
+% been read with category code $12$ (other).
+% Note that |\ifcat| expands the following tokens so that
+% |\the\verbatim@line| is replaced by the accumulated
+% characters
+% \changes{v1.2d}{1989/11/29}{Changed \cs{ifx} to \cs{ifcat} test.}
+% \changes{v1.1b}{1989/10/18}{Corrected bug in if test (found by CRo).}
+% \begin{macrocode}
+\def\verbatim@finish{\ifcat$\the\verbatim@line$\else
+ \verbatim@processline\fi}
+% \end{macrocode}
+% \end{macro}
+%
+%
+% \subsection{The \texttt{verbatim} and \texttt{verbatim*} environments}
+%
+% \begin{macro}{\verbatim@font}
+% \changes{v1.2f}{1990/01/31}{\cs{@lquote} macro removed.}
+% \changes{v1.1b}{1989/10/18}{\cs{@noligs} removed. Code inserted
+% directly into \cs{verbatim@font}.}
+% \changes{v1.1a}{1989/10/16}{\cs{verbatim@font} added.}
+% \changes{v1.1a}{1989/10/16}{\cs{@noligs} added.}
+% \changes{v1.1a}{1989/10/16}{\cs{@lquote} added.}
+% We start by defining the macro |\verbatim@font| that is
+% to select the font and to set font-dependent parameters.
+% Then we expand |\@noligs| (defined in the \LaTeXe{} kernel). Among
+% possibly other things, it will go through |\verbatim@nolig@list|
+% to avoid certain ligatures.
+% |\verbatim@nolig@list| is a macro defined in the \LaTeXe{} kernel
+% to expand to
+% \begin{verbatim}
+% \do\`\do\<\do\>\do\,\do\'\do\-
+%\end{verbatim}
+% All the characters in this list can be part of a ligature in some
+% font or other.
+% \changes{v1.2f}{1990/01/31}{\cs{@lquote} macro removed.}
+% \changes{v1.4c}{1990/10/18}{Added \cs{leavevmode}.}
+% \changes{v1.4k}{1992/07/13}{Replaced Blank after $96$ by \cs{relax}.
+% (Proposed by Dan Dill.)}
+% \changes{v1.5}{1993/10/11}{Definition changed according to new code
+% in latex.tex and to avoid global definition.}
+% \changes{v1.5c}{1994/02/07}{Changed to use new font switching
+% commands.}
+% \changes{v1.5m}{2000/01/07}{Disable hyphenation even if the font
+% allows it.}
+% \changes{v1.5q}{2003/08/22}{Use \cs{@noligs}, as it is by now properly
+% defined in the \LaTeXe{} kernel.}
+% \begin{macrocode}
+\def\verbatim@font{\normalfont\ttfamily
+ \hyphenchar\font\m@ne
+ \@noligs}
+% \end{macrocode}
+% \end{macro}
+%
+%
+% \begin{macro}{\@verbatim}
+% \changes{v1.1a}{1989/10/16}{\cs{@verbatim} added.}
+% The macro |\@verbatim| sets up things properly.
+% First of all, the tokens of the |\every@verbatim| hook
+% are inserted.
+% Then a \texttt{trivlist} environment is started and its first
+% |\item| command inserted.
+% Each line of the \texttt{verbatim} or \texttt{verbatim*}
+% environment will be treated as a separate paragraph.
+% \changes{v1.2e}{1990/01/15}{Added \cs{every@verbatim} hook.}
+% \changes{v1.5b}{1994/01/24}{Removed optional argument of \cs{item}.}
+% \begin{macrocode}
+\def\@verbatim{\the\every@verbatim
+ \trivlist \item \relax
+% \end{macrocode}
+% \changes{v1.5b}{1994/01/24}{Set \texttt{@inlabel} switch to false.}
+% \changes{v1.5f}{1994/10/25}{Removed setting of \texttt{@inlabel}
+% switch again.}
+% \changes{v1.3c}{1990/02/26}{Removed extra vertical space.
+% Suggested by Frank Mittelbach.}
+% \changes{v1.5h}{1995/09/21}{Added the space again, since it is
+% necessary for correct vertical spacing if \texttt{verbatim}
+% is nested inside \texttt{quote}.}
+% The following extra vertical space is for compatibility with the
+% \LaTeX kernel: otherwise, using the |verbatim| package changes
+% the vertical spacing of a |verbatim| environment nested within a
+% |quote| environment.
+% \begin{macrocode}
+ \if@minipage\else\vskip\parskip\fi
+% \end{macrocode}
+% \changes{v1.4k}{1992/07/13}{Added setting for
+% \cs{@beginparpenalty}. Suggested by Frank Mittelbach.}
+% The paragraph parameters are set appropriately:
+% the penalty at the beginning of the environment,
+% left and right margins, paragraph indentation, the glue to
+% fill the last line, and the vertical space between paragraphs.
+% The latter space has to be zero since we do not want to add
+% extra space between lines.
+% \begin{macrocode}
+ \@beginparpenalty \predisplaypenalty
+ \leftskip\@totalleftmargin\rightskip\z@
+ \parindent\z@\parfillskip\@flushglue\parskip\z@
+% \end{macrocode}
+% \changes{v1.1b}{1989/10/18}{Added resetting of \cs{parshape}
+% if at beginning of a list.
+% (Problem pointed out by Chris Rowley.)}
+% There's one point to make here:
+% the \texttt{list} environment uses \TeX's |\parshape|
+% primitive to get a special indentation for the first line
+% of the list.
+% If the list begins with a \texttt{verbatim} environment
+% this |\parshape| is still in effect.
+% Therefore we have to reset this internal parameter explicitly.
+% We could do this by assigning $0$ to |\parshape|.
+% However, there is a simpler way to achieve this:
+% we simply tell \TeX{} to start a new paragraph.
+% As is explained on p.~103 of the \TeX{}book, this resets
+% |\parshape| to zero.
+% \changes{v1.1c}{1989/10/19}{Replaced explicit resetting of
+% \cs{parshape} by \cs{@@par}.}
+% \begin{macrocode}
+ \@@par
+% \end{macrocode}
+% We now ensure that |\par| has the correct definition,
+% namely to force \TeX{} into horizontal mode
+% and to include an empty box.
+% This is to ensure that empty lines do appear in the output.
+% Afterwards, we insert the |\interlinepenalty| since \TeX{}
+% does not add a penalty between paragraphs (here: lines)
+% by its own initiative. Otherwise a |verbatim| environment
+% could be broken across pages even if a |\samepage|
+% declaration were present.
+%
+% However, in a top-aligned minipage, this will result in an extra
+% empty line added at the top. Therefore, a slightly more
+% complicated construct is necessary.
+% One of the important things here is the inclusion of
+% |\leavevmode| as the first macro in the first line, for example,
+% a blank verbatim line is the first thing in a list item.
+% \changes{v1.2c}{1989/10/31}{Definition of \cs{par} added.
+% Ensures identical behaviour for
+% verbatim and \cs{verbatiminput}.
+% Problem pointed out by Chris.}
+% \changes{v1.4d}{1991/04/24}{\cs{penalty}\cs{interlinepenalty} added.
+% Necessary to avoid page breaks in
+% the scope of a \cs{samepage} declaration.}
+% \changes{v1.5b}{1994/01/24}{Improved definition of \cs{par} to work
+% under all circumstances.}
+% \changes{v1.5f}{1994/10/25}{\cs{leavevmode} added for first line.}
+% \begin{macrocode}
+ \def\par{%
+ \if@tempswa
+ \leavevmode\null\@@par\penalty\interlinepenalty
+ \else
+ \@tempswatrue
+ \ifhmode\@@par\penalty\interlinepenalty\fi
+ \fi}%
+% \end{macrocode}
+% But to avoid an error message when the environment
+% doesn't contain any text, we redefine |\@noitemerr|
+% which will in this case be called by |\endtrivlist|.
+% \changes{v1.4j}{1992/06/30}{Introduced warning instead of error
+% for empty body of verbatim text.
+% Suggested by Nelson Beebe.}
+% \begin{macrocode}
+ \def\@noitemerr{\@warning{No verbatim text}}%
+% \end{macrocode}
+% Now we call |\obeylines| to make the end of line character
+% active,
+% \begin{macrocode}
+ \obeylines
+% \end{macrocode}
+% change the category code of all special characters,
+% to $12$ (other).
+% \changes{v1.5i}{1996/06/04}{Moved \cs{verbatim@font} after
+% \cs{dospecials}.}
+% \begin{macrocode}
+ \let\do\@makeother \dospecials
+% \end{macrocode}
+% and switch to the font to be used.
+% \begin{macrocode}
+ \verbatim@font
+% \end{macrocode}
+% To avoid a breakpoint after the labels box, we remove the penalty
+% put there by the list macros: another use of |\unpenalty|!
+% \changes{v1.5f}{1994/10/25}{Change to \cs{everypar} added.}
+% \begin{macrocode}
+ \everypar \expandafter{\the\everypar \unpenalty}}
+% \end{macrocode}
+% \end{macro}
+%
+%
+% \begin{macro}{\verbatim}
+% \begin{macro}{\verbatim*}
+% Now we define the toplevel macros.
+% |\verbatim| is slightly changed:
+% after setting up things properly it calls
+% |\verbatim@start|.
+% \changes{v1.5l}{1999/12/14}{Added \cs{begingroup} for cases where
+% \cs{verbatim} is used directly, rather than in \cs{begin}: see
+% pr/3115.}
+% This is done inside a group, so that |\verbatim| can be used
+% directly, without |\begin|.
+% \begin{macrocode}
+\def\verbatim{\begingroup\@verbatim \frenchspacing\@vobeyspaces
+ \verbatim@start}
+% \end{macrocode}
+% |\verbatim*| is defined accordingly.
+% \begin{macrocode}
+\@namedef{verbatim*}{\begingroup\@verbatim\verbatim@start}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\endverbatim}
+% \begin{macro}{\endverbatim*}
+% To end the \texttt{verbatim} and \texttt{verbatim*}
+% environments it is only necessary to finish the
+% \texttt{trivlist} environment started in |\@verbatim| and
+% close the corresponding group.
+% \changes{v1.5l}{1999/12/14}{Added \cs{endgroup} for cases where
+% \cs{endverbatim} is used directly, rather than in \cs{end}: see
+% pr/3115.}
+% \changes{v1.5n}{2000/08/03}{Added \cs{@endpetrue}: needed when
+% faking such a \cs{end} (pr/3234).}
+% \changes{v1.5o}{2000/08/23}{Changed \cs{@endpetrue} to \cs{@doendpe}:
+% see (pr/3234).}
+% \begin{macrocode}
+\def\endverbatim{\endtrivlist\endgroup\@doendpe}
+\expandafter\let\csname endverbatim*\endcsname =\endverbatim
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+%
+% \subsection{The \texttt{comment} environment}
+%
+% \begin{macro}{\comment}
+% \begin{macro}{\endcomment}
+% \changes{v1.1c}{1989/10/19}{Added \cs{@bsphack}/\cs{@esphack} to the
+% \texttt{comment} environment. Suggested by Chris Rowley.}
+% The |\comment| macro is similar to |\verbatim*|.
+% However, we do not need to switch fonts or set special
+% formatting parameters such as |\parindent| or |\parskip|.
+% We need only set the category code of all special characters
+% to $12$ (other) and that of |^^M| (the end of line character)
+% to $13$ (active).
+% The latter is needed for macro parameter delimiter matching in
+% the internal macros defined below.
+% In contrast to the default definitions used by the
+% |\verbatim| and |\verbatim*| macros,
+% we define |\verbatim@addtoline| to throw away its argument
+% and |\verbatim@processline|, |\verbatim@startline|,
+% and |\verbatim@finish| to act as no-ops.
+% Then we call |\verbatim@|.
+% But the first thing we do is to call |\@bsphack| so that
+% this environment has no influence whatsoever upon the spacing.
+% \changes{v1.1c}{1989/10/19}{Changed \cs{verbatim@start} to
+% \cs{verbatim@}. Suggested by Chris Rowley.}
+% \changes{v1.1c}{1989/10/19}{\cs{verbatim@startline} and
+% \cs{verbatim@finish} are now
+% also redefined to do nothing.}
+% \begin{macrocode}
+\def\comment{\@bsphack
+ \let\do\@makeother\dospecials\catcode`\^^M\active
+ \let\verbatim@startline\relax
+ \let\verbatim@addtoline\@gobble
+ \let\verbatim@processline\relax
+ \let\verbatim@finish\relax
+ \verbatim@}
+% \end{macrocode}
+% |\endcomment| is very simple: it only calls
+% |\@esphack| to take care of the spacing.
+% The |\end| macro closes the group and therefore takes care
+% of restoring everything we changed.
+% \begin{macrocode}
+\let\endcomment=\@esphack
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+%
+%
+% \subsection{The main loop}
+%
+% Here comes the tricky part:
+% During the definition of the macros we need to use the special
+% characters |\|, |{|, and |}| not only with their
+% normal category codes,
+% but also with category code $12$ (other).
+% We achieve this by the following trick:
+% first we tell \TeX{} that |\|, |{|, and |}|
+% are the lowercase versions of |!|, |[|, and |]|.
+% Then we replace every occurrence of |\|, |{|, and |}|
+% that should be read with category code $12$ by |!|, |[|,
+% and |]|, respectively,
+% and give the whole list of tokens to |\lowercase|,
+% knowing that category codes are not altered by this primitive!
+%
+% But first we have ensure that
+% |!|, |[|, and |]| themselves have
+% the correct category code!
+% \changes{v1.3b}{1990/02/07}{Introduced \cs{vrb@catcodes} instead
+% of explicit setting of category codes.}
+% To allow special settings of these codes we hide their setting in
+% the macro |\vrb@catcodes|. If it is already defined our new
+% definition is skipped.
+% \begin{macrocode}
+\@ifundefined{vrb@catcodes}%
+ {\def\vrb@catcodes{%
+ \catcode`\!12\catcode`\[12\catcode`\]12}}{}
+% \end{macrocode}
+% This trick allows us to use this code for applications where other
+% category codes are in effect.
+%
+% We start a group to keep the category code changes local.
+% \begin{macrocode}
+\begingroup
+ \vrb@catcodes
+ \lccode`\!=`\\ \lccode`\[=`\{ \lccode`\]=`\}
+% \end{macrocode}
+% \changes{v1.2f}{1990/01/31}{Code for TABs removed.}
+% We also need the end-of-line character |^^M|,
+% as an active character.
+% If we were to simply write |\catcode`\^^M=\active|
+% then we would get an unwanted active end of line character
+% at the end of every line of the following macro definitions.
+% Therefore we use the same trick as above:
+% we write a tilde |~| instead of |^^M| and
+% pretend that the
+% latter is the lowercase variant of the former.
+% Thus we have to ensure now that the tilde character has
+% category code $13$ (active).
+% \begin{macrocode}
+ \catcode`\~=\active \lccode`\~=`\^^M
+% \end{macrocode}
+% The use of the |\lowercase| primitive leads to one problem:
+% the uppercase character `|C|' needs to be used in the
+% code below and its case must be preserved.
+% So we add the command:
+% \begin{macrocode}
+ \lccode`\C=`\C
+% \end{macrocode}
+% Now we start the token list passed to |\lowercase|.
+% We use the following little trick (proposed by Bernd Raichle):
+% The very first token in the token list we give to |\lowercase| is
+% the |\endgroup| primitive. This means that it is processed by
+% \TeX{} immediately after |\lowercase| has finished its operation,
+% thus ending the group started by |\begingroup| above. This avoids
+% the global definition of all macros.
+% \begin{macrocode}
+ \lowercase{\endgroup
+% \end{macrocode}
+% \begin{macro}{\verbatim@start}
+% The purpose of |\verbatim@start| is to check whether there
+% are any characters on the same line as the |\begin{verbatim}|
+% and to pretend that they were on a line by themselves.
+% On the other hand, if there are no characters remaining
+% on the current line we shall just find an end of line character.
+% |\verbatim@start| performs its task by first grabbing the
+% following character (its argument).
+% This argument is then compared to an active |^^M|,
+% the end of line character.
+% \begin{macrocode}
+ \def\verbatim@start#1{%
+ \verbatim@startline
+ \if\noexpand#1\noexpand~%
+% \end{macrocode}
+% If this is true we transfer control to |\verbatim@|
+% to process the next line. We use
+% |\next| as the macro which will continue the work.
+% \begin{macrocode}
+ \let\next\verbatim@
+% \end{macrocode}
+% Otherwise, we define |\next| to expand to a call
+% to |\verbatim@| followed by the character just
+% read so that it is reinserted into the text.
+% This means that those characters remaining on this line
+% are handled as if they formed a line by themselves.
+% \begin{macrocode}
+ \else \def\next{\verbatim@#1}\fi
+% \end{macrocode}
+% Finally we call |\next|.
+% \begin{macrocode}
+ \next}%
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\verbatim@}
+% The three macros |\verbatim@|, |\verbatim@@|,
+% and |\verbatim@@@| form the ``main loop'' of the
+% \texttt{verbatim} environment.
+% The purpose of |\verbatim@| is to read exactly one line
+% of input.
+% |\verbatim@@| and |\verbatim@@@| work together to
+% find out whether the four characters
+% |\end| (all with category code $12$ (other)) occur in that
+% line.
+% If so, |\verbatim@@@| will call
+% |\verbatim@test| to check whether this |\end| is
+% part of |\end{verbatim}| and will terminate the environment
+% if this is the case.
+% Otherwise we continue as if nothing had happened.
+% So let's have a look at the definition of |\verbatim@|:
+% \changes{v1.1a}{1989/10/16}{Replaced \cs{verbatim@@@} by \cs{@nil}.}
+% \begin{macrocode}
+ \def\verbatim@#1~{\verbatim@@#1!end\@nil}%
+% \end{macrocode}
+% Note that the |!| character will have been replaced by a
+% |\| with category code $12$ (other) by the |\lowercase|
+% primitive governing this code before the definition of this
+% macro actually takes place.
+% That means that
+% it takes the line, puts |\end| (four character tokens)
+% and |\@nil| (one control sequence token) as a
+% delimiter behind it, and
+% then calls |\verbatim@@|.
+% \end{macro}
+%
+% \begin{macro}{\verbatim@@}
+% |\verbatim@@| takes everything up to the next occurrence of
+% the four characters |\end| as its argument.
+% \begin{macrocode}
+ \def\verbatim@@#1!end{%
+% \end{macrocode}
+% That means: if they do not occur in the original line, then
+% argument |#1| is the
+% whole input line, and |\@nil| is the next token
+% to be processed.
+% However, if the four characters |\end| are part of the
+% original line, then
+% |#1| consists of the characters in front of |\end|,
+% and the next token is the following character (always remember
+% that the line was lengthened by five tokens).
+% Whatever |#1| may be, it is verbatim text,
+% so |#1| is added to the line currently built.
+% \begin{macrocode}
+ \verbatim@addtoline{#1}%
+% \end{macrocode}
+% The next token in the input stream
+% is of special interest to us.
+% Therefore |\futurelet| defines |\next| to be equal
+% to it before calling |\verbatim@@@|.
+% \begin{macrocode}
+ \futurelet\next\verbatim@@@}%
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\verbatim@@@}
+% \changes{v1.1a}{1989/10/16}{Replaced \cs{verbatim@@@} by
+% \cs{@nil} where used as delimiter.}
+% |\verbatim@@@| will now read the rest of the tokens on
+% the current line,
+% up to the final |\@nil| token.
+% \begin{macrocode}
+ \def\verbatim@@@#1\@nil{%
+% \end{macrocode}
+% If the first of the above two cases occurred, i.e.\ no
+% |\end| characters were on that line, |#1| is empty
+% and |\next| is equal to |\@nil|.
+% This is easily checked.
+% \begin{macrocode}
+ \ifx\next\@nil
+% \end{macrocode}
+% If so, this was a simple line.
+% We finish it by processing the line we accumulated so far.
+% Then we prepare to read the next line.
+% \changes{v1.2f}{1990/01/31}{Added \cs{verbatim@startline}.}
+% \begin{macrocode}
+ \verbatim@processline
+ \verbatim@startline
+ \let\next\verbatim@
+% \end{macrocode}
+% Otherwise we have to check what follows these |\end|
+% tokens.
+% \begin{macrocode}
+ \else
+% \end{macrocode}
+% Before we continue, it's a good idea to stop for a moment
+% and remember where we are:
+% We have just read the four character tokens |\end|
+% and must now check whether the name of the environment (surrounded
+% by braces) follows.
+% To this end we define a macro called |\@tempa|
+% that reads exactly one character and decides what to do next.
+% This macro should do the following: skip spaces until
+% it encounters either a left brace or the end of the line.
+% But it is important to remember which characters are skipped.
+% The |\end|\meta{optional spaces}|{| characters
+% may be part of the verbatim text, i.e.\ these characters
+% must be printed.
+%
+% Assume for example that the current line contains
+% \begin{verbatim*}
+% \end {AVeryLongEnvironmentName}
+%\end{verbatim*}
+% As we shall soon see, the scanning mechanism implemented here
+% will not find out that this is text to be printed until
+% it has read the right brace.
+% Therefore we need a way to accumulate the characters read
+% so that we can reinsert them if necessary.
+% The token register |\@temptokena| is used for this purpose.
+%
+% Before we do this we have to get rid of the superfluous
+% |\end| tokens at the end of the line.
+% \changes{v1.4j}{1992/06/30}{Removed use of \cs{toks@}. Suggested by
+% Bernd Raichle.}
+% To this end we define a temporary macro whose argument
+% is delimited by |\end\@nil| (four character tokens
+% and one control sequence token) to be used below
+% on the rest of the line, after appending a |\@nil| token to it.
+% (Note that this token can never appear in |#1|.)
+% We use the following definition of
+% |\@tempa| to get the rest of the line (after the first
+% |\end|).
+% \begin{macrocode}
+ \def\@tempa##1!end\@nil{##1}%
+% \end{macrocode}
+% We mentioned already that we use token register
+% |\@temptokena|
+% to remember the characters we skip, in case we need them again.
+% We initialize this with the |\end| we have thrown away
+% in the call to |\@tempa|.
+% \begin{macrocode}
+ \@temptokena{!end}%
+% \end{macrocode}
+% We shall now call |\verbatim@test|
+% to process the characters
+% remaining on the current line.
+% But wait a moment: we cannot simply call this macro
+% since we have already read the whole line.
+% Therefore we have to first expand the macro |\@tempa| to insert
+% them again after the |\verbatim@test| token.
+% A |^^M| character is appended to denote the end of the line.
+% (Remember that this character comes disguised as a tilde.)
+% \changes{v1.2}{1989/10/20}{Taken local definition of \cs{@tempa} out
+% of \cs{verbatim@@@} and introduced
+% \cs{verbatim@test} instead.}
+% \begin{macrocode}
+ \def\next{\expandafter\verbatim@test\@tempa#1\@nil~}%
+% \end{macrocode}
+% That's almost all, but we still have to
+% now call |\next| to do the work.
+% \begin{macrocode}
+ \fi \next}%
+% \end{macrocode}
+% \end{macro}
+%
+%
+% \begin{macro}{\verbatim@test}
+% \changes{v1.2}{1989/10/20}{Introduced \cs{verbatim@test}.}
+% We define |\verbatim@test| to investigate every token
+% in turn.
+% \begin{macrocode}
+ \def\verbatim@test#1{%
+% \end{macrocode}
+% First of all we set |\next| equal to |\verbatim@test|
+% in case this macro must call itself recursively in order to
+% skip spaces.
+% \begin{macrocode}
+ \let\next\verbatim@test
+% \end{macrocode}
+% We have to distinguish four cases:
+% \begin{enumerate}
+% \item The next token is a |^^M|, i.e.\ we reached
+% the end of the line. That means that nothing
+% special was found.
+% Note that we use |\if| for the following
+% comparisons so that the category code of the
+% characters is irrelevant.
+% \begin{macrocode}
+ \if\noexpand#1\noexpand~%
+% \end{macrocode}
+% We add the characters accumulated in token register
+% |\@temptokena| to the current line. Since
+% |\verbatim@addtoline| does not expand its argument,
+% we have to do the expansion at this point. Then we
+% |\let| |\next| equal to |\verbatim@|
+% to prepare to read the next line.
+% \changes{v1.2f}{1990/01/31}{Added \cs{verbatim@startline}.}
+% \begin{macrocode}
+ \expandafter\verbatim@addtoline
+ \expandafter{\the\@temptokena}%
+ \verbatim@processline
+ \verbatim@startline
+ \let\next\verbatim@
+% \end{macrocode}
+% \item A space character follows.
+% This is allowed, so we add it to |\@temptokena|
+% and continue.
+% \begin{macrocode}
+ \else \if\noexpand#1
+ \@temptokena\expandafter{\the\@temptokena#1}%
+% \end{macrocode}
+% \changes{v1.2f}{1990/01/31}{Code for TABs removed.}
+% \item An open brace follows.
+% This is the most interesting case.
+% We must now collect characters until we read the closing
+% brace and check whether they form the environment name.
+% This will be done by |\verbatim@testend|, so here
+% we let |\next| equal this macro.
+% Again we will process the rest of the line, character
+% by character.
+% \changes{v1.2}{1989/10/20}{Moved the initialization of
+% \cs{@tempc} from \cs{verbatim@testend} into
+% \cs{verbatim@test}.}
+% The characters forming the name of the environment will
+% be accumulated in |\@tempc|.
+% We initialize this macro to expand to nothing.
+% \changes{v1.3b}{1990/02/07}{\cs{noexpand} added.}
+% \begin{macrocode}
+ \else \if\noexpand#1\noexpand[%
+ \let\@tempc\@empty
+ \let\next\verbatim@testend
+% \end{macrocode}
+% Note that the |[| character will be a |{| when
+% this macro is defined.
+% \item Any other character means that the |\end| was part
+% of the verbatim text.
+% Add the characters to the current line and prepare to call
+% |\verbatim@| to process the rest of the line.
+% \changes{v1.0f}{1989/10/09}{Fixed \cs{end} \cs{end} bug
+% found by Chris Rowley}
+% \begin{macrocode}
+ \else
+ \expandafter\verbatim@addtoline
+ \expandafter{\the\@temptokena}%
+ \def\next{\verbatim@#1}%
+ \fi\fi\fi
+% \end{macrocode}
+% \end{enumerate}
+% The last thing this macro does is to call |\next|
+% to continue processing.
+% \begin{macrocode}
+ \next}%
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\verbatim@testend}
+% |\verbatim@testend| is called when
+% |\end|\meta{optional spaces}|{| was seen.
+% Its task is to scan everything up to the next |}|
+% and to call |\verbatim@@testend|.
+% If no |}| is found it must reinsert the characters it read
+% and return to |\verbatim@|.
+% The following definition is similar to that of
+% |\verbatim@test|:
+% it takes the next character and decides what to do.
+% \changes{v1.2}{1989/10/20}{Removed local definition of \cs{@tempa}
+% from \cs{verbatim@testend} which now
+% does the work itself.}
+% \begin{macrocode}
+ \def\verbatim@testend#1{%
+% \end{macrocode}
+% Again, we have four cases:
+% \begin{enumerate}
+% \item |^^M|: As no |}| is found in the current line,
+% add the characters to the buffer. To avoid a
+% complicated construction for expanding
+% |\@temptokena|
+% and |\@tempc| we do it in two steps. Then we
+% continue with |\verbatim@| to process the
+% next line.
+% \changes{v1.2f}{1990/01/31}{Added \cs{verbatim@startline}.}
+% \begin{macrocode}
+ \if\noexpand#1\noexpand~%
+ \expandafter\verbatim@addtoline
+ \expandafter{\the\@temptokena[}%
+ \expandafter\verbatim@addtoline
+ \expandafter{\@tempc}%
+ \verbatim@processline
+ \verbatim@startline
+ \let\next\verbatim@
+% \end{macrocode}
+% \item |}|: Call |\verbatim@@testend| to check
+% if this is the right environment name.
+% \changes{v1.3b}{1990/02/07}{\cs{noexpand} added.}
+% \begin{macrocode}
+ \else\if\noexpand#1\noexpand]%
+ \let\next\verbatim@@testend
+% \end{macrocode}
+% \changes{v1.0f}{1989/10/09}{Introduced check for
+% {\tt\string\verb!\string|!\string\!\string|} to fix
+% single brace bug found by Chris Rowley}
+% \item |\|: This character must not occur in the name of
+% an environment. Thus we stop collecting characters.
+% In principle, the same argument would apply to other
+% characters as well, e.g., |{|.
+% However, |\| is a special case, since it may be
+% the first character of |\end|. This means that
+% we have to look again for
+% |\end{|\meta{environment name}|}|.
+% Note that we prefixed the |!| by a |\noexpand|
+% primitive, to protect ourselves against it being an
+% active character.
+% \changes{v1.3b}{1990/02/07}{\cs{noexpand} added.}
+% \begin{macrocode}
+ \else\if\noexpand#1\noexpand!%
+ \expandafter\verbatim@addtoline
+ \expandafter{\the\@temptokena[}%
+ \expandafter\verbatim@addtoline
+ \expandafter{\@tempc}%
+ \def\next{\verbatim@!}%
+% \end{macrocode}
+% \item Any other character: collect it and continue.
+% We cannot use |\edef| to define |\@tempc|
+% since its replacement text might contain active
+% character tokens.
+% \begin{macrocode}
+ \else \expandafter\def\expandafter\@tempc\expandafter
+ {\@tempc#1}\fi\fi\fi
+% \end{macrocode}
+% \end{enumerate}
+% As before, the macro ends by calling itself, to
+% process the next character if appropriate.
+% \begin{macrocode}
+ \next}%
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\verbatim@@testend}
+% Unlike the previous macros |\verbatim@@testend| is simple:
+% it has only to check if the |\end{|\ldots|}|
+% matches the corresponding |\begin{|\ldots|}|.
+% \begin{macrocode}
+ \def\verbatim@@testend{%
+% \end{macrocode}
+% We use |\next| again to define the things that are
+% to be done.
+% Remember that the name of the current environment is
+% held in |\@currenvir|, the characters accumulated
+% by |\verbatim@testend| are in |\@tempc|.
+% So we simply compare these and prepare to execute
+% |\end{|\meta{current environment}|}|
+% macro if they match.
+% Before we do this we call |\verbatim@finish| to process
+% the last line.
+% We define |\next| via |\edef| so that
+% |\@currenvir| is replaced by its expansion.
+% Therefore we need |\noexpand| to inhibit the expansion
+% of |\end| at this point.
+% \begin{macrocode}
+ \ifx\@tempc\@currenvir
+ \verbatim@finish
+ \edef\next{\noexpand\end{\@currenvir}%
+% \end{macrocode}
+% Without this trick the |\end| command would not be able
+% to correctly check whether its argument matches the name of
+% the current environment and you'd get an
+% interesting \LaTeX{} error message such as:
+% \begin{verbatim}
+%! \begin{verbatim*} ended by \end{verbatim*}.
+%\end{verbatim}
+% But what do we do with the rest of the characters, those
+% that remain on that line?
+% We call |\verbatim@rescan| to take care of that.
+% Its first argument is the name of the environment just
+% ended, in case we need it again.
+% |\verbatim@rescan| takes the list of characters to be
+% reprocessed as its second argument.
+% (This token list was inserted after the current macro
+% by |\verbatim@@@|.)
+% Since we are still in an |\edef| we protect it
+% by means of|\noexpand|.
+% \begin{macrocode}
+ \noexpand\verbatim@rescan{\@currenvir}}%
+% \end{macrocode}
+% If the names do not match, we reinsert everything read up
+% to now and prepare to call |\verbatim@| to process
+% the rest of the line.
+% \begin{macrocode}
+ \else
+ \expandafter\verbatim@addtoline
+ \expandafter{\the\@temptokena[}%
+ \expandafter\verbatim@addtoline
+ \expandafter{\@tempc]}%
+ \let\next\verbatim@
+ \fi
+% \end{macrocode}
+% Finally we call |\next|.
+% \begin{macrocode}
+ \next}%
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\verbatim@rescan}
+% In principle |\verbatim@rescan| could be used to
+% analyse the characters remaining after the |\end{...}|
+% command and pretend that these were read
+% ``properly'', assuming ``standard'' category codes are in
+% force.\footnote{Remember that they were all read with
+% category codes $11$ (letter) and $12$ (other) so
+% that control sequences are not recognized as such.}
+% But this is not always possible (when there are unmatched
+% curly braces in the rest of the line).
+% Besides, we think that this is not worth the effort:
+% After a \texttt{verbatim} or \texttt{verbatim*} environment
+% a new line in the output is begun anyway,
+% and an |\end{comment}| can easily be put on a line by itself.
+% So there is no reason why there should be any text here.
+% For the benefit of the user who did put something there
+% (a comment, perhaps)
+% we simply issue a warning and drop them.
+% The method of testing is explained in Appendix~D, p.\ 376 of
+% the \TeX{}book. We use |^^M| instead of the |!|
+% character used there
+% since this is a character that cannot appear in |#1|.
+% The two |\noexpand| primitives are necessary to avoid
+% expansion of active characters and macros.
+%
+% One extra subtlety should be noted here: remember that
+% the token list we are currently building will first be
+% processed by the |\lowercase| primitive before \TeX{}
+% carries out the definitions.
+% This means that the `|C|' character in the
+% argument to the |\@warning| macro must be protected against
+% being changed to `|c|'. That's the reason why we added the
+% |\lccode`\C=`\C| assignment above.
+% We can now finish the argument to |\lowercase| as well as the
+% group in which the category codes were changed.
+% \begin{macrocode}
+ \def\verbatim@rescan#1#2~{\if\noexpand~\noexpand#2~\else
+ \@warning{Characters dropped after `\string\end{#1}'}\fi}}
+% \end{macrocode}
+% \end{macro}
+%
+% \subsection{The \cs{verbatiminput} command}
+%
+% \begin{macro}{\verbatim@in@stream}
+% We begin by allocating an input stream (out of the 16 available
+% input streams).
+%\iffalse
+% Vorstellbar ist auch der Aufruf von |`verbatiminput| innerhalb eines
+% |`verbatiminput| (z.B: wenn man |`input|-Anweisungen im zu lesenden
+% File hat und auch diese Files automatisch lesen will). Dies kann
+% man jedoch nur ermoeglichen, wenn man einen besseren Mechanismus
+% verwendet als es das simple, statische |`newread| darstellt.
+% Vorstellbar fuer eine neuere \LaTeX-Version ist eine (lokale)
+% Allokation des Streams durch ein |`open| und eine Freigabe des
+% Streams durch |`close| oder Verlassen der Gruppe.
+%\fi
+% \begin{macrocode}
+\newread\verbatim@in@stream
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\verbatim@readfile}
+% The macro |\verbatim@readfile| encloses the main loop by calls to
+% the macros |\verbatim@startline| and |\verbatim@finish|,
+% respectively. This makes sure
+% that the user can initialize and finish the command when the file
+% is empty or doesn't exist. The \texttt{verbatim} environment has a
+% similar behaviour when called with an empty text.
+% \begin{macrocode}
+\def\verbatim@readfile#1{%
+ \verbatim@startline
+% \end{macrocode}
+% When the file is not found we issue a warning.
+% \begin{macrocode}
+ \openin\verbatim@in@stream #1\relax
+ \ifeof\verbatim@in@stream
+ \typeout{No file #1.}%
+ \else
+% \end{macrocode}
+% At this point we pass the name of the file to |\@addtofilelist|
+% so that its appears appears in the output of a |\listfiles|
+% command.
+% \changes{v1.5j}{1996/09/25}{Add \cs{@addtofilelist} and
+% \cs{ProvidesFile} so that the name of the file
+% read in appears in the \cs{listfiles} output (Omission pointed
+% out by Patrick W.~Daly).}
+% In addition, we use |\ProvidesFile| to make a log entry in the
+% transcript file and to distinguish files read in via
+% |\verbatiminput| from others.
+% \begin{macrocode}
+ \@addtofilelist{#1}%
+ \ProvidesFile{#1}[(verbatim)]%
+% \end{macrocode}
+% While reading from the file it is useful to switch off the
+% recognition of the end-of-line character. This saves us stripping
+% off spaces from the contents of the line.
+% \begin{macrocode}
+ \expandafter\endlinechar\expandafter\m@ne
+ \expandafter\verbatim@read@file
+ \expandafter\endlinechar\the\endlinechar\relax
+ \closein\verbatim@in@stream
+ \fi
+ \verbatim@finish
+}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\verbatim@read@file}
+% All the work is done in |\verbatim@read@file|. It reads the input
+% file line by line and recursively calls itself until the end of
+% the file.
+% \begin{macrocode}
+\def\verbatim@read@file{%
+ \read\verbatim@in@stream to\next
+ \ifeof\verbatim@in@stream
+ \else
+% \end{macrocode}
+% For each line we call |\verbatim@addtoline| with the contents of
+% the line. \hskip0pt plus 3cm\penalty0\hskip0pt plus -3cm
+% |\verbatim@processline| is called next.
+% \begin{macrocode}
+ \expandafter\verbatim@addtoline\expandafter{\next}%
+ \verbatim@processline
+% \end{macrocode}
+% After processing the line we call |\verbatim@startline| to
+% initialize all before we read the next line.
+% \begin{macrocode}
+ \verbatim@startline
+% \end{macrocode}
+% Without |\expandafter| each call of |\verbatim@read@file| uses
+% space in \TeX's input stack.\footnote{A standard \TeX\ would
+% report an overflow error if you try to read a file with more than
+% ca.\ 200~lines. The same error occurs if the first line of code
+% in \S 390 of \textsl{``TeX: The Program''\/} is missing.}
+% \begin{macrocode}
+ \expandafter\verbatim@read@file
+ \fi
+}
+% \end{macrocode}
+% \end{macro}
+%
+%
+% \begin{macro}{\verbatiminput}
+% |\verbatiminput| first starts a group to keep font and category
+% changes local.
+% Then it calls the macro |\verbatim@input| with additional
+% arguments, depending on whether an asterisk follows.
+% \begin{macrocode}
+\def\verbatiminput{\begingroup
+ \@ifstar{\verbatim@input\relax}%
+ {\verbatim@input{\frenchspacing\@vobeyspaces}}}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\verbatim@input}
+% \changes{1.5k}{1997/04/30}{Have \cs{verbatim@input} check for
+% existence of file.}
+% |\verbatim@input| first checks whether the file exists, using
+% the standard macro |\IfFileExists| which leaves the name of the
+% file found in |\@filef@und|.
+% Then everything is set up as in the |\verbatim| macro.
+% \begin{macrocode}
+\def\verbatim@input#1#2{%
+ \IfFileExists {#2}{\@verbatim #1\relax
+% \end{macrocode}
+% Then it reads in the file, finishes off the \texttt{trivlist}
+% environment started by |\@verbatim| and closes the group.
+% This restores everything to its normal settings.
+% \begin{macrocode}
+ \verbatim@readfile{\@filef@und}\endtrivlist\endgroup\@doendpe}%
+% \end{macrocode}
+% If the file is not found a more or less helpful message is
+% printed. The final |\endgroup| is needed to close the group
+% started in |\verbatiminput| above.
+% \begin{macrocode}
+ {\typeout {No file #2.}\endgroup}}
+%</package>
+% \end{macrocode}
+% \end{macro}
+%
+%
+% \subsection{Getting verbatim text into arguments.}
+%
+% One way of achieving this is to define a macro (command) whose
+% expansion is the required verbatim text. This command can then be
+% used anywhere that the verbatim text is required. It can be used in
+% arguments, even moving ones, but it is fragile (at least, the
+% version here is).
+%
+% Here is some code which claims to provide this. It is a much revised
+% version of something I (Chris) did about 2 years ago. Maybe it needs
+% further revision.
+%
+% It is only intended as an extension to |\verb|, not to the
+% \texttt{verbatim} environment. It should therefore, perhaps, treat
+% line-ends similarly to whatever is best for |\verb|.
+%
+% \begin{macro}{\newverbtext}
+% This is the command to produce a new macro whose expansion is
+% verbatim text. This command itself cannot be used in arguments,
+% of course! It is used as follows:
+%
+% \begin{verbatim}
+% \newverbtext{\myverb}"^%{ &~_\}}@ #"
+% \end{verbatim}
+%
+% The rules for delimiting the verbatim text are the same as those for
+% |\verb|.
+%
+% \begin{macrocode}
+%<*verbtext>
+\def \newverbtext {%
+ \@ifstar {\@tempswatrue \@verbtext }{\@tempswafalse \@verbtext *}%
+}
+% \end{macrocode}
+% \end{macro}
+% I think that a temporary switch is safe here: if not, then
+% suitable |\let|s can be used.
+% \changes{v1.5i}{1996/06/04}{Moved processing of
+% \cs{verbatim@nolig@list} after \cs{dospecials}.}
+% \changes{v1.5p}{2001/03/12}{Added missing right brace in
+% definition of \cs{@verbtext} (PR 3314).}
+% \begin{macrocode}
+\def \@verbtext *#1#2{%
+ \begingroup
+ \let\do\@makeother \dospecials
+ \let\do\do@noligs \verbatim@nolig@list
+ \@vobeyspaces
+ \catcode`#2\active
+ \catcode`~\active
+ \lccode`\~`#2%
+ \lowercase
+% \end{macrocode}
+% We use a temporary macro here and a trick so that the definition of
+% the command itself can be done inside the group and be a local
+% definition (there may be better ways to achieve this).
+% \begin{macrocode}
+ {\def \@tempa ##1~%
+ {\whitespaces
+% \end{macrocode}
+% If these |\noexpand|s were |\noexpand\protect\noexpand|, would
+% this make these things robust?
+% \begin{macrocode}
+ \edef #1{\noexpand \@verbtextmcheck
+ \bgroup
+ \if@tempswa
+ \noexpand \visiblespaces
+ \fi
+ \noexpand \@verbtextsetup
+ ##1%
+ \egroup}%
+ }%
+ \expandafter\endgroup\@tempa
+ }
+}
+% \end{macrocode}
+% This sets up the correct type of group for the mode: it must not
+% be expanded at define time!
+% \begin{macrocode}
+\def \@verbtextmcheck {%
+ \relax\ifmmode
+ \hbox
+ \else
+ \leavevmode
+ \null
+ \fi
+}
+% \end{macrocode}
+% This contains other things which should not be expanded during the
+% definition.
+% \begin{macrocode}
+\def \@verbtextsetup {%
+ \frenchspacing
+ \verbatim@font
+ \verbtextstyle
+}
+% \end{macrocode}
+% The command |\verbtextstyle| is a document-level hook which can be
+% used to override the predefined typographic treatment of commands
+% defined with |\newverbtext| commands.
+%
+% |\visiblespaces| and |\whitespaces| are examples of possible values
+% of this hook.
+% \begin{macrocode}
+\let \verbtextstyle \relax
+\def \visiblespaces {\chardef \ 32\relax}
+\def \whitespaces {\let \ \@@space}
+\let \@@space \ %
+%</verbtext>
+% \end{macrocode}
+%
+%
+% \section{Testing the implementation}
+%
+% For testing the implementation and for demonstration we provide
+% an extra file. It can be extracted by using the conditional
+% `\textsf{testdriver}'. It uses a small input file called
+% `\texttt{verbtest.tst}' that is distributed separately.
+% Again, we use individual `+' guards.
+% \begin{macrocode}
+%<*testdriver>
+\documentclass{article}
+
+\usepackage{verbatim}
+
+\newenvironment{myverbatim}%
+ {\endgraf\noindent MYVERBATIM:\endgraf\verbatim}%
+ {\endverbatim}
+
+\makeatletter
+
+\newenvironment{verbatimlisting}[1]%
+ {\def\verbatim@startline{\input{#1}%
+ \def\verbatim@startline{\verbatim@line{}}%
+ \verbatim@startline}%
+ \verbatim}{\endverbatim}
+
+\newwrite\verbatim@out
+
+\newenvironment{verbatimwrite}[1]%
+ {\@bsphack
+ \immediate\openout \verbatim@out #1
+ \let\do\@makeother\dospecials\catcode`\^^M\active
+ \def\verbatim@processline{%
+ \immediate\write\verbatim@out{\the\verbatim@line}}%
+ \verbatim@start}%
+ {\immediate\closeout\verbatim@out\@esphack}
+
+\makeatother
+
+\addtolength{\textwidth}{30pt}
+
+\begin{document}
+
+\typeout{}
+\typeout{===> Expect ``characters dropped''
+ warning messages in this test! <====}
+\typeout{}
+
+Text Text Text Text Text Text Text Text Text Text Text
+Text Text Text Text Text Text Text Text Text Text Text
+Text Text Text Text Text Text Text Text Text Text Text
+ \begin{verbatim}
+ test
+ \end{verbatim*}
+ test
+ \end{verbatim
+ test of ligatures: <`!`?`>
+ \endverbatim
+ test
+ \end verbatim
+ test
+ test of end of line:
+ \end
+ {verbatim}
+ \end{verbatim} Further text to be typeset: $\alpha$.
+Text Text Text Text Text Text Text Text Text Text Text
+Text Text Text Text Text Text Text Text Text Text Text
+Text Text Text Text Text Text Text Text Text Text Text
+ \begin{verbatim*}
+ test
+ test
+ \end {verbatim*}
+Text Text Text Text Text Text Text Text Text Text Text
+Text Text Text Text Text Text Text Text Text Text Text
+Text Text Text Text Text Text Text Text Text Text Text
+ \begin{verbatim*} bla bla
+ test
+ test
+ \end {verbatim*}
+Text Text Text Text Text Text Text Text Text Text Text
+Text Text Text Text Text Text Text Text Text Text Text
+Text Text Text Text Text Text Text Text Text Text Text
+Text Text Text Text Text Text Text Text Text Text Text
+
+First of Chris Rowley's fiendish tests:
+\begin{verbatim}
+the double end test<text>
+\end\end{verbatim} or even \end \end{verbatim}
+%
+%not \end\ended??
+%\end{verbatim}
+
+Another of Chris' devils:
+\begin{verbatim}
+the single brace test<text>
+\end{not the end\end{verbatim}
+%
+%not \end}ed??
+%\end{verbatim}
+Back to my own tests:
+ \begin{myverbatim}
+ test
+ test
+ \end {myverbatim} rest of line
+Text Text Text Text Text Text Text Text Text Text Text
+Text Text Text Text Text Text Text Text Text Text Text
+Text Text Text Text Text Text Text Text Text Text Text
+
+Test of empty verbatim:
+\begin{verbatim}
+\end{verbatim}
+Text Text Text Text Text Text Text Text Text Text Text
+Text Text Text Text Text Text Text Text Text Text Text
+Text Text Text Text Text Text Text Text Text Text Text
+ \begin {verbatimlisting}{verbtest.tex}
+ Additonal verbatim text
+ ...
+ \end{verbatimlisting}
+And here for listing a file:
+ \verbatiminput{verbtest.tex}
+And again, with explicit spaces:
+ \verbatiminput*{verbtest.tex}
+Text Text Text Text Text Text Text Text Text Text Text
+Text Text Text Text Text Text Text Text Text Text Text
+Text Text Text Text Text Text Text Text Text Text Text
+ \begin{comment}
+ test
+ \end{verbatim*}
+ test
+ \end {comment
+ test
+ \endverbatim
+ test
+ \end verbatim
+ test
+ \end {comment} Further text to be typeset: $\alpha$.
+Text Text Text Text Text Text Text Text Text Text Text
+Text Text Text Text Text Text Text Text Text Text Text
+Text Text Text Text Text Text Text Text Text Text Text
+ \begin{comment} bla bla
+ test
+ test
+ \end {comment}
+Text Text Text Text Text Text Text Text Text Text Text
+Text Text Text Text Text Text Text Text Text Text Text
+Text Text Text Text Text Text Text Text Text Text Text
+Text Text Text Text Text Text Text Text Text Text Text
+
+\begin{verbatimwrite}{verbtest.txt}
+asfa<fa<df
+sdfsdfasd
+asdfa<fsa
+\end{verbatimwrite}
+
+\end{document}
+%</testdriver>
+% \end{macrocode}
+%
+%
+% \Finale
+%
+\endinput
+%% \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 \~}
+%%
diff --git a/Master/texmf-dist/source/latex/tools/xr.dtx b/Master/texmf-dist/source/latex/tools/xr.dtx
new file mode 100644
index 00000000000..de50c9f674c
--- /dev/null
+++ b/Master/texmf-dist/source/latex/tools/xr.dtx
@@ -0,0 +1,172 @@
+% \iffalse meta-comment
+%
+% Copyright 1993 1994 1995 1996 1997 1998 1999 2000 2001 2002 2003
+% The LaTeX3 Project and any individual authors listed elsewhere
+% in this file.
+%
+% This file is part of the Standard LaTeX `Tools Bundle'.
+% -------------------------------------------------------
+%
+% It 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.3 or later is part of all distributions of LaTeX
+% version 2003/12/01 or later.
+%
+% The list of all files belonging to the LaTeX `Tools Bundle' is
+% given in the file `manifest.txt'.
+%
+% \fi
+% \iffalse
+%% File: xr.dtx Copyright (C) 1994-1994 David Carlisle
+%
+%<package>\NeedsTeXFormat{LaTeX2e}
+%<package>\ProvidesPackage{xr}
+%<package> [1994/05/28 v5.02 eXternal References (DPC)]
+%
+%<*driver>
+\documentclass{ltxdoc}
+\usepackage{xr}
+\GetFileInfo{xr.sty}
+\begin{document}
+\title{The \textsf{xr} package\thanks{This file
+ has version number \fileversion, last
+ revised \filedate.}}
+\author{David Carlisle\thanks{%
+ The Author of Versions 1--4 was Jean-Pierre Drucbert}\\
+ carlisle@cs.man.ac.uk}
+\date{\filedate}
+\maketitle
+\DocInput{xr.dtx}
+\end{document}
+%</driver>
+% \fi
+%
+% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%
+% \CheckSum{87}
+%
+% \changes{v5.00}{1993/07/07}
+% {First DPC version (by agreement with J-PD). New mechanism
+% (\cmd{\read} instead of \cmd\input).}
+%
+% \changes{v5.01}{1993/07/20}{Fix bug added by DPC, v5.00 did not import
+% aux files of \cmd\include'ed files. (Reported by J-PD)}
+%
+% \changes{v5.02}{1994/05/28}{Update for LaTeX2e}
+%
+%
+% This package implements a system for eXternal References.
+%
+% If one document needs to refer to sections of another, say |aaa.tex|,
+% then this package may be loaded in the main file, and the command\\
+% |\externaldocument{aaa}|\\
+% given in the preamble.
+%
+% Then you may use |\ref| and |\pageref| to refer to anything which has
+% been given a |\label| in either |aaa.tex| or the main document.
+% You may declare any number of such external documents.
+%
+% If any of the external documents, or the main document, use the same
+% |\label| then an error will occur as the label will be multiply
+% defined. To overcome this problem |\externaldocument| has an optional
+% argument. If you declare |\externaldocument[A-]{aaa}| Then all
+% references from |aaa| are prefixed by |A-|. So for instance, if a
+% section of |aaa| had |\label{intro}|, then this could be referenced
+% with |\ref{A-intro}|. The prefix need not be |A-|, it can be any
+% string chosen to ensure that all the labels imported from external
+% files are unique. Note however that if your style declares certain
+% active characters (|:| in French, |"| in German) then these
+% characters can not usually be used in |\label|, and similarly may not
+% be used in the optional argument to |\externaldocument|.
+%
+% \StopEventually{}
+%
+% \section{The macros}
+%
+% \begin{macrocode}
+%<*package>
+% \end{macrocode}
+%
+% Check for the optional argument.
+% \begin{macrocode}
+\def\externaldocument{\@ifnextchar[\XR@{\XR@[]}}
+% \end{macrocode}
+%
+% Save the optional prefix. Start processing the first |aux| file.
+% \begin{macrocode}
+\def\XR@[#1]#2{{%
+ \makeatletter
+ \def\XR@prefix{#1}%
+ \XR@next#2.aux\relax\\}}
+% \end{macrocode}
+%
+% Process the next |aux| file in the list and remove it from the head of
+% the list of files to process.
+% \begin{macrocode}
+\def\XR@next#1\relax#2\\{%
+ \edef\XR@list{#2}%
+ \XR@loop{#1}}
+% \end{macrocode}
+%
+% Check whether the list of |aux| files is empty.
+% \begin{macrocode}
+\def\XR@aux{%
+ \ifx\XR@list\@empty\else\expandafter\XR@explist\fi}
+% \end{macrocode}
+%
+
+% Expand the list of aux files, and call |\XR@next| to process the first
+% one.
+% \begin{macrocode}
+\def\XR@explist{\expandafter\XR@next\XR@list\\}
+% \end{macrocode}
+%
+% If the |aux| file exists, loop through line by line, looking for
+% |\newlabel| and |\@input|. Otherwise process the next file in the
+% list.
+% \begin{macrocode}
+\def\XR@loop#1{\openin\@inputcheck#1\relax
+ \ifeof\@inputcheck
+ \PackageWarning{xr}{^^JNo file #1^^JLABELS NOT IMPORTED.^^J}%
+ \expandafter\XR@aux
+ \else
+ \PackageInfo{xr}{IMPORTING LABELS FROM #1}%
+ \expandafter\XR@read\fi}
+% \end{macrocode}
+%
+% Read the next line of the aux file.
+% \begin{macrocode}
+\def\XR@read{%
+ \read\@inputcheck to\XR@line
+% \end{macrocode}
+% The |...| make sure that |\XR@test| always has sufficient arguments.
+% \begin{macrocode}
+ \expandafter\XR@test\XR@line...\XR@}
+% \end{macrocode}
+%
+% Look at the first token of the line.
+% If it is |\newlabel|, do the |\newlabel|. If it is |\@input|, add the
+% filename to the list of files to process. Otherwise ignore.
+% Go around the loop if not at end of file. Finally process the next
+% file in the list.
+% \begin{macrocode}
+\long\def\XR@test#1#2#3#4\XR@{%
+ \ifx#1\newlabel
+ \newlabel{\XR@prefix#2}{#3}%
+ \else\ifx#1\@input
+ \edef\XR@list{\XR@list#2\relax}%
+ \fi\fi
+ \ifeof\@inputcheck\expandafter\XR@aux
+ \else\expandafter\XR@read\fi}
+% \end{macrocode}
+%
+% \begin{macrocode}
+%</package>
+% \end{macrocode}
+%
+% \Finale
+%
+
diff --git a/Master/texmf-dist/source/latex/tools/xspace.dtx b/Master/texmf-dist/source/latex/tools/xspace.dtx
new file mode 100644
index 00000000000..1d3c2ff1642
--- /dev/null
+++ b/Master/texmf-dist/source/latex/tools/xspace.dtx
@@ -0,0 +1,144 @@
+% \iffalse meta-comment
+%
+% Copyright 1993 1994 1995 1996 1997 1998 1999 2000 2001 2002 2003
+% The LaTeX3 Project and any individual authors listed elsewhere
+% in this file.
+%
+% This file is part of the Standard LaTeX `Tools Bundle'.
+% -------------------------------------------------------
+%
+% It 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.3 or later is part of all distributions of LaTeX
+% version 2003/12/01 or later.
+%
+% The list of all files belonging to the LaTeX `Tools Bundle' is
+% given in the file `manifest.txt'.
+%
+% \fi
+% \iffalse
+%% File: xspace.dtx Copyright (C) 1991-1996 David Carlisle
+%
+%<*dtx>
+ \ProvidesFile{xspace.dtx}
+%</dtx>
+%<package>\NeedsTeXFormat{LaTeX2e}
+%<package>\ProvidesPackage{xspace}
+%<driver>\ProvidesFile{xspace.drv}
+% \fi
+% \ProvidesFile{xspace.dtx}
+ [1997/10/13 v1.06 Space after command names (DPC)]
+%
+% \iffalse
+%<*driver>
+\documentclass{ltxdoc}
+\usepackage{xspace}
+\begin{document}
+\DocInput{xspace.dtx}
+\end{document}
+%</driver>
+% \fi
+%
+% \GetFileInfo{xspace.dtx}
+% \title{The \textsf{xspace} package\thanks{This file
+% has version number \fileversion, last
+% revised \filedate.}}
+% \author{David Carlisle}
+% \date{\filedate}
+% \maketitle
+%
+% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%
+% \CheckSum{87}
+%
+% \changes{v1.00}{1991/08/30}{Initial version}
+% \changes{v1.01}{1992/06/26}{Re-issue for the new doc and docstrip}
+% \changes{v1.02}{1994/01/31}{Re-issue for LaTeX2e (no change to code)}
+%
+% \begin{abstract}
+% |\xspace| should be used at the end of a macro designed to be used
+% mainly in text. It adds a space unless the macro is followed by
+% certain punctuation characters.
+% \end{abstract}
+%
+% \section{Introduction}
+% After |\newcommand{\gb}{Great Britain\xspace}|\\
+% \newcommand{\gb}{Great Britain\xspace}
+% |\gb is a very nice place to live.|\\
+% \gb is a very nice place to live.\\
+% |\gb, a small island off the coast of France.|\\
+% \gb, a small island off the coast of France.
+%
+% |\xspace| saves the user from having to type \verb*+\ + or |{}| after
+% most occurrences of a macro name in text. However if either of these
+% constructions follows |\xspace|, a space is not added by |\xspace|.
+% This means that it is safe to add |\xspace| to the end of an existing
+% macro without making too many changes in your document.
+%
+% Sometimes |\xspace| may make the wrong decision, and add a space when
+% it is not required. In these cases follow the macro with |{}|, as this
+% has the effect of suppressing the space.
+%
+% Note that this package must be loaded \emph{after} any language (or
+% other) packages that make punctuation characters `active'.
+%
+% \StopEventually{}
+%
+% \section{The Macros}
+%
+% \begin{macrocode}
+%<*package>
+% \end{macrocode}
+%
+% \begin{macro}{\xspace}
+% |\xspace| just looks ahead, and then calls |\@xspace|.
+% \changes{v1.03}{1994/11/15}{Make robust}
+% \begin{macrocode}
+\DeclareRobustCommand\xspace{\futurelet\@let@token\@xspace}
+% \end{macrocode}
+% \end{macro}
+% \begin{macro}{\@xspace}
+% If the next token is one of a specified list of characters, do
+% nothing, otherwise add a space. If you often use a different
+% punctuation character, add the appropriate line (do not forget the
+% |\fi| at the end!)
+% \changes{v1.03}{1994/11/15}{Add exclamation mark}
+% \changes{v1.04}{1996/05/17}{Add slash}
+% \changes{v1.05}{1996/12/06}{Add space for alltt etc. tools/2322}
+% \changes{v1.06}{1997/10/13}{Add normal space. tools/2632}
+% \begin{macrocode}
+\def\@xspace{%
+ \ifx\@let@token\bgroup\else
+ \ifx\@let@token\egroup\else
+ \ifx\@let@token\/\else
+ \ifx\@let@token\ \else
+ \ifx\@let@token~\else
+ \ifx\@let@token.\else
+ \ifx\@let@token!\else
+ \ifx\@let@token,\else
+ \ifx\@let@token:\else
+ \ifx\@let@token;\else
+ \ifx\@let@token?\else
+ \ifx\@let@token/\else
+ \ifx\@let@token'\else
+ \ifx\@let@token)\else
+ \ifx\@let@token-\else
+ \ifx\@let@token\@xobeysp\else
+ \ifx\@let@token\space\else
+ \ifx\@let@token\@sptoken\else
+ \space
+% \end{macrocode}
+% When I first wrote this there were about half a dozen |\fi| here,
+% and I thought that was bad enough.
+% \begin{macrocode}
+ \fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi}
+%</package>
+% \end{macrocode}
+% \end{macro}
+%
+% \Finale
+%
+