path: root/macros/latex/contrib/boxhandler/boxhandler.dtx

% \CheckSum{948}
% \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>[2012/10/18 v1.30
%<package> Tools for Optimizing Captions, Presentation, and
%<package> Placement of Tables and Figures]
%<package>\NeedsTeXFormat{LaTeX2e}
%<*driver>
% V1.02-Corrected minor grammar issue in documentation.
% V1.03-Changed some tabs into spaces that were screwing up appearance
%       but not function of sty file.
% V1.04-Reset one of the parameters left set in Fig.6, which 
%       inadvertantly affected appearance of Tables 3 and 4.
%      -Minor grammar correction.
%      -Added \CharacterTable & \CheckSum features to dtx file.
%      -Added Acknowledgments (belatedly... mea culpa)
% V1.10-added features \nextTable and \nextFigure for clearing
%       a single table or figure at a time.
%      -explained in documentation how to handle captions with
%       citations in boxhandler environment.
% V1.11-added RequirePackage{ifthen}, which should have been there
%       all along (got by, since pbox required it).
%      -corrected a typo.
% V1.12-added % to end of every key line to prevent extraneous spaces.
% V1.20-added support for figure and table wrappers
% V1.21-modified documentation slightly
% V1.22-changed [h] default specifiers to [ht] to avoid warnings
% V1.30-Corrected errors in manual (\theClearedTable example)
%      -Added support for use with hyperref package
\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
\newcommand\boxhandler{\textsf{boxhandler}~}
\GetFileInfo{boxhandler.sty}
\begin{document}
   \title{The \textsf{boxhandler} Package\\
         \rule{0em}{0.7em}\small\fileinfo}
   \author{Steven B. Segletes\\
           steven.b.segletes.civ@mail.mil}
   \date{\filedate\\
         \fileversion}
   \maketitle
   \DocInput{boxhandler.dtx}
