summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/eqparbox/eqparbox.dtx
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2010-01-03 23:18:55 +0000
committerKarl Berry <karl@freefriends.org>2010-01-03 23:18:55 +0000
commit96662256e48807dae530a28c31a897821d23edeb (patch)
treea909a52ae9b201e56e76dc7875435bb228684f2a /Master/texmf-dist/source/latex/eqparbox/eqparbox.dtx
parent61fde15d66144e23ae18862f485ded6391975a14 (diff)
eqparbox 3.1 (2jan10)
git-svn-id: svn://tug.org/texlive/trunk@16589 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/latex/eqparbox/eqparbox.dtx')
-rw-r--r--Master/texmf-dist/source/latex/eqparbox/eqparbox.dtx585
1 files changed, 425 insertions, 160 deletions
diff --git a/Master/texmf-dist/source/latex/eqparbox/eqparbox.dtx b/Master/texmf-dist/source/latex/eqparbox/eqparbox.dtx
index bd7f402172c..df63e1cce1f 100644
--- a/Master/texmf-dist/source/latex/eqparbox/eqparbox.dtx
+++ b/Master/texmf-dist/source/latex/eqparbox/eqparbox.dtx
@@ -1,27 +1,33 @@
% \iffalse meta-comment
%
-% Copyright (C) 2004 Scott Pakin <scott+eqp@pakin.org>
+% Copyright (C) 2010 Scott Pakin <scott+eqp@pakin.org>
% ----------------------------------------------------
%
% This package may be distributed and/or modified under the
-% conditions of the LaTeX Project Public License, either version 1.2
+% conditions of the LaTeX Project Public License, either version 1.3c
% 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.2 or later is part of all distributions of LaTeX
-% version 1999/12/01 or later.
+% and version 1.3c or later is part of all distributions of LaTeX
+% version 2008/05/04 or later.
%
% \fi
-% \iffalse
-%% File: eqparbox.dtx Copyright (C) 2004 Scott Pakin <scott+eqp@pakin.org>
%
-%<package>\NeedsTeXFormat{LaTeX2e}
+% \iffalse
+%<*driver>
+\ProvidesFile{eqparbox.dtx}
+%</driver>
+%<package>\NeedsTeXFormat{LaTeX2e}[1999/12/01]
%<package>\ProvidesPackage{eqparbox}
-%<package> [2004/08/02 v2.1 Create equal-widthed parboxes]
+%<*package>
+ [2010/01/01 v3.1 Create equal-widthed boxes]
+%</package>
%
%<*driver>
\documentclass{ltxdoc}
\usepackage{eqparbox}
+\usepackage{calligra}
+\usepackage{hyperref}
\EnableCrossrefs
\CodelineIndex
\RecordChanges
@@ -30,40 +36,33 @@
% source-code listing.
%\OnlyDescription
-% Give LaTeX some more leeway in placing floats
-% (suggested by Donald Arseneau <asnd@triumf.ca>).
-\renewcommand{\topfraction}{0.85}
-\renewcommand{\bottomfraction}{0.7}
-\renewcommand{\textfraction}{0.15}
-\renewcommand{\floatpagefraction}{0.66}
-\renewcommand{\dbltopfraction}{0.66}
-\renewcommand{\dblfloatpagefraction}{0.66}
-\setcounter{topnumber}{9}
-\setcounter{bottomnumber}{9}
-\setcounter{totalnumber}{20}
-\setcounter{dbltopnumber}{9}
-
-% Because we put table captions *above* tables, we should add a
-% little extra space between the caption and the table.
-\setlength{\belowcaptionskip}{2ex}
-
\begin{document}
-\DocInput{eqparbox.dtx}
+ \DocInput{eqparbox.dtx}
+ \PrintChanges
+ \PrintIndex
\end{document}
%</driver>
% \fi
%
% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
-% \CheckSum{169}
-% \GetFileInfo{eqparbox.sty}
-%
-% \title{The \textsf{eqparbox} package\thanks{This file
-% has version number \fileversion, last
-% revised \filedate.}}
-% \author{Scott Pakin \\ \textit{scott+eqp@pakin.org}}
-% \date{\filedate}
-% \maketitle
+% \CheckSum{203}
+%
+% \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.0}{2001/04/19}{Initial version}
% \changes{v2.0}{2004/07/31}{Rewrote to use only two \meta{dimen}s total
@@ -71,6 +70,8 @@
% Plamen Tanovski; solution suggested by David Kastrup and Donald
% Arseneau)}
%
+% \GetFileInfo{eqparbox.dtx}
+%
% \DoNotIndex{\@auxout,\@ifnextchar,\@ifundefined}
% \DoNotIndex{\begin,\begingroup,\csname,\DeclareRobustCommand,\def}
% \DoNotIndex{\else,\end,\endcsname,\endgroup,\expandafter,\fi,\gdef,\global}
@@ -78,13 +79,68 @@
% \DoNotIndex{\newcommand,\newdimen,\newif,\newlength,\noexpand}
% \DoNotIndex{\relax,\setbox,\space,\string,\the,\wd,\xdef,\z@}
%
+% ^^A The following environment, which typesets a declaration of a command
+% ^^A in a box set out into the margin, was copied almost verbatim from
+% ^^A ltxguide.cls.
+% \newenvironment{decl}[1][]^^A
+% {\par\small\addvspace{4.5ex plus 1ex}^^A
+% \vskip -\parskip
+% \ifx\relax#1\relax
+% \def\@decl@date{}^^A
+% \else
+% \def\@decl@date{\NEWfeature{#1}}^^A
+% \fi
+% \noindent\hspace{-\leftmargini}^^A
+% \begin{tabular}{|l|}\hline\ignorespaces}^^A
+% {\\\hline\end{tabular}\nobreak\@decl@date\par\nobreak
+% \vspace{2.3ex}\vskip -\parskip}
+%
+% ^^A Define a style for typesetting package names.
+% \DeclareRobustCommand{\pkgname}[1]{^^A
+% \textsf{#1}\index{#1=\textsf{#1} (package)}}
+%
+% ^^A Give LaTeX some more leeway in placing floats
+% ^^A (suggested by Donald Arseneau <asnd@triumf.ca>).
+% \renewcommand{\topfraction}{0.85}
+% \renewcommand{\bottomfraction}{0.7}
+% \renewcommand{\textfraction}{0.15}
+% \renewcommand{\floatpagefraction}{0.66}
+% \renewcommand{\dbltopfraction}{0.66}
+% \renewcommand{\dblfloatpagefraction}{0.66}
+% \setcounter{topnumber}{9}
+% \setcounter{bottomnumber}{9}
+% \setcounter{totalnumber}{20}
+% \setcounter{dbltopnumber}{9}
+%
+% ^^A Because we put table captions *above* tables, we should add a
+% ^^A little extra space between the caption and the table.
+% \setlength{\belowcaptionskip}{2ex}
+%
+% ^^A Properly hyphenate Rob Verhoeven's name.
+% \hyphenation{Ver-hoe-ven}
+%
+% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%
+% \title{The \pkgname{eqparbox} package\thanks{This document
+% corresponds to \pkgname{eqparbox}~\fileversion, dated \filedate.}}
+% \author{Scott Pakin \\ \textit{scott+eqp@pakin.org}}
+% \hypersetup{^^A
+% pdftitle={The eqparbox package},
+% pdfauthor={Scott Pakin <scott+eqp@pakin.org>},
+% pdfsubject={LaTeX package for typesetting text in equal-widthed boxes},
+% pdfkeywords={LaTeX2e, parbox, makebox, framebox, savebox, boxes, automatic width, largest}
+% }
+%
+% \maketitle
+%
% \begin{abstract}
-% The \textsf{eqparbox} package makes it easy to define a group of
-% \verb|\parbox|es whose members all have the same width, the natural
-% width of the widest member. A document can contain any number of
-% groups, and each group can contain any number of members. This
-% simple, equal-width mechanism can be used for a variety of alignment
-% purposes, as is evidenced by the examples in this document.
+% The \pkgname{eqparbox} package makes it easy to define a group of
+% boxes (such as those produced by |\parbox| or |\makebox|) whose
+% members all have the same width, the natural width of the widest
+% member. A document can contain any number of groups, and each group
+% can contain any number of members. This simple, equal-width
+% mechanism can be used for a variety of alignment purposes, as is
+% evidenced by the examples in this document.
% \end{abstract}
%
% \section{Motivation}
@@ -99,7 +155,7 @@
% \begin{enumerate}
% \item The header columns must be left-justified relative to each
% other.
-% \item The headers columns should be evenly spaced across the page.
+% \item The header columns should be evenly spaced across the page.
% \item Page breaks should be allowed within the r\'esum\'e.
% \end{enumerate}
%
@@ -192,46 +248,47 @@
% way to keep a set of |\parbox|es as wide as the widest entry in the
% set\,\dots
%
-% That simpler way is the \textsf{eqparbox} package. \textsf{eqparbox}
-% exports a macro, |\eqparbox|, which works just like |\parbox|, except
-% that instead of specifying the width of the box, one specifies the
-% group that the box belongs to. All boxes in the same group will be
-% typeset as wide as the widest member of the group. In that sense, an
-% |\eqparbox| behaves like a cell in an~|l|, |c|, or~|r| column in a
-% |tabular|; |\eqparbox|es in the same group are analogous to
-% cells in the same column.
+% That simpler way is the \pkgname{eqparbox} package.
+% \pkgname{eqparbox} exports an |\eqparbox| macro that works just like
+% |\parbox|, except that instead of specifying the width of the box, one
+% specifies the group that the box belongs to. All boxes in the same
+% group will be typeset as wide as the widest member of the group. In
+% that sense, an |\eqparbox| behaves like a cell in an~|l|, |c|, or~|r|
+% column in a |tabular|; |\eqparbox|es in the same group are analogous
+% to cells in the same column. Unlike the cells in a |tabular| column,
+% however, a group of |\eqparbox|es can be spread throughout the
+% document.
%
% \section{Usage}
%
-% \DescribeMacro{\eqparbox}
-% The primary macro in the \textsf{eqparbox} package is |\eqparbox|.
-% Usage is almost identical to that of |\parbox|:
-%
-% \begin{center}
-% |\eqparbox| \oarg{pos} \oarg{height} \oarg{inner-pos}
-% \marg{tag} \marg{text}
-% \end{center}
-%
-% \noindent
-% The only difference is that, where |\parbox| has its \meta{width}
-% argument, |\eqparbox| has \meta{tag}. (For a description of the
-% remaining arguments, look up |\parbox| in any \LaTeXe\ book or in
-% the \texttt{usrguide.tex} file that comes with \LaTeXe.) \meta{tag}
-% can be any valid identifier. All |\eqparbox|es with the same tag
-% will be typeset in a box wide enough to hold the widest of them.
+% \begin{decl}
+% |\eqparbox| \oarg{pos} \oarg{height} \oarg{inner-pos} \marg{tag} \marg{text} \\
+% |\eqmakebox| \oarg{tag} \oarg{pos} \marg{text} \\
+% |\eqframebox| \oarg{tag} \oarg{pos} \marg{text} \\
+% |\eqsavebox| \marg{cmd} \oarg{tag} \oarg{pos} \marg{text}
+% \end{decl}
+%
+% These macros are almost identical to |\parbox|, |\makebox|,
+% |\framebox|, and |\savebox|, respectively. The key difference is
+% that the \meta{width} argument is replaced by a \meta{tag} argument.
+% (For a description of the remaining arguments, look up |\parbox|,
+% |\makebox|, |\framebox|, and |\savebox| in any \LaTeXe\ book or in the
+% \texttt{usrguide.pdf} file that comes with all \TeX\ distributions.)
+% \meta{tag} can be any valid identifier. All boxes produced using the
+% same tag are typeset in a box wide enough to hold the widest of them.
% Discounting \TeX's limitations, any number of tags can be used in the
% same document, and any number of |\eqparbox|es can share a tag.
-%
% The only catch is that \texttt{latex} will need to be run a second
% time for the various box widths to stabilize.
%
-% \bigskip
+% \begin{decl}
+% |\eqboxwidth|
+% \end{decl}
%
-% \DescribeMacro{\eqboxwidth}
-% It is sometimes useful to take the width of an |\eqparbox| to use in
-% other \LaTeX{} commands. While the width can be determined by
-% creating an |\eqparbox| and using |\settowidth| to measure it, the
-% \textsf{eqparbox} package defines a convenience routine called
+% It is sometimes useful to take the width of a box produced by one of
+% the preceding commands. While the width can be determined by creating
+% an |\eqparbox| and using |\settowidth| to measure it, the
+% \pkgname{eqparbox} package defines a convenience routine called
% |\eqboxwidth| that achieves the same result.
%
% |\eqboxwidth| makes it easy to typeset something like
@@ -242,7 +299,7 @@
% typeset in an~|l| column, while the final cell behaves as if it were
% typeset in a~|p| column. In actuality, the column is an~|l| column;
% an |\eqparbox| for the first four cells ensures the column stretches
-% appropriately, while a |\parbox| of width |\eqboxwidth{|\meta{tag}|}|
+% appropriately while a |\parbox| of width |\eqboxwidth{|\meta{tag}|}|
% in the final cell ensures that the final cell word-wraps.
%
% \begin{table}
@@ -336,7 +393,7 @@
% inter-paragraph page breaks. Of course, if the labels are made wider
% or narrower, we'd like the paragraph widths to adjust automatically.
% (Can any word processor do that, incidentally?) By using a custom
-% |list| environment which typesets its labels with |\eqparbox|, this is
+% |list| environment that typesets its labels with |\eqparbox| this is
% fairly straightforward:
%
% \begin{figure}[tbp] ^^A NOT "here" (in case the default is changed)
@@ -393,23 +450,129 @@
% \end{list}
% \end{verbatim}
%
+% Finally, consider line-by-line transcription of a piece of text as
+% illustrated by the mockup in Figure~\ref{fig:line-by-line}. The idea is
+% to juxtapose a scanned piece of handwritten text with its typeset
+% version (or, similarly, to typeset a piece of text in one language
+% alongside a line-by-line translation into another language). The
+% challenge is in ensuring that (1)~the same words appear on
+% corresponding lines of text and that (2)~the typeset text is fully
+% justified. While the \pkgname{parallel} package can typeset fully
+% justified paragraphs aligned in parallel columns, it does not support
+% the alignment of individual lines. |tabular| and |minipage|
+% environments provide control of line breaks but do not support full
+% justification of the text when explicit line breaks are used.
+%
+% \begin{figure}
+% \centering
+% \DeleteShortVerb{\|}
+% \newsavebox{\tstretchbox}
+% \newcolumntype{S}[1]{^^A
+% >{\begin{lrbox}{\tstretchbox}}^^A
+% l^^A
+% <{\end{lrbox}^^A
+% \eqmakebox[#1][s]{\unhcopy\tstretchbox}}}
+% \begin{tabular}{|l|l|}
+% \hline
+% \calligra
+% \begin{tabular}{S{handwritten}}
+% Lorem ipsum dolor sit amet, \\
+% consectetur adipiscing elit. \\
+% Phasellus volutpat, nibh sit \\
+% amet mattis convallis, metus \\
+% libero rhoncus justo, sed auctor \\
+% erat mauris sit amet tellus. \\
+% \end{tabular}
+% &
+% \begin{tabular}{S{typeset}}
+% Lorem ipsum dolor sit amet, \\
+% consectetur adipiscing elit. \\
+% Phasellus volutpat, nibh sit \\
+% amet mattis convallis, metus \\
+% libero rhoncus justo, sed auctor \\
+% erat mauris sit amet tellus. \\
+% \end{tabular} \\
+% \hline
+% \end{tabular}
+% \MakeShortVerb{\|}
+% \caption{Line-by-line transcription of text with full justification}
+% \label{fig:line-by-line}
+% \end{figure}
+%
+% One solution is to use \pkgname{eqparbox}'s |\eqmakebox| macro. Like
+% |\makebox|, |\eqmakebox| supports the ``|s|'' (stretch) value for the
+% \meta{pos} argument, which causes the \meta{text} argument to stretch
+% to the width of the box. However, while |\makebox| requires the width
+% to be specified explicitly, |\eqmakebox| automatically sizes all boxes
+% that use the same tag (in this case, each line of the input paragraph)
+% to the widest text's natural width. Here's how to use the
+% \pkgname{array} package's |\newcolumntype| macro to define a new
+% |tabular| column type, ``|S|'', that stretches whitespace as needed to
+% fit the widest line in the column:
+%
+% \begin{verbatim}
+% \newsavebox{\tstretchbox}
+% \newcolumntype{S}[1]{%
+% >{\begin{lrbox}{\tstretchbox}}%
+% l%
+% <{\end{lrbox}%
+% \eqmakebox[#1][s]{\unhcopy\tstretchbox}}}
+% \end{verbatim}
+%
+% \noindent
+% That code works by storing the current cell's contents within a box
+% called |\tstretchbox| then passing |\tstretchbox|'s contents to
+% |\eqmakebox|. (The |tabular| environment does not enable a cell's
+% contents to be passed directly to a macro, hence the |lrbox|
+% trickery.) Note that the ``|S|'' column type takes an argument, which
+% is the tag to pass to |\eqmakebox|. Using the preceding definition we
+% can typeset Figure~\ref{fig:line-by-line} as follows. To simulate
+% scanned handwriting in the left column we use the Calligra handwriting
+% font provided by the \pkgname{calligra} package.
+%
+% \begin{verbatim}
+% \begin{tabular}{|l|l|}
+% \hline
+% \calligra
+% \begin{tabular}{S{handwritten}}
+% Lorem ipsum dolor sit amet, \\
+% consectetur adipiscing elit. \\
+% Phasellus volutpat, nibh sit \\
+% amet mattis convallis, metus \\
+% libero rhoncus justo, sed auctor \\
+% erat mauris sit amet tellus. \\
+% \end{tabular}
+% &
+% \begin{tabular}{S{typeset}}
+% Lorem ipsum dolor sit amet, \\
+% consectetur adipiscing elit. \\
+% Phasellus volutpat, nibh sit \\
+% amet mattis convallis, metus \\
+% libero rhoncus justo, sed auctor \\
+% erat mauris sit amet tellus. \\
+% \end{tabular} \\
+% \hline
+% \end{tabular}
+% \end{verbatim}
+%
%
% \section{Limitations}
%
-% Unfortunately, |\eqparbox| has a number of limitations not exhibited
-% by the original |\parbox| command. First, |\eqparbox| internally
-% typesets the given text within a |tabular| environment---specifically,
-% using ``|@{}l@{}|'' as the template---in order to determine the text's
-% natural width. Consequently, commands not valid within such a
-% |tabular| (e.g.,~list environments) are also not valid within the
-% \meta{text} argument of |\eqparbox|. As a corollary, an |\eqparbox|
+% Unfortunately, \pkgname{eqparbox}'s macros have a number of
+% limitations not exhibited by the corresponding \LaTeXe\ commands.
+% First, \pkgname{eqparbox}'s macros internally typeset the given text
+% within a |tabular| environment---specifically, using ``|@{}l@{}|'' as
+% the template---in order to determine the text's natural width.
+% Consequently, commands not valid within such a |tabular| (e.g.,~list
+% environments) are also not valid within the \meta{text} argument of an
+% \pkgname{eqparbox} macro. As a corollary, \pkgname{eqparbox}'s macros
% can appear only where a |tabular| is also acceptable.
%
-% A second limitation is that |\eqparbox| typesets its \meta{text}
-% argument \emph{twice}: once within a |tabular| to determine the
-% natural width and again within a parbox large enough to hold all text
-% associated with tag \meta{tag}. This approach may cause unexpected
-% results if \meta{text} is non-idempotent (i.e.,~has side
+% A second limitation is that \pkgname{eqparbox}'s macros typeset their
+% \meta{text} argument \emph{twice}: once within a |tabular| to
+% determine the natural width and again within a box wide enough to hold
+% all text associated with tag \meta{tag}. This approach may cause
+% unexpected results if \meta{text} is non-idempotent (i.e.,~has side
% effects). For example, if \meta{text} increments a counter, the
% counter will be incremented twice per invocation of |\eqparbox|.
%
@@ -418,51 +581,44 @@
% \section{Future Work}
%
% The following are some of the features people have requested I implement
-% in \textsf{eqparbox}:
+% in \pkgname{eqparbox}:
%
% \begin{itemize}
% \item Evalaute \texttt{\string\eqparbox}'s \meta{text} argument
% exactly once in case it contains side effects. Currently,
% \meta{text} is evaluated twice: once to determine its natural
-% size and once to put it in a parbox of the width associated with
+% size and once to put it in a box of the width associated with
% the given tag. (Feature requested by Bernd Schandl.)
%
-% \item Get \textsf{eqparbox} to work properly within an
-% \textsf{algorithmic} environment. (Feature requested by Mike
+% \item Get \pkgname{eqparbox} to work properly within an
+% \pkgname{algorithmic} environment. (Feature requested by Mike
% Shell.)
%
% \item Support pre-1999 \LaTeXe. (Feature requested by Mike Shell.)
% \end{itemize}
%
% One idea I've been toying with that may resolve the first two items in
-% that list is to typeset \meta{text} within a parbox, then check
+% that list is to typeset \meta{text} within a box, then check
% \texttt{\string\badness} to see if the box was too small for
% \meta{text}. If not (i.e.,~the box was not overfull), then the
-% initial parbox can be reused directly without needing to re-typeset
+% initial box can be reused directly without needing to re-typeset
% \meta{text}. With this approach, \texttt{\string\eqparbox} will work
% anywhere \texttt{\string\parbox} works. Unfortunately, I don't know
% how to get at the \texttt{\string\badness} of the
% \texttt{\string\hbox}es that comprise the \texttt{\string\vbox}
% utilized by \texttt{\string\parbox}. If anyone has a suggestion, I'm
% all ears.
-%
-% \PrintChanges
-% \PrintIndex
% }
%
% \section{Implementation}
%
% The one-sentence summary of the implementation is, ``As
-% \textsf{eqparbox} goes along, it keeps track of the maximum width of
+% \pkgname{eqparbox} goes along, it keeps track of the maximum width of
% each box type, and when it's finished, it writes those widths to
% the~|.aux| file for use on subsequent runs.'' If you're satisfied
% with that summary, then read no further. Otherwise, get ready to
% tackle the following annotated code listing.
%
-% \begin{macrocode}
-%<*package>
-% \end{macrocode}
-%
% \begin{macro}{\eqp@tempdima}
% \begin{macro}{\eqp@tempdimb}
% Define a couple temporary \meta{dimen}s for use in a variety of locations.
@@ -564,7 +720,7 @@
% \end{macro}
% \end{macro}
%
-% The following macro (|\eqp@settowidth|) requires the \textsf{array}
+% The following macro (|\eqp@settowidth|) requires the \pkgname{array}
% package's ability to inject code into every cell.
% \begin{macrocode}
\RequirePackage{array}
@@ -573,7 +729,7 @@
% \begin{macro}{\eqp@settowidth}
% This macro is just like |\settowidth|, but it puts its argument in a
% |tabular|, which means that it can contain |\\|. We use the
-% \textsf{array} package's ``|>|'' and ``|<|'' template parameters to
+% \pkgname{array} package's ``|>|'' and ``|<|'' template parameters to
% inject an |\eqp@restorefont| at the start of every cell and an
% |\eqp@storefont| at the end of every cell. Doing so preserves fonts
% and font sizes across |\\| boundaries, just like |\parbox|.
@@ -593,8 +749,6 @@
% \end{macro}
%
% \begin{macro}{\eqparbox}
-% \begin{macro}{\eqparbox@i}
-% \begin{macro}{\eqparbox@ii}
% We want |\eqparbox| to take the same arguments as |\parbox|, with the
% same default values for the optional arguments. The only difference
% in argument processing is that |\eqparbox| has a \meta{tag} argument
@@ -602,39 +756,41 @@
%
% Because |\eqparbox| has more than one optional argument, we can't use
% a single function defined by |\DeclareRobustCommand|. Instead, we
-% have to split |\eqparbox| into the following four macros:
-%
-% \begin{description}
-% \item[\texttt{\string\eqparbox}] Takes zero or more optional arguments.
-% First optional argument defaults to~|c|. Calls |\eqparbox@i|.
-%
-% \item[\texttt{\string\eqparbox@i}] Takes one or more optional arguments.
-% Second optional argument defaults to~|\relax|. Calls |\eqparbox@ii|.
+% have to split |\eqparbox| into |\eqparbox|, |\eqparbox@i|,
+% |\eqparbox@ii|, and |\eqparbox@iii| macros, which correspond to
+% |\parbox|, |\@iparbox|, |\@iiparbox|, and |\@iiiparbox| in
+% |ltboxes.dtx|.
%
-% \item[\texttt{\string\eqparbox@ii}] Takes two or more optional arguments.
-% Third optional argument defaults to~|s| if either of the first two
-% arguments is absent or to the first argument if both are present.
-% Calls |\eqparbox@iii|.
-%
-% \item[\texttt{\string\eqparbox@iii}] Takes three optional arguments
-% and two mandatory arguments. Does all the work for |\eqparbox|.
-% \end{description}
-%
-% \noindent
-% Note the direct correspondence between these macros and
-% |ltboxes.dtx|'s |\parbox|, |\@iparbox|, |\@iiparbox|, and
-% |\@iiiparbox| macros.
+% |\eqparbox| takes an optional \meta{pos} argument that defaults
+% to~|c|. It passes the value of this argument to |\eqparbox@i|.
% \begin{macrocode}
-\DeclareRobustCommand\eqparbox{%
+\DeclareRobustCommand{\eqparbox}{%
\@ifnextchar[%]
{\eqparbox@i}%
{\eqparbox@iii[c][\relax][s]}%
}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\eqparbox@i}
+% |\eqparbox@i| takes a \meta{pos} argument followed by an optional
+% \meta{height} argument that defaults to~|\relax|. It passes both
+% \meta{pos} and \meta{height} to |\eqparbox@ii|.
+% \begin{macrocode}
\def\eqparbox@i[#1]{%
\@ifnextchar[%]
{\eqparbox@ii[#1]}%
{\eqparbox@iii[#1][\relax][s]}%
}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\eqparbox@ii}
+% |\eqparbox@ii| takes \meta{pos} and \meta{height} arguments followed
+% by an optional \meta{inner-pos} argument that defaults to \meta{pos}.
+% It passes \meta{pos}, \meta{height}, and \meta{inner-pos} to
+% |\eqparbox@iii|.
+% \begin{macrocode}
\def\eqparbox@ii[#1][#2]{%
\@ifnextchar[%]
{\eqparbox@iii[#1][#2]}%
@@ -642,16 +798,125 @@
}
% \end{macrocode}
% \end{macro}
+% \begin{macro}{\eqparbox@iii}
+% \begin{macro}{\eqp@produce@box}
+% |\eqparbox@iii| takes \meta{pos}, \meta{height} and \meta{inner-pos}
+% arguments. It defines an |\eqp@produce@box| macro that takes a
+% \meta{width} argument and a \meta{text} argument and passes all of
+% \meta{pos}, \meta{height}, \meta{inner-pos}, \meta{width}, and
+% \meta{text} to \LaTeX's |\parbox| macro. |\eqparbox@iii| ends by
+% calling |\eqp@compute@width|, which will eventually invoke
+% |\eqp@produce@box|.
+% \begin{macrocode}
+\def\eqparbox@iii[#1][#2][#3]{%
+ \gdef\eqp@produce@box##1##2{%
+ \parbox[#1][#2][#3]{##1}{##2}%
+ }%
+ \eqp@compute@width
+}
+% \end{macrocode}
% \end{macro}
% \end{macro}
%
-% \begin{macro}{\eqparbox@iii}
-% The following function does all the real work for |\eqparbox|. It takes
-% five parameters---\meta{pos}, \meta{height}, \meta{inner-pos},
-% \meta{tag}, and \meta{text}---and ensures that all boxes with the same
-% tag will be as wide as the widest box with that tag.
+% \begin{macro}{\eqmakebox}
+% |\eqmakebox| provides an automatic-width analogue to \LaTeX's
+% |\makebox|. It takes the same arguments as |\makebox| with the same
+% default values for the optional arguments. The only difference in
+% argument processing is that |\eqmakebox| has a \meta{tag} argument
+% where |\makebox| has \meta{width}. Note that if \meta{width} is not
+% specified, |\eqmakebox| simply invokes |\makebox|.
+% \changes{v3.0}{2010/01/01}{Included Rob Verhoeven's
+% \texttt{\string\string\string\eqmakebox} macro}
+% \changes{v3.1}{2010/01/01}{Modified the argument processing to match
+% \texttt{\string\string\string\makebox}'s}
+% \begin{macrocode}
+\DeclareRobustCommand{\eqmakebox}{%
+ \@ifnextchar[%]
+ {\eqlrbox@i\makebox}%
+ {\makebox}%
+}
+% \end{macrocode}
+% \end{macro}
%
-% To keep track of box widths, |\eqparbox| makes use of two global
+% \begin{macro}{\eqframebox}
+% |\eqframebox| provides an automatic-width analogue to \LaTeX's
+% |\framebox|. It takes the same arguments as |\framebox| with the same
+% default values for the optional arguments. The only difference in
+% argument processing is that |\eqframebox| has a \meta{tag} argument
+% where |\framebox| has \meta{width}. Note that if \meta{width} is not
+% specified, |\eqframebox| simply invokes |\framebox|.
+% \changes{v3.1}{2010/01/01}{Introduced this macro}
+% \begin{macrocode}
+\DeclareRobustCommand{\eqframebox}{%
+ \@ifnextchar[%]
+ {\eqlrbox@i\framebox}%
+ {\framebox}%
+}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\eqsavebox}
+% |\eqsavebox| provides an automatic-width analogue to \LaTeX's
+% |\savebox|. It takes the same arguments as |\savebox| with the same
+% default values for the optional arguments. The only difference in
+% argument processing is that |\eqsavebox| has a \meta{tag} argument
+% where |\savebox| has \meta{width}. Note that if \meta{width} is not
+% specified, |\eqsavebox| simply invokes |\savebox|.
+% \changes{v3.1}{2010/01/01}{Introduced this macro}
+% \begin{macrocode}
+\DeclareRobustCommand{\eqsavebox}[1]{%
+ \@ifnextchar[%]
+ {\eqlrbox@i{\savebox{#1}}}%
+ {\savebox{#1}}%
+}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\eqlrbox@i}
+% |\eqlrbox@i| takes a \marg{command} argument (one of |\makebox|,
+% |\framebox|, or |\savebox|\marg{cmd}) and a \oarg{tag} argument and
+% checks if those arguments are followed by a \oarg{pos} argument. If
+% not, then \meta{pos} defaults to ``|c|''. All of \meta{command},
+% \meta{tag}, and \meta{pos} are passed to |\eqlrbox@ii|.
+% \begin{macrocode}
+\def\eqlrbox@i#1[#2]{%
+ \@ifnextchar[%]
+ {\eqlrbox@ii{#1}[#2]}%
+ {\eqlrbox@ii{#1}[#2][c]}%
+}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\eqlrbox@ii}
+% \begin{macro}{\eqp@produce@box}
+% |\eqlrbox@i| takes a \marg{command} argument (one of |\makebox|,
+% |\framebox|, or |\savebox|\marg{cmd}), a \oarg{tag} argument, and a
+% \oarg{pos} argument. It defines |\eqp@produce@box| to take a
+% \meta{width} argument and a \meta{text} argument and invoke
+% \meta{command}\oarg{width}\oarg{pos}\marg{text}. |\eqlrbox@ii| ends
+% by calling |\eqp@compute@width|, which will eventually invoke
+% |\eqp@produce@box|.
+% \begin{macrocode}
+\def\eqlrbox@ii#1[#2][#3]{%
+ \gdef\eqp@produce@box##1##2{%
+ #1[##1][#3]{##2}%
+ }%
+ \eqp@compute@width{#2}%
+}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\eqp@compute@width}
+% The following function does all the real work for the
+% \pkgname{eqparbox} package. It takes two parameters---\meta{tag} and
+% \meta{text}---and ensures that all boxes with the same tag will be as
+% wide as the widest box with that tag. It ends by passing \meta{tag}
+% and \meta{text} to the |\eqp@produce@box| command, which was defined
+% by the calling macro to produce a box using one of the existing
+% \LaTeXe\ commands.
+%
+% To keep track of box widths, |\eqp@compute@width| makes use of two global
% variables for each tag: |\eqp@this@|\meta{tag} and
% |\eqp@next|\meta{tag}. |\eqp@this@|\meta{tag} is the maximum width
% ever seen for tag \meta{tag}, including in previous |latex| runs.
@@ -659,41 +924,45 @@
% to~|0.0pt|. It represents the maximum width to assume in
% \emph{subsequent} |latex| runs. It is needed to detect whether the
% dest text with tag \meta{tag} has been removed/shrunk. At the end of
-% a run, \textsf{eqparbox} prepares the next run (via the~|.aux| file)
+% a run, \pkgname{eqparbox} prepares the next run (via the~|.aux| file)
% to initialize |\eqp@this@|\meta{tag} to the final value of
% |\eqp@next@|\meta{tag}.
% \changes{v2.0}{2004/07/30}{Removed extraneous \texttt{\string\string\string\global}s
% (suggested by David Kastrup)}
+% \changes{v3.1}{2010/01/01}{Restructured the package to make all
+% user-callable functions eventually call
+% \texttt{\string\string\string\eqp@compute@width}, which does the
+% bulk of the work}
% \begin{macrocode}
-\def\eqparbox@iii[#1][#2][#3]#4#5{%
- \eqp@settowidth{\eqp@tempdimb}{#5}%
+\def\eqp@compute@width#1#2{%
+ \eqp@settowidth{\eqp@tempdimb}{#2}%
\expandafter
- \ifx\csname eqp@this@#4\endcsname\relax
+ \ifx\csname eqp@this@#1\endcsname\relax
% \end{macrocode}
% If we get here, then we've never encountered tag \meta{tag}, even in a
% previous |latex| run. We request that the user re-run |latex| This is
-% not always necessary (e.g., when all uses of the |\eqparbox| with tag
+% not always necessary (e.g.,~when all uses of the |\eqparbox| with tag
% \meta{tag} are left-justified), but it's better to be safe than sorry.
% \begin{macrocode}
\global\eqp@must@reruntrue
- \expandafter\xdef\csname eqp@this@#4\endcsname{\the\eqp@tempdimb}%
- \expandafter\xdef\csname eqp@next@#4\endcsname{\the\eqp@tempdimb}%
+ \expandafter\xdef\csname eqp@this@#1\endcsname{\the\eqp@tempdimb}%
+ \expandafter\xdef\csname eqp@next@#1\endcsname{\the\eqp@tempdimb}%
\else
% \end{macrocode}
% If we get here, then we \emph{have} previously seen tag \meta{tag}.
% We just have to keep track of the maximum text width associated with
% it.
% \begin{macrocode}
- \eqp@tempdima=\csname eqp@this@#4\endcsname\relax
+ \eqp@tempdima=\csname eqp@this@#1\endcsname\relax
\ifdim\eqp@tempdima<\eqp@tempdimb
- \expandafter\xdef\csname eqp@this@#4\endcsname{\the\eqp@tempdimb}%
+ \expandafter\xdef\csname eqp@this@#1\endcsname{\the\eqp@tempdimb}%
\global\eqp@must@reruntrue
\fi
% \end{macrocode}
% \begin{macrocode}
- \eqp@tempdima=\csname eqp@next@#4\endcsname\relax
+ \eqp@tempdima=\csname eqp@next@#1\endcsname\relax
\ifdim\eqp@tempdima<\eqp@tempdimb
- \expandafter\xdef\csname eqp@next@#4\endcsname{\the\eqp@tempdimb}%
+ \expandafter\xdef\csname eqp@next@#1\endcsname{\the\eqp@tempdimb}%
\fi
\fi
% \end{macrocode}
@@ -702,30 +971,30 @@
% ensure \LaTeX{} will notify the user if he needs to re-run |latex| on
% account of that tag.
% \begin{macrocode}
- \@ifundefined{eqp@seen@#4}{%
- \expandafter\gdef\csname eqp@seen@#4\endcsname{}%
- \@cons\eqp@taglist{{#4}}%
+ \@ifundefined{eqp@seen@#1}{%
+ \expandafter\gdef\csname eqp@seen@#1\endcsname{}%
+ \@cons\eqp@taglist{{#1}}%
}{}%
% \end{macrocode}
%
-% Finally, we can call |\parbox|. We pass it \meta{pos}, \meta{height},
-% \meta{inner-pos}, and \meta{text} directly, and we pass it
-% |\eqp@this@|\meta{tag} for its \meta{width} argument.
+% Finally, we can call |\eqp@produce@box|. We pass it
+% |\eqp@this@|\meta{tag} for its \meta{width} argument and |#2| for its
+% \meta{text} argument.
% \begin{macrocode}
- \eqp@tempdima=\csname eqp@this@#4\endcsname\relax
- \parbox[#1][#2][#3]{\eqp@tempdima}{#5}%
+ \eqp@tempdima=\csname eqp@this@#1\endcsname\relax
+ \eqp@produce@box{\eqp@tempdima}{#2}%
}
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{\eqboxwidth}
-% For the times that the user wants to make something other than a box
+% For the times that the user wants to make something other than a box to
% match an |\eqparbox|'s width, we provide |\eqboxwidth|. |\eqboxwidth|
% returns the width of a box corresponding to a given tag. More
% precisely, if |\eqp@this@|\meta{tag} is defined, it's returned.
% Otherwise,~|0pt| is returned.
% \changes{v2.1}{2004/08/02}{Rewrote so as to be compatible with the
-% \textsf{calc} package's \texttt{\string\string\string\setlength}
+% \pkgname{calc} package's \texttt{\string\string\string\setlength}
% command (problem initially reported by Gary L. Gray and narrowed
% down by Martin Vaeth)}
% \begin{macrocode}
@@ -738,7 +1007,7 @@
% \DeleteShortVerb{\|}
% \MakeShortVerb{\!}
% \paragraph{Per-tag memory usage}
-% The \textsf{eqparbox} package defines three macros for each unique
+% The \pkgname{eqparbox} package defines three macros for each unique
% tag: !\eqp@this@!\meta{tag}, !\eqp@next@!\meta{tag}, and
% !\eqp@seen@!\meta{tag}. Consequently, each unique tag subtracts three
% strings from \TeX's string pool and three multiletter control
@@ -753,9 +1022,5 @@
% \DeleteShortVerb{\!}
% \MakeShortVerb{\|}
%
-% \begin{macrocode}
-%</package>
-% \end{macrocode}
-%
% \Finale
-%
+\endinput