new package boxhandler

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

2 files changed, 1727 insertions, 0 deletions

diff --git a/Master/texmf-dist/source/latex/boxhandler/boxhandler.dtx b/Master/texmf-dist/source/latex/boxhandler/boxhandler.dtx
new file mode 100644
index 00000000000..0bdf9b34289
--- /dev/null
+++ b/Master/texmf-dist/source/latex/boxhandler/boxhandler.dtx
@@ -0,0 +1,1721 @@
+% \iffalse
+%%
+%% boxhandler.sty
+%% Copyright Steven B. Segletes.
+%%
+%% This file may be redistributed and/or modified with attribution.
+%%
+%% This is boxhandler.sty, derived from earlier incarnations of savcap.sty &
+%% arlcaptions.sty.
+%%
+%<package>\ProvidesPackage{boxhandler}
+%<package>[2006/04/24 v1.03
+%<package>    Flexible Captioning Styles and Deferred Box/List Printing]
+%<package>\NeedsTeXFormat{LaTeX2e}
+%<*driver>
+% V1.02 Corrected minor grammar issue in documentation.
+% V1.03 Changed some tabs into spaces that were screwing up appearance
+\documentclass{ltxdoc}
+\usepackage{boxhandler}
+\DisableCrossrefs
+\CodelineNumbered
+% DEFINE SOME COMMANDS THAT ARE EASIER HERE THAN IN DocInput ENVIRONMENT
+\def\tbllayout{|c|}% CAN'T GET PLAIN "|" CHARACTER IN DocInput MODE
+\def\lb{\char'173}%  LEFT BRACE  "{" WHEN INVOKED IN \tt FONT
+\def\rb{\char'175}%  RIGHT BRACE "}" WHEN INVOKED IN \tt FONT
+\def\bs{\char'134}%  BACKSLASH   "\" WHEN INVOKED IN \tt FONT
+\let\iq\itshape%     SHORTHAND FOR ITALIC  FONT
+\let\uq\upshape%     SHORTHAND FOR UPSHAPE FONT
+\GetFileInfo{boxhandler.sty}
+\begin{document}
+   \title{The \textsf{boxhandler} Package\\
+         \rule{0em}{0.7em}\small\fileinfo}
+   \author{Steven B. Segletes\\
+           steven@arl.army.mil}
+   \date{\filedate\\
+         \fileversion}
+   \maketitle
+   \DocInput{boxhandler.dtx}
+\end{document}
+%</driver>
+% \fi
+% \parskip 1ex
+% \begin{abstract}
+% This package was developed as a tool to manage the handling of \LaTeX{}
+% tables and figures, especially for conditionally compiled documents.
+% With these tools, not only can one conveniently define table and figure
+% captions with a wide variety of stylistic appearances, but one can
+% create a single \LaTeX{} document that can, with a single line change
+% in the source code, produce an output that has vastly different layout
+% from the baseline configuration, not only in terms of caption style,
+% but also in terms of the locations where figures, tables and lists
+% appear (or not) in the document.
+% \end{abstract}
+%
+% \tableofcontents\rule[.2em]{4.5in}{.3mm}\vspace{-1.5em}
+%
+% \section {Introduction}
+%
+% The commands described in the |boxhandler| style accomplish a number of
+% useful functions. Even without the use of a conditionally-compiled
+% document:
+% \begin{enumerate}
+% \item they allow the definition of figures and tables in compact routine
+% calls;
+% \item they retain wide flexibility in caption appearance \& table/figure
+% placement, through the use of simple setup calls.
+% \end{enumerate}
+% And for those who wish, from a single \LaTeX{} source file to
+% conditionally produce, on one hand, an internal technical report for
+% example, and on the other hand, a journal manuscript submission, this
+% style additionally allows:
+% \begin{enumerate}\setcounter{enumi}{2}
+% \item printing of figures \& tables to be [conditionally] deferred to later
+% in the document;
+% \item printing of lists (\textit{lof}, \textit{lot}) to be deferred later
+% in document; and
+% \item the preemptive cancellation of the \textit{toc}, \textit{lof}, and
+% \textit{lot}.
+% \end{enumerate}
+%
+% \section{Caption Style, Appearance and Box Placement}
+%
+% \subsection{Commands}
+%
+% This routine provides several routines for creating and tailoring the
+% appearance of captioned ``boxes'' (that is, figures and tables). 
+% They include:
+% \begin{verse}
+% |\bxtable[|\iq loc\uq|]{|\iq caption\uq|}{|\iq boxed object\uq|}|\\
+% |\bxfigure[|\iq loc\uq|]{|\iq caption\uq|}{|\iq boxed object\uq|}|\\
+% |\relaxCaptionWidth[|\iq len\uq|]|\\
+% |\limitCaptionWidth[|\iq len\uq|]|\\
+% |\constrainCaptionWidth[|\iq len\uq|]{|\iq len\uq|}|\\
+% |\captionStyle{|\iq offset type\uq|}{|\iq alignment type\uq|}|\\
+% \end{verse}
+% \DescribeMacro{\bxtable}
+% \DescribeMacro{\bxfigure}
+% The routines |\bxtable| and |\bxfigure| will actually produce the
+% complete table or figure, including caption.  In these two routines,
+% \iq loc \uq is an optional argument.  It can take on a value of: |h|,
+% |t|, |b|, or |p|.  This parameter refers to the same location argument
+% that goes with the \LaTeX{} float environments, to help \LaTeX{}
+% determine the placement of the item on your page. |h| is `here', |t| is
+% `top', |b| is `bottom', |p| is `page of floats'.  Omitting the first
+% argument just uses the default placement of the table and figure
+% environments.
+%
+% In |\bxtable| and |\bxfigure|, \iq caption \uq is the argument that
+% will eventually get passed on to the |\caption| call, after the routine
+% properly formulates it to match the desired figure/caption style.  The
+% caption may include |\label| identifiers to be referenced by the main
+% text.
+%
+% For |\bxtable|, the \iq boxed object \uq will typically be a tabular
+% box, though any \LaTeX{} boxed object will satisfy the routine.  Thus,
+% the difference between a |\bxtable| and a |\bxfigure| is largely a
+% semantic one.  The true difference between |\bxtable| and |\bxfigure|
+% in this regard is that the table caption is placed above the table,
+% whereas the figure caption is placed below it.  In addition, because
+% these routines make use of the standard |\caption| call within the
+% table and figure environments, calls to |\bxtable| and |\bxfigure| will
+% have their references automatically available to the List of Tables and
+% List of Figures, respectively.
+%
+% One of the differences between the |boxhandler| style and \LaTeX{}'s
+% default captioning environments is the default caption width.  Whereas
+% \LaTeX{} defaults to a full margin-to-margin caption width,
+% |boxhandler| defaults to a caption width equal to and aligned with the
+% width of the box being captioned. However, this caption-width default
+% within |boxhandler| can be changed to any arbitrary value, including
+% full-width, if desired.  The caption width, through the use of the
+% ``dead margin,'' can also be conveniently set to a fixed offset from
+% the table or figure width.  For example, all table captions could be
+% set to a width 1 inch larger than their associated tables.
+%
+% \DescribeMacro{\relaxCaptionWidth}
+% The routine |\relaxCaptionWidth| takes as its optional argument a
+% length dimension corresponding to the minimum allowed caption width,
+% even if an associated table or figure is of lesser box width.  While
+% this command might technically violate an organization's style
+% guideline, it allows one to avoid the situation of trying to assign a
+% caption to fit the width dimension of an extremely narrow table or
+% figure.  An example of this use is shown in Tables~\ref{tbl:narrow} and
+% \ref{tbl:wide}.  In the first table, the default minimum caption width
+% of 1~inch is retained, resulting in an unwieldy caption.  The second
+% table has been printed following an invocation of
+% |\relaxCaptionWidth[4.0in]|.  Using |\relaxcaption| with no argument
+% resets the minimum allowed caption width to the default value of 1
+% inch.
+%
+% \def\mycaption{A table which provides the secret entryword of the
+%                Halloween Ghost Club, assuming you can read the caption}
+% \def\mytabular{
+%   \begin{tabular}{\tbllayout}
+%     \hline
+%   Boohoocachoo\\
+%   \hline
+%   \end{tabular}
+%   }
+% \relaxCaptionWidth
+% \bxtable[t]{\mycaption\label{tbl:narrow}}{\mytabular}
+% \relaxCaptionWidth[4.0in]
+% \bxtable[t]{\mycaption\label{tbl:wide}}{\mytabular}
+% \relaxCaptionWidth
+%
+% If the minimum caption width is relaxed, the maximum allowed width
+% will be bumped up, if necessary, to remain greater than or equal to
+% the minimum allowed caption width.
+%
+% \DescribeMacro{\limitCaptionWidth}
+% The routine |\limitCaptionWidth| is analogous to |\relaxCaptionWidth|.
+% In this case, however, the maximum allowable caption width will be
+% defined.  If no argument is specified, the maximum allowed caption
+% width is reset to the default value, which is |\textwidth|.
+%
+% If the maximum caption width is constrained, the minimum allowed width
+% will be reduced, if necessary, to remain less than or equal to the
+% maximum allowed caption width.
+%
+% \DescribeMacro{\constrainCaptionWidth}
+% The minimum and maximum allowed caption widths may be simultaneously
+% specified with |\constrainCaptionWidth|.  The order of the two length
+% arguments is not important.  Omitting the optional argument will cause
+% both the min and max allowable caption widths to be fixed at the
+% specified value. In this manner, all caption widths will be set to this
+% single value, regardless of the size of the table or figure box it
+% describes.  Note that the use of |\constrainCaptionWidth| with a single
+% argument of |{\textwidth}| allows a full-width left-to-right margin
+% caption style to be achieved, if desired, as in Figure~\ref{fig:cnst}.
+%
+% \DescribeMacro{\captionStyle}
+% To understand the the figure and table caption style 
+% command, examine the caption styles in
+% Figures~\ref{fig:styo}--\ref{fig:styc}, in reference to the
+% boxed object with which they are paired.
+% |\captionStyle{|\iq offset type\uq|}{|\iq alignment type\uq|}| is a
+% compact way of specifying the caption style.  The first parameter
+% specifies the \textit{offset type} for long captions (since ``offset''
+% has no meaning for short captions).  It can take
+% the value of |o| for ``offset'' captions, such as that found in
+% Figure~\ref{fig:styo}, or |n| for ``nooffset'' captions, such as
+% that found in Figure~\ref{fig:styn}.
+%
+% \relaxCaptionWidth[\textwidth]
+% \captionStyle{n}{l}
+% \bxfigure[p]
+%   {Here is a full-width caption that takes up the full
+%   margin-to-margin dimension, regardless of how wide the boxed object
+%   it serves is. In this case, the caption is of the ``nooffset''
+%   variety\label{fig:cnst}}
+% {\framebox(260,40){Boxed Object: \tt\bs
+%   constrainCaptionWidth\lb\bs textwidth\rb}}
+% \relaxCaptionWidth
+% \captionStyle{o}{}
+% \bxfigure[p]{For ``offset'' captions, the ID label for the caption
+%            is offset to the left of the caption text\label{fig:styo}}
+%            {\framebox(180,40){Boxed Object: \tt\bs captionStyle\{o\}\{\}}}
+% \captionStyle{n}{}
+% \bxfigure[p]{For ``nooffset'' captions, the caption's ID label 
+%            is integrated into the caption text itself\label{fig:styn}}
+%            {\framebox(180,40){Boxed Object: \tt\bs captionStyle\{n\}\{\}}}
+% \captionStyle{}{l}
+% \bxfigure[p]{A short ``left''-aligned caption\label{fig:styl}}
+%            {\framebox(250,40){Boxed Object: \tt\bs captionStyle\{\}\{l\}}}
+% \captionStyle{}{c}
+% \bxfigure[p]{A short ``center''-aligned caption\label{fig:styc}}
+%            {\framebox(250,40){Boxed Object: \tt\bs captionStyle\{\}\{c\}}}
+%
+% The second parameter specifies the \textit{alignment type} for short
+% captions (since long captions are already fully aligned).  It can take
+% on the value of |l| for ``left''-aligned
+% captions, such as that in Figure~\ref{fig:styl}, the value |c| for
+% ``center''-aligned captions, such as that in Figure~\ref{fig:styc},
+% or the value of |r| for ``right''-aligned captions.
+%
+% The default style for this package is |\captionstyle{o}{l}|, or
+% ``offset''-style, ``left''-aligned captions.  This default caption
+% style is that displayed in Figures~\ref{fig:styo} and \ref{fig:styl},
+% for long and short captions, respectively.
+%
+% Note that caption alignment is not the same as caption justification.
+% Regardless of alignment, any caption of size sufficient to span the
+% full width of the caption box will be, by default, fully justified or
+% ``flushed'' within that caption box.  The captions in Figures~1 and 2
+% demonstrate this for both offset and nooffset caption types.  Text
+% justification can, however, be altered, as described later by the
+% |\CaptionJustification| parameter.
+%
+% \subsection {Additional User Parameters}
+%
+% In addition to the above commands, there are a variety of
+% lengths, counters, and modes, which may be set by the user,
+% to adjust the appearance of the caption
+% presentation.  The settings for all these parameters hold until and
+% unless subsequently reset by the user.
+%
+% \begin{verse}
+% |\setlength\captionGap{|\iq len\uq|}|\\
+% |\setlength\TableDeadMargin{|\iq len\uq|}|\\
+% |\setlength\FigureDeadMargin{|\iq len\uq|}|\\
+% |\setcounter{abovecaptionskipterm}{|\iq integer\uq|}|\\
+% |\setcounter{belowcaptionskipterm}{|\iq integer\uq|}|\\
+% |\let\CaptionFontSize |\iq fontsize, e.g., \uq|\small|\\
+% |\let\TableFontSize |\iq fontsize, e.g., \uq|\small|\\
+% |\def\LRTablePlacement{flushleft|\iq , \uq|center|\iq , or \uq
+% |flushright}|\\
+% |\def\LRFigurePlacement{flushleft|\iq , \uq|center|\iq , or \uq
+% |flushright}|\\
+% |\def\CaptionJustification{|\iq blank, \uq|\raggedright|\iq ,\\\uq
+% |                          \centering|\iq , or \uq
+% |\raggedleft}|\\
+% \end{verse}
+%
+% \DescribeMacro{\captionGap}
+% |\captionGap| defines the horizontal space
+% between the caption identifier (e.g., ``Figure~1.'') and the start
+% of the caption text itself.  Its default value is 1ex.
+%
+% \DescribeMacro{\TableDeadMargin}
+% \DescribeMacro{\FigureDeadMargin}
+% |\TableDeadMargin| and |\FigureDeadMargin| may be set to correct the
+% caption alignment for boxes that have a deadzone around their border.
+% Such dead space takes up boxwidth, but shows no visible data.  These
+% parameter values should be set to the left or right-hand dead  space
+% (assumed symmetric).  The default value for |\TableDeadMargin|, which
+% is suitable for \LaTeX{} generated tabular data, is 0.375em. The default
+% for |\FigureDeadMargin| is 0em.
+%
+% Additionally, these |\...DeadMargin| commands can be used to set the
+% box-size-to-caption-size disparity to any desired non-flush value.  As
+% an example, setting the value of |\FigureDeadMargin| to 0.5 inch will
+% make the figure captions always 1~inch smaller than the actual figure
+% size.  Setting it to $-0.5$ inch (\textit{a negative value!}) will make
+% the caption always 1 inch larger than the actual figure size (within
+% the error of the actual figure dead margin width, and subject to the
+% caption width min/max constraints).
+%
+% \DescribeMacro{\abovecaptionskipterm}
+% \DescribeMacro{\belowcaptionskipterm}
+% The quantities |\abovecaptionskipterm| and |\belowcaptionskipterm|
+% are related to
+% \LaTeX{}'s |\abovecaptionskip| and |\belowcaptionskip| functions,
+% defining the white- space above and below a caption.  Unlike the
+% corresponding \LaTeX{} functions, the parameters here are integers (not
+% lengths).  The terms represent multipliers of the \LaTeX{} length
+% measure |\p@| to be  used for the above- and below- captionskip. 
+% Their default values are 10 and 7, respectively.  These
+% values affect only captions that are created as part of bxtable and
+% bxfigure, and do not affect the |\abovecaptionskip| and
+% |\belowcaptionskip| definitions intrinsic to your default document
+% class.
+% \begin{picture} (0,0)
+%   \put(-63,191){\makebox(20,0)[l]
+%                 {\small\tt\bs abovecaption-}}
+%   \put(-63,182){\makebox(20,0)[l]
+%          {\small~~|skipterm| = 3~~$\rightarrow$}}
+%   \put(-90,164){\makebox(20,0)[l]
+%          {\small\tt\bs FigureDeadMargin\rm = 1em~$\uparrow$}}
+%   \put(-90,155){\makebox(20,0)[l]
+%          {\small (1em on left; 1em on right)}}
+% \end{picture}
+%
+% \DescribeMacro{\CaptionFontSize}
+% |\CaptionFontSize| defines the default size of the caption font, for
+% example \normalsize, |\large|, |\scriptsize|, etc.  The default value
+% is |\small|.
+%
+% \DescribeMacro{\TableFontSize}
+% |\TableFontSize| defines the default size of the font that appears
+% within the tables themselves.  Its default value is |\small|.
+%
+% \DescribeMacro{\LRTablePlacement}
+% \DescribeMacro{\LRFigurePlacement}
+% |\LRTablePlacement| and |\LRFigurePlacement| define the horizontal
+% placement of tables and figures with respect to the paper margins.  The
+% options for these two parameters include |{flushleft}|, |{center}| and
+% |{flushright}|.  The default is |{center}|.  This is different from the
+% ``left'', ``center'', and ``right'' alignment modes for captions,
+% which align short captions with respect to the boxed data.
+%
+% \DescribeMacro{\CaptionJustification}
+% By default, any caption that spans the entire width of the caption box
+% will be fully justified, or ``flushed'' with respect to the caption box
+% margins.  However, this behavior can be reset by redefining the
+% parameter |\CaptionJustification|.  For a ragged-right style within the
+% caption box, the definition should be set to |\raggedright|.  For the
+% brave and daring, |\raggedleft| and/or |\centering| can be explored.
+% Use |\def\CaptionJustification{}| to reset subsequent captions for full
+% flushing.
+%
+% Figure~\ref{fig:ragged} is provided to demonstrate some of these
+% features including:  caption justification (|\raggedright|), caption gap
+% (2.5~ex), caption font size (|\scriptsize|), LR figure placement 
+% (|flushright|), |abovecaptionskipterm| (3), and a value for
+% |\FigureDeadMargin| of 1em.
+%
+% \captionStyle{o}{l}\setlength\captionGap{2.5ex}
+% \def\CaptionJustification{\raggedright}\let\CaptionFontSize\scriptsize
+% \setcounter{abovecaptionskipterm}{3}
+% \def\LRFigurePlacement{flushright}\setlength\FigureDeadMargin{1em}
+% \bxfigure[t]{Here is one example of a caption that has been set for
+%            a ragged right justification.  Justification, or ``flushing,''
+%            is different than caption alignment, which is specified
+%            independently and deals with how short captions are
+%            aligned with respect to the boxed object\label{fig:ragged}}
+%            {\framebox(263,60)
+%              {\parbox{3.5in}{Boxed Object:\\
+%               \small \hspace*{2.05in}
+%               |flushright| \textit{placement $\rightarrow$\\
+%               \hspace*{.17in} \uq 2.5ex \hspace*{0.45in}
+%               \tt\bs\rm|scriptsize| \iq \\
+%               caption gap \hfill caption font size \hfill
+%               \uq\tt\bs\rm{|raggedright|} \iq justification}\\
+%               \hspace*{.50in} $\downarrow$ \hfill $\downarrow$
+%                        \hfill \hfill $\downarrow$~~~}
+%              }
+%            }
+% \def\CaptionJustification{}\setlength\captionGap{2.5ex}
+% \let\CaptionFontSize\small \setcounter{abovecaptionskipterm}{10}
+% \def\LRFigurePlacement{center}\setlength\FigureDeadMargin{0em}
+%
+% \section{Box and List Deferral/Preemption}
+%
+% \subsection{Description of Problem}
+%
+% For those using conditional compilation to create various versions of
+% the same basic document, the |boxhandler| package can provide great
+% utility.  The package has been designed to permit the deferral and
+% preemption of certain aspects of the document, such as figures, tables
+% and lists.  With such a capability, one has the capacity to not only
+% change the appearance of the alternate document version, but to
+% fundamentally change its layout too.  Table~\ref{tbl:cccode} provides a
+% simple example of how a document may be set up for conditional
+% compilation.
+% 
+% \setlength\TableDeadMargin{0.2em}\bxtable[h]
+% {Conditionally compiled \LaTeX{} code\label{tbl:cccode}}
+% {\begin{tabular}{c}\hline\\
+%   \ttfamily\parbox{4.15in}{
+%     \bs def\bs PREPARETYPE\lb\bs TECHRPT\rb\% choices: \bs TECHRPT or
+%     \bs MANUSCRIPT\\
+%     \bs newcommand\bs TECHRPT\lb\% class for ARL organizational tech rpts\\
+%     \% CONDITIONALLY COMPILED CODE FOR TECHRPT DOCUMENTS\\
+%     | |\bs documentclass\lb arlticle\rb\\
+%     \rb\\
+%     \bs newcommand\bs MANUSCRIPT\lb\% article-ized version of tech rpt.\\
+%     \% CONDITIONALLY COMPILED CODE FOR MANUSCRIPTS\\
+%     | |\bs documentclass[11pt]\lb article\rb\\
+%     | |\bs usepackage\lb TR2article\rb\\
+%     \% VARIOUS \bs MANUSCRIPT-SPECIFIC SETUP COMMANDS GO HERE\\
+%     \rb\\
+%     \bs PREPARETYPE\\
+%     \% LaTeX CODE \& DOCUMENT COMMON TO BOTH STYLES FOLLOWS HEREAFTER\\
+%   }\\
+% \hline\end{tabular}
+% }
+%
+% In this example, by setting the parameter in the first line of the
+% document to either |\TECHRPT| or |\MANUSCRIPT|, a different collection
+% of setup routines may be invoked for each particular document style.
+% This works great for such parameters that affect appearance, but not
+% placement of the \LaTeX{} entities.  For example, changing fonts,
+% margins, indents, etc. works fine with the conditional code shown in
+% Table~\ref{tbl:cccode}.  Even when a particular document class has
+% unique commands not found in other classes, a converter style file may
+% be created (such as |TR2article| in the Table~\ref{tbl:cccode} example)
+% to deal rationally with invocations of class-specific features.
+%
+% Where great difficulty arises is when the different styles desired of a
+% conditional compilation utilize fundamentally different layouts of the
+% principal document elements, such as figures, tables, and lists.  For
+% example, a technical report would have it's tables and figures
+% interspersed throughout the document, whereas the corresponding journal
+% manuscript submission might have tables and figures collected, one per
+% page, at the end of the document.  Whereas the report would have the
+% List of Figures (\textit{lof}) as part of the report's front matter,
+% the journal manuscript might request to have the \textit{lof} preceding
+% the figures located at the end of the manuscript.  A typical scientific journal
+% manuscript submission would not include a Table of Contents
+% (\textit{toc}), and perhaps not a List of Tables (\textit{lot}) either.
+%
+% Arranging for such options to unfold from a single input source file is
+% cumbersome without a special treatment.  The |boxhandler| style
+% provides routines to expedite and ease this cumbersome process.
+%
+% \subsection{Deferral and Preemption Commands}
+%
+% For figure and table deferral, and/or list deferral/preemption, the
+% following commands are available, all without arguments:
+%
+% \begin{verse}
+% |\holdTables|\\
+% |\holdFigures|\\
+% |\clearTables|\\
+% |\clearFigures|\\
+% |\killlistoftables|\\
+% |\killlistoffigures|\\
+% |\killtableofcontents|\\
+% |\holdlistoftables|\\
+% |\holdlistoffigures|\\
+% |\clearlistoftables|\\
+% |\clearlistoffigures|\\
+% \end{verse}
+%
+% \DescribeMacro{\holdTables}
+% \DescribeMacro{\holdFigures}
+% |\holdTables| and |\holdFigures| are used to direct that any subsequent
+% invocations of |\bxtable| and |\bxfigure| merely store, rather than
+% store \& print the table or figure.  These |\hold...| commands would
+% typically be found in the conditionally compiled code for manuscripts,
+% for example.
+%
+% While the calculated width of the caption is saved at the time of call
+% to |\bxtable| and |\bxfigure| based upon the |boxtable| parameters at
+% the time of the |\bx...| call, the caption format (i.e., [no]offset,
+% center/left alignment, caption justification) is not set until the
+% figure/table is later printed as part of a |\clear...| command (the
+% logic here is that the caption style will be consistent through the
+% course of the document, thus alleviating the need to store this data
+% for each figure and table).
+%
+% \DescribeMacro{\clearTables}
+% \DescribeMacro{\clearFigures}
+% |\clearTables| and |\clearFigures| directs that any tables or figures
+% that have been stored, but not yet printed, be output at this point.
+% As mentioned above, the offset, alignment, and justification for
+% captions is set at the time of printing, not at the time of table or
+% figure creation.  The format for presenting tables and figures to be
+% cleared (i.e., one table/figure per page, vertically centered) can be
+% changed by renewing the commands |\theClearedTable| and/or
+% |\theClearedFigure|.  See the next section on Advanced Use for details.
+%
+% Note that if tables and figures have not been subject to a |\hold...|
+% command, the |\clear...| commands have no effect, since they affect
+% only those tables and/or figures which have not already been printed.
+% Thus, these commands would typically appear in the common document text
+% at the appropriate point where tables and figures, if previously held,
+% should be printed.  Note that, though commands have not been explicitly
+% provided to kill the printing of figures and tables, this can be
+% effectively accomplished by putting figures and/or tables on hold, and
+% then ending the document without having issued a corresponding
+% |\clear...| command.
+%
+% \DescribeMacro{\killlistoftables}
+% \DescribeMacro{\killlistoffigures}
+% \DescribeMacro{\killtableofcontents}
+% |\killlistoftables|, |\killlistoffigures| and |\killtableofcontents|
+% direct that any subsequent calls to print the respective list be
+% ignored and that the list be discarded.  This action cannot later be
+% undone with a |\hold...| command.  These commands would typically
+% appear in the conditionally compiled region of the document.
+%
+% \DescribeMacro{\holdlistoftables}
+% \DescribeMacro{\holdlistoffigures}
+% |\holdlistoftables| and |\holdlistoffigures| direct that calls to print
+% the particular list cited be deferred until a later invocation of the
+% corresponding |\clear...| command.  Note that a call to |\clearTables|
+% and |\clearFigures| will also clear the corresponding list first, if it
+% has been subject to a |\hold...| command (but not a |\kill...|
+% command).  These |\hold...| commands would typically appear in the
+% conditionally compiled region of the document.
+%
+% \DescribeMacro{\clearlistoftables}
+% \DescribeMacro{\clearlistoffigures}
+% |\clearlistoftables| and |\clearlistoffigures| clear the cited list
+% (i.e., those lists currently ``on hold'').  No list will be
+% printed if:  the |\listoftables| or |\listoffigures| command hadn't
+% earlier been invoked; if it had already been printed out because it
+% hadn't been subject to a hold; or if the list had previously been
+% killed. Note: calls to |\clearTables| or |\clearFigures| automatically
+% causes a call to |\clearlistoftables| or |\clearlistoffigures|,
+% respectively.  Therefore, these particular calls are only needed
+% explicitly in your \LaTeX{} document if it is desired to clear the list
+% well in advance of the associated tables or figures.
+%
+% With the deferral and preemption commands now described, we show how
+% they might be used to complete the multi-mode \LaTeX{} document stencil
+% that was first laid out in Table~\ref{tbl:cccode}.  To see this, refer
+% to Table~\ref{tbl:bxcode}.  The document is created with |\bxtable| and
+% |\bxfigure| calls dispersed throughout text, and nominally asks for the
+% \textit{toc}, \textit{lof}, and \textit{lot} to be printed at the
+% beginning of the document.  When |\PREPARETYPE| is defined as
+% |{\TECHRPT}|, this is exactly how the document unfolds.
+%
+% \setlength\TableDeadMargin{0.2em}\bxtable[t!]
+% {Conditionally compiled \LaTeX{} code with \texttt{boxhandler} package
+% deferral and preemption directives\label{tbl:bxcode}}
+% {\begin{tabular}{c}\hline\\
+%   \ttfamily\parbox{4.15in}{
+%     \bs def\bs PREPARETYPE\lb\bs TECHRPT\rb\% choices: \bs TECHRPT or
+%     \bs MANUSCRIPT\\
+%     \bs newcommand\bs TECHRPT\lb\% class for ARL organizational tech rpts\\
+%     \% CONDITIONALLY COMPILED CODE FOR TECHRPT DOCUMENTS\\
+%     | |\bs documentclass\lb arlticle\rb\\
+%     | |\bs usepackage\lb boxhandler\rb\\
+%     \rb\\
+%     \bs newcommand\bs MANUSCRIPT\lb\% article-ized version of tech rpt.\\
+%     \% CONDITIONALLY COMPILED CODE FOR MANUSCRIPTS\\
+%     | |\bs documentclass[11pt]\lb article\rb\\
+%     | |\bs usepackage\lb TR2article\rb\\
+%     | |\bs usepackage\lb boxhandler\rb\\
+%     | |\bs killtableofcontents\\
+%     | |\bs killlistoftables\\
+%     | |\bs holdlistoffigures\\
+%     | |\bs holdTables\\
+%     | |\bs holdFigures\\
+%     \% VARIOUS \bs MANUSCRIPT-SPECIFIC SETUP COMMANDS GO HERE\\
+%     \rb\\
+%     \bs PREPARETYPE\\
+%     \% LaTeX CODE \& DOCUMENT COMMON TO BOTH STYLES FOLLOWS HEREAFTER\\
+%     \bs begin\lb document\rb\\
+%     \bs maketitle\\
+%     \bs tableofcontents\\
+%     \bs listoffigures\\
+%     \bs listoftables\\
+%     ...\\
+%     \% DOCUMENT CONTAINING \bs bxtable AND \bs bxfigure CALLS GOES HERE.\\
+%     ...\\
+%     \bs clearTables\\
+%     \bs clearFigures\\
+%     \bs end\lb document\rb\\
+%   }\\
+% \hline\end{tabular}
+% }
+%
+% However, by merely defining |\PREPARETYPE| as |{\MANUSCRIPT}|, the
+% \textit{toc} and \textit{lot} will be killed, preempting subsequent
+% invocations.  Printing of the \textit{lof} will be deferred.  As
+% |bxtables| and |bxfigures| are invoked, they will be created and
+% stored, but not printed.  At the very end of the document, all the
+% tables will first be cleared, one per page, vertically centered. The
+% call to |\clearFigures| will then clear the \textit{lof} on a new page,
+% and finally clear all the figures in a similar manner.
+%
+% \textbf{With the change of a single line of code, a vastly different
+% document layout has been achieved!}
+%
+% \section {Advanced Use (DANGER!)}
+%
+% Additionally, there are certain lower level, yet accessible, counters,
+% macros and lengths, which are intended for advanced use only.  It is
+% possible to get into difficulty if not thinking through their use
+% thoroughly.  Pitfalls will be laid out, where known.  These accessible
+% hooks into the inner workings of the |boxhandler| package include:
+%
+% \begin{verse}
+% \underline{Lengths:}\\
+% |\DeadMargin, \CaptionBoxWidth|\\
+% \underline{Counters:}\\
+% |TableIndex, FigureIndex, TableClearedIndex,|\\
+% |FigureClearedIndex, promptTablesFlag, promptFiguresFlag|\\
+% \underline{Macros:}\\
+% |\StoreTable{|\iq caption\uq|}{|\iq boxed object\uq|}|\\
+% |\StoreFigure{|\iq caption\uq|}{|\iq boxed object\uq|}|\\
+% |\SaveCBox{|\iq new cmd\uq|}{|\iq boxed object\uq|}|\\
+% |\ReciteTable[|\iq loc\uq|]{|\iq caption\uq|}{|\iq cmd\uq
+%    |}{|\iq wdth\uq|}|\\
+% |\ReciteFigure[|\iq loc\uq|]{|\iq caption\uq|}{|\iq cmd\uq
+%    |}{|\iq wdth\uq|}|\\
+% |\theClearedTable[|\iq loc\uq|]{|\iq caption\uq|}{|\iq cmd\uq
+%    |}{|\iq wdth\uq|}|\\
+% |\theClearedFigure[|\iq loc\uq|]{|\iq caption\uq|}{|\iq cmd\uq
+%    |}{|\iq wdth\uq|}|\\
+% \end{verse}
+%
+% \DescribeMacro{TableIndex}
+% \DescribeMacro{FigureIndex}
+% \DescribeMacro{TableClearedIndex}
+% \DescribeMacro{FigureClearedIndex}
+% To keep track of tables and figures as they are created, the counters
+% |TableIndex| and |FigureIndex| are used.  To keep track of how many
+% tables and figures have already been printed, |TableClearedIndex|, and
+% |FigureClearedIndex| are used.  The appropriate index is incremented
+% whenever a table or figure is created or cleared.  These index counters
+% are also used as part of the naming convention employed by the
+% |\StoreTable| and |\StoreFigure| commands, to be subsequently
+% described.
+%
+% \DescribeMacro{promptTablesFlag}
+% \DescribeMacro{promptFiguresFlag}
+% The counters |promptTablesFlag| and |promptFiguresFlag| are used as
+% binary switches to determine whether calls to |\bxtable| and
+% |\bxfigure| result in the prompt display (1) or deferred display (0) of
+% the table or figure.  The |\holdTables| and |\holdFigures| commands
+% change these switches to their `0' state.  Any significant use of these
+% switches to achieve the printing of latter tables/figures prior to the
+% clearing of earlier ones will require the rewrite, by the user, of the
+% |\clearTables| and |\clearFigures| commands, since these |\clear...|
+% macros were written using a first-in-first-out (FIFO) methodology.
+%
+% \DescribeMacro{\StoreTable}
+% \DescribeMacro{\StoreFigure}
+% The macros |\StoreTable| and |\StoreFigure| use the same form of
+% caption and data arguments as |\bxtable| and |\bxfigure|.  In fact, the
+% |\bx...| commands call upon the |\Store...| macros.  The difference
+% is that the |\StoreTable| and |\StoreFigure| macros will save the
+% boxed object without printing it, regardless of whether a |\hold...|
+% command has been issued.  The saved information will consist of three
+% pointers necessary to recreate the table or figure.  These pointers
+% will be named according to |boxhandler|'s internal naming convention.
+%
+% At this point, it is worth noting the naming convention of the pointers
+% used by |boxhandler| to store the variables for figures and tables.
+% The saved information resulting from a |\StoreTable| or |\StoreFigure|
+% command will consist of a pointer to a saved box, a pointer to the
+% caption text, and a pointer to the calculated width of the caption box
+% (based on the state of the |boxhandler| parameters at the time of the
+% function call).
+%
+% The counters |TableIndex| and |FigureIndex| are used to create a unique
+% part of these pointer names, in the form of |\roman{|\iq
+% indexname\uq|}|.  Saved box pointers have the prefix |tbl-| or |fig-|,
+% saved caption pointers have the prefix |tblcap-| or |figcap-| and
+% caption-width pointers have the prefix |tblcapwdth-| and |figcapwdth-|.
+% Thus, for example, the fourth invocation of |\bxtable| or |\StoreTable|
+% will create an sbox named |\tbliv| that is used to store the boxed
+% (e.g., tabular) data, a pointer |\tblcapiv| that is used to store the
+% caption text, and a length pointer |\tblcapwdthiv| that stores the
+% value of the calculated caption width.  When avoiding creative
+% programming, the pointer index (e.g., `iv' in this example) will
+% correspond to the actual Table or Figure number (i.e., `4') appearing
+% in the caption ID label.  However, it is wise to remember,
+% \begin{enumerate}
+% \item when creating tables or figures outside of the |boxhandler| style;
+% \item when bypassing the |\Store...| commands and going straight to the
+% lower level |\SaveCBox| command; or
+% \item when using the |\Recite...| commands to print multiple occurances
+% of a box;
+% \end{enumerate}
+% that the internal numbering of |boxhandler| tables and figures will
+% likely be out of syncronization with the Table and Figure counters.
+%
+% \DescribeMacro{\SaveCBox}
+% The low-level routine which saves a ``captioned box'' is called
+% |\SaveCBox|.  As its arguments, it follows the form of the \LaTeX{}
+% |\sbox| command: it takes a new command name and the boxed object as
+% its parameters.  This is the routine called by the |\Store...| commands
+% with a command argument something like |\tbliv| or |\figiii|, for
+% example.  You are, however, free to pass your own command names to this
+% routine, so as not to conflict with the names autogenerated by the
+% |\Store...| commands.  Keep in mind that calls to |\SaveCBox| will not,
+% by themselves, increment |TableIndex| or |FigureIndex|, and will not be
+% tracked by the |\clear...| commands.
+%
+% \DescribeMacro{\DeadMargin}
+% \DescribeMacro{\CaptionBoxWidth}
+% In addition to saving the boxed object in the specified command bin,
+% the width of the associated caption is calculated, based upon the
+% prevailing |boxhandler| parameters at the time of call.  One such
+% parameter that is used to calculate the caption width, is the dead
+% margin.  |\SaveCBox|, being a low-level routine, is used for both
+% tables and figures.  As such, the appropriate variable to set, in order
+% to define the dead margin is the generic length |\DeadMargin|,
+% regardless of whether the call is to save a figure or a table box. The
+% calculated caption width is stored in the length variable
+% |\CaptionBoxWidth|.  This length variable is ephemeral, being updated
+% with each new figure or table generated, and so it is up to the user to
+% save the value of |\CaptionBoxWidth| somewhere else if it is to be used
+% to later define a recited box's caption width.  Likewise, while
+% |\SaveCBox| does not even deal with the box's caption text per se, it
+% is the user's responsibility to save the actual caption somewhere, for
+% later recitation.
+%
+% \DescribeMacro{\ReciteTable}
+% \DescribeMacro{\ReciteFigure}
+% Reciting stored tables or figures is accomplished by way of
+% |\ReciteTable| and |\ReciteFigure|.  As the [optional] first of their
+% four arguments, they take the location directive for placement on the
+% page (e.g., |h|, |t|, |b|, or |p|).  Both the caption and the caption
+% width arguments may be specified directly, or indirectly by way of a
+% stored string and length variable, respectively.  The command argument
+% to these macros must be the bin for the saved box object that
+% constitutes the actual table or figure data.
+%
+% If one desires, the |\Recite...| commands may be used repeatedly to
+% print a given table or figure multiple times.  However, any |\label|
+% associated with the [repeatedly recited] caption will be reassigned to
+% the most recent invocation of the |\Recite...| call.  Thus, references
+% to the table or figure number by way of a |\ref| call are likely to
+% produce an undesired result, if a given table or figure is recited
+% multiple times.
+%
+% \DescribeMacro{\theClearedTable}
+% \DescribeMacro{\theClearedFigure}
+% Finally, two very useful routines to be familiar with are the
+% |\theClearedTable| and |\theClearedFigure| macros.  These are the
+% routines which are repeatedly called by |\clearTables| and
+% |\clearFigures|, respectively, to print out all tables and figures
+% which have been ``on hold.''  The manner in which |boxhandler| clears
+% them is one per page, vertically centered.  It is easy to envision
+% applications in which the method of clearing would take on a different
+% appearance than this.  To change the appearance by which tables and/or
+% figures are cleared, these commands need to be redefined by the user by
+% way of a |\renewcommand|.  For reference, the |\theClearedTable|
+% command is defined by |boxhandler| as:
+%
+%| |\\
+%|\newcommand\theClearedTable[4][h]{|\\
+%|  \vspace*{\fill}|\\
+%|  \ReciteTable[#1]{#2}{#3}{#4}|\\
+%|  \vspace*{\fill}|\\
+%|  \clearpage|\\
+%|}|\\
+%
+% As one can see, |\theClearedTable| is a call to |\ReciteTable| that is
+% surrounded by the code necessary to place the table recitation at the
+% desired location upon the page.  |\theClearedFigure| is defined
+% analogously.  Modification of this layout should be straightforward for
+% the user.  For example, if it were desired to have two tables per page
+% during the clearing process, one might use the following renewal:
+%
+%| |\\
+%|\newcounter{toggle} \setcounter{toggle}{0}|\\
+%|\renewcommand\theClearedTable[4][h]{|\\
+%|  \addtocounter{toggle}{1}|\\
+%|  \ifnum \arabic{toggle} = 2 \setcounter{toggle}{0} \fi|\\
+%|  \ifnum \arabic{toggle} = 1|\\
+%|    \ReciteTable[t]{#2}{#3}{#4}|\\
+%|  \else|\\
+%|    \ReciteTable[b]{#2}{#3}{#4}|\\
+%|    \clearpage|\\
+%|  \fi|\\
+%|}|
+%
+% \section {Examples}
+%
+%% Examples of a number of calls provided in this style are given below,
+%% in no particular order:
+%%
+%%|                                                                 |\\
+%%|\bxtable[t]                                                      |\\
+%%|  {This is a test of nonwrapping caption\label{tb:mytable}}      |\\
+%%|  {                                                              |\\
+% \iffalse
+%<package>%%|  \begin{tabular}{|c|c|c|}                                       |\\
+% \fi
+%|  \begin{tabular}{|\verb,|c|c|c|,|}                              |\\
+%%|    \hline                                                       |\\
+%%|    column 1 data & 2nd column data & and the third column data\\|\\
+%%|    \hline                                                       |\\
+%%|  \end{tabular}                                                  |\\
+%%|  }                                                              |\\
+%%|                                                                 |\\
+%%|\usepackage{graphicx}                                            |\\
+%%|\bxfigure[h]                                                     |\\
+%%|  {Here is an example of a particularly long caption that will   |\\
+%%|          test wrapping}                                         |\\
+%%|  {\includegraphics[width=3.64in,height=4.30in]{Atest1.eps}}     |\\
+%%|                                                                 |\\
+%%|\relaxCaptionWidth[2in]                                          |\\
+%%|                                                                 |\\
+%%|\captionStyle{}{c}                                               |\\
+%%|                                                                 |\\
+%%|\setlength\captionGap{3ex}                                       |\\
+%%|                                                                 |\\
+%%|\setcounter{abovecaptionskipterm}{10}                            |\\
+%%|\setcounter{belowcaptionskipterm}{0}                             |\\
+%%|                                                                 |\\
+%%|\TableFontSize\normalsize                                        |\\
+%%|                                                                 |\\
+%%|\LRFigurePlacement{flushleft}                                    |\\
+%%|                                                                 |\\
+%%|\killtableofcontents                                             |\\
+%%|                                                                 |\\
+%%|\holdFigures                                                     |\\
+%%|                                                                 |\\
+%%|\clearFigures                                                    |\\
+%%|                                                                 |\\
+%%|\newsavebox{\mybox}                                              |\\
+%%|\SaveCBox{\mybox}{\framebox(200,100){Ack!}}                      |\\
+%%|                                                                 |\\
+%%|\ReciteFigure[h]{\figcapii}{\figii}{\figcapwdthii}               |\\
+%%
+% \section {Vestigials}
+%
+% \DescribeMacro{\arltable}
+% \DescribeMacro{\arlfigure}
+% In order to retain backward compatibility with the predecessor to the
+% |boxhandler| package, the vestigial commands |\arltable| and
+% |\arlfigure| are defined in this package, and are equivalent to
+% |\bxtable| and |\bxfigure|, respectively.
+%
+% As an historical note, the genesis of the |boxhandler| package was a
+% requirement to comply with my organization's caption style (``offset''
+% style, ``left'' aligned) specified for its technical reports.  Various
+% kludges were out there to handle it, requiring a fair amount of
+% case-specific hand-holding and babysitting, depending on the specifics
+% of the figure/table box and the caption.  |boxhandler| was intended to
+% simplify and generalize the approach.
+%
+% The figure/table deferral features of |boxhandler| were borne of my own
+% laziness.  I just didn't relish keeping two different versions of the
+% same document up to date... one for my organization, and the other as a
+% manuscript for possible journal submission.  The |\bx...| commands
+% provided an easier ``hook'' through which to achieve the holding and
+% clearing of boxes than did any attempt to muck with the underlying
+% |Figure| and |Table| environments of \LaTeX{}.
+%
+% \section {Salutations}
+% That's it for a description of |boxhandler|!  I hope the package
+% provides you some utility. The only thing left is the code listing
+% itself.
+% \StopEventually{}
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+% \vspace{-0.8em}
+% \begin{macro}{boxhandler.sty}
+% \section{Code Listing}
+% I'll try to lay out herein
+% the workings of the |boxhandler| style package.  I apologize if
+% the code fails in some way to conform to \LaTeX{} programming
+% conventions. I am but an enthusiastic novice.
+%    \begin{macrocode}
+%<*package>
+%    \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{pbox}
+% This package makes use of the |pbox| style package to aid in the
+% boxing of captions.
+%    \begin{macrocode}
+\usepackage{pbox}
+%    \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{TableIndex}
+%   \begin{macro}{FigureIndex}
+%     \begin{macro}{TableClearedIndex}
+%       \begin{macro}{FigureClearedIndex}
+% We start by defining and initializing the counters that keep track of
+% how many tables and figures have been created and how many have been
+% cleared (i.e., printed out).
+%    \begin{macrocode}
+\newcounter{TableIndex}          \setcounter{TableIndex}{0}
+\newcounter{FigureIndex}         \setcounter{FigureIndex}{0}
+\newcounter{TableClearedIndex}   \setcounter{TableClearedIndex}{0}
+\newcounter{FigureClearedIndex}  \setcounter{FigureClearedIndex}{0}
+%    \end{macrocode}
+%      \end{macro}
+%    \end{macro}
+%   \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\old@makecaption}
+%   \begin{macro}{\oldabovecaptionskip}
+%     \begin{macro}{\oldbelowcaptionskip}
+% Here, we save the prevailing definitions of |\@makecaption|,
+% |\abovecaptionskip| and |\belowcaptionskip|, so that they can be
+% altered before and restored after every invocation of |\bxtable| and
+% |\bxfigure|.
+% \begin{macrocode}
+\let\old@makecaption \@makecaption% SAVE PREVAILING \@makecaption STYLE
+\newlength\oldabovecaptionskip
+\setlength\oldabovecaptionskip \abovecaptionskip
+\newlength\oldbelowcaptionskip
+\setlength\oldbelowcaptionskip \belowcaptionskip
+%    \end{macrocode}
+%     \end{macro}
+%   \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\captionGap}
+% Initialize |\captionGap| to 1ex, which sets the horizontal space
+% between the caption label and the caption box for offset-style
+% captions.
+%    \begin{macrocode}
+%% \captionGap CAN BE INCREASED TO PLACE MORE SPACE BETWEEN THE CAPTION
+%% LABEL AND THE ACTUAL CAPTION TEXT.
+\newlength\captionGap          \setlength\captionGap{1ex}
+%    \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\TableDeadMargin}
+%   \begin{macro}{\FigureDeadMargin}
+% The default values for the dead margin around tables and figures is
+% initialized here.  The value of 0.375em for tables corresponds to what
+% the |tabular| environment seems to produce.  No presupposition is made
+% on what the dead margin is for the figure environment, however.
+%    \begin{macrocode}
+%% \TableDeadMargin AND \FigureDeadMargin REFER TO THE TABLE & FIGURE
+%% MARGIN OF A BOX THAT COUNTS TOWARDS ITS SIZE, BUT IN WHICH NO
+%% ACTIVE DATA FALLS; DEADMARGIN ASSUMED ON BOTH LEFT & RIGHT SIDE.
+\newlength\TableDeadMargin     \setlength\TableDeadMargin{0.375em}
+\newlength\FigureDeadMargin    \setlength\FigureDeadMargin{0em}
+%    \end{macrocode}
+%   \end{macro}
+% \end{macro}
+%
+% \begin{macro}{abovecaptionskipterm}
+%   \begin{macro}{belowcaptionskipterm} The integer parameters
+% |abovecaptionskipterm| and |belowcaptionskipterm| are initialized here.
+% They will be used to guide the temporarily alteration of
+% |\abovecaptionskip| and |\belowcaptionskip| during invocations of
+% |\bxtable| and |\bxfigure|.
+%    \begin{macrocode}
+%% INITIALIZE \above- AND \belowcaptionskip VALUES; CAN BE RESET
+%% USED TO SET GAPS ABOVE & BELOW CAPTIONS
+\newcounter{abovecaptionskipterm}  \setcounter{abovecaptionskipterm}{10}
+\newcounter{belowcaptionskipterm}  \setcounter{belowcaptionskipterm}{7}
+%    \end{macrocode}
+%   \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\@minCaptionBoxWidth}
+%   \begin{macro}{\@minCaptionBoxWidthDefault}
+%     \begin{macro}{\@maxCaptionBoxWidth}
+%       \begin{macro}{\@maxCaptionBoxWidthDefault}
+% The minimum and maximum allowed width defaults for the caption box are
+% defined here.  The variables holding the current values of min/max
+% caption width are also allocated here.  Their values will be set and
+% altered through the use of the macros |\relaxCaptionWidth|,
+% |\limitCaptionWidth| and |\constrainCaptionWidth|, to be described
+% later.
+%    \begin{macrocode}
+%% RESET \@minCaptionBoxWidth TO Default VALUE WITH \relaxCaptionWidth
+%% SET \@minCaptionBoxWidth TO USER VALUE WITH \relaxCaptionWidth[<len>]
+\newlength\@minCaptionBoxWidth
+\newlength\@minCaptionBoxWidthDefault
+\setlength\@minCaptionBoxWidthDefault{1in}
+%% RESET \@maxCaptionBoxWidth TO Default WITH \limitCaptionWidth
+%% SET \@maxCaptionBoxWidth WITH \limitCaptionWidth[<len>]
+\newlength\@maxCaptionBoxWidth
+\newlength\@maxCaptionBoxWidthDefault
+\setlength\@maxCaptionBoxWidthDefault{\textwidth}
+%    \end{macrocode}
+%       \end{macro}
+%     \end{macro}
+%   \end{macro}
+% \end{macro}
+%
+% \begin{macro}{promptTablesFlag}
+%   \begin{macro}{promptFiguresFlag}
+%     \begin{macro}{\holdTables}
+%       \begin{macro}{\holdFigures}
+% |promptTablesFlag| and |promptFiguresFlag| are binary switches to
+% define whether calls to |\bxtable| and |\bxfigure| are cleared (i.e.,
+% printed) promptly or merely stored for later clearing.  The change to
+% put them ``on hold'' is actuated by the |\holdTables| and
+% |\holdFigures| commands, respectively.  Because the associated
+% |\clear...| commands were written with FIFO logic, no mechanism is
+% provided to reset the flags to ``prompt'', once set to ``on hold.''
+% Even so, tables and figures can be cleared in sub-batches, by issuing a
+% series of |\clear...| commands at intermediate points in the document.
+%    \begin{macrocode}
+%% DEFINE promptTablesFlag & PROVIDE ROUTINE TO CHANGE IT FROM
+%% "PROMPT"(1) TO "ON HOLD"(0)
+\newcounter{promptTablesFlag}    \setcounter{promptTablesFlag}{1}
+\newcommand\holdTables{\setcounter{promptTablesFlag}{0}}
+%% SAME FOR promptFiguresFlag
+\newcounter{promptFiguresFlag}   \setcounter{promptFiguresFlag}{1}
+\newcommand\holdFigures{\setcounter{promptFiguresFlag}{0}}
+%    \end{macrocode}
+%       \end{macro}
+%     \end{macro}
+%   \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\CaptionFontSize}
+%   \begin{macro}{\TableFontSize}
+% Default size of font in both captions and tables is, by default,
+% |\small|.  However, these variables allow those defaults to be reset to
+% the desired font size.
+%    \begin{macrocode}
+%% DEFAULT CaptionFontSize & TableFontSize AS \small; CAN BE RESET
+\let \CaptionFontSize \small
+\let \TableFontSize \small
+%    \end{macrocode}
+%   \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\LRTablePlacement}
+%   \begin{macro}{\LRFigurePlacement}
+% These variables set the placement of the table or figure either flushed
+% to the left or right margin, or else centered between the margins (the
+% default).  They can be reset by the user.
+%    \begin{macrocode}
+%% DEFAULT TABLE & FIGURE LR ALIGNMENT TO center;
+%% CAN RESET TO flushleft/-right
+\def \LRTablePlacement {center}
+\def \LRFigurePlacement {center}
+%    \end{macrocode}
+%   \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\CaptionJustification}
+% The flushing of the actual text within the caption box may be
+% accomplished by setting |\CaptionJustification|.  When it is defined
+% as |{}| (the default), the caption is fully justified (i.e.,
+% flushed) within the caption box.  It may also be set to
+% |{\raggedleft}|, |{\raggedright}| or |{\centering}|.
+%    \begin{macrocode}
+%% WITHIN-CAPTION JUSTIFICATION CAN BE SET
+%% OPTIONS: {}, {\raggedleft}, {\raggedright}, or {\centering}
+\def\CaptionJustification{} % <---DEFAULT IS FULL JUSTIFICATION
+%    \end{macrocode}
+% \end{macro}
+%
+%\vspace{2em}
+% \begin{macro}{\DeadMargin}
+%   \begin{macro}{\CaptionBoxWidth}
+%     \begin{macro}{\@DataBoxWidth}
+%       \begin{macro}{\@DataBoxOffset}
+%         \begin{macro}{\@CaptionBoxOffset}
+%           \begin{macro}{\@captionIDwidth}
+%             \begin{macro}{\@captionWidth}
+%               \begin{macro}{\@DataBoxSurplus}
+% New working variables are defined here.  All are |@|-protected from
+% access except for |\DeadMargin| and |\CaptionBoxWidth|, which have been
+% made accessible for so-called ``Advanced Use.''
+% |\DeadMargin| is the low-level variable where the dead margin of the
+% current figure or table box is specified by the advanced user.
+% |\@DataBoxWidth| is the calculated width of the data-box portion of
+% the current table or figure.
+% |\CaptionBoxWidth| is the calculated width of the caption box for the
+% current figure, taking into account the dead margin as well as the
+% min/max allowed caption widths.  The ``advanced user'' can save this
+% datum for future figure/table recitation.
+% |\@DataBoxOffset| is the calculated spacer length that must be added to
+% both sides of the data box to bring it to the size of the caption box.
+% It will be zeroed, if the data box width exceeds the caption box width.
+% |\@CaptionBoxOffset| is the calculated spacer length that must be added
+% to both sides of the caption box to bring it to the size of the data
+% box.  It will be zeroed, if the caption box width exceeds the data box
+% width.
+% |\@captionIDwidth| is used for offset-style captions, and is the width
+% of the caption ID plus the caption gap (e.g., the width of
+% ``Figure 4.~~'').
+% |\@captionWidth| is, for offset-style captions, simply
+% |\CaptionBoxWidth| minus |\@captionIDwidth|; this value equals the
+% width of the |\parbox| which is used for the caption text in
+% offset-style captions.  Finally,
+% |\@DataBoxSurplus| is the excess of data box width over the caption box
+% width.  It can be positive or negative, depending on whether the data
+% box or caption box is larger.
+%    \begin{macrocode}
+%% WORKING VARIABLES
+\newlength\DeadMargin
+\newlength\@DataBoxWidth
+\newlength\CaptionBoxWidth
+\newlength\@DataBoxOffset
+\newlength\@CaptionBoxOffset
+\newlength\@captionIDwidth
+\newlength\@captionWidth
+\newlength\@DataBoxSurplus
+
+%    \end{macrocode}
+%               \end{macro}
+%             \end{macro}
+%           \end{macro}
+%         \end{macro}
+%       \end{macro}
+%     \end{macro}
+%   \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\bxtable}
+% The routine |\bxtable| will store the specified table.  If
+% |promptTablesFlag| equals unity, the table will also be immediately
+% cleared using the specified \textit{loc} parameter.  If
+% |\roman{TableIndex}| equalled, for example, |vii|, then the table data
+% would be stored in the box |\tblvii|, the caption text would be stored
+% in the pointer |\tblcapvii|, and the calculated caption width would be
+% stored in the pointer |\tblcapwdthvii|.
+%    \begin{macrocode}
+\newcommand\bxtable[3][t]{
+  \StoreTable[#1]{#2}{#3}
+  \ifnum \arabic{promptTablesFlag} = 1
+    \addtocounter{TableClearedIndex}{1}
+    \def\TableBoxLabel{tbl\roman{TableIndex}}
+    \def\TableCaptionLabel{tblcap\roman{TableIndex}}
+    \def\TblCaptionWidthLabel{tblcapwdth\roman{TableIndex}}
+    \ReciteTable[#1]{\csname\TableCaptionLabel\endcsname}
+                       {\csname\TableBoxLabel\endcsname}
+                        {\csname\TblCaptionWidthLabel\endcsname}
+  \fi
+}
+
+%    \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\StoreTable}
+% |\StoreTable| calculates the names of the pointers where the
+% table-data, -caption, and -width will be stored, and calls upon the
+% low-level |\SaveCbox| routine to actually save the tabular data and
+% compute the caption width.  It finally stores the caption text itself
+% and the calculated caption width.  Note that the optional first
+% argument, \textit{loc}, is a dummy argument that is not used here.
+%    \begin{macrocode}
+\newcommand\StoreTable[3][]{
+  \addtocounter{TableIndex}{1}
+  \setlength\DeadMargin\TableDeadMargin
+  \def\TableBoxLabel{tbl\roman{TableIndex}}
+  \def\TableCaptionLabel{tblcap\roman{TableIndex}}
+  \def\TblCaptionWidthLabel{tblcapwdth\roman{TableIndex}}
+  \expandafter\SaveCBox\csname\TableBoxLabel\endcsname{\TableFontSize#3}
+  \expandafter\def\csname\TableCaptionLabel\endcsname{#2}
+  \expandafter\newlength\csname\TblCaptionWidthLabel\endcsname
+  \expandafter\setlength\csname\TblCaptionWidthLabel\endcsname
+                                              \CaptionBoxWidth
+}
+
+%    \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\ReciteTable}
+% The |\ReciteTable| routine recites a previously stored table, using the
+% pointers that are provided as arguments.  First, the |\Table|
+% environment is invoked, and the left/right table-placement environment
+% is opened.  The routine then defines new definitions for
+% |\@makecaption|, |\abovecaptionskip| and |\belowcaptionskip|.  It then
+% uses the provided pointers to set the data-box and caption-box widths,
+% and calculates the offsets.  It recites the box caption (using the
+% caption-box offset, if needed) and then it recites the tabular-data box
+% (using the data-box offset, if needed).  The original definitions for
+% |\@makecaption|, |\abovecaptionskip| and |\belowcaptionskip| are
+% restored, the table placement environment is concluded and the table
+% itself is ended.
+%    \begin{macrocode}
+\newcommand\ReciteTable[4][h]{
+  \begin{table}[#1]
+    \begin{\LRTablePlacement}
+      \let\@makecaption \new@makecaption
+      \setlength\abovecaptionskip{\arabic{abovecaptionskipterm}\p@}
+      \setlength\belowcaptionskip{\arabic{belowcaptionskipterm}\p@}
+        \set@DataBoxWidth{#3}
+        \setlength\CaptionBoxWidth{#4}
+        \set@BoxOffsets
+        \rule{\@CaptionBoxOffset}{0em}%
+        \parbox{\CaptionBoxWidth}{\caption {#2}}%
+        \rule{\@CaptionBoxOffset}{0em}%
+        \par
+        \rule{\@DataBoxOffset}{0in}% 
+        \usebox{#3}
+        \rule{\@DataBoxOffset}{0in}% 
+      \let\@makecaption \old@makecaption
+      \setlength\abovecaptionskip \oldabovecaptionskip
+      \setlength\belowcaptionskip \oldbelowcaptionskip
+    \end{\LRTablePlacement}
+  \end{table}
+}
+
+%    \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\clearTables}
+% This routine will clear all stored tables that have not yet been
+% printed.  It assumes a FIFO logic.  It starts by clearing the page and
+% clearing the List of Tables (i.e., prints the \textit{lot} \textbf{if}
+% the List of Tables had been put on hold, and subsequently invoked while
+% ``on hold'').  If the \textit{lot} had previously been killed, then
+% |\clearlistoftables| will have no effect.  Once the \textit{lot} has
+% been cleared (or not), a loop is set up in which the names of
+% stored-table pointers are reconstructed, and successively passed to
+% |\theClearedTable| which defines the format for clearing and actually
+% calls for the table to be recited.
+%    \begin{macrocode}
+\newcommand\clearTables{
+  \clearpage
+  \clearlistoftables
+  \clearpage
+%%DO UNTIL ALL HELD TABLES ARE CLEARED
+  \whiledo{\arabic{TableClearedIndex} < \arabic{TableIndex}}{
+    \addtocounter{TableClearedIndex}{1}
+%%  \TableBoxLabel       : tbli,    tblii,    tbliii,    tbliv,    etc.
+%%  \TableCaptionLabel   : tblcapi, tblcapii, tblcapiii, tblcapiv, etc.
+%%  \TblCaptionWidthLabel: tblcapwdthi, tblcapwdthii, tblcapwdthiii,etc.
+    \def\TableBoxLabel{tbl\roman{TableClearedIndex}}
+    \def\TableCaptionLabel{tblcap\roman{TableClearedIndex}}
+    \def\TblCaptionWidthLabel{tblcapwdth\roman{TableClearedIndex}}
+    \theClearedTable{\csname\TableCaptionLabel\endcsname}
+                    {\csname\TableBoxLabel\endcsname}
+                    {\csname\TblCaptionWidthLabel\endcsname}
+  }
+}
+
+%    \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\theClearedTable}
+% Quite simply, this routine prints out each table to be cleared, one per
+% page, vertically centered.  It can be renewed by the user if a
+% different clearing format is desired.
+%    \begin{macrocode}
+%% \theClearedTable CAN BE RENEWED IF DIFFERENT OUTPUT FORMAT IS DESIRED
+\newcommand\theClearedTable[4][h]{
+%%  CLEAR THIS TABLE ON A PAGE BY ITSELF, CENTERED VERTICALLY
+  \vspace*{\fill}
+  \ReciteTable[#1]{#2}{#3}{#4}
+  \vspace*{\fill}
+  \clearpage
+}
+
+%    \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\bxfigure}
+% This routine is analogous to |\bxtable| in every way.  For figures, the
+% pointers which save the figure use a |\fig-| prefix, instead of a
+% |\tbl-| prefix.
+%    \begin{macrocode}
+\newcommand\bxfigure[3][t]{
+  \StoreFigure[#1]{#2}{#3}
+  \ifnum \arabic{promptFiguresFlag} = 1
+    \addtocounter{FigureClearedIndex}{1}
+    \def\FigureBoxLabel{fig\roman{FigureIndex}}
+    \def\FigureCaptionLabel{figcap\roman{FigureIndex}}
+    \def\FigCaptionWidthLabel{figcapwdth\roman{FigureIndex}}
+    \ReciteFigure[#1]{\csname\FigureCaptionLabel\endcsname}
+                        {\csname\FigureBoxLabel\endcsname}
+                        {\csname\FigCaptionWidthLabel\endcsname}
+  \fi
+}
+
+%    \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\StoreFigure}
+% This routine is analogous to |\StoreTable| in every way.
+%    \begin{macrocode}
+\newcommand\StoreFigure[3][]{
+  \addtocounter{FigureIndex}{1}
+  \setlength\DeadMargin\FigureDeadMargin
+  \def\FigureBoxLabel{fig\roman{FigureIndex}}
+  \def\FigureCaptionLabel{figcap\roman{FigureIndex}}
+  \def\FigCaptionWidthLabel{figcapwdth\roman{FigureIndex}}
+  \expandafter\SaveCBox\csname\FigureBoxLabel\endcsname{#3}
+  \expandafter\def\csname\FigureCaptionLabel\endcsname{#2}
+  \expandafter\newlength\csname\FigCaptionWidthLabel\endcsname
+  \expandafter\setlength\csname\FigCaptionWidthLabel\endcsname
+                                              \CaptionBoxWidth
+}
+
+%    \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\ReciteFigure}
+% This routine is analogous to |\ReciteTable| in every way, except one.
+% In the case of |\ReciteFigure|, the figure-data box is output
+% \textbf{before} the caption, not after.
+%    \begin{macrocode}
+\newcommand\ReciteFigure[4][h]{
+  \begin{figure}[#1]
+    \begin{\LRFigurePlacement}
+      \let\@makecaption \new@makecaption
+      \setlength\abovecaptionskip{\arabic{abovecaptionskipterm}\p@}
+      \setlength\belowcaptionskip{\arabic{belowcaptionskipterm}\p@}
+        \set@DataBoxWidth{#3}
+        \setlength\CaptionBoxWidth{#4}
+        \set@BoxOffsets
+        \rule{\@DataBoxOffset}{0in}%
+        \usebox{#3}%
+        \rule{\@DataBoxOffset}{0in}%
+        \par
+        \rule{\@CaptionBoxOffset}{0em}%
+        \parbox{\CaptionBoxWidth}{\caption {#2}}%
+        \rule{\@CaptionBoxOffset}{0em}%
+      \let\@makecaption \old@makecaption
+      \setlength\abovecaptionskip \oldabovecaptionskip
+      \setlength\belowcaptionskip \oldbelowcaptionskip
+    \end{\LRFigurePlacement}
+  \end{figure}
+}
+
+%    \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\clearFigures}
+% This routine is analogous to |\clearTables| in every way.
+%    \begin{macrocode}
+\newcommand\clearFigures{
+  \clearpage
+  \clearlistoffigures
+  \clearpage
+%%DO UNTIL ALL HELD FIGURES ARE CLEARED
+  \whiledo{\arabic{FigureClearedIndex} < \arabic{FigureIndex}}{
+    \addtocounter{FigureClearedIndex}{1}
+%%  \FigureBoxLabel:     : figi,    figii,    figiii,    figiv,    etc.
+%%  \FigureCaptionLabel  : figcapi, figcapii, figcapiii, figcapiv, etc.
+%%  \FigCaptionWidthLabel: figcapwdthi, figcapwdthii, figcapwdthiii,etc.
+    \def\FigureBoxLabel{fig\roman{FigureClearedIndex}}
+    \def\FigureCaptionLabel{figcap\roman{FigureClearedIndex}}
+    \def\FigCaptionWidthLabel{figcapwdth\roman{FigureClearedIndex}}
+    \theClearedFigure{\csname\FigureCaptionLabel\endcsname}
+                     {\csname\FigureBoxLabel\endcsname}
+                     {\csname\FigCaptionWidthLabel\endcsname}
+  }
+}
+
+%    \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\theClearedFigure}
+% This routine is analogous to |\theClearedTable| in every way... one
+% figure per page, vertically centered.
+%    \begin{macrocode}
+%% \theClearedFigure CAN BE RENEWED IF DIFFERENT OUTPUT FORMAT DESIRED
+\newcommand\theClearedFigure[4][h]{
+%%  CLEAR THIS FIGURE ON A PAGE BY ITSELF, CENTERED VERTICALLY
+  \vspace*{\fill}
+  \ReciteFigure[#1]{#2}{#3}{#4}
+  \vspace*{\fill}
+  \clearpage
+}
+
+%    \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\relaxCaptionWidth}
+% This routine sets the minimum permitted caption width.  When called
+% with no argument, it resets the min caption width to its 1 inch default
+% value.  If necessary, the maximum allowed caption width will be bumped
+% up, so as to remain greater than or equal the minimum allowed caption
+% width.
+%    \begin{macrocode}
+\newcommand\relaxCaptionWidth[1][\@minCaptionBoxWidthDefault]{
+  \setlength\@minCaptionBoxWidth{#1}
+  \ifdim \@minCaptionBoxWidth > \@maxCaptionBoxWidth
+    \setlength\@maxCaptionBoxWidth\@minCaptionBoxWidth
+  \fi
+}
+\relaxCaptionWidth% SET INITIAL \@minCaptionBoxWidth TO DEFAULT VALUE
+
+%    \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\limitCaptionWidth}
+% This routine sets the maximum permitted caption width.  When called
+% with no argument, it resets the max caption width to its default value
+% of |\textwidth|.  If necessary, the minimum allowed caption width will
+% be reduced, so as to remain less than or equal the maximum allowed
+% caption width.
+%    \begin{macrocode}
+\newcommand\limitCaptionWidth[1][\@maxCaptionBoxWidthDefault]{
+  \setlength\@maxCaptionBoxWidth{#1}
+  \ifdim \@maxCaptionBoxWidth < \@minCaptionBoxWidth
+    \setlength\@minCaptionBoxWidth\@maxCaptionBoxWidth
+  \fi
+}
+\limitCaptionWidth% SET INITIAL \@maxCaptionBoxWidth TO DEFAULT VALUE
+
+%    \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\constrainCaptionWidth}
+% Straightforward code to set both min- and max-allowed caption widths.
+% Only twist: if only one argument given, both min- and max-caption
+% widths set to that value.
+%    \begin{macrocode}
+\newcommand\constrainCaptionWidth[2][-1in]{
+  \ifdim #1 < 0in
+    \setlength\@minCaptionBoxWidth{#2}
+    \setlength\@maxCaptionBoxWidth{#2}
+  \else
+    \ifdim #1 < #2
+      \setlength\@minCaptionBoxWidth{#1}
+      \setlength\@maxCaptionBoxWidth{#2}
+    \else
+      \setlength\@minCaptionBoxWidth{#2}
+      \setlength\@maxCaptionBoxWidth{#1}
+    \fi
+  \fi
+}
+
+%    \end{macrocode}
+% \end{macro}
+%
+%\vspace{1em}
+% \begin{macro}{\SaveCBox}
+% Low-level routine to save box data in an |sbox|.  Also, calculates data
+% box width and associated caption box width.
+%    \begin{macrocode}
+\newcommand\SaveCBox[2]{
+  \newsavebox{#1}
+  \sbox{#1}{#2}
+  \set@BoxWidths{#1}
+}
+
+%    \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\set@BoxWidths}
+% Call successive routines to define |\@DataBoxWidth| and 
+% |\CaptionBoxWidth|.
+%    \begin{macrocode}
+\newcommand\set@BoxWidths[1]{% of DataBox & CaptionBox (-2\DeadMargin)
+  \set@DataBoxWidth{#1}
+  \set@CaptionBoxWidth
+}
+
+%    \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\set@DataBoxWidth}
+% Calculate and set data-box width.
+%    \begin{macrocode}
+\newcommand\set@DataBoxWidth[1]{
+  \setlength {\@DataBoxWidth}{\widthof{\usebox{#1}}}
+}
+
+%    \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\set@CaptionBoxWidth}
+% Calculate and set caption-box width, subject to constraints of dead
+% margin as well as caption-box min/max allowable widths.
+%    \begin{macrocode}
+\newcommand\set@CaptionBoxWidth{
+  \setlength\CaptionBoxWidth\@DataBoxWidth
+  \addtolength{\CaptionBoxWidth}{-2\DeadMargin}
+  \ifdim \CaptionBoxWidth < \@minCaptionBoxWidth
+    \setlength\CaptionBoxWidth\@minCaptionBoxWidth
+  \fi
+  \ifdim \CaptionBoxWidth > \@maxCaptionBoxWidth
+    \setlength\CaptionBoxWidth\@maxCaptionBoxWidth
+  \fi
+}
+
+%    \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\set@BoxOffsets}
+% Calculate |\DataBoxSurplus| which holds the excess width of the data
+% box with respect to the associated caption box.  Use it to set
+% |\@DataBoxOffset| and |\@CaptionBoxOffset|.
+%    \begin{macrocode}
+\newcommand\set@BoxOffsets{
+  \setlength\@DataBoxSurplus{\@DataBoxWidth}
+  \addtolength\@DataBoxSurplus{-\CaptionBoxWidth}
+  \ifdim \@DataBoxSurplus > 0in
+    \setlength\@CaptionBoxOffset{0.5\@DataBoxSurplus}
+    \setlength\@DataBoxOffset{0in}
+  \else
+    \setlength\@CaptionBoxOffset{0in}
+    \setlength\@DataBoxOffset{-0.5\@DataBoxSurplus}
+  \fi
+}
+
+%    \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\offset@caption}
+%   \begin{macro}{\nooffset@caption}
+% Define the code for placing offset- and nooffset-captions in the
+% caption box.
+%    \begin{macrocode}
+\long\def\offset@caption#1#2{
+  \setlength\@captionIDwidth{\widthofpbox{\CaptionFontSize{#1.}}}
+  \addtolength\@captionIDwidth\captionGap
+  \setlength\@captionWidth\CaptionBoxWidth
+  \addtolength\@captionWidth{-\@captionIDwidth}
+  \CaptionFontSize{#1.}\hfill\parbox[t]{\@captionWidth}
+                  {\CaptionJustification\CaptionFontSize{#2.}}%
+}
+
+\long\def\nooffset@caption#1#2{%
+  \CaptionJustification\CaptionFontSize #1.\rule{\captionGap}{0in}#2.%
+}
+
+%    \end{macrocode}
+%   \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\shortleft@caption}
+%   \begin{macro}{\shortcenter@caption}
+%     \begin{macro}{\shortright@caption}
+% Define the code for placing short-left, -center, and -right
+% captions in the caption box.
+%    \begin{macrocode}
+\long\def\shortleft@caption#1#2{%
+  \raggedright         \CaptionFontSize #1.\rule{\captionGap}{0in}#2.%
+}
+
+\long\def\shortcenter@caption#1#2{%
+  \centering           \CaptionFontSize #1.\rule{\captionGap}{0in}#2.%
+}
+
+\long\def\shortright@caption#1#2{%
+  \raggedleft          \CaptionFontSize #1.\rule{\captionGap}{0in}#2.%
+}
+
+%    \end{macrocode}
+%     \end{macro}
+%   \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\new@makecaption}
+% Define the new |@makecaption| code, which is defined in terms of
+% long- and short-caption definitions, that can be changed on the fly.
+%    \begin{macrocode}
+\long\def\new@makecaption#1#2{%
+  \vskip\abovecaptionskip
+  \sbox\@tempboxa{\CaptionFontSize #1.\rule{\captionGap}{0in}#2.}%
+  \ifdim \wd\@tempboxa >\hsize
+    \long@caption{#1}{#2}
+  \else
+    \short@caption{#1}{#2}
+  \fi
+  \vskip\belowcaptionskip
+}
+
+%    \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\captionStyle}
+%   \begin{macro}{\long@caption}
+%     \begin{macro}{\short@caption}
+% Define the user routine |\captionStyle|, which allows the user to
+% redefine the captions styles for long and short captions,
+% respectively.
+%    \begin{macrocode}
+\newcommand\captionStyle[2]{
+  \if o#1        \let\long@caption  \offset@caption       \fi
+  \if n#1        \let\long@caption  \nooffset@caption     \fi
+  \if l#2        \let\short@caption \shortleft@caption    \fi
+  \if c#2        \let\short@caption \shortcenter@caption  \fi
+  \if r#2        \let\short@caption \shortright@caption   \fi
+}
+
+%    \end{macrocode}
+%     \end{macro}
+%   \end{macro}
+% \end{macro}
+%
+% Define the default value for caption style, which is offset-style,
+% left-aligned.
+%    \begin{macrocode}
+%% SET DEFAULT CAPTION STYLE: CAPTION ID OFFSET FOR LONG CAPTIONS,
+%%                            SHORT CAPTIONS LEFT ALIGNED
+\captionStyle{o}{l}
+
+%    \end{macrocode}
+%
+% \begin{macro}{\killtableofcontents}
+% Kills subsequent calls for the Table of Contents by renewing the
+% command as null.
+%    \begin{macrocode}
+\newcommand\killtableofcontents{
+  \renewcommand\tableofcontents{}
+}
+
+%    \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{lofInvocations}
+%   \begin{macro}{lofprints}
+%     \begin{macro}{\oldlistoffigures}
+% Set up for \textit{lof} handling, by preparing to count invocations of
+% \textit{lof}, the number of times the \textit{lof} is printed, and by
+% saving prevailing definition of |\listoffigures|.
+%    \begin{macrocode}
+%%LIST OF FIGURES HANDLING:
+\newcounter{lofInvocations}   \setcounter{lofInvocations}{0}
+\newcounter{lofPrints}        \setcounter{lofPrints}{0}
+\let\oldlistoffigures\listoffigures
+
+%    \end{macrocode}
+%     \end{macro}
+%   \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\killlistoffigures}
+% Kills subsequent calls for List of Figures by renewing the command (and
+% redefining the saved command) as null.
+%    \begin{macrocode}
+\newcommand\killlistoffigures{
+  \def\oldlistoffigures {}
+  \renewcommand\listoffigures{}
+}
+
+%    \end{macrocode}
+% \end{macro}
+%
+%\vspace{2em}
+% \begin{macro}{\holdlistoffigures}
+% To put the \textit{lof} ``on hold,'' we merely redefine
+% |\listoffigures| to increment the |lofInvocations| counter.
+%    \begin{macrocode}
+\newcommand\holdlistoffigures{
+  \renewcommand\listoffigures{\addtocounter{lofInvocations}{1}}
+}
+
+%    \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\clearlistoffigures}
+% This routine will clear (i.e., print) the List of Figures the number of
+% times it was invoked while ``on hold'' (most likely 0 or 1 time).  It
+% does this by incrementing |lofPrints| until it reaches a value of
+% |lofInvocations|.
+%    \begin{macrocode}
+\newcommand\clearlistoffigures{
+  \whiledo{\arabic{lofPrints} < \arabic{lofInvocations}}{
+    \addtocounter{lofPrints}{1}
+    \oldlistoffigures
+  }
+}
+
+%    \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{lotInvocations}
+%   \begin{macro}{lotPrints}
+%     \begin{macro}{\oldlistoftables}
+%       \begin{macro}{\killlistoftables}
+%         \begin{macro}{\holdlistoftables}
+%           \begin{macro}{\clearlistoftables}
+% List of Tables handling is wholly analogous to List of Figures handling
+% just described.
+%    \begin{macrocode}
+%%LIST OF TABLES HANDLING:
+\newcounter{lotInvocations}   \setcounter{lotInvocations}{0}
+\newcounter{lotPrints}        \setcounter{lotPrints}{0}
+\let\oldlistoftables\listoftables
+
+\newcommand\killlistoftables{
+  \def\oldlistoftables {}
+  \renewcommand\listoftables{}
+}
+
+\newcommand\holdlistoftables{
+  \renewcommand\listoftables{\addtocounter{lotInvocations}{1}}
+}
+
+\newcommand\clearlistoftables{
+  \whiledo{\arabic{lotPrints} < \arabic{lotInvocations}}{
+    \addtocounter{lotPrints}{1}
+    \oldlistoftables
+  }
+}
+
+%    \end{macrocode}
+%           \end{macro}
+%         \end{macro}
+%       \end{macro}
+%     \end{macro}
+%   \end{macro}
+% \end{macro}
+%
+% \begin{macro}{arltable}
+%   \begin{macro}{arlfigure}
+% To retain backward compatibility to the simpler predecessor of the
+% |boxtable| package, the vestigial commands |\arltable| and |\arlfigure|
+% are provided.  Their definitions are directly linked to |\bxtable| and
+% |\bxfigure|.
+%    \begin{macrocode}
+%% TO RETAIN BACKWARD COMPATIBILITY WITH THE PREDECESSOR TO boxtable,
+%% THE FOLLOWING ASSIGNMENTS ARE MADE.
+\let\arltable\bxtable
+\let\arlfigure\bxfigure
+
+%    \end{macrocode}
+%   \end{macro}
+% \end{macro}
+% We are done now.
+%    \begin{macrocode}
+%</package>
+%    \end{macrocode}
+%
+% \Finale
+\endinput
+%
+%End of file `boxhandler.dtx'.
diff --git a/Master/texmf-dist/source/latex/boxhandler/boxhandler.ins b/Master/texmf-dist/source/latex/boxhandler/boxhandler.ins
new file mode 100644
index 00000000000..f382a6296ba
--- /dev/null
+++ b/Master/texmf-dist/source/latex/boxhandler/boxhandler.ins
@@ -0,0 +1,6 @@
+% LaTeX this .ins file in order to generate the .sty file from the .dtx file
+\input docstrip
+\askforoverwritefalse
+\generate{\file{boxhandler.sty}{\from{boxhandler.dtx}{package}}
+         }
+\endbatchfile