From 8eb89f2adefbbdc3005c34350665a94992d4b300 Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Wed, 11 Jan 2006 23:58:32 +0000 Subject: trunk/Master/texmf-dist/source/latex/tools git-svn-id: svn://tug.org/texlive/trunk@559 c570f23f-e606-0410-a88d-b1316a301751 --- Master/texmf-dist/source/latex/tools/afterpage.dtx | 384 +++ Master/texmf-dist/source/latex/tools/array.dtx | 2820 ++++++++++++++++ Master/texmf-dist/source/latex/tools/bm.dtx | 1636 +++++++++ Master/texmf-dist/source/latex/tools/calc.dtx | 950 ++++++ Master/texmf-dist/source/latex/tools/dcolumn.dtx | 360 ++ Master/texmf-dist/source/latex/tools/delarray.dtx | 205 ++ Master/texmf-dist/source/latex/tools/enumerate.dtx | 335 ++ Master/texmf-dist/source/latex/tools/fileerr.dtx | 137 + Master/texmf-dist/source/latex/tools/fontsmpl.dtx | 352 ++ Master/texmf-dist/source/latex/tools/ftnright.dtx | 995 ++++++ Master/texmf-dist/source/latex/tools/hhline.dtx | 321 ++ .../texmf-dist/source/latex/tools/indentfirst.dtx | 75 + Master/texmf-dist/source/latex/tools/layout.dtx | 1024 ++++++ Master/texmf-dist/source/latex/tools/longtable.dtx | 2146 ++++++++++++ Master/texmf-dist/source/latex/tools/multicol.dtx | 3472 ++++++++++++++++++++ Master/texmf-dist/source/latex/tools/rawfonts.dtx | 218 ++ Master/texmf-dist/source/latex/tools/showkeys.dtx | 796 +++++ Master/texmf-dist/source/latex/tools/somedefs.dtx | 171 + Master/texmf-dist/source/latex/tools/tabularx.dtx | 896 +++++ Master/texmf-dist/source/latex/tools/theorem.dtx | 1163 +++++++ Master/texmf-dist/source/latex/tools/tools.ins | 208 ++ Master/texmf-dist/source/latex/tools/trace.dtx | 708 ++++ Master/texmf-dist/source/latex/tools/varioref.dtx | 1903 +++++++++++ Master/texmf-dist/source/latex/tools/verbatim.dtx | 1881 +++++++++++ Master/texmf-dist/source/latex/tools/xr.dtx | 172 + Master/texmf-dist/source/latex/tools/xspace.dtx | 144 + 26 files changed, 23472 insertions(+) create mode 100644 Master/texmf-dist/source/latex/tools/afterpage.dtx create mode 100644 Master/texmf-dist/source/latex/tools/array.dtx create mode 100644 Master/texmf-dist/source/latex/tools/bm.dtx create mode 100644 Master/texmf-dist/source/latex/tools/calc.dtx create mode 100644 Master/texmf-dist/source/latex/tools/dcolumn.dtx create mode 100644 Master/texmf-dist/source/latex/tools/delarray.dtx create mode 100644 Master/texmf-dist/source/latex/tools/enumerate.dtx create mode 100644 Master/texmf-dist/source/latex/tools/fileerr.dtx create mode 100644 Master/texmf-dist/source/latex/tools/fontsmpl.dtx create mode 100644 Master/texmf-dist/source/latex/tools/ftnright.dtx create mode 100644 Master/texmf-dist/source/latex/tools/hhline.dtx create mode 100644 Master/texmf-dist/source/latex/tools/indentfirst.dtx create mode 100644 Master/texmf-dist/source/latex/tools/layout.dtx create mode 100644 Master/texmf-dist/source/latex/tools/longtable.dtx create mode 100644 Master/texmf-dist/source/latex/tools/multicol.dtx create mode 100644 Master/texmf-dist/source/latex/tools/rawfonts.dtx create mode 100644 Master/texmf-dist/source/latex/tools/showkeys.dtx create mode 100644 Master/texmf-dist/source/latex/tools/somedefs.dtx create mode 100644 Master/texmf-dist/source/latex/tools/tabularx.dtx create mode 100644 Master/texmf-dist/source/latex/tools/theorem.dtx create mode 100644 Master/texmf-dist/source/latex/tools/tools.ins create mode 100644 Master/texmf-dist/source/latex/tools/trace.dtx create mode 100644 Master/texmf-dist/source/latex/tools/varioref.dtx create mode 100644 Master/texmf-dist/source/latex/tools/verbatim.dtx create mode 100644 Master/texmf-dist/source/latex/tools/xr.dtx create mode 100644 Master/texmf-dist/source/latex/tools/xspace.dtx (limited to 'Master/texmf-dist/source/latex/tools') 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 +% +%\NeedsTeXFormat{LaTeX2e} +%\ProvidesPackage{afterpage} +% [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} +% +% \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} +% +% \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} +% +% \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} +% +% \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}} +% +% \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} +% +%\NeedsTeXFormat{LaTeX2e} +%\ProvidesPackage{bm} +%\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} +% +% \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} +% +% \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} +% +%\NeedsTeXFormat{LaTeX2e} +%\ProvidesPackage{calc} +% \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} +% +% \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 \, and \textit{len} is replaced by +% \. The formal syntax of \ and +% \ 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 \. 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 \. \LaTeX\ length commands correspond to +% \TeX's dimen (for rigid lengths) and skip (for rubber lengths) +% registers; they hold quantities of types \ and \, +% 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{|\|}|\footnote{Actually, instead of +% \, the more general \\ can +% be used. However, that doesn't add any extra expressive power to +% the language of infix expressions.} or +% |\ratio{|\|}{|\|}| 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{|\|}|\quad +% |\heightof{|\|}|\quad +% |\depthof{|\|}| +%\end{quote} +% These calculate the natural sizes of the \ 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 \, \, \, +% \, and \ are +% as in Chapter~24 of The \TeX book~\cite{texbook}; and \ +% 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> \ \<\textit{type} term> +% +% \<\textit{type} term> +% \is \<\textit{type} factor> +% \alt \<\textit{type} term> \ \ +% \alt \<\textit{type} term> \ \ +% +% \<\textit{type} factor> +% \is \<\textit{type}> +% \alt \ +% \alt |(|$_{12}$ \<\textit{type} expression> |)|$_{12}$ +% +% \ \is \ +% +% \ +% \is \|{| \ |}| +% +% \ +% \is |\widthof| +% \alt |\heightof| +% \alt |\depthof| +% +% \ +% \is |*|$_{12}$ +% \alt |/|$_{12}$ +% +% \ +% \is |\ratio{| \ |}{| \ |}| +% \alt |\real{| \ |}| +% \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 \ 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 \ 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} +% \ \is \ \alt \ \alt \ \alt \ +% \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 \, (2)~all +% \s in an expression, except those which are part of an +% \, are of the same type as the whole expression, and +% all \s in an \ are \s. +% +% We have to ensure that $A$ and~$B$ always have an appropriate type +% for the \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 \ 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 \. +% +% 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 \, \, and \. +% \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 \ or \ is seen; in fact, anything not explicitly +% recognized here is taken to be a \ 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 \. +% 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 \ +% \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 \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: + - * / )}} +% +% \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} +% +%\NeedsTeXFormat{LaTeX2e} +%\ProvidesPackage{dcolumn} +%\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} +% +% \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}} +% +% \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 +% +%\NeedsTeXFormat{LaTeX2e} +%\ProvidesPackage{delarray} +% [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} +% +% \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} +% +% \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} +% +%\NeedsTeXFormat{LaTeX2e} +%\ProvidesPackage{enumerate} +% \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} +% +% \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} +% +% \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} +% +% \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 `' 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{} +% +% \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} +% +% \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} +% +% \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% + }% +} +% +% \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} +% +% \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} +% +% \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 +% +%\NeedsTeXFormat{LaTeX2e} +%\ProvidesPackage{hhline} +% [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} +% +% \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} +% +% \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 +% +%\NeedsTeXFormat{LaTeX2e} +%\ProvidesPackage{indentfirst} +% [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} +% +% \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 +% +% \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} +% +%<+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} +% +% \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 +} +% +% \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} +% +%\NeedsTeXFormat{LaTeX2e}[1995/06/01] +%\ProvidesPackage{longtable} +% \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} +% +% \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} +% +% \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} +% +%\NeedsTeXFormat{LaTeX2e}[1997/12/01] +%\ProvidesPackage{multicol} +% \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} +% +% \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 +% + \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 }% +% +% \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 +% +% \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}% +% + \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@} +% + #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 +% +% \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}% +% +% \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}% +% +% \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 +% +% \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 +% + \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}% +% + \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 +% +% \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 +% + }}% +% \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 +% + \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 +% +% \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 +% +% \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 +% + \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 +% +% \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}% +% +% \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}% +% +} +% \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 +% + \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}% +% + \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 +% + \unskip\unpenalty\unkern +%<*debug> + \edef\@tempa{s=\the\lastskip, + p=\the\lastpenalty, + k=\the\lastkern}% + \typeout\@tempa +% + \unskip\unpenalty\unkern +%<*debug> + \edef\@tempa{s=\the\lastskip, + p=\the\lastpenalty, + k=\the\lastkern}% + \typeout\@tempa +% + \unskip\unpenalty\unkern +%<*debug> + \edef\@tempa{s=\the\lastskip, + p=\the\lastpenalty, + k=\the\lastkern}% + \typeout\@tempa +% + \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 +% +% \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}} +% +% \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 +% +% +% \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} +% +% \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} +% +% \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} +% +%\NeedsTeXFormat{LaTeX2e} +%\ProvidesPackage{showkeys} +% \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} +% +% \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} +% +% \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} +% +% \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} +% +% \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} +% +%\NeedsTeXFormat{LaTeX2e} +%\ProvidesPackage{tabularx} +% \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} +% +% \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} +% +% \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} +% +% \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} +% +% \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 +% +% \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 +% +% \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 +% +% \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 +% +% \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 +% +% \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 +% +% \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} +% +% \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} +% +%\NeedsTeXFormat{LaTeX2e} +%\ProvidesPackage{trace} +%\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} +% +% \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} +% +% \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. +%% +% +%\NeedsTeXFormat{LaTeX2e}[1995/05/16] +%\ProvidesPackage{varioref} +% [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} +% +% \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==. +% \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{}: +% ``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== and Karl Ove Hufthammer +% \verb==. +% \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==. +% 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==). +% \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==). +% \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==). +% \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} +% +% \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} +% +% \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}} +% +% \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 \ % +% +% \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 +\end\end{verbatim} or even \end \end{verbatim} +% +%not \end\ended?? +%\end{verbatim} + +Another of Chris' devils: +\begin{verbatim} +the single brace test +\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 +% \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 +% +%\NeedsTeXFormat{LaTeX2e} +%\ProvidesPackage{xr} +% [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} +% +% \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} +% +% \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} +% +%\NeedsTeXFormat{LaTeX2e} +%\ProvidesPackage{xspace} +%\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} +% +% \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} +% +% \end{macrocode} +% \end{macro} +% +% \Finale +% + -- cgit v1.2.3