\end{document}
%</driver>
% \fi
% \parskip 1ex
% \begin{abstract}
% This package facilitates the optimized presentation of \LaTeX{}
% tables and figures.
% Not only can boxhandler conveniently lay out table and figure
% captions with a wide variety of stylistic appearances, but allows
% for figures and tables to be ``wrapped'' in a manner consistent with
% many business and government documents. For a document that might
% appear in different venues with different formatting, boxhandler
% very powerfully permits the creation of a \LaTeX{} source
% document that can, with a single-line change
% in the source code, produce an output that has vastly different layout
% from the baseline configuration, both in terms of caption style,
% and in terms of the locations where figures, tables and lists
% appear (or not) in the document.  Deferral routines also allow
% one to keep all figure and table data in a separate source file, while
% nonetheless producing a document with figures and tables appearing
% in the desired location in the document.  
% 
% \end{abstract}
%
% \vspace{-.55em}
% \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|}|\\
% |\hyperactive[|\iq len\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:
% |ht|, |hb|,
% |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 environment 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 |\relaxCaptionWidth| 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.
%
% \DescribeMacro{\hyperactive}
% |\hyperactive| was added in v1.22 to provide compatibility with the
% \textsf{hyperref} package, which is known to redefine many \LaTeX{} 
% variables, including |\caption|.  It was found, when the
% \textsf{hyperref} package was active, offset captions experienced a 
% vertical gap between the caption label and the caption text.  The
% command |\hyperactive| should be invoked only if the \textsf{hyperref}
% package is being utilized. The optional argument to this command is
% the length that boxhandler will shift the caption text downward, so
% as to achieve alignment with the caption label.  The default value is
% -1.55ex, which was the required corrective shift observed for some
% applications, when the \textsf{hyperref} package was active.
%
% \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.
%
% \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.%
%
% \clearpage%
% \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$~~~}%
%              }%
%            }%
% \setlength\captionGap{1ex}%
% \def\CaptionJustification{}%
% \let\CaptionFontSize\small%
% \setcounter{abovecaptionskipterm}{10}%
% \def\LRFigurePlacement{center}%
% \setlength\FigureDeadMargin{0em}%
% \begin{picture} (0,0)%
%   \put(-4,95){\makebox(20,0)[l]%
%                 {\small\tt\bs abovecaption-}}%
%   \put(-4,86){\makebox(20,0)[l]%
%          {\small~~|skipterm| = 3~~$\rightarrow$}}%
%   \put(-31,68){\makebox(20,0)[l]%
%          {\small\tt\bs FigureDeadMargin\rm = 1em~$\uparrow$}}%
%   \put(-31,59){\makebox(20,0)[l]%
%          {\small (1em on left; 1em on right)}}%
% \end{picture}%
% 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.
%
% \section{Figure and Table ``Wrappers''}
%
% With \boxhandler v1.20, figure and table wrappers have been added.
% A wrapper is here defined to mean an item that bounds a figure or
% table by appearing in the upper-left and lower-right corners of
% the figure or table.  It could be an iconic image such as the company
% logo, a reminder such as ``COMPANY PROPRIETARY'', or some other such
% delimiter to the figure/table.  The relevant commands to use them are
% as follows:
% 
% \begin{verse}
% |\WrapperOn[|\iq default wrapper\uq|]|\\
% |\WrapperOff|\\
% |\Wrapper{|\iq custom wrapper\uq|}|\\
% |\def\WrapperTextStyle{|\iq text style\uq|}|\\
% \end{verse}
% 
% By default, wrappers are turned off in boxhandler.  They may be
% activated with the command |\WrapperOn|.  The optional argument to
% |\WrapperOn|, which should be used on the initial invocation,
% specifies the default wrapper.  Likewise,
% wrappers may be disabled with the command |\WrapperOff|.  When wrappers
% are activated, every table and figure subsequently created will be
% wrapped using the default wrapper.
%
% If, however, the user would like
% for a given figure or table to have a custom wrapper different than the
% default, the |\Wrapper{}| command should be used within the second
% mandatory argument of the call to |\bxtable| or |\bxfigure|.  That is
% to say, the call to |\Wrapper| should be included within the argument
% where the actual figure or table contents are defined. 
%
% \clearpage Here is an example:
%
% \begin{verse}
% |\bxfigure[ht]{Widget details for the XMC-7936}%|\\
% |  {\fbox{\hspace{1in}\rule[-.5ex]{3ex}{3ex} $\rightarrow$%|\\
% |   \rule[-.2ex]{2ex}{2ex}\hspace{1in}}\Wrapper{PROPRIETARY}}%|\\
% \end{verse}
%
% \WrapperOn
% \bxfigure[ht]{Widget details for the XMC-7936}%
%   {\fbox{\hspace{1in}\rule[-.5ex]{3ex}{3ex} $\rightarrow$%
%    \rule[-.2ex]{2ex}{2ex}\hspace{1in}}\Wrapper{PROPRIETARY}%
%   }
% \WrapperOff
% Wrapper text (both default and custom) are given a style defined by
% |\WrapperTextStyle|.  The default style is small, boldface text,
% |\bf\small|.
%
% \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[ht]
% {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.
%
% The \boxhandler style also conveniently allows for another useful
% scenario, in which figure and table data may be kept in a separate
% file from the document text, but nonetheless be made to print out with
% figures and tables appearing in the proper location in the text.  The
% |\nextTable| and |\nextFigure| commands aid in this approach.
%
% \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|\\
% |\nextTable[|\iq loc\uq|]|\\
% |\nextFigure[|\iq loc\uq|]|\\
% \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 \boxhandler 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).
%
% The one potential pitfall with the use of these commands
% is the situation when a citation is made within
% the caption of a deferred table or figure.  In this case, the citation
% is numbered based on when the table or figure is finally displayed,
% not when it was created.
% Thus, if |\holdTables| and/or |\holdFigures| is used to prevent the
% printing of tables and/or figures until the end of the document,
% then any unique citation defined in a table or figure
% caption will receive a higher citation number than even a citation
% appearing in the last line of document text.
%
% There is, however, an easy solution to this predicament.  That is,
% when a figure or table is employed which contains a citation, the
% main text of the document should invoke |\nocite{|\iq key\_list\uq|}|
% to the same reference.  This occurance of |\nocite| should be
% placed in the main document (\textit{i.e.}, outside of |bxtable|
% or |bxfigure|) at the point where the table or figure is actually
% being invoked.  In this manner, the citation gets added to the
% \textit{.aux} file at the proper spot, regardless of when the table
% or figure is actually printed out.
%
% \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!}
%
% \DescribeMacro{\nextTable}
% \DescribeMacro{\nextFigure}
% The deferral commands described to this point have been cast in terms
% of tools to aid in printing out multiple vastly different versions
% of a document from a single source file.  With \boxhandler v1.10, the
% commands |\nextTable| and |\nextFigure| have been introduced.  These
% commands, while somewhat similar in function to |\clearTables| and
% |\clearFigures|, are useful in a completely different regard.  In the
% case of |\nextTable| and |\nextFigure|, only a single table or figure
% is cleared.  Unlike |\clearTables| and |\clearFigures|, the table or
% figure is not printed on a page by itself, but inline the document.
% The optional argument specifies the location on the page (|ht|, |hb|, |t|,
% |b| or |p|) where the
% table or figure should appear, consistent with \LaTeX{} convention.
%
% The unique utility of the |\nextTable| and |\nextFigure| commands
% is in allowing one to define all the document's figures and tables
% ``up front,'' at the beginning of the document, perhaps even in a
% seperate file that is |\input| into the document.  Then, when a table
% or figure is referred to in the text, all that need be included in
% the main document is an occurance of |\nextTable| or |\nextFigure|.
%
% In this manner, all the tables and figures can be printed out in the
% document at their appropriate location, while logically, the document
% can be organized during preparation to keep the figure and table
% matter separate from the text matter of the document.
%
% If one wishes to incorporate conditional compiliation
% (as in Table~\ref{tbl:bxcode}) while simultaneously keeping table
% and figure definition in a separate file |\input| at the beginning
% of the document, this can be done, too.  The tables and figures would
% be added after the |\begin{document}| command and invocation would
% be accomplished by way of |\nextTable| and |\nextFigure| as described
% here.  However, in the |\MANUSCRIPT| preamble (using the nomenclature
% of Table~\ref{tbl:bxcode}), |\nextTable| and |\nextFigure| would be
% nullified as:\\
% |    \renewcommand\nextTable[1][]{}|\\ and\\
% |    \renewcommand\nextFigure[1][]{}|.\\
% In this manner, for the |\MANUSCRIPT| report type, tables and figures
% would be made to not appear until the final invocations of
% |\clearTables| and |\clearFigures|.
% 
%
% \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
% |}{|\iq wrapper\uq|}{|\iq wrapper status\uq|}|\\
% |\StoreFigure{|\iq caption\uq|}{|\iq boxed object\uq
% |}{|\iq wrapper\uq|}{|\iq wrapper status\uq|}|\\
% |\SaveCBox{|\iq new cmd\uq|}{|\iq boxed object\uq|}|\\
% |\ReciteTable[|\iq loc\uq|]{|\iq caption\uq|}{|\iq cmd\uq
%    |}{|\iq wdth\uq|}{|\iq wrapper\uq|}{|\iq wrapper status\uq|}|\\
% |\ReciteFigure[|\iq loc\uq|]{|\iq caption\uq|}{|\iq cmd\uq
%    |}{|\iq wdth\uq|}{|\iq wrapper\uq|}{|\iq wrapper status\uq|}|\\
% |\theClearedTable[|\iq loc\uq|]{|\iq caption\uq|}{|\iq cmd\uq
%    |}{|\iq wdth\uq|}{|\iq wrapper\uq|}{|\iq wrapper status\uq|}|\\
% |\theClearedFigure[|\iq loc\uq|]{|\iq caption\uq|}{|\iq cmd\uq
%    |}{|\iq wdth\uq|}{|\iq wrapper\uq|}{|\iq wrapper status\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|, with two
% additional wrapper variables added.  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 five
% pointers necessary to recreate the table or figure.  These pointers
% will be named according to \textsf{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, 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), and pointers to the wrapper and a flag indicating
% whether wrappers are active for this figure or table.
%
% 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-|.
% The wrapper pointer has the prefix |tblwrap-| and the pointer to flag
% indicating the status of wrapper activity is |tblwrapstatus-|.
% 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, a length pointer |\tblcapwdthiv| that stores the
% value of the calculated caption width, a wrapper pointer |\tblwrapiv|,
% which stores the wrapper, and a pointer |\tblwrapstatusiv|, which
% stores a `T' or `F' to indicate whether wrappers are currently active
% or not.  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., |ht|, |hb|, |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[6][ht]{|\\
%|  \vspace*{\fill}|\\
%|  \ReciteTable[#1]{#2}{#3}{#4}{#5}{#6}|\\
%|  \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[6][ht]{|\\
%|  \addtocounter{toggle}{1}|\\
%|  \ifnum \arabic{toggle} = 2 \setcounter{toggle}{0} \fi|\\
%|  \ifnum \arabic{toggle} = 1|\\
%|    \ReciteTable[t]{#2}{#3}{#4}{#5}{#6}|\\
%|  \else|\\
%|    \ReciteTable[b]{#2}{#3}{#4}{#5}{#6}|\\
%|    \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[ht]                                                    |\\
%%|  {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[ht]{\figcapii}{\figii}{\figcapwdthii}%             |\\
%%|                {\figwrapii}{\figwrapstatusii}                   |\\
%%
% \vspace{-1em}
% \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
% piecemeal approaches were out there to handle it, requiring 
% case-specific decisions on the part of the author, 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 {Acknowledgments/Salutations}
% That's it for a description of \textsf{boxhandler}!  I would like to thank
% a number of colleagues for their consultive assistance.  Several were
% instrumental in getting me over early bumps in my \LaTeX{} learning
% curve, including Mike Scheidler, Stephen Schraml, Brian Krzewinski,
% and Paul Tanenbaum, all of the USARL.  I am particularly grateful
% to Fred Brundick (also of ARL) for sharing his extensive knowledge
% of \LaTeX{} with me.  He clued me in to the sticky quirks of offset
% captions, and shared his methods for dealing with the different cases.
% He also pointed me in the right direction for the systematic saving
% of \LaTeX{} box objects, which contributed to the section of this
% package dealing with object deferral.
%
% I hope this package provides you some utility. The only thing left
% is the code listing itself.
%% \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         \~}
% \StopEventually{}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% \clearpage
% \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 \textsf{ifthen} and \textsf{pbox} style
% packages to aid in the boxing of captions.
%    \begin{macrocode}
\RequirePackage{ifthen}
\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}
%
% \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}{\WrapperOn}
%   \begin{macro}{\WrapperOff}
%     \begin{macro}{\Wrapper}
%       \begin{macro}{\WrapperTextStyle}
% Wrappers are identifying text (or icons) that bound figures and
% tables in the
% upper-left and lower-right corners.  Initially disabled, |\WrapperOn|
% turns wrappers on.  The optional argument of |\WrapperOn|, which
% should be used on the first invocation, specifies the default wrapper.
% Wrappers can be turned off with |\WrapperOff|.  
% The default wrapper can be changed with a subsequent invocation
% to |\WrapperOn|.
% 
% However, the wrapper for any given figure
% or table may be individually specified (without changing the default
% wrapper) by way of the
% argument to |\Wrapper|.  Both the default wrapper as well as one
% passed as an argument to |\Wrapper| are presented with the style
% given in |\WrapperTextStyle|, which defaults to small, bold font,
% |\bf\small|.  The command |\Wrapper|, if used, should be placed within
% the second mandatory argument of |\bxtable| and |\bxfigure|, if a
% wrapper other than the default is desired.
%    \begin{macrocode}
%% FIGURE & TABLE WRAPPER INITIALIZATIONS
\def\wrapper{F}
\def\WrapperTextStyle{\bf\small}
\def\WrapperTextDefault{DEFAULT WRAPPER}
\global\def\WrapperText{\noexpand\WrapperTextStyle\WrapperTextDefault}
\newcommand\WrapperOn[1][]{%
  \def\wrapper{T}%
  \ifthenelse{\equal{#1}{}}%
  {}{\def\WrapperTextDefault{\noexpand#1}}%
  \global\def%
     \WrapperText{\noexpand\WrapperTextStyle\WrapperTextDefault}%
}
\newcommand\WrapperOff{\def\wrapper{F}}
\newcommand\Wrapper[1]{\global\def%
  \WrapperText{\noexpand\WrapperTextStyle\noexpand#1}}

%    \end{macrocode}
%       \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}{\WrapperText}{\wrapper}%
  \ifnum\arabic{promptTablesFlag}=1%
    \addtocounter{TableClearedIndex}{1}%
    \def\TableBoxLabel{tbl\roman{TableIndex}}%
    \def\TableCaptionLabel{tblcap\roman{TableIndex}}%
    \def\TblCaptionWidthLabel{tblcapwdth\roman{TableIndex}}%
    \def\TableWrapper{tblwrap\roman{TableIndex}}%
    \def\WrapperStatus{tblwrapstatus\roman{TableIndex}}%
    \ReciteTable[#1]{\csname\TableCaptionLabel\endcsname}%
                    {\csname\TableBoxLabel\endcsname}%
                    {\csname\TblCaptionWidthLabel\endcsname}%
                    {\csname\TableWrapper\endcsname}%
                    {\csname\WrapperStatus\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[5][]{%
  \addtocounter{TableIndex}{1}%
  \setlength\DeadMargin\TableDeadMargin%
  \def\TableBoxLabel{tbl\roman{TableIndex}}%
  \def\TableCaptionLabel{tblcap\roman{TableIndex}}%
  \def\TblCaptionWidthLabel{tblcapwdth\roman{TableIndex}}%
  \def\TableWrapper{tblwrap\roman{TableIndex}}%
  \def\WrapperStatus{tblwrapstatus\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%
  \expandafter\edef\csname\TableWrapper\endcsname{#4}%
  \expandafter\edef\csname\WrapperStatus\endcsname{#5}%
%% After storing table, reset wrapper to default value
  \global\def%
   \WrapperText{\noexpand\WrapperTextStyle\WrapperTextDefault}%
}

%    \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[6][ht]{%
  \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%
        \if T#6%
          \rule{\@DataBoxOffset}{0in}%
          \makebox[\@DataBoxWidth][l]{#5}%
          \rule{\@DataBoxOffset}{0in}\\%
        \fi
        \rule{\@CaptionBoxOffset}{0em}%
        \parbox{\CaptionBoxWidth}{\bx@caption{#2}}%
        \rule{\@CaptionBoxOffset}{0em}%
        \par%
        \rule{\@DataBoxOffset}{0in}% 
        \usebox{#3}%
        \rule{\@DataBoxOffset}{0in}\\%
        \if T#6%
          \rule{\@DataBoxOffset}{0in}\\%
          \makebox[\@DataBoxWidth][r]{#5}%
        \rule{\@DataBoxOffset}{0in}%
        \fi
      \let\@makecaption\old@makecaption%
      \setlength\abovecaptionskip \oldabovecaptionskip%
      \setlength\belowcaptionskip \oldbelowcaptionskip%
    \end{\LRTablePlacement}%
  \end{table}%
}

%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\nextTable}
% This routine will clear a single table, if there are any that have
% not yet been printed as a result of a previously invoked \holdTables
% command. It assumes FIFO logic.  The optional argument is the location
% on the page where the table is to be printed, in accordance with
% standard \LaTeX{} logic.  If there are no uncleared tables left to
% format, then the command has no effect.
%    \begin{macrocode}
\newcommand\nextTable[1][ht]{%
  \ifnum\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}}%
    \def\TableWrapper{tblwrap\roman{TableClearedIndex}}%
    \def\WrapperStatus{tblwrapstatus\roman{TableClearedIndex}}%
    \ReciteTable[#1]{\csname\TableCaptionLabel\endcsname}%
                    {\csname\TableBoxLabel\endcsname}%
                    {\csname\TblCaptionWidthLabel\endcsname}%
                    {\csname\TableWrapper\endcsname}%
                    {\csname\WrapperStatus\endcsname}%
  }\fi
}

%    \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}}%
    \def\TableWrapper{tblwrap\roman{TableClearedIndex}}%
    \def\WrapperStatus{tblwrapstatus\roman{TableClearedIndex}}%
    \theClearedTable{\csname\TableCaptionLabel\endcsname}%
                    {\csname\TableBoxLabel\endcsname}%
                    {\csname\TblCaptionWidthLabel\endcsname}%
                    {\csname\TableWrapper\endcsname}%
                    {\csname\WrapperStatus\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[6][ht]{%
%%  CLEAR THIS TABLE ON A PAGE BY ITSELF, CENTERED VERTICALLY
  \vspace*{\fill}%
  \ReciteTable[#1]{#2}{#3}{#4}{#5}{#6}%
  \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}{\WrapperText}{\wrapper}%
  \ifnum\arabic{promptFiguresFlag}=1%
    \addtocounter{FigureClearedIndex}{1}%
    \def\FigureBoxLabel{fig\roman{FigureIndex}}%
    \def\FigureCaptionLabel{figcap\roman{FigureIndex}}%
    \def\FigCaptionWidthLabel{figcapwdth\roman{FigureIndex}}%
    \def\FigureWrapper{figwrap\roman{FigureIndex}}%
    \def\WrapperStatus{figwrapstatus\roman{FigureIndex}}%
    \ReciteFigure[#1]{\csname\FigureCaptionLabel\endcsname}%
                        {\csname\FigureBoxLabel\endcsname}%
                        {\csname\FigCaptionWidthLabel\endcsname}%
                        {\csname\FigureWrapper\endcsname}%
                        {\csname\WrapperStatus\endcsname}%
  \fi
}

%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\StoreFigure}
% This routine is analogous to |\StoreTable| in every way.
%    \begin{macrocode}
\newcommand\StoreFigure[5][]{%
  \addtocounter{FigureIndex}{1}%
  \setlength\DeadMargin\FigureDeadMargin%
  \def\FigureBoxLabel{fig\roman{FigureIndex}}%
  \def\FigureCaptionLabel{figcap\roman{FigureIndex}}%
  \def\FigCaptionWidthLabel{figcapwdth\roman{FigureIndex}}%
  \def\FigureWrapper{figwrap\roman{FigureIndex}}%
  \def\WrapperStatus{figwrapstatus\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%
  \expandafter\edef\csname\FigureWrapper\endcsname{#4}%
  \expandafter\edef\csname\WrapperStatus\endcsname{#5}%
%% After storing figure, reset wrapper to default value
  \global\def%
   \WrapperText{\noexpand\WrapperTextStyle\WrapperTextDefault}%
}

%    \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[6][ht]{%
  \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%
        \if T#6%
          \rule{\@DataBoxOffset}{0in}%
          \makebox[\@DataBoxWidth][l]{#5}%
          \rule{\@DataBoxOffset}{0in}\\%
        \fi
        \rule{\@DataBoxOffset}{0in}%
        \usebox{#3}%
        \rule{\@DataBoxOffset}{0in}%
        \par%
        \rule{\@CaptionBoxOffset}{0em}%
        \parbox{\CaptionBoxWidth}{\bx@caption{#2}}%
        \rule{\@CaptionBoxOffset}{0em}%
        \if T#6%
          \rule{\@DataBoxOffset}{0in}\\%
          \makebox[\@DataBoxWidth][r]{#5}%
          \rule{\@DataBoxOffset}{0in}%
        \fi
      \let\@makecaption\old@makecaption%
      \setlength\abovecaptionskip\oldabovecaptionskip%
      \setlength\belowcaptionskip\oldbelowcaptionskip%
    \end{\LRFigurePlacement}%
  \end{figure}%
}

%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\nextFigure}
% This routine is analogous to |\nextTable| in every way.
%    \begin{macrocode}
\newcommand\nextFigure[1][ht]{%
  \ifnum\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}}%
    \def\FigureWrapper{figwrap\roman{FigureClearedIndex}}%
    \def\WrapperStatus{figwrapstatus\roman{FigureClearedIndex}}%
    \ReciteFigure[#1]{\csname\FigureCaptionLabel\endcsname}%
                     {\csname\FigureBoxLabel\endcsname}%
                     {\csname\FigCaptionWidthLabel\endcsname}%
                     {\csname\FigureWrapper\endcsname}%
                     {\csname\WrapperStatus\endcsname}%
  }\fi
}

%    \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}}%
    \def\FigureWrapper{figwrap\roman{FigureClearedIndex}}%
    \def\WrapperStatus{figwrapstatus\roman{FigureClearedIndex}}%
    \theClearedFigure{\csname\FigureCaptionLabel\endcsname}%
                     {\csname\FigureBoxLabel\endcsname}%
                     {\csname\FigCaptionWidthLabel\endcsname}%
                     {\csname\FigureWrapper\endcsname}%
                     {\csname\WrapperStatus\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[6][ht]{%
%%  CLEAR THIS FIGURE ON A PAGE BY ITSELF, CENTERED VERTICALLY
  \vspace*{\fill}%
  \ReciteFigure[#1]{#2}{#3}{#4}{#5}{#6}%
  \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}
%
% \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}
%
% \clearpage
% \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}
%
% \clearpage
% \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}
%
% \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}{\hyperactive}
% Prepare corrections if the \textsf{hyperref} package is being used.
% Set default caption treatment in \textsf{boxhandler} to |\caption|.
% Define alternate caption treatment as |\hyper@cap|.  If |\hyperactive|
% is invoked, redefine caption treatment as |\hyper@cap|.  The optional
% argument to |\hyperactive| is the downward-shift to be applied to the
% caption, relative to the caption label.
%    \begin{macrocode}
%% \hyperactive PROVIDES A CORRECTIVE CAPTION SHIFT WHEN USING THE
%% hyperref PACKAGE; OPTIONAL ARGUMENT IS SHIFT LENGTH
\let\bx@caption\caption
\newlength\hyper@shift
\newcommand\hyper@cap[1]{\caption{\vspace*{\hyper@shift}#1}}%
\newcommand\hyperactive[1][-1.55ex]{%
  \setlength\hyper@shift{#1}\let\bx@caption\hyper@cap}

%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{arltable}
%   \begin{macro}{arlfigure}
% To retain backward compatibility to the simpler predecessor of the
% \boxhandler 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 boxhandler,
%% 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'.