eqparbox 3.1 (2jan10)

git-svn-id: svn://tug.org/texlive/trunk@16589 c570f23f-e606-0410-a88d-b1316a301751

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