Debian Codegraph @

texmf-dist/source/latex/boxhandler/boxhandler.dtx

raw
1 % \CheckSum{948}
2 % \iffalse
3 %%
4 %% boxhandler.sty
5 %% Copyright Steven B. Segletes.
6 %%
7 %% This file may be redistributed and/or modified with attribution.
8 %%
9 %% This is boxhandler.sty, derived from earlier incarnations of savcap.sty &
10 %% arlcaptions.sty.
11 %%
12 %<package>\ProvidesPackage{boxhandler}
13 %<package>[2012/10/18 v1.30
14 %<package> Tools for Optimizing Captions, Presentation, and
15 %<package> Placement of Tables and Figures]
16 %<package>\NeedsTeXFormat{LaTeX2e}
17 %<*driver>
18 % V1.02-Corrected minor grammar issue in documentation.
19 % V1.03-Changed some tabs into spaces that were screwing up appearance
20 % but not function of sty file.
21 % V1.04-Reset one of the parameters left set in Fig.6, which
22 % inadvertantly affected appearance of Tables 3 and 4.
23 % -Minor grammar correction.
24 % -Added \CharacterTable & \CheckSum features to dtx file.
25 % -Added Acknowledgments (belatedly... mea culpa)
26 % V1.10-added features \nextTable and \nextFigure for clearing
27 % a single table or figure at a time.
28 % -explained in documentation how to handle captions with
29 % citations in boxhandler environment.
30 % V1.11-added RequirePackage{ifthen}, which should have been there
31 % all along (got by, since pbox required it).
32 % -corrected a typo.
33 % V1.12-added % to end of every key line to prevent extraneous spaces.
34 % V1.20-added support for figure and table wrappers
35 % V1.21-modified documentation slightly
36 % V1.22-changed [h] default specifiers to [ht] to avoid warnings
37 % V1.30-Corrected errors in manual (\theClearedTable example)
38 % -Added support for use with hyperref package
39 \documentclass{ltxdoc}
40 \usepackage{boxhandler}
41 \DisableCrossrefs
42 \CodelineNumbered
43 % DEFINE SOME COMMANDS THAT ARE EASIER HERE THAN IN DocInput ENVIRONMENT
44 \def\tbllayout{|c|}% CAN'T GET PLAIN "|" CHARACTER IN DocInput MODE
45 \def\lb{\char'173}% LEFT BRACE "{" WHEN INVOKED IN \tt FONT
46 \def\rb{\char'175}% RIGHT BRACE "}" WHEN INVOKED IN \tt FONT
47 \def\bs{\char'134}% BACKSLASH "\" WHEN INVOKED IN \tt FONT
48 \let\iq\itshape% SHORTHAND FOR ITALIC FONT
49 \let\uq\upshape% SHORTHAND FOR UPSHAPE FONT
50 \newcommand\boxhandler{\textsf{boxhandler}~}
51 \GetFileInfo{boxhandler.sty}
52 \begin{document}
53 \title{The \textsf{boxhandler} Package\\
54 \rule{0em}{0.7em}\small\fileinfo}
55 \author{Steven B. Segletes\\
56 [email protected]}
57 \date{\filedate\\
58 \fileversion}
59 \maketitle
60 \DocInput{boxhandler.dtx}
61 \end{document}
62 %</driver>
63 % \fi
64 % \parskip 1ex
65 % \begin{abstract}
66 % This package facilitates the optimized presentation of \LaTeX{}
67 % tables and figures.
68 % Not only can boxhandler conveniently lay out table and figure
69 % captions with a wide variety of stylistic appearances, but allows
70 % for figures and tables to be ``wrapped'' in a manner consistent with
71 % many business and government documents. For a document that might
72 % appear in different venues with different formatting, boxhandler
73 % very powerfully permits the creation of a \LaTeX{} source
74 % document that can, with a single-line change
75 % in the source code, produce an output that has vastly different layout
76 % from the baseline configuration, both in terms of caption style,
77 % and in terms of the locations where figures, tables and lists
78 % appear (or not) in the document. Deferral routines also allow
79 % one to keep all figure and table data in a separate source file, while
80 % nonetheless producing a document with figures and tables appearing
81 % in the desired location in the document.
82 %
83 % \end{abstract}
84 %
85 % \vspace{-.55em}
86 % \tableofcontents\rule[.2em]{4.5in}{.3mm}\vspace{-1.5em}
87 %
88 % \section {Introduction}
89 %
90 % The commands described in the \boxhandler style accomplish a number of
91 % useful functions. Even without the use of a conditionally-compiled
92 % document:
93 % \begin{enumerate}
94 % \item they allow the definition of figures and tables in compact routine
95 % calls;
96 % \item they retain wide flexibility in caption appearance \& table/figure
97 % placement, through the use of simple setup calls.
98 % \end{enumerate}
99 % And for those who wish, from a single \LaTeX{} source file to
100 % conditionally produce, on one hand, an internal technical report for
101 % example, and on the other hand, a journal manuscript submission, this
102 % style additionally allows:
103 % \begin{enumerate}\setcounter{enumi}{2}
104 % \item printing of figures \& tables to be [conditionally] deferred to later
105 % in the document;
106 % \item printing of lists (\textit{lof}, \textit{lot}) to be deferred later
107 % in document; and
108 % \item the preemptive cancellation of the \textit{toc}, \textit{lof}, and
109 % \textit{lot}.
110 % \end{enumerate}
111 %
112 % \section{Caption Style, Appearance and Box Placement}
113 %
114 % \subsection{Commands}
115 %
116 % This routine provides several routines for creating and tailoring the
117 % appearance of captioned ``boxes'' (that is, figures and tables).
118 % They include:
119 % \begin{verse}
120 % |\bxtable[|\iq loc\uq|]{|\iq caption\uq|}{|\iq boxed object\uq|}|\\
121 % |\bxfigure[|\iq loc\uq|]{|\iq caption\uq|}{|\iq boxed object\uq|}|\\
122 % |\relaxCaptionWidth[|\iq len\uq|]|\\
123 % |\limitCaptionWidth[|\iq len\uq|]|\\
124 % |\constrainCaptionWidth[|\iq len\uq|]{|\iq len\uq|}|\\
125 % |\captionStyle{|\iq offset type\uq|}{|\iq alignment type\uq|}|\\
126 % |\hyperactive[|\iq len\uq|]|\\
127 % \end{verse}
128 % \DescribeMacro{\bxtable}
129 % \DescribeMacro{\bxfigure}
130 % The routines |\bxtable| and |\bxfigure| will actually produce the
131 % complete table or figure, including caption. In these two routines,
132 % \iq loc \uq is an optional argument. It can take on a value of:
133 % |ht|, |hb|,
134 % |t|, |b|, or |p|. This parameter refers to the same location argument
135 % that goes with the \LaTeX{} float environments, to help \LaTeX{}
136 % determine the placement of the item on your page. |h| is `here', |t| is
137 % `top', |b| is `bottom', |p| is `page of floats'. Omitting the first
138 % argument just uses the default placement of the table and figure
139 % environments.
140 %
141 % In |\bxtable| and |\bxfigure|, \iq caption \uq is the argument that
142 % will eventually get passed on to the |\caption| call, after the routine
143 % properly formulates it to match the desired figure/caption style. The
144 % caption may include |\label| identifiers to be referenced by the main
145 % text.
146 %
147 % For |\bxtable|, the \iq boxed object \uq will typically be a tabular
148 % box, though any \LaTeX{} boxed object will satisfy the routine. Thus,
149 % the difference between a |\bxtable| and a |\bxfigure| is largely a
150 % semantic one. The true difference between |\bxtable| and |\bxfigure|
151 % in this regard is that the table caption is placed above the table,
152 % whereas the figure caption is placed below it. In addition, because
153 % these routines make use of the standard |\caption| call within the
154 % table and figure environments, calls to |\bxtable| and |\bxfigure| will
155 % have their references automatically available to the List of Tables and
156 % List of Figures, respectively.
157 %
158 % One of the differences between the \boxhandler style and \LaTeX{}'s
159 % default captioning environment is the default caption width. Whereas
160 % \LaTeX{} defaults to a full margin-to-margin caption width,
161 % \boxhandler defaults to a caption width equal to and aligned with the
162 % width of the box being captioned. However, this caption-width default
163 % within \boxhandler can be changed to any arbitrary value, including
164 % full-width, if desired. The caption width, through the use of the
165 % ``dead margin,'' can also be conveniently set to a fixed offset from
166 % the table or figure width. For example, all table captions could be
167 % set to a width 1 inch larger than their associated tables.
168 %
169 % \DescribeMacro{\relaxCaptionWidth}
170 % The routine |\relaxCaptionWidth| takes as its optional argument a
171 % length dimension corresponding to the minimum allowed caption width,
172 % even if an associated table or figure is of lesser box width. While
173 % this command might technically violate an organization's style
174 % guideline, it allows one to avoid the situation of trying to assign a
175 % caption to fit the width dimension of an extremely narrow table or
176 % figure. An example of this use is shown in Tables~\ref{tbl:narrow} and
177 % \ref{tbl:wide}. In the first table, the default minimum caption width
178 % of 1~inch is retained, resulting in an unwieldy caption. The second
179 % table has been printed following an invocation of
180 % |\relaxCaptionWidth[4.0in]|. Using |\relaxCaptionWidth| with no argument
181 % resets the minimum allowed caption width to the default value of 1
182 % inch.
183 %
184 % \def\mycaption{A table which provides the secret entryword of the
185 % Halloween Ghost Club, assuming you can read the caption}
186 % \def\mytabular{
187 % \begin{tabular}{\tbllayout}
188 % \hline
189 % Boohoocachoo\\
190 % \hline
191 % \end{tabular}
192 % }
193 % \relaxCaptionWidth
194 % \bxtable[t]{\mycaption\label{tbl:narrow}}{\mytabular}
195 % \relaxCaptionWidth[4.0in]
196 % \bxtable[t]{\mycaption\label{tbl:wide}}{\mytabular}
197 % \relaxCaptionWidth
198 %
199 % If the minimum caption width is relaxed, the maximum allowed width
200 % will be bumped up, if necessary, to remain greater than or equal to
201 % the minimum allowed caption width.
202 %
203 % \DescribeMacro{\limitCaptionWidth}
204 % The routine |\limitCaptionWidth| is analogous to |\relaxCaptionWidth|.
205 % In this case, however, the maximum allowable caption width will be
206 % defined. If no argument is specified, the maximum allowed caption
207 % width is reset to the default value, which is |\textwidth|.
208 %
209 % If the maximum caption width is constrained, the minimum allowed width
210 % will be reduced, if necessary, to remain less than or equal to the
211 % maximum allowed caption width.
212 %
213 % \DescribeMacro{\constrainCaptionWidth}
214 % The minimum and maximum allowed caption widths may be simultaneously
215 % specified with |\constrainCaptionWidth|. The order of the two length
216 % arguments is not important. Omitting the optional argument will cause
217 % both the min and max allowable caption widths to be fixed at the
218 % specified value. In this manner, all caption widths will be set to this
219 % single value, regardless of the size of the table or figure box it
220 % describes. Note that the use of |\constrainCaptionWidth| with a single
221 % argument of |{\textwidth}| allows a full-width left-to-right margin
222 % caption style to be achieved, if desired, as in Figure~\ref{fig:cnst}.
223 %
224 % \DescribeMacro{\captionStyle}
225 % To understand the the figure and table caption style
226 % command, examine the caption styles in
227 % Figures~\ref{fig:styo}--\ref{fig:styc}, in reference to the
228 % boxed object with which they are paired.
229 % |\captionStyle{|\iq offset type\uq|}{|\iq alignment type\uq|}| is a
230 % compact way of specifying the caption style. The first parameter
231 % specifies the \textit{offset type} for long captions (since ``offset''
232 % has no meaning for short captions). It can take
233 % the value of |o| for ``offset'' captions, such as that found in
234 % Figure~\ref{fig:styo}, or |n| for ``nooffset'' captions, such as
235 % that found in Figure~\ref{fig:styn}.
236 %
237 % \relaxCaptionWidth[\textwidth]
238 % \captionStyle{n}{l}
239 % \bxfigure[p]
240 % {Here is a full-width caption that takes up the full
241 % margin-to-margin dimension, regardless of how wide the boxed object
242 % it serves is. In this case, the caption is of the ``nooffset''
243 % variety\label{fig:cnst}}
244 % {\framebox(260,40){Boxed Object: \tt\bs
245 % constrainCaptionWidth\lb\bs textwidth\rb}}
246 % \relaxCaptionWidth
247 % \captionStyle{o}{}
248 % \bxfigure[p]{For ``offset'' captions, the ID label for the caption
249 % is offset to the left of the caption text\label{fig:styo}}
250 % {\framebox(180,40){Boxed Object: \tt\bs captionStyle\{o\}\{\}}}
251 % \captionStyle{n}{}
252 % \bxfigure[p]{For ``nooffset'' captions, the caption's ID label
253 % is integrated into the caption text itself\label{fig:styn}}
254 % {\framebox(180,40){Boxed Object: \tt\bs captionStyle\{n\}\{\}}}
255 % \captionStyle{}{l}
256 % \bxfigure[p]{A short ``left''-aligned caption\label{fig:styl}}
257 % {\framebox(250,40){Boxed Object: \tt\bs captionStyle\{\}\{l\}}}
258 % \captionStyle{}{c}
259 % \bxfigure[p]{A short ``center''-aligned caption\label{fig:styc}}
260 % {\framebox(250,40){Boxed Object: \tt\bs captionStyle\{\}\{c\}}}
261 %
262 % The second parameter specifies the \textit{alignment type} for short
263 % captions (since long captions are already fully aligned). It can take
264 % on the value of |l| for ``left''-aligned
265 % captions, such as that in Figure~\ref{fig:styl}, the value |c| for
266 % ``center''-aligned captions, such as that in Figure~\ref{fig:styc},
267 % or the value of |r| for ``right''-aligned captions.
268 %
269 % The default style for this package is |\captionstyle{o}{l}|, or
270 % ``offset''-style, ``left''-aligned captions. This default caption
271 % style is that displayed in Figures~\ref{fig:styo} and \ref{fig:styl},
272 % for long and short captions, respectively.
273 %
274 % Note that caption alignment is not the same as caption justification.
275 % Regardless of alignment, any caption of size sufficient to span the
276 % full width of the caption box will be, by default, fully justified or
277 % ``flushed'' within that caption box. The captions in Figures~1 and 2
278 % demonstrate this for both offset and nooffset caption types. Text
279 % justification can, however, be altered, as described later by the
280 % |\CaptionJustification| parameter.
281 %
282 % \DescribeMacro{\hyperactive}
283 % |\hyperactive| was added in v1.22 to provide compatibility with the
284 % \textsf{hyperref} package, which is known to redefine many \LaTeX{}
285 % variables, including |\caption|. It was found, when the
286 % \textsf{hyperref} package was active, offset captions experienced a
287 % vertical gap between the caption label and the caption text. The
288 % command |\hyperactive| should be invoked only if the \textsf{hyperref}
289 % package is being utilized. The optional argument to this command is
290 % the length that boxhandler will shift the caption text downward, so
291 % as to achieve alignment with the caption label. The default value is
292 % -1.55ex, which was the required corrective shift observed for some
293 % applications, when the \textsf{hyperref} package was active.
294 %
295 % \subsection {Additional User Parameters}
296 %
297 % In addition to the above commands, there are a variety of
298 % lengths, counters, and modes, which may be set by the user,
299 % to adjust the appearance of the caption
300 % presentation. The settings for all these parameters hold until and
301 % unless subsequently reset by the user.
302 %
303 % \begin{verse}
304 % |\setlength\captionGap{|\iq len\uq|}|\\
305 % |\setlength\TableDeadMargin{|\iq len\uq|}|\\
306 % |\setlength\FigureDeadMargin{|\iq len\uq|}|\\
307 % |\setcounter{abovecaptionskipterm}{|\iq integer\uq|}|\\
308 % |\setcounter{belowcaptionskipterm}{|\iq integer\uq|}|\\
309 % |\let\CaptionFontSize |\iq fontsize, e.g., \uq|\small|\\
310 % |\let\TableFontSize |\iq fontsize, e.g., \uq|\small|\\
311 % |\def\LRTablePlacement{flushleft|\iq , \uq|center|\iq , or \uq
312 % |flushright}|\\
313 % |\def\LRFigurePlacement{flushleft|\iq , \uq|center|\iq , or \uq
314 % |flushright}|\\
315 % |\def\CaptionJustification{|\iq blank, \uq|\raggedright|\iq ,\\\uq
316 % | \centering|\iq , or \uq
317 % |\raggedleft}|\\
318 % \end{verse}
319 %
320 % \DescribeMacro{\captionGap}
321 % |\captionGap| defines the horizontal space
322 % between the caption identifier (e.g., ``Figure~1.'') and the start
323 % of the caption text itself. Its default value is 1ex.
324 %
325 % \DescribeMacro{\TableDeadMargin}
326 % \DescribeMacro{\FigureDeadMargin}
327 % |\TableDeadMargin| and |\FigureDeadMargin| may be set to correct the
328 % caption alignment for boxes that have a deadzone around their border.
329 % Such dead space takes up boxwidth, but shows no visible data. These
330 % parameter values should be set to the left or right-hand dead space
331 % (assumed symmetric). The default value for |\TableDeadMargin|, which
332 % is suitable for \LaTeX{} generated tabular data, is 0.375em. The default
333 % for |\FigureDeadMargin| is 0em.
334 %
335 % Additionally, these |\...DeadMargin| commands can be used to set the
336 % box-size-to-caption-size disparity to any desired non-flush value. As
337 % an example, setting the value of |\FigureDeadMargin| to 0.5 inch will
338 % make the figure captions always 1~inch smaller than the actual figure
339 % size. Setting it to $-0.5$ inch (\textit{a negative value!}) will make
340 % the caption always 1 inch larger than the actual figure size (within
341 % the error of the actual figure dead margin width, and subject to the
342 % caption width min/max constraints).
343 %
344 % \DescribeMacro{\abovecaptionskipterm}
345 % \DescribeMacro{\belowcaptionskipterm}
346 % The quantities |\abovecaptionskipterm| and |\belowcaptionskipterm|
347 % are related to
348 % \LaTeX{}'s |\abovecaptionskip| and |\belowcaptionskip| functions,
349 % defining the white- space above and below a caption. Unlike the
350 % corresponding \LaTeX{} functions, the parameters here are integers (not
351 % lengths). The terms represent multipliers of the \LaTeX{} length
352 % measure |\p@| to be used for the above- and below- captionskip.
353 % Their default values are 10 and 7, respectively. These
354 % values affect only captions that are created as part of bxtable and
355 % bxfigure, and do not affect the |\abovecaptionskip| and
356 % |\belowcaptionskip| definitions intrinsic to your default document
357 % class.
358 %
359 % \DescribeMacro{\CaptionFontSize}
360 % |\CaptionFontSize| defines the default size of the caption font, for
361 % example \normalsize, |\large|, |\scriptsize|, etc. The default value
362 % is |\small|.
363 %
364 % \DescribeMacro{\TableFontSize}
365 % |\TableFontSize| defines the default size of the font that appears
366 % within the tables themselves. Its default value is |\small|.
367 %
368 % \DescribeMacro{\LRTablePlacement}
369 % \DescribeMacro{\LRFigurePlacement}
370 % |\LRTablePlacement| and |\LRFigurePlacement| define the horizontal
371 % placement of tables and figures with respect to the paper margins. The
372 % options for these two parameters include |{flushleft}|, |{center}| and
373 % |{flushright}|. The default is |{center}|. This is different from the
374 % ``left'', ``center'', and ``right'' alignment modes for captions,
375 % which align short captions with respect to the boxed data.
376 %
377 % \DescribeMacro{\CaptionJustification}
378 % By default, any caption that spans the entire width of the caption box
379 % will be fully justified, or ``flushed'' with respect to the caption box
380 % margins. However, this behavior can be reset by redefining the
381 % parameter |\CaptionJustification|. For a ragged-right style within the
382 % caption box, the definition should be set to |\raggedright|. For the
383 % brave and daring, |\raggedleft| and/or |\centering| can be explored.
384 % Use |\def\CaptionJustification{}| to reset subsequent captions for full
385 % flushing.%
386 %
387 % \clearpage%
388 % \captionStyle{o}{l}%
389 % \setlength\captionGap{2.5ex}%
390 % \def\CaptionJustification{\raggedright}%
391 % \let\CaptionFontSize\scriptsize%
392 % \setcounter{abovecaptionskipterm}{3}%
393 % \def\LRFigurePlacement{flushright}%
394 % \setlength\FigureDeadMargin{1em}%
395 % \bxfigure[t]{Here is one example of a caption that has been set for%
396 % a ragged right justification. Justification, or ``flushing,''%
397 % is different than caption alignment, which is specified%
398 % independently and deals with how short captions are%
399 % aligned with respect to the boxed object\label{fig:ragged}}%
400 % {\framebox(263,60)%
401 % {\parbox{3.5in}{Boxed Object:\\%
402 % \small \hspace*{2.05in}%
403 % |flushright| \textit{placement $\rightarrow$\\%
404 % \hspace*{.17in} \uq 2.5ex \hspace*{0.45in}%
405 % \tt\bs\rm|scriptsize|\iq\\%
406 % caption gap \hfill caption font size \hfill%
407 % \uq\tt\bs\rm{|raggedright|} \iq justification}\\%
408 % \hspace*{.50in} $\downarrow$ \hfill $\downarrow$%
409 % \hfill \hfill $\downarrow$~~~}%
410 % }%
411 % }%
412 % \setlength\captionGap{1ex}%
413 % \def\CaptionJustification{}%
414 % \let\CaptionFontSize\small%
415 % \setcounter{abovecaptionskipterm}{10}%
416 % \def\LRFigurePlacement{center}%
417 % \setlength\FigureDeadMargin{0em}%
418 % \begin{picture} (0,0)%
419 % \put(-4,95){\makebox(20,0)[l]%
420 % {\small\tt\bs abovecaption-}}%
421 % \put(-4,86){\makebox(20,0)[l]%
422 % {\small~~|skipterm| = 3~~$\rightarrow$}}%
423 % \put(-31,68){\makebox(20,0)[l]%
424 % {\small\tt\bs FigureDeadMargin\rm = 1em~$\uparrow$}}%
425 % \put(-31,59){\makebox(20,0)[l]%
426 % {\small (1em on left; 1em on right)}}%
427 % \end{picture}%
428 % Figure~\ref{fig:ragged} is provided to demonstrate some of these
429 % features including: caption justification (|\raggedright|), caption gap
430 % (2.5~ex), caption font size (|\scriptsize|), LR figure placement
431 % (|flushright|), |abovecaptionskipterm| (3), and a value for
432 % |\FigureDeadMargin| of 1em.
433 %
434 % \section{Figure and Table ``Wrappers''}
435 %
436 % With \boxhandler v1.20, figure and table wrappers have been added.
437 % A wrapper is here defined to mean an item that bounds a figure or
438 % table by appearing in the upper-left and lower-right corners of
439 % the figure or table. It could be an iconic image such as the company
440 % logo, a reminder such as ``COMPANY PROPRIETARY'', or some other such
441 % delimiter to the figure/table. The relevant commands to use them are
442 % as follows:
443 %
444 % \begin{verse}
445 % |\WrapperOn[|\iq default wrapper\uq|]|\\
446 % |\WrapperOff|\\
447 % |\Wrapper{|\iq custom wrapper\uq|}|\\
448 % |\def\WrapperTextStyle{|\iq text style\uq|}|\\
449 % \end{verse}
450 %
451 % By default, wrappers are turned off in boxhandler. They may be
452 % activated with the command |\WrapperOn|. The optional argument to
453 % |\WrapperOn|, which should be used on the initial invocation,
454 % specifies the default wrapper. Likewise,
455 % wrappers may be disabled with the command |\WrapperOff|. When wrappers
456 % are activated, every table and figure subsequently created will be
457 % wrapped using the default wrapper.
458 %
459 % If, however, the user would like
460 % for a given figure or table to have a custom wrapper different than the
461 % default, the |\Wrapper{}| command should be used within the second
462 % mandatory argument of the call to |\bxtable| or |\bxfigure|. That is
463 % to say, the call to |\Wrapper| should be included within the argument
464 % where the actual figure or table contents are defined.
465 %
466 % \clearpage Here is an example:
467 %
468 % \begin{verse}
469 % |\bxfigure[ht]{Widget details for the XMC-7936}%|\\
470 % | {\fbox{\hspace{1in}\rule[-.5ex]{3ex}{3ex} $\rightarrow$%|\\
471 % | \rule[-.2ex]{2ex}{2ex}\hspace{1in}}\Wrapper{PROPRIETARY}}%|\\
472 % \end{verse}
473 %
474 % \WrapperOn
475 % \bxfigure[ht]{Widget details for the XMC-7936}%
476 % {\fbox{\hspace{1in}\rule[-.5ex]{3ex}{3ex} $\rightarrow$%
477 % \rule[-.2ex]{2ex}{2ex}\hspace{1in}}\Wrapper{PROPRIETARY}%
478 % }
479 % \WrapperOff
480 % Wrapper text (both default and custom) are given a style defined by
481 % |\WrapperTextStyle|. The default style is small, boldface text,
482 % |\bf\small|.
483 %
484 % \section{Box and List Deferral/Preemption}
485 %
486 % \subsection{Description of Problem}
487 %
488 % For those using conditional compilation to create various versions of
489 % the same basic document, the \boxhandler package can provide great
490 % utility. The package has been designed to permit the deferral and
491 % preemption of certain aspects of the document, such as figures, tables
492 % and lists. With such a capability, one has the capacity to not only
493 % change the appearance of the alternate document version, but to
494 % fundamentally change its layout too. Table~\ref{tbl:cccode} provides a
495 % simple example of how a document may be set up for conditional
496 % compilation.
497 %
498 % \setlength\TableDeadMargin{0.2em}\bxtable[ht]
499 % {Conditionally compiled \LaTeX{} code\label{tbl:cccode}}
500 % {\begin{tabular}{c}\hline\\
501 % \ttfamily\parbox{4.15in}{
502 % \bs def\bs PREPARETYPE\lb\bs TECHRPT\rb\% choices: \bs TECHRPT or
503 % \bs MANUSCRIPT\\
504 % \bs newcommand\bs TECHRPT\lb\% class for ARL organizational tech rpts\\
505 % \% CONDITIONALLY COMPILED CODE FOR TECHRPT DOCUMENTS\\
506 % | |\bs documentclass\lb arlticle\rb\\
507 % \rb\\
508 % \bs newcommand\bs MANUSCRIPT\lb\% article-ized version of tech rpt.\\
509 % \% CONDITIONALLY COMPILED CODE FOR MANUSCRIPTS\\
510 % | |\bs documentclass[11pt]\lb article\rb\\
511 % | |\bs usepackage\lb TR2article\rb\\
512 % \% VARIOUS \bs MANUSCRIPT-SPECIFIC SETUP COMMANDS GO HERE\\
513 % \rb\\
514 % \bs PREPARETYPE\\
515 % \% LaTeX CODE \& DOCUMENT COMMON TO BOTH STYLES FOLLOWS HEREAFTER\\
516 % }\\
517 % \hline\end{tabular}
518 % }
519 %
520 % In this example, by setting the parameter in the first line of the
521 % document to either |\TECHRPT| or |\MANUSCRIPT|, a different collection
522 % of setup routines may be invoked for each particular document style.
523 % This works great for such parameters that affect appearance, but not
524 % placement of the \LaTeX{} entities. For example, changing fonts,
525 % margins, indents, etc. works fine with the conditional code shown in
526 % Table~\ref{tbl:cccode}. Even when a particular document class has
527 % unique commands not found in other classes, a converter style file may
528 % be created (such as |TR2article| in the Table~\ref{tbl:cccode} example)
529 % to deal rationally with invocations of class-specific features.
530 %
531 % Where great difficulty arises is when the different styles desired of a
532 % conditional compilation utilize fundamentally different layouts of the
533 % principal document elements, such as figures, tables, and lists. For
534 % example, a technical report would have it's tables and figures
535 % interspersed throughout the document, whereas the corresponding journal
536 % manuscript submission might have tables and figures collected, one per
537 % page, at the end of the document. Whereas the report would have the
538 % List of Figures (\textit{lof}) as part of the report's front matter,
539 % the journal manuscript might request to have the \textit{lof} preceding
540 % the figures located at the end of the manuscript. A typical scientific journal
541 % manuscript submission would not include a Table of Contents
542 % (\textit{toc}), and perhaps not a List of Tables (\textit{lot}) either.
543 %
544 % Arranging for such options to unfold from a single input source file is
545 % cumbersome without a special treatment. The \boxhandler style
546 % provides routines to expedite and ease this cumbersome process.
547 %
548 % The \boxhandler style also conveniently allows for another useful
549 % scenario, in which figure and table data may be kept in a separate
550 % file from the document text, but nonetheless be made to print out with
551 % figures and tables appearing in the proper location in the text. The
552 % |\nextTable| and |\nextFigure| commands aid in this approach.
553 %
554 % \subsection{Deferral and Preemption Commands}
555 %
556 % For figure and table deferral, and/or list deferral/preemption, the
557 % following commands are available, all without arguments:
558 %
559 % \begin{verse}
560 % |\holdTables|\\
561 % |\holdFigures|\\
562 % |\clearTables|\\
563 % |\clearFigures|\\
564 % |\killlistoftables|\\
565 % |\killlistoffigures|\\
566 % |\killtableofcontents|\\
567 % |\holdlistoftables|\\
568 % |\holdlistoffigures|\\
569 % |\clearlistoftables|\\
570 % |\clearlistoffigures|\\
571 % |\nextTable[|\iq loc\uq|]|\\
572 % |\nextFigure[|\iq loc\uq|]|\\
573 % \end{verse}
574 %
575 % \DescribeMacro{\holdTables}
576 % \DescribeMacro{\holdFigures}
577 % |\holdTables| and |\holdFigures| are used to direct that any subsequent
578 % invocations of |\bxtable| and |\bxfigure| merely store, rather than
579 % store \& print the table or figure. These |\hold...| commands would
580 % typically be found in the conditionally compiled code for manuscripts,
581 % for example.
582 %
583 % While the calculated width of the caption is saved at the time of call
584 % to |\bxtable| and |\bxfigure| based upon the \boxhandler parameters at
585 % the time of the |\bx...| call, the caption format (i.e., [no]offset,
586 % center/left alignment, caption justification) is not set until the
587 % figure/table is later printed as part of a |\clear...| command (the
588 % logic here is that the caption style will be consistent through the
589 % course of the document, thus alleviating the need to store this data
590 % for each figure and table).
591 %
592 % The one potential pitfall with the use of these commands
593 % is the situation when a citation is made within
594 % the caption of a deferred table or figure. In this case, the citation
595 % is numbered based on when the table or figure is finally displayed,
596 % not when it was created.
597 % Thus, if |\holdTables| and/or |\holdFigures| is used to prevent the
598 % printing of tables and/or figures until the end of the document,
599 % then any unique citation defined in a table or figure
600 % caption will receive a higher citation number than even a citation
601 % appearing in the last line of document text.
602 %
603 % There is, however, an easy solution to this predicament. That is,
604 % when a figure or table is employed which contains a citation, the
605 % main text of the document should invoke |\nocite{|\iq key\_list\uq|}|
606 % to the same reference. This occurance of |\nocite| should be
607 % placed in the main document (\textit{i.e.}, outside of |bxtable|
608 % or |bxfigure|) at the point where the table or figure is actually
609 % being invoked. In this manner, the citation gets added to the
610 % \textit{.aux} file at the proper spot, regardless of when the table
611 % or figure is actually printed out.
612 %
613 % \DescribeMacro{\clearTables}
614 % \DescribeMacro{\clearFigures}
615 % |\clearTables| and |\clearFigures| directs that any tables or figures
616 % that have been stored, but not yet printed, be output at this point.
617 % As mentioned above, the offset, alignment, and justification for
618 % captions is set at the time of printing, not at the time of table or
619 % figure creation. The format for presenting tables and figures to be
620 % cleared (i.e., one table/figure per page, vertically centered) can be
621 % changed by renewing the commands |\theClearedTable| and/or
622 % |\theClearedFigure|. See the next section on Advanced Use for details.
623 %
624 % Note that if tables and figures have not been subject to a |\hold...|
625 % command, the |\clear...| commands have no effect, since they affect
626 % only those tables and/or figures which have not already been printed.
627 % Thus, these commands would typically appear in the common document text
628 % at the appropriate point where tables and figures, if previously held,
629 % should be printed. Note that, though commands have not been explicitly
630 % provided to kill the printing of figures and tables, this can be
631 % effectively accomplished by putting figures and/or tables on hold, and
632 % then ending the document without having issued a corresponding
633 % |\clear...| command.
634 %
635 % \DescribeMacro{\killlistoftables}
636 % \DescribeMacro{\killlistoffigures}
637 % \DescribeMacro{\killtableofcontents}
638 % |\killlistoftables|, |\killlistoffigures| and |\killtableofcontents|
639 % direct that any subsequent calls to print the respective list be
640 % ignored and that the list be discarded. This action cannot later be
641 % undone with a |\hold...| command. These commands would typically
642 % appear in the conditionally compiled region of the document.
643 %
644 % \DescribeMacro{\holdlistoftables}
645 % \DescribeMacro{\holdlistoffigures}
646 % |\holdlistoftables| and |\holdlistoffigures| direct that calls to print
647 % the particular list cited be deferred until a later invocation of the
648 % corresponding |\clear...| command. Note that a call to |\clearTables|
649 % and |\clearFigures| will also clear the corresponding list first, if it
650 % has been subject to a |\hold...| command (but not a |\kill...|
651 % command). These |\hold...| commands would typically appear in the
652 % conditionally compiled region of the document.
653 %
654 % \DescribeMacro{\clearlistoftables}
655 % \DescribeMacro{\clearlistoffigures}
656 % |\clearlistoftables| and |\clearlistoffigures| clear the cited list
657 % (i.e., those lists currently ``on hold''). No list will be
658 % printed if: the |\listoftables| or |\listoffigures| command hadn't
659 % earlier been invoked; if it had already been printed out because it
660 % hadn't been subject to a hold; or if the list had previously been
661 % killed. Note: calls to |\clearTables| or |\clearFigures| automatically
662 % causes a call to |\clearlistoftables| or |\clearlistoffigures|,
663 % respectively. Therefore, these particular calls are only needed
664 % explicitly in your \LaTeX{} document if it is desired to clear the list
665 % well in advance of the associated tables or figures.
666 %
667 % With the deferral and preemption commands now described, we show how
668 % they might be used to complete the multi-mode \LaTeX{} document stencil
669 % that was first laid out in Table~\ref{tbl:cccode}. To see this, refer
670 % to Table~\ref{tbl:bxcode}. The document is created with |\bxtable| and
671 % |\bxfigure| calls dispersed throughout text, and nominally asks for the
672 % \textit{toc}, \textit{lof}, and \textit{lot} to be printed at the
673 % beginning of the document. When |\PREPARETYPE| is defined as
674 % |{\TECHRPT}|, this is exactly how the document unfolds.
675 %
676 % \setlength\TableDeadMargin{0.2em}\bxtable[t!]
677 % {Conditionally compiled \LaTeX{} code with \texttt{boxhandler} package
678 % deferral and preemption directives\label{tbl:bxcode}}
679 % {\begin{tabular}{c}\hline\\
680 % \ttfamily\parbox{4.15in}{
681 % \bs def\bs PREPARETYPE\lb\bs TECHRPT\rb\% choices: \bs TECHRPT or
682 % \bs MANUSCRIPT\\
683 % \bs newcommand\bs TECHRPT\lb\% class for ARL organizational tech rpts\\
684 % \% CONDITIONALLY COMPILED CODE FOR TECHRPT DOCUMENTS\\
685 % | |\bs documentclass\lb arlticle\rb\\
686 % | |\bs usepackage\lb boxhandler\rb\\
687 % \rb\\
688 % \bs newcommand\bs MANUSCRIPT\lb\% article-ized version of tech rpt.\\
689 % \% CONDITIONALLY COMPILED CODE FOR MANUSCRIPTS\\
690 % | |\bs documentclass[11pt]\lb article\rb\\
691 % | |\bs usepackage\lb TR2article\rb\\
692 % | |\bs usepackage\lb boxhandler\rb\\
693 % | |\bs killtableofcontents\\
694 % | |\bs killlistoftables\\
695 % | |\bs holdlistoffigures\\
696 % | |\bs holdTables\\
697 % | |\bs holdFigures\\
698 % \% VARIOUS \bs MANUSCRIPT-SPECIFIC SETUP COMMANDS GO HERE\\
699 % \rb\\
700 % \bs PREPARETYPE\\
701 % \% LaTeX CODE \& DOCUMENT COMMON TO BOTH STYLES FOLLOWS HEREAFTER\\
702 % \bs begin\lb document\rb\\
703 % \bs maketitle\\
704 % \bs tableofcontents\\
705 % \bs listoffigures\\
706 % \bs listoftables\\
707 % ...\\
708 % \% DOCUMENT CONTAINING \bs bxtable AND \bs bxfigure CALLS GOES HERE.\\
709 % ...\\
710 % \bs clearTables\\
711 % \bs clearFigures\\
712 % \bs end\lb document\rb\\
713 % }\\
714 % \hline\end{tabular}
715 % }
716 %
717 % However, by merely defining |\PREPARETYPE| as |{\MANUSCRIPT}|, the
718 % \textit{toc} and \textit{lot} will be killed, preempting subsequent
719 % invocations. Printing of the \textit{lof} will be deferred. As
720 % |bxtables| and |bxfigures| are invoked, they will be created and
721 % stored, but not printed. At the very end of the document, all the
722 % tables will first be cleared, one per page, vertically centered. The
723 % call to |\clearFigures| will then clear the \textit{lof} on a new page,
724 % and finally clear all the figures in a similar manner.
725 %
726 % \textbf{With the change of a single line of code, a vastly different
727 % document layout has been achieved!}
728 %
729 % \DescribeMacro{\nextTable}
730 % \DescribeMacro{\nextFigure}
731 % The deferral commands described to this point have been cast in terms
732 % of tools to aid in printing out multiple vastly different versions
733 % of a document from a single source file. With \boxhandler v1.10, the
734 % commands |\nextTable| and |\nextFigure| have been introduced. These
735 % commands, while somewhat similar in function to |\clearTables| and
736 % |\clearFigures|, are useful in a completely different regard. In the
737 % case of |\nextTable| and |\nextFigure|, only a single table or figure
738 % is cleared. Unlike |\clearTables| and |\clearFigures|, the table or
739 % figure is not printed on a page by itself, but inline the document.
740 % The optional argument specifies the location on the page (|ht|, |hb|, |t|,
741 % |b| or |p|) where the
742 % table or figure should appear, consistent with \LaTeX{} convention.
743 %
744 % The unique utility of the |\nextTable| and |\nextFigure| commands
745 % is in allowing one to define all the document's figures and tables
746 % ``up front,'' at the beginning of the document, perhaps even in a
747 % seperate file that is |\input| into the document. Then, when a table
748 % or figure is referred to in the text, all that need be included in
749 % the main document is an occurance of |\nextTable| or |\nextFigure|.
750 %
751 % In this manner, all the tables and figures can be printed out in the
752 % document at their appropriate location, while logically, the document
753 % can be organized during preparation to keep the figure and table
754 % matter separate from the text matter of the document.
755 %
756 % If one wishes to incorporate conditional compiliation
757 % (as in Table~\ref{tbl:bxcode}) while simultaneously keeping table
758 % and figure definition in a separate file |\input| at the beginning
759 % of the document, this can be done, too. The tables and figures would
760 % be added after the |\begin{document}| command and invocation would
761 % be accomplished by way of |\nextTable| and |\nextFigure| as described
762 % here. However, in the |\MANUSCRIPT| preamble (using the nomenclature
763 % of Table~\ref{tbl:bxcode}), |\nextTable| and |\nextFigure| would be
764 % nullified as:\\
765 % | \renewcommand\nextTable[1][]{}|\\ and\\
766 % | \renewcommand\nextFigure[1][]{}|.\\
767 % In this manner, for the |\MANUSCRIPT| report type, tables and figures
768 % would be made to not appear until the final invocations of
769 % |\clearTables| and |\clearFigures|.
770 %
771 %
772 % \section {Advanced Use (DANGER!)}
773 %
774 % Additionally, there are certain lower level, yet accessible, counters,
775 % macros and lengths, which are intended for advanced use only. It is
776 % possible to get into difficulty if not thinking through their use
777 % thoroughly. Pitfalls will be laid out, where known. These accessible
778 % hooks into the inner workings of the \boxhandler package include:
779 %
780 % \begin{verse}
781 % \underline{Lengths:}\\
782 % |\DeadMargin, \CaptionBoxWidth|\\
783 % \underline{Counters:}\\
784 % |TableIndex, FigureIndex, TableClearedIndex,|\\
785 % |FigureClearedIndex, promptTablesFlag, promptFiguresFlag|\\
786 % \underline{Macros:}\\
787 % |\StoreTable{|\iq caption\uq|}{|\iq boxed object\uq
788 % |}{|\iq wrapper\uq|}{|\iq wrapper status\uq|}|\\
789 % |\StoreFigure{|\iq caption\uq|}{|\iq boxed object\uq
790 % |}{|\iq wrapper\uq|}{|\iq wrapper status\uq|}|\\
791 % |\SaveCBox{|\iq new cmd\uq|}{|\iq boxed object\uq|}|\\
792 % |\ReciteTable[|\iq loc\uq|]{|\iq caption\uq|}{|\iq cmd\uq
793 % |}{|\iq wdth\uq|}{|\iq wrapper\uq|}{|\iq wrapper status\uq|}|\\
794 % |\ReciteFigure[|\iq loc\uq|]{|\iq caption\uq|}{|\iq cmd\uq
795 % |}{|\iq wdth\uq|}{|\iq wrapper\uq|}{|\iq wrapper status\uq|}|\\
796 % |\theClearedTable[|\iq loc\uq|]{|\iq caption\uq|}{|\iq cmd\uq
797 % |}{|\iq wdth\uq|}{|\iq wrapper\uq|}{|\iq wrapper status\uq|}|\\
798 % |\theClearedFigure[|\iq loc\uq|]{|\iq caption\uq|}{|\iq cmd\uq
799 % |}{|\iq wdth\uq|}{|\iq wrapper\uq|}{|\iq wrapper status\uq|}|\\
800 % \end{verse}
801 %
802 % \DescribeMacro{TableIndex}
803 % \DescribeMacro{FigureIndex}
804 % \DescribeMacro{TableClearedIndex}
805 % \DescribeMacro{FigureClearedIndex}
806 % To keep track of tables and figures as they are created, the counters
807 % |TableIndex| and |FigureIndex| are used. To keep track of how many
808 % tables and figures have already been printed, |TableClearedIndex|, and
809 % |FigureClearedIndex| are used. The appropriate index is incremented
810 % whenever a table or figure is created or cleared. These index counters
811 % are also used as part of the naming convention employed by the
812 % |\StoreTable| and |\StoreFigure| commands, to be subsequently
813 % described.
814 %
815 % \DescribeMacro{promptTablesFlag}
816 % \DescribeMacro{promptFiguresFlag}
817 % The counters |promptTablesFlag| and |promptFiguresFlag| are used as
818 % binary switches to determine whether calls to |\bxtable| and
819 % |\bxfigure| result in the prompt display (1) or deferred display (0) of
820 % the table or figure. The |\holdTables| and |\holdFigures| commands
821 % change these switches to their `0' state. Any significant use of these
822 % switches to achieve the printing of latter tables/figures prior to the
823 % clearing of earlier ones will require the rewrite, by the user, of the
824 % |\clearTables| and |\clearFigures| commands, since these |\clear...|
825 % macros were written using a first-in-first-out (FIFO) methodology.
826 %
827 % \DescribeMacro{\StoreTable}
828 % \DescribeMacro{\StoreFigure}
829 % The macros |\StoreTable| and |\StoreFigure| use the same form of
830 % caption and data arguments as |\bxtable| and |\bxfigure|, with two
831 % additional wrapper variables added. In fact, the
832 % |\bx...| commands call upon the |\Store...| macros. The difference
833 % is that the |\StoreTable| and |\StoreFigure| macros will save the
834 % boxed object without printing it, regardless of whether a |\hold...|
835 % command has been issued. The saved information will consist of five
836 % pointers necessary to recreate the table or figure. These pointers
837 % will be named according to \textsf{boxhandler}'s internal naming
838 % convention.
839 %
840 % At this point, it is worth noting the naming convention of the pointers
841 % used by \boxhandler to store the variables for figures and tables.
842 % The saved information resulting from a |\StoreTable| or |\StoreFigure|
843 % command will consist of a pointer to a saved box, a pointer to the
844 % caption text, a pointer to the calculated width of the caption box
845 % (based on the state of the \boxhandler parameters at the time of the
846 % function call), and pointers to the wrapper and a flag indicating
847 % whether wrappers are active for this figure or table.
848 %
849 % The counters |TableIndex| and |FigureIndex| are used to create a unique
850 % part of these pointer names, in the form of |\roman{|\iq
851 % indexname\uq|}|. Saved box pointers have the prefix |tbl-| or |fig-|,
852 % saved caption pointers have the prefix |tblcap-| or |figcap-| and
853 % caption-width pointers have the prefix |tblcapwdth-| and |figcapwdth-|.
854 % The wrapper pointer has the prefix |tblwrap-| and the pointer to flag
855 % indicating the status of wrapper activity is |tblwrapstatus-|.
856 % Thus, for example, the fourth invocation of |\bxtable| or |\StoreTable|
857 % will create an sbox named |\tbliv| that is used to store the boxed
858 % (e.g., tabular) data, a pointer |\tblcapiv| that is used to store the
859 % caption text, a length pointer |\tblcapwdthiv| that stores the
860 % value of the calculated caption width, a wrapper pointer |\tblwrapiv|,
861 % which stores the wrapper, and a pointer |\tblwrapstatusiv|, which
862 % stores a `T' or `F' to indicate whether wrappers are currently active
863 % or not. When avoiding creative
864 % programming, the pointer index (e.g., `iv' in this example) will
865 % correspond to the actual Table or Figure number (i.e., `4') appearing
866 % in the caption ID label. However, it is wise to remember,
867 % \begin{enumerate}
868 % \item when creating tables or figures outside of the \boxhandler style;
869 % \item when bypassing the |\Store...| commands and going straight to the
870 % lower level |\SaveCBox| command; or
871 % \item when using the |\Recite...| commands to print multiple occurances
872 % of a box;
873 % \end{enumerate}
874 % that the internal numbering of \boxhandler tables and figures will
875 % likely be out of syncronization with the Table and Figure counters.
876 %
877 % \DescribeMacro{\SaveCBox}
878 % The low-level routine which saves a ``captioned box'' is called
879 % |\SaveCBox|. As its arguments, it follows the form of the \LaTeX{}
880 % |\sbox| command: it takes a new command name and the boxed object as
881 % its parameters. This is the routine called by the |\Store...| commands
882 % with a command argument something like |\tbliv| or |\figiii|, for
883 % example. You are, however, free to pass your own command names to this
884 % routine, so as not to conflict with the names autogenerated by the
885 % |\Store...| commands. Keep in mind that calls to |\SaveCBox| will not,
886 % by themselves, increment |TableIndex| or |FigureIndex|, and will not be
887 % tracked by the |\clear...| commands.
888 %
889 % \DescribeMacro{\DeadMargin}
890 % \DescribeMacro{\CaptionBoxWidth}
891 % In addition to saving the boxed object in the specified command bin,
892 % the width of the associated caption is calculated, based upon the
893 % prevailing \boxhandler parameters at the time of call. One such
894 % parameter that is used to calculate the caption width, is the dead
895 % margin. |\SaveCBox|, being a low-level routine, is used for both
896 % tables and figures. As such, the appropriate variable to set, in order
897 % to define the dead margin is the generic length |\DeadMargin|,
898 % regardless of whether the call is to save a figure or a table box. The
899 % calculated caption width is stored in the length variable
900 % |\CaptionBoxWidth|. This length variable is ephemeral, being updated
901 % with each new figure or table generated, and so it is up to the user to
902 % save the value of |\CaptionBoxWidth| somewhere else if it is to be used
903 % to later define a recited box's caption width. Likewise, while
904 % |\SaveCBox| does not even deal with the box's caption text per se, it
905 % is the user's responsibility to save the actual caption somewhere, for
906 % later recitation.
907 %
908 % \DescribeMacro{\ReciteTable}
909 % \DescribeMacro{\ReciteFigure}
910 % Reciting stored tables or figures is accomplished by way of
911 % |\ReciteTable| and |\ReciteFigure|. As the [optional] first of their
912 % four arguments, they take the location directive for placement on the
913 % page (e.g., |ht|, |hb|, |t|, |b|, or |p|). Both the caption and the caption
914 % width arguments may be specified directly, or indirectly by way of a
915 % stored string and length variable, respectively. The command argument
916 % to these macros must be the bin for the saved box object that
917 % constitutes the actual table or figure data.
918 %
919 % If one desires, the |\Recite...| commands may be used repeatedly to
920 % print a given table or figure multiple times. However, any |\label|
921 % associated with the [repeatedly recited] caption will be reassigned to
922 % the most recent invocation of the |\Recite...| call. Thus, references
923 % to the table or figure number by way of a |\ref| call are likely to
924 % produce an undesired result, if a given table or figure is recited
925 % multiple times.
926 %
927 % \DescribeMacro{\theClearedTable}
928 % \DescribeMacro{\theClearedFigure}
929 % Finally, two very useful routines to be familiar with are the
930 % |\theClearedTable| and |\theClearedFigure| macros. These are the
931 % routines which are repeatedly called by |\clearTables| and
932 % |\clearFigures|, respectively, to print out all tables and figures
933 % which have been ``on hold.'' The manner in which \boxhandler clears
934 % them is one per page, vertically centered. It is easy to envision
935 % applications in which the method of clearing would take on a different
936 % appearance than this. To change the appearance by which tables and/or
937 % figures are cleared, these commands need to be redefined by the user by
938 % way of a |\renewcommand|. For reference, the |\theClearedTable|
939 % command is defined by \boxhandler as:
940 %
941 %| |\\
942 %|\newcommand\theClearedTable[6][ht]{|\\
943 %| \vspace*{\fill}|\\
944 %| \ReciteTable[#1]{#2}{#3}{#4}{#5}{#6}|\\
945 %| \vspace*{\fill}|\\
946 %| \clearpage|\\
947 %|}|\\
948 %
949 % As one can see, |\theClearedTable| is a call to |\ReciteTable| that is
950 % surrounded by the code necessary to place the table recitation at the
951 % desired location upon the page. |\theClearedFigure| is defined
952 % analogously. Modification of this layout should be straightforward for
953 % the user. For example, if it were desired to have two tables per page
954 % during the clearing process, one might use the following renewal:
955 %
956 %| |\\
957 %|\newcounter{toggle} \setcounter{toggle}{0}|\\
958 %|\renewcommand\theClearedTable[6][ht]{|\\
959 %| \addtocounter{toggle}{1}|\\
960 %| \ifnum \arabic{toggle} = 2 \setcounter{toggle}{0} \fi|\\
961 %| \ifnum \arabic{toggle} = 1|\\
962 %| \ReciteTable[t]{#2}{#3}{#4}{#5}{#6}|\\
963 %| \else|\\
964 %| \ReciteTable[b]{#2}{#3}{#4}{#5}{#6}|\\
965 %| \clearpage|\\
966 %| \fi|\\
967 %|}|
968 %
969 % \section {Examples}
970 %
971 %% Examples of a number of calls provided in this style are given below,
972 %% in no particular order:
973 %%
974 %%| |\\
975 %%|\bxtable[t] |\\
976 %%| {This is a test of nonwrapping caption\label{tb:mytable}} |\\
977 %%| { |\\
978 % \iffalse
979 %<package>%%| \begin{tabular}{|c|c|c|} |\\
980 % \fi
981 %| \begin{tabular}{|\verb,|c|c|c|,|} |\\
982 %%| \hline |\\
983 %%| column 1 data & 2nd column data & and the third column data\\|\\
984 %%| \hline |\\
985 %%| \end{tabular} |\\
986 %%| } |\\
987 %%| |\\
988 %%|\usepackage{graphicx} |\\
989 %%|\bxfigure[ht] |\\
990 %%| {Here is an example of a particularly long caption that will |\\
991 %%| test wrapping} |\\
992 %%| {\includegraphics[width=3.64in,height=4.30in]{Atest1.eps}} |\\
993 %%| |\\
994 %%|\relaxCaptionWidth[2in] |\\
995 %%| |\\
996 %%|\captionStyle{}{c} |\\
997 %%| |\\
998 %%|\setlength\captionGap{3ex} |\\
999 %%| |\\
1000 %%|\setcounter{abovecaptionskipterm}{10} |\\
1001 %%|\setcounter{belowcaptionskipterm}{0} |\\
1002 %%| |\\
1003 %%|\TableFontSize\normalsize |\\
1004 %%| |\\
1005 %%|\LRFigurePlacement{flushleft} |\\
1006 %%| |\\
1007 %%|\killtableofcontents |\\
1008 %%| |\\
1009 %%|\holdFigures |\\
1010 %%| |\\
1011 %%|\clearFigures |\\
1012 %%| |\\
1013 %%|\newsavebox{\mybox} |\\
1014 %%|\SaveCBox{\mybox}{\framebox(200,100){Ack!}} |\\
1015 %%| |\\
1016 %%|\ReciteFigure[ht]{\figcapii}{\figii}{\figcapwdthii}% |\\
1017 %%| {\figwrapii}{\figwrapstatusii} |\\
1018 %%
1019 % \vspace{-1em}
1020 % \section {Vestigials}
1021 %
1022 % \DescribeMacro{\arltable}
1023 % \DescribeMacro{\arlfigure}
1024 % In order to retain backward compatibility with the predecessor to the
1025 % \boxhandler package, the vestigial commands |\arltable| and
1026 % |\arlfigure| are defined in this package, and are equivalent to
1027 % |\bxtable| and |\bxfigure|, respectively.
1028 %
1029 % As an historical note, the genesis of the \boxhandler package was a
1030 % requirement to comply with my organization's caption style (``offset''
1031 % style, ``left'' aligned) specified for its technical reports. Various
1032 % piecemeal approaches were out there to handle it, requiring
1033 % case-specific decisions on the part of the author, depending on the
1034 % specifics of the figure/table box and the caption. \boxhandler was
1035 % intended to simplify and generalize the approach.
1036 %
1037 % The figure/table deferral features of \boxhandler were borne of my own
1038 % laziness. I just didn't relish keeping two different versions of the
1039 % same document up to date... one for my organization, and the other as a
1040 % manuscript for possible journal submission. The |\bx...| commands
1041 % provided an easier ``hook'' through which to achieve the holding and
1042 % clearing of boxes than did any attempt to muck with the underlying
1043 % |Figure| and |Table| environments of \LaTeX{}.
1044 %
1045 % \section {Acknowledgments/Salutations}
1046 % That's it for a description of \textsf{boxhandler}! I would like to thank
1047 % a number of colleagues for their consultive assistance. Several were
1048 % instrumental in getting me over early bumps in my \LaTeX{} learning
1049 % curve, including Mike Scheidler, Stephen Schraml, Brian Krzewinski,
1050 % and Paul Tanenbaum, all of the USARL. I am particularly grateful
1051 % to Fred Brundick (also of ARL) for sharing his extensive knowledge
1052 % of \LaTeX{} with me. He clued me in to the sticky quirks of offset
1053 % captions, and shared his methods for dealing with the different cases.
1054 % He also pointed me in the right direction for the systematic saving
1055 % of \LaTeX{} box objects, which contributed to the section of this
1056 % package dealing with object deferral.
1057 %
1058 % I hope this package provides you some utility. The only thing left
1059 % is the code listing itself.
1060 %% \CharacterTable
1061 %% {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
1062 %% 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
1063 %% Digits \0\1\2\3\4\5\6\7\8\9
1064 %% Exclamation \! Double quote \" Hash (number) \#
1065 %% Dollar \$ Percent \% Ampersand \&
1066 %% Acute accent \' Left paren \( Right paren \)
1067 %% Asterisk \* Plus \+ Comma \,
1068 %% Minus \- Point \. Solidus \/
1069 %% Colon \: Semicolon \; Less than \<
1070 %% Equals \= Greater than \> Question mark \?
1071 %% Commercial at \@ Left bracket \[ Backslash \\
1072 %% Right bracket \] Circumflex \^ Underscore \_
1073 %% Grave accent \` Left brace \{ Vertical bar \|
1074 %% Right brace \} Tilde \~}
1075 % \StopEventually{}
1076 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1077 % \clearpage
1078 % \vspace{-0.8em}
1079 % \begin{macro}{boxhandler.sty}
1080 % \section{Code Listing}
1081 % I'll try to lay out herein
1082 % the workings of the \boxhandler style package. I apologize if
1083 % the code fails in some way to conform to \LaTeX{} programming
1084 % conventions. I am but an enthusiastic novice.
1085 % \begin{macrocode}
1086 %<*package>
1087 % \end{macrocode}
1088 % \end{macro}
1089 %
1090 % \begin{macro}{pbox}
1091 % This package makes use of the \textsf{ifthen} and \textsf{pbox} style
1092 % packages to aid in the boxing of captions.
1093 % \begin{macrocode}
1094 \RequirePackage{ifthen}
1095 \usepackage{pbox}
1096 % \end{macrocode}
1097 % \end{macro}
1098 %
1099 % \begin{macro}{TableIndex}
1100 % \begin{macro}{FigureIndex}
1101 % \begin{macro}{TableClearedIndex}
1102 % \begin{macro}{FigureClearedIndex}
1103 % We start by defining and initializing the counters that keep track of
1104 % how many tables and figures have been created and how many have been
1105 % cleared (i.e., printed out).
1106 % \begin{macrocode}
1107 \newcounter{TableIndex} \setcounter{TableIndex}{0}
1108 \newcounter{FigureIndex} \setcounter{FigureIndex}{0}
1109 \newcounter{TableClearedIndex} \setcounter{TableClearedIndex}{0}
1110 \newcounter{FigureClearedIndex} \setcounter{FigureClearedIndex}{0}
1111 % \end{macrocode}
1112 % \end{macro}
1113 % \end{macro}
1114 % \end{macro}
1115 % \end{macro}
1116 %
1117 % \begin{macro}{\old@makecaption}
1118 % \begin{macro}{\oldabovecaptionskip}
1119 % \begin{macro}{\oldbelowcaptionskip}
1120 % Here, we save the prevailing definitions of |\@makecaption|,
1121 % |\abovecaptionskip| and |\belowcaptionskip|, so that they can be
1122 % altered before and restored after every invocation of |\bxtable| and
1123 % |\bxfigure|.
1124 % \begin{macrocode}
1125 \let\old@makecaption \@makecaption% SAVE PREVAILING \@makecaption STYLE
1126 \newlength\oldabovecaptionskip
1127 \setlength\oldabovecaptionskip \abovecaptionskip
1128 \newlength\oldbelowcaptionskip
1129 \setlength\oldbelowcaptionskip \belowcaptionskip
1130 % \end{macrocode}
1131 % \end{macro}
1132 % \end{macro}
1133 % \end{macro}
1134 %
1135 % \begin{macro}{\captionGap}
1136 % Initialize |\captionGap| to 1ex, which sets the horizontal space
1137 % between the caption label and the caption box for offset-style
1138 % captions.
1139 % \begin{macrocode}
1140 %% \captionGap CAN BE INCREASED TO PLACE MORE SPACE BETWEEN THE CAPTION
1141 %% LABEL AND THE ACTUAL CAPTION TEXT.
1142 \newlength\captionGap \setlength\captionGap{1ex}
1143 % \end{macrocode}
1144 % \end{macro}
1145 %
1146 % \begin{macro}{\TableDeadMargin}
1147 % \begin{macro}{\FigureDeadMargin}
1148 % The default values for the dead margin around tables and figures is
1149 % initialized here. The value of 0.375em for tables corresponds to what
1150 % the |tabular| environment seems to produce. No presupposition is made
1151 % on what the dead margin is for the figure environment, however.
1152 % \begin{macrocode}
1153 %% \TableDeadMargin AND \FigureDeadMargin REFER TO THE TABLE & FIGURE
1154 %% MARGIN OF A BOX THAT COUNTS TOWARDS ITS SIZE, BUT IN WHICH NO
1155 %% ACTIVE DATA FALLS; DEADMARGIN ASSUMED ON BOTH LEFT & RIGHT SIDE.
1156 \newlength\TableDeadMargin \setlength\TableDeadMargin{0.375em}
1157 \newlength\FigureDeadMargin \setlength\FigureDeadMargin{0em}
1158 % \end{macrocode}
1159 % \end{macro}
1160 % \end{macro}
1161 %
1162 % \begin{macro}{abovecaptionskipterm}
1163 % \begin{macro}{belowcaptionskipterm} The integer parameters
1164 % |abovecaptionskipterm| and |belowcaptionskipterm| are initialized here.
1165 % They will be used to guide the temporarily alteration of
1166 % |\abovecaptionskip| and |\belowcaptionskip| during invocations of
1167 % |\bxtable| and |\bxfigure|.
1168 % \begin{macrocode}
1169 %% INITIALIZE \above- AND \belowcaptionskip VALUES; CAN BE RESET
1170 %% USED TO SET GAPS ABOVE & BELOW CAPTIONS
1171 \newcounter{abovecaptionskipterm} \setcounter{abovecaptionskipterm}{10}
1172 \newcounter{belowcaptionskipterm} \setcounter{belowcaptionskipterm}{7}
1173 % \end{macrocode}
1174 % \end{macro}
1175 % \end{macro}
1176 %
1177 % \begin{macro}{\@minCaptionBoxWidth}
1178 % \begin{macro}{\@minCaptionBoxWidthDefault}
1179 % \begin{macro}{\@maxCaptionBoxWidth}
1180 % \begin{macro}{\@maxCaptionBoxWidthDefault}
1181 % The minimum and maximum allowed width defaults for the caption box are
1182 % defined here. The variables holding the current values of min/max
1183 % caption width are also allocated here. Their values will be set and
1184 % altered through the use of the macros |\relaxCaptionWidth|,
1185 % |\limitCaptionWidth| and |\constrainCaptionWidth|, to be described
1186 % later.
1187 % \begin{macrocode}
1188 %% RESET \@minCaptionBoxWidth TO Default VALUE WITH \relaxCaptionWidth
1189 %% SET \@minCaptionBoxWidth TO USER VALUE WITH \relaxCaptionWidth[<len>]
1190 \newlength\@minCaptionBoxWidth
1191 \newlength\@minCaptionBoxWidthDefault
1192 \setlength\@minCaptionBoxWidthDefault{1in}
1193 %% RESET \@maxCaptionBoxWidth TO Default WITH \limitCaptionWidth
1194 %% SET \@maxCaptionBoxWidth WITH \limitCaptionWidth[<len>]
1195 \newlength\@maxCaptionBoxWidth
1196 \newlength\@maxCaptionBoxWidthDefault
1197 \setlength\@maxCaptionBoxWidthDefault{\textwidth}
1198 % \end{macrocode}
1199 % \end{macro}
1200 % \end{macro}
1201 % \end{macro}
1202 % \end{macro}
1203 %
1204 % \begin{macro}{promptTablesFlag}
1205 % \begin{macro}{promptFiguresFlag}
1206 % \begin{macro}{\holdTables}
1207 % \begin{macro}{\holdFigures}
1208 % |promptTablesFlag| and |promptFiguresFlag| are binary switches to
1209 % define whether calls to |\bxtable| and |\bxfigure| are cleared (i.e.,
1210 % printed) promptly or merely stored for later clearing. The change to
1211 % put them ``on hold'' is actuated by the |\holdTables| and
1212 % |\holdFigures| commands, respectively. Because the associated
1213 % |\clear...| commands were written with FIFO logic, no mechanism is
1214 % provided to reset the flags to ``prompt'', once set to ``on hold.''
1215 % Even so, tables and figures can be cleared in sub-batches, by issuing a
1216 % series of |\clear...| commands at intermediate points in the document.
1217 % \begin{macrocode}
1218 %% DEFINE promptTablesFlag & PROVIDE ROUTINE TO CHANGE IT FROM
1219 %% "PROMPT"(1) TO "ON HOLD"(0)
1220 \newcounter{promptTablesFlag} \setcounter{promptTablesFlag}{1}
1221 \newcommand\holdTables{\setcounter{promptTablesFlag}{0}}
1222 %% SAME FOR promptFiguresFlag
1223 \newcounter{promptFiguresFlag} \setcounter{promptFiguresFlag}{1}
1224 \newcommand\holdFigures{\setcounter{promptFiguresFlag}{0}}
1225 % \end{macrocode}
1226 % \end{macro}
1227 % \end{macro}
1228 % \end{macro}
1229 % \end{macro}
1230 %
1231 % \begin{macro}{\CaptionFontSize}
1232 % \begin{macro}{\TableFontSize}
1233 % Default size of font in both captions and tables is, by default,
1234 % |\small|. However, these variables allow those defaults to be reset to
1235 % the desired font size.
1236 % \begin{macrocode}
1237 %% DEFAULT CaptionFontSize & TableFontSize AS \small; CAN BE RESET
1238 \let \CaptionFontSize \small
1239 \let \TableFontSize \small
1240 % \end{macrocode}
1241 % \end{macro}
1242 % \end{macro}
1243 %
1244 % \begin{macro}{\LRTablePlacement}
1245 % \begin{macro}{\LRFigurePlacement}
1246 % These variables set the placement of the table or figure either flushed
1247 % to the left or right margin, or else centered between the margins (the
1248 % default). They can be reset by the user.
1249 % \begin{macrocode}
1250 %% DEFAULT TABLE & FIGURE LR ALIGNMENT TO center;
1251 %% CAN RESET TO flushleft/-right
1252 \def \LRTablePlacement {center}
1253 \def \LRFigurePlacement {center}
1254 % \end{macrocode}
1255 % \end{macro}
1256 % \end{macro}
1257 %
1258 % \begin{macro}{\CaptionJustification}
1259 % The flushing of the actual text within the caption box may be
1260 % accomplished by setting |\CaptionJustification|. When it is defined
1261 % as |{}| (the default), the caption is fully justified (i.e.,
1262 % flushed) within the caption box. It may also be set to
1263 % |{\raggedleft}|, |{\raggedright}| or |{\centering}|.
1264 % \begin{macrocode}
1265 %% WITHIN-CAPTION JUSTIFICATION CAN BE SET
1266 %% OPTIONS: {}, {\raggedleft}, {\raggedright}, or {\centering}
1267 \def\CaptionJustification{} % <---DEFAULT IS FULL JUSTIFICATION
1268
1269 % \end{macrocode}
1270 % \end{macro}
1271 %
1272 % \begin{macro}{\DeadMargin}
1273 % \begin{macro}{\CaptionBoxWidth}
1274 % \begin{macro}{\@DataBoxWidth}
1275 % \begin{macro}{\@DataBoxOffset}
1276 % \begin{macro}{\@CaptionBoxOffset}
1277 % \begin{macro}{\@captionIDwidth}
1278 % \begin{macro}{\@captionWidth}
1279 % \begin{macro}{\@DataBoxSurplus}
1280 % New working variables are defined here. All are |@|-protected from
1281 % access except for |\DeadMargin| and |\CaptionBoxWidth|, which have been
1282 % made accessible for so-called ``Advanced Use.''
1283 % |\DeadMargin| is the low-level variable where the dead margin of the
1284 % current figure or table box is specified by the advanced user.
1285 % |\@DataBoxWidth| is the calculated width of the data-box portion of
1286 % the current table or figure.
1287 % |\CaptionBoxWidth| is the calculated width of the caption box for the
1288 % current figure, taking into account the dead margin as well as the
1289 % min/max allowed caption widths. The ``advanced user'' can save this
1290 % datum for future figure/table recitation.
1291 % |\@DataBoxOffset| is the calculated spacer length that must be added to
1292 % both sides of the data box to bring it to the size of the caption box.
1293 % It will be zeroed, if the data box width exceeds the caption box width.
1294 % |\@CaptionBoxOffset| is the calculated spacer length that must be added
1295 % to both sides of the caption box to bring it to the size of the data
1296 % box. It will be zeroed, if the caption box width exceeds the data box
1297 % width.
1298 % |\@captionIDwidth| is used for offset-style captions, and is the width
1299 % of the caption ID plus the caption gap (e.g., the width of
1300 % ``Figure 4.~~'').
1301 % |\@captionWidth| is, for offset-style captions, simply
1302 % |\CaptionBoxWidth| minus |\@captionIDwidth|; this value equals the
1303 % width of the |\parbox| which is used for the caption text in
1304 % offset-style captions. Finally,
1305 % |\@DataBoxSurplus| is the excess of data box width over the caption box
1306 % width. It can be positive or negative, depending on whether the data
1307 % box or caption box is larger.
1308 % \begin{macrocode}
1309 %% WORKING VARIABLES
1310 \newlength\DeadMargin
1311 \newlength\@DataBoxWidth
1312 \newlength\CaptionBoxWidth
1313 \newlength\@DataBoxOffset
1314 \newlength\@CaptionBoxOffset
1315 \newlength\@captionIDwidth
1316 \newlength\@captionWidth
1317 \newlength\@DataBoxSurplus
1318
1319 % \end{macrocode}
1320 % \end{macro}
1321 % \end{macro}
1322 % \end{macro}
1323 % \end{macro}
1324 % \end{macro}
1325 % \end{macro}
1326 % \end{macro}
1327 % \end{macro}
1328 % \begin{macro}{\WrapperOn}
1329 % \begin{macro}{\WrapperOff}
1330 % \begin{macro}{\Wrapper}
1331 % \begin{macro}{\WrapperTextStyle}
1332 % Wrappers are identifying text (or icons) that bound figures and
1333 % tables in the
1334 % upper-left and lower-right corners. Initially disabled, |\WrapperOn|
1335 % turns wrappers on. The optional argument of |\WrapperOn|, which
1336 % should be used on the first invocation, specifies the default wrapper.
1337 % Wrappers can be turned off with |\WrapperOff|.
1338 % The default wrapper can be changed with a subsequent invocation
1339 % to |\WrapperOn|.
1340 %
1341 % However, the wrapper for any given figure
1342 % or table may be individually specified (without changing the default
1343 % wrapper) by way of the
1344 % argument to |\Wrapper|. Both the default wrapper as well as one
1345 % passed as an argument to |\Wrapper| are presented with the style
1346 % given in |\WrapperTextStyle|, which defaults to small, bold font,
1347 % |\bf\small|. The command |\Wrapper|, if used, should be placed within
1348 % the second mandatory argument of |\bxtable| and |\bxfigure|, if a
1349 % wrapper other than the default is desired.
1350 % \begin{macrocode}
1351 %% FIGURE & TABLE WRAPPER INITIALIZATIONS
1352 \def\wrapper{F}
1353 \def\WrapperTextStyle{\bf\small}
1354 \def\WrapperTextDefault{DEFAULT WRAPPER}
1355 \global\def\WrapperText{\noexpand\WrapperTextStyle\WrapperTextDefault}
1356 \newcommand\WrapperOn[1][]{%
1357 \def\wrapper{T}%
1358 \ifthenelse{\equal{#1}{}}%
1359 {}{\def\WrapperTextDefault{\noexpand#1}}%
1360 \global\def%
1361 \WrapperText{\noexpand\WrapperTextStyle\WrapperTextDefault}%
1362 }
1363 \newcommand\WrapperOff{\def\wrapper{F}}
1364 \newcommand\Wrapper[1]{\global\def%
1365 \WrapperText{\noexpand\WrapperTextStyle\noexpand#1}}
1366
1367 % \end{macrocode}
1368 % \end{macro}
1369 % \end{macro}
1370 % \end{macro}
1371 % \end{macro}
1372 %
1373 % \begin{macro}{\bxtable}
1374 % The routine |\bxtable| will store the specified table. If
1375 % |promptTablesFlag| equals unity, the table will also be immediately
1376 % cleared using the specified \textit{loc} parameter. If
1377 % |\roman{TableIndex}| equalled, for example, |vii|, then the table data
1378 % would be stored in the box |\tblvii|, the caption text would be stored
1379 % in the pointer |\tblcapvii|, and the calculated caption width would be
1380 % stored in the pointer |\tblcapwdthvii|.
1381 % \begin{macrocode}
1382 \newcommand\bxtable[3][t]{%
1383 \StoreTable[#1]{#2}{#3}{\WrapperText}{\wrapper}%
1384 \ifnum\arabic{promptTablesFlag}=1%
1385 \addtocounter{TableClearedIndex}{1}%
1386 \def\TableBoxLabel{tbl\roman{TableIndex}}%
1387 \def\TableCaptionLabel{tblcap\roman{TableIndex}}%
1388 \def\TblCaptionWidthLabel{tblcapwdth\roman{TableIndex}}%
1389 \def\TableWrapper{tblwrap\roman{TableIndex}}%
1390 \def\WrapperStatus{tblwrapstatus\roman{TableIndex}}%
1391 \ReciteTable[#1]{\csname\TableCaptionLabel\endcsname}%
1392 {\csname\TableBoxLabel\endcsname}%
1393 {\csname\TblCaptionWidthLabel\endcsname}%
1394 {\csname\TableWrapper\endcsname}%
1395 {\csname\WrapperStatus\endcsname}%
1396 \fi
1397 }
1398
1399 % \end{macrocode}
1400 % \end{macro}
1401 %
1402 % \begin{macro}{\StoreTable}
1403 % |\StoreTable| calculates the names of the pointers where the
1404 % table-data, -caption, and -width will be stored, and calls upon the
1405 % low-level |\SaveCbox| routine to actually save the tabular data and
1406 % compute the caption width. It finally stores the caption text itself
1407 % and the calculated caption width. Note that the optional first
1408 % argument, \textit{loc}, is a dummy argument that is not used here.
1409 % \begin{macrocode}
1410 \newcommand\StoreTable[5][]{%
1411 \addtocounter{TableIndex}{1}%
1412 \setlength\DeadMargin\TableDeadMargin%
1413 \def\TableBoxLabel{tbl\roman{TableIndex}}%
1414 \def\TableCaptionLabel{tblcap\roman{TableIndex}}%
1415 \def\TblCaptionWidthLabel{tblcapwdth\roman{TableIndex}}%
1416 \def\TableWrapper{tblwrap\roman{TableIndex}}%
1417 \def\WrapperStatus{tblwrapstatus\roman{TableIndex}}%
1418 \expandafter\SaveCBox\csname\TableBoxLabel\endcsname{\TableFontSize#3}%
1419 \expandafter\def\csname\TableCaptionLabel\endcsname{#2}%
1420 \expandafter\newlength\csname\TblCaptionWidthLabel\endcsname%
1421 \expandafter\setlength\csname\TblCaptionWidthLabel\endcsname%
1422 \CaptionBoxWidth%
1423 \expandafter\edef\csname\TableWrapper\endcsname{#4}%
1424 \expandafter\edef\csname\WrapperStatus\endcsname{#5}%
1425 %% After storing table, reset wrapper to default value
1426 \global\def%
1427 \WrapperText{\noexpand\WrapperTextStyle\WrapperTextDefault}%
1428 }
1429
1430 % \end{macrocode}
1431 % \end{macro}
1432 %
1433 % \begin{macro}{\ReciteTable}
1434 % The |\ReciteTable| routine recites a previously stored table, using the
1435 % pointers that are provided as arguments. First, the |\Table|
1436 % environment is invoked, and the left/right table-placement environment
1437 % is opened. The routine then defines new definitions for
1438 % |\@makecaption|, |\abovecaptionskip| and |\belowcaptionskip|. It then
1439 % uses the provided pointers to set the data-box and caption-box widths,
1440 % and calculates the offsets. It recites the box caption (using the
1441 % caption-box offset, if needed) and then it recites the tabular-data box
1442 % (using the data-box offset, if needed). The original definitions for
1443 % |\@makecaption|, |\abovecaptionskip| and |\belowcaptionskip| are
1444 % restored, the table placement environment is concluded and the table
1445 % itself is ended.
1446 % \begin{macrocode}
1447 \newcommand\ReciteTable[6][ht]{%
1448 \begin{table}[#1]%
1449 \begin{\LRTablePlacement}%
1450 \let\@makecaption\new@makecaption%
1451 \setlength\abovecaptionskip{\arabic{abovecaptionskipterm}\p@}%
1452 \setlength\belowcaptionskip{\arabic{belowcaptionskipterm}\p@}%
1453 \set@DataBoxWidth{#3}%
1454 \setlength\CaptionBoxWidth{#4}%
1455 \set@BoxOffsets%
1456 \if T#6%
1457 \rule{\@DataBoxOffset}{0in}%
1458 \makebox[\@DataBoxWidth][l]{#5}%
1459 \rule{\@DataBoxOffset}{0in}\\%
1460 \fi
1461 \rule{\@CaptionBoxOffset}{0em}%
1462 \parbox{\CaptionBoxWidth}{\bx@caption{#2}}%
1463 \rule{\@CaptionBoxOffset}{0em}%
1464 \par%
1465 \rule{\@DataBoxOffset}{0in}%
1466 \usebox{#3}%
1467 \rule{\@DataBoxOffset}{0in}\\%
1468 \if T#6%
1469 \rule{\@DataBoxOffset}{0in}\\%
1470 \makebox[\@DataBoxWidth][r]{#5}%
1471 \rule{\@DataBoxOffset}{0in}%
1472 \fi
1473 \let\@makecaption\old@makecaption%
1474 \setlength\abovecaptionskip \oldabovecaptionskip%
1475 \setlength\belowcaptionskip \oldbelowcaptionskip%
1476 \end{\LRTablePlacement}%
1477 \end{table}%
1478 }
1479
1480 % \end{macrocode}
1481 % \end{macro}
1482 %
1483 % \begin{macro}{\nextTable}
1484 % This routine will clear a single table, if there are any that have
1485 % not yet been printed as a result of a previously invoked \holdTables
1486 % command. It assumes FIFO logic. The optional argument is the location
1487 % on the page where the table is to be printed, in accordance with
1488 % standard \LaTeX{} logic. If there are no uncleared tables left to
1489 % format, then the command has no effect.
1490 % \begin{macrocode}
1491 \newcommand\nextTable[1][ht]{%
1492 \ifnum\arabic{TableClearedIndex}<\arabic{TableIndex}{%
1493 \addtocounter{TableClearedIndex}{1}%
1494 %% \TableBoxLabel : tbli, tblii, tbliii, tbliv, etc.
1495 %% \TableCaptionLabel : tblcapi, tblcapii, tblcapiii, tblcapiv, etc.
1496 %% \TblCaptionWidthLabel: tblcapwdthi, tblcapwdthii, tblcapwdthiii,etc.
1497 \def\TableBoxLabel{tbl\roman{TableClearedIndex}}%
1498 \def\TableCaptionLabel{tblcap\roman{TableClearedIndex}}%
1499 \def\TblCaptionWidthLabel{tblcapwdth\roman{TableClearedIndex}}%
1500 \def\TableWrapper{tblwrap\roman{TableClearedIndex}}%
1501 \def\WrapperStatus{tblwrapstatus\roman{TableClearedIndex}}%
1502 \ReciteTable[#1]{\csname\TableCaptionLabel\endcsname}%
1503 {\csname\TableBoxLabel\endcsname}%
1504 {\csname\TblCaptionWidthLabel\endcsname}%
1505 {\csname\TableWrapper\endcsname}%
1506 {\csname\WrapperStatus\endcsname}%
1507 }\fi
1508 }
1509
1510 % \end{macrocode}
1511 % \end{macro}
1512 % \begin{macro}{\clearTables}
1513 % This routine will clear all stored tables that have not yet been
1514 % printed. It assumes a FIFO logic. It starts by clearing the page and
1515 % clearing the List of Tables (i.e., prints the \textit{lot} \textbf{if}
1516 % the List of Tables had been put on hold, and subsequently invoked while
1517 % ``on hold''). If the \textit{lot} had previously been killed, then
1518 % |\clearlistoftables| will have no effect. Once the \textit{lot} has
1519 % been cleared (or not), a loop is set up in which the names of
1520 % stored-table pointers are reconstructed, and successively passed to
1521 % |\theClearedTable| which defines the format for clearing and actually
1522 % calls for the table to be recited.
1523 % \begin{macrocode}
1524 \newcommand\clearTables{%
1525 \clearpage%
1526 \clearlistoftables%
1527 \clearpage%
1528 %%DO UNTIL ALL HELD TABLES ARE CLEARED
1529 \whiledo{\arabic{TableClearedIndex}<\arabic{TableIndex}}{%
1530 \addtocounter{TableClearedIndex}{1}%
1531 %% \TableBoxLabel : tbli, tblii, tbliii, tbliv, etc.
1532 %% \TableCaptionLabel : tblcapi, tblcapii, tblcapiii, tblcapiv, etc.
1533 %% \TblCaptionWidthLabel: tblcapwdthi, tblcapwdthii, tblcapwdthiii,etc.
1534 \def\TableBoxLabel{tbl\roman{TableClearedIndex}}%
1535 \def\TableCaptionLabel{tblcap\roman{TableClearedIndex}}%
1536 \def\TblCaptionWidthLabel{tblcapwdth\roman{TableClearedIndex}}%
1537 \def\TableWrapper{tblwrap\roman{TableClearedIndex}}%
1538 \def\WrapperStatus{tblwrapstatus\roman{TableClearedIndex}}%
1539 \theClearedTable{\csname\TableCaptionLabel\endcsname}%
1540 {\csname\TableBoxLabel\endcsname}%
1541 {\csname\TblCaptionWidthLabel\endcsname}%
1542 {\csname\TableWrapper\endcsname}%
1543 {\csname\WrapperStatus\endcsname}%
1544 }%
1545 }
1546
1547 % \end{macrocode}
1548 % \end{macro}
1549 %
1550 % \begin{macro}{\theClearedTable}
1551 % Quite simply, this routine prints out each table to be cleared, one per
1552 % page, vertically centered. It can be renewed by the user if a
1553 % different clearing format is desired.
1554 % \begin{macrocode}
1555 %% \theClearedTable CAN BE RENEWED IF DIFFERENT OUTPUT FORMAT IS DESIRED
1556 \newcommand\theClearedTable[6][ht]{%
1557 %% CLEAR THIS TABLE ON A PAGE BY ITSELF, CENTERED VERTICALLY
1558 \vspace*{\fill}%
1559 \ReciteTable[#1]{#2}{#3}{#4}{#5}{#6}%
1560 \vspace*{\fill}%
1561 \clearpage%
1562 }
1563
1564 % \end{macrocode}
1565 % \end{macro}
1566 %
1567 % \begin{macro}{\bxfigure}
1568 % This routine is analogous to |\bxtable| in every way. For figures, the
1569 % pointers which save the figure use a |\fig-| prefix, instead of a
1570 % |\tbl-| prefix.
1571 % \begin{macrocode}
1572 \newcommand\bxfigure[3][t]{%
1573 \StoreFigure[#1]{#2}{#3}{\WrapperText}{\wrapper}%
1574 \ifnum\arabic{promptFiguresFlag}=1%
1575 \addtocounter{FigureClearedIndex}{1}%
1576 \def\FigureBoxLabel{fig\roman{FigureIndex}}%
1577 \def\FigureCaptionLabel{figcap\roman{FigureIndex}}%
1578 \def\FigCaptionWidthLabel{figcapwdth\roman{FigureIndex}}%
1579 \def\FigureWrapper{figwrap\roman{FigureIndex}}%
1580 \def\WrapperStatus{figwrapstatus\roman{FigureIndex}}%
1581 \ReciteFigure[#1]{\csname\FigureCaptionLabel\endcsname}%
1582 {\csname\FigureBoxLabel\endcsname}%
1583 {\csname\FigCaptionWidthLabel\endcsname}%
1584 {\csname\FigureWrapper\endcsname}%
1585 {\csname\WrapperStatus\endcsname}%
1586 \fi
1587 }
1588
1589 % \end{macrocode}
1590 % \end{macro}
1591 %
1592 % \begin{macro}{\StoreFigure}
1593 % This routine is analogous to |\StoreTable| in every way.
1594 % \begin{macrocode}
1595 \newcommand\StoreFigure[5][]{%
1596 \addtocounter{FigureIndex}{1}%
1597 \setlength\DeadMargin\FigureDeadMargin%
1598 \def\FigureBoxLabel{fig\roman{FigureIndex}}%
1599 \def\FigureCaptionLabel{figcap\roman{FigureIndex}}%
1600 \def\FigCaptionWidthLabel{figcapwdth\roman{FigureIndex}}%
1601 \def\FigureWrapper{figwrap\roman{FigureIndex}}%
1602 \def\WrapperStatus{figwrapstatus\roman{FigureIndex}}%
1603 \expandafter\SaveCBox\csname\FigureBoxLabel\endcsname{#3}%
1604 \expandafter\def\csname\FigureCaptionLabel\endcsname{#2}%
1605 \expandafter\newlength\csname\FigCaptionWidthLabel\endcsname%
1606 \expandafter\setlength\csname\FigCaptionWidthLabel\endcsname%
1607 \CaptionBoxWidth%
1608 \expandafter\edef\csname\FigureWrapper\endcsname{#4}%
1609 \expandafter\edef\csname\WrapperStatus\endcsname{#5}%
1610 %% After storing figure, reset wrapper to default value
1611 \global\def%
1612 \WrapperText{\noexpand\WrapperTextStyle\WrapperTextDefault}%
1613 }
1614
1615 % \end{macrocode}
1616 % \end{macro}
1617 %
1618 % \begin{macro}{\ReciteFigure}
1619 % This routine is analogous to |\ReciteTable| in every way, except one.
1620 % In the case of |\ReciteFigure|, the figure-data box is output
1621 % \textbf{before} the caption, not after.
1622 % \begin{macrocode}
1623 \newcommand\ReciteFigure[6][ht]{%
1624 \begin{figure}[#1]%
1625 \begin{\LRFigurePlacement}%
1626 \let\@makecaption\new@makecaption%
1627 \setlength\abovecaptionskip{\arabic{abovecaptionskipterm}\p@}%
1628 \setlength\belowcaptionskip{\arabic{belowcaptionskipterm}\p@}%
1629 \set@DataBoxWidth{#3}%
1630 \setlength\CaptionBoxWidth{#4}%
1631 \set@BoxOffsets%
1632 \if T#6%
1633 \rule{\@DataBoxOffset}{0in}%
1634 \makebox[\@DataBoxWidth][l]{#5}%
1635 \rule{\@DataBoxOffset}{0in}\\%
1636 \fi
1637 \rule{\@DataBoxOffset}{0in}%
1638 \usebox{#3}%
1639 \rule{\@DataBoxOffset}{0in}%
1640 \par%
1641 \rule{\@CaptionBoxOffset}{0em}%
1642 \parbox{\CaptionBoxWidth}{\bx@caption{#2}}%
1643 \rule{\@CaptionBoxOffset}{0em}%
1644 \if T#6%
1645 \rule{\@DataBoxOffset}{0in}\\%
1646 \makebox[\@DataBoxWidth][r]{#5}%
1647 \rule{\@DataBoxOffset}{0in}%
1648 \fi
1649 \let\@makecaption\old@makecaption%
1650 \setlength\abovecaptionskip\oldabovecaptionskip%
1651 \setlength\belowcaptionskip\oldbelowcaptionskip%
1652 \end{\LRFigurePlacement}%
1653 \end{figure}%
1654 }
1655
1656 % \end{macrocode}
1657 % \end{macro}
1658 %
1659 % \begin{macro}{\nextFigure}
1660 % This routine is analogous to |\nextTable| in every way.
1661 % \begin{macrocode}
1662 \newcommand\nextFigure[1][ht]{%
1663 \ifnum\arabic{FigureClearedIndex}<\arabic{FigureIndex}{%
1664 \addtocounter{FigureClearedIndex}{1}%
1665 %% \FigureBoxLabel: : figi, figii, figiii, figiv, etc.
1666 %% \FigureCaptionLabel : figcapi, figcapii, figcapiii, figcapiv, etc.
1667 %% \FigCaptionWidthLabel: figcapwdthi, figcapwdthii, figcapwdthiii,etc.
1668 \def\FigureBoxLabel{fig\roman{FigureClearedIndex}}%
1669 \def\FigureCaptionLabel{figcap\roman{FigureClearedIndex}}%
1670 \def\FigCaptionWidthLabel{figcapwdth\roman{FigureClearedIndex}}%
1671 \def\FigureWrapper{figwrap\roman{FigureClearedIndex}}%
1672 \def\WrapperStatus{figwrapstatus\roman{FigureClearedIndex}}%
1673 \ReciteFigure[#1]{\csname\FigureCaptionLabel\endcsname}%
1674 {\csname\FigureBoxLabel\endcsname}%
1675 {\csname\FigCaptionWidthLabel\endcsname}%
1676 {\csname\FigureWrapper\endcsname}%
1677 {\csname\WrapperStatus\endcsname}%
1678 }\fi
1679 }
1680
1681 % \end{macrocode}
1682 % \end{macro}
1683 % \begin{macro}{\clearFigures}
1684 % This routine is analogous to |\clearTables| in every way.
1685 % \begin{macrocode}
1686 \newcommand\clearFigures{%
1687 \clearpage%
1688 \clearlistoffigures%
1689 \clearpage%
1690 %%DO UNTIL ALL HELD FIGURES ARE CLEARED
1691 \whiledo{\arabic{FigureClearedIndex}<\arabic{FigureIndex}}{%
1692 \addtocounter{FigureClearedIndex}{1}%
1693 %% \FigureBoxLabel : figi, figii, figiii, figiv, etc.
1694 %% \FigureCaptionLabel : figcapi, figcapii, figcapiii, figcapiv, etc.
1695 %% \FigCaptionWidthLabel: figcapwdthi, figcapwdthii, figcapwdthiii,etc.
1696 \def\FigureBoxLabel{fig\roman{FigureClearedIndex}}%
1697 \def\FigureCaptionLabel{figcap\roman{FigureClearedIndex}}%
1698 \def\FigCaptionWidthLabel{figcapwdth\roman{FigureClearedIndex}}%
1699 \def\FigureWrapper{figwrap\roman{FigureClearedIndex}}%
1700 \def\WrapperStatus{figwrapstatus\roman{FigureClearedIndex}}%
1701 \theClearedFigure{\csname\FigureCaptionLabel\endcsname}%
1702 {\csname\FigureBoxLabel\endcsname}%
1703 {\csname\FigCaptionWidthLabel\endcsname}%
1704 {\csname\FigureWrapper\endcsname}%
1705 {\csname\WrapperStatus\endcsname}%
1706 }%
1707 }
1708
1709 % \end{macrocode}
1710 % \end{macro}
1711 %
1712 % \begin{macro}{\theClearedFigure}
1713 % This routine is analogous to |\theClearedTable| in every way... one
1714 % figure per page, vertically centered.
1715 % \begin{macrocode}
1716 %% \theClearedFigure CAN BE RENEWED IF DIFFERENT OUTPUT FORMAT DESIRED
1717 \newcommand\theClearedFigure[6][ht]{%
1718 %% CLEAR THIS FIGURE ON A PAGE BY ITSELF, CENTERED VERTICALLY
1719 \vspace*{\fill}%
1720 \ReciteFigure[#1]{#2}{#3}{#4}{#5}{#6}%
1721 \vspace*{\fill}%
1722 \clearpage%
1723 }
1724
1725 % \end{macrocode}
1726 % \end{macro}
1727 %
1728 % \begin{macro}{\relaxCaptionWidth}
1729 % This routine sets the minimum permitted caption width. When called
1730 % with no argument, it resets the min caption width to its 1 inch default
1731 % value. If necessary, the maximum allowed caption width will be bumped
1732 % up, so as to remain greater than or equal the minimum allowed caption
1733 % width.
1734 % \begin{macrocode}
1735 \newcommand\relaxCaptionWidth[1][\@minCaptionBoxWidthDefault]{%
1736 \setlength\@minCaptionBoxWidth{#1}%
1737 \ifdim \@minCaptionBoxWidth > \@maxCaptionBoxWidth%
1738 \setlength\@maxCaptionBoxWidth\@minCaptionBoxWidth%
1739 \fi
1740 }
1741 \relaxCaptionWidth% SET INITIAL \@minCaptionBoxWidth TO DEFAULT VALUE
1742
1743 % \end{macrocode}
1744 % \end{macro}
1745 %
1746 % \begin{macro}{\limitCaptionWidth}
1747 % This routine sets the maximum permitted caption width. When called
1748 % with no argument, it resets the max caption width to its default value
1749 % of |\textwidth|. If necessary, the minimum allowed caption width will
1750 % be reduced, so as to remain less than or equal the maximum allowed
1751 % caption width.
1752 % \begin{macrocode}
1753 \newcommand\limitCaptionWidth[1][\@maxCaptionBoxWidthDefault]{%
1754 \setlength\@maxCaptionBoxWidth{#1}%
1755 \ifdim \@maxCaptionBoxWidth < \@minCaptionBoxWidth%
1756 \setlength\@minCaptionBoxWidth\@maxCaptionBoxWidth%
1757 \fi
1758 }
1759 \limitCaptionWidth% SET INITIAL \@maxCaptionBoxWidth TO DEFAULT VALUE
1760
1761 % \end{macrocode}
1762 % \end{macro}
1763 %
1764 % \begin{macro}{\constrainCaptionWidth}
1765 % Straightforward code to set both min- and max-allowed caption widths.
1766 % Only twist: if only one argument given, both min- and max-caption
1767 % widths set to that value.
1768 % \begin{macrocode}
1769 \newcommand\constrainCaptionWidth[2][-1in]{%
1770 \ifdim #1 < 0in%
1771 \setlength\@minCaptionBoxWidth{#2}%
1772 \setlength\@maxCaptionBoxWidth{#2}%
1773 \else
1774 \ifdim #1 < #2%
1775 \setlength\@minCaptionBoxWidth{#1}%
1776 \setlength\@maxCaptionBoxWidth{#2}%
1777 \else
1778 \setlength\@minCaptionBoxWidth{#2}%
1779 \setlength\@maxCaptionBoxWidth{#1}%
1780 \fi
1781 \fi
1782 }
1783
1784 % \end{macrocode}
1785 % \end{macro}
1786 %
1787 % \begin{macro}{\SaveCBox}
1788 % Low-level routine to save box data in an |sbox|. Also, calculates data
1789 % box width and associated caption box width.
1790 % \begin{macrocode}
1791 \newcommand\SaveCBox[2]{%
1792 \newsavebox{#1}%
1793 \sbox{#1}{#2}%
1794 \set@BoxWidths{#1}%
1795 }
1796
1797 % \end{macrocode}
1798 % \end{macro}
1799 %
1800 % \begin{macro}{\set@BoxWidths}
1801 % Call successive routines to define |\@DataBoxWidth| and
1802 % |\CaptionBoxWidth|.
1803 % \begin{macrocode}
1804 \newcommand\set@BoxWidths[1]{% of DataBox & CaptionBox (-2\DeadMargin)%
1805 \set@DataBoxWidth{#1}%
1806 \set@CaptionBoxWidth%
1807 }
1808
1809 % \end{macrocode}
1810 % \end{macro}
1811 %
1812 % \begin{macro}{\set@DataBoxWidth}
1813 % Calculate and set data-box width.
1814 % \begin{macrocode}
1815 \newcommand\set@DataBoxWidth[1]{%
1816 \setlength {\@DataBoxWidth}{\widthof{\usebox{#1}}}%
1817 }
1818
1819 % \end{macrocode}
1820 % \end{macro}
1821 %
1822 % \begin{macro}{\set@CaptionBoxWidth}
1823 % Calculate and set caption-box width, subject to constraints of dead
1824 % margin as well as caption-box min/max allowable widths.
1825 % \begin{macrocode}
1826 \newcommand\set@CaptionBoxWidth{%
1827 \setlength\CaptionBoxWidth\@DataBoxWidth%
1828 \addtolength{\CaptionBoxWidth}{-2\DeadMargin}%
1829 \ifdim \CaptionBoxWidth < \@minCaptionBoxWidth%
1830 \setlength\CaptionBoxWidth\@minCaptionBoxWidth%
1831 \fi
1832 \ifdim \CaptionBoxWidth > \@maxCaptionBoxWidth%
1833 \setlength\CaptionBoxWidth\@maxCaptionBoxWidth%
1834 \fi
1835 }
1836
1837 % \end{macrocode}
1838 % \end{macro}
1839 %
1840 % \clearpage
1841 % \begin{macro}{\set@BoxOffsets}
1842 % Calculate |\DataBoxSurplus| which holds the excess width of the data
1843 % box with respect to the associated caption box. Use it to set
1844 % |\@DataBoxOffset| and |\@CaptionBoxOffset|.
1845 % \begin{macrocode}
1846 \newcommand\set@BoxOffsets{%
1847 \setlength\@DataBoxSurplus{\@DataBoxWidth}%
1848 \addtolength\@DataBoxSurplus{-\CaptionBoxWidth}%
1849 \ifdim \@DataBoxSurplus > 0in%
1850 \setlength\@CaptionBoxOffset{0.5\@DataBoxSurplus}%
1851 \setlength\@DataBoxOffset{0in}%
1852 \else
1853 \setlength\@CaptionBoxOffset{0in}%
1854 \setlength\@DataBoxOffset{-0.5\@DataBoxSurplus}%
1855 \fi
1856 }
1857
1858 % \end{macrocode}
1859 % \end{macro}
1860 %
1861 % \begin{macro}{\offset@caption}
1862 % \begin{macro}{\nooffset@caption}
1863 % Define the code for placing offset- and nooffset-captions in the
1864 % caption box.
1865 % \begin{macrocode}
1866 \long\def\offset@caption#1#2{%
1867 \setlength\@captionIDwidth{\widthofpbox{\CaptionFontSize{#1.}}}%
1868 \addtolength\@captionIDwidth\captionGap%
1869 \setlength\@captionWidth\CaptionBoxWidth%
1870 \addtolength\@captionWidth{-\@captionIDwidth}%
1871 \CaptionFontSize{#1.}\hfill\parbox[t]{\@captionWidth}%
1872 {\CaptionJustification\CaptionFontSize{#2.}}%
1873 }
1874
1875 \long\def\nooffset@caption#1#2{%
1876 \CaptionJustification\CaptionFontSize #1.\rule{\captionGap}{0in}#2.%
1877 }
1878
1879 % \end{macrocode}
1880 % \end{macro}
1881 % \end{macro}
1882 %
1883 % \begin{macro}{\shortleft@caption}
1884 % \begin{macro}{\shortcenter@caption}
1885 % \begin{macro}{\shortright@caption}
1886 % Define the code for placing short-left, -center, and -right
1887 % captions in the caption box.
1888 % \begin{macrocode}
1889 \long\def\shortleft@caption#1#2{%
1890 \raggedright\CaptionFontSize #1.\rule{\captionGap}{0in}#2.%
1891 }
1892
1893 \long\def\shortcenter@caption#1#2{%
1894 \centering\CaptionFontSize #1.\rule{\captionGap}{0in}#2.%
1895 }
1896
1897 \long\def\shortright@caption#1#2{%
1898 \raggedleft\CaptionFontSize #1.\rule{\captionGap}{0in}#2.%
1899 }
1900
1901 % \end{macrocode}
1902 % \end{macro}
1903 % \end{macro}
1904 % \end{macro}
1905 %
1906 % \clearpage
1907 % \begin{macro}{\new@makecaption}
1908 % Define the new |@makecaption| code, which is defined in terms of
1909 % long- and short-caption definitions, that can be changed on the fly.
1910 % \begin{macrocode}
1911 \long\def\new@makecaption#1#2{%
1912 \vskip\abovecaptionskip%
1913 \sbox\@tempboxa{\CaptionFontSize #1.\rule{\captionGap}{0in}#2.}%
1914 \ifdim \wd\@tempboxa >\hsize%
1915 \long@caption{#1}{#2}%
1916 \else
1917 \short@caption{#1}{#2}%
1918 \fi
1919 \vskip\belowcaptionskip%
1920 }
1921
1922 % \end{macrocode}
1923 % \end{macro}
1924 %
1925 % \begin{macro}{\captionStyle}
1926 % \begin{macro}{\long@caption}
1927 % \begin{macro}{\short@caption}
1928 % Define the user routine |\captionStyle|, which allows the user to
1929 % redefine the captions styles for long and short captions,
1930 % respectively.
1931 % \begin{macrocode}
1932 \newcommand\captionStyle[2]{%
1933 \if o#1\let\long@caption\offset@caption\fi
1934 \if n#1\let\long@caption\nooffset@caption\fi
1935 \if l#2\let\short@caption\shortleft@caption\fi
1936 \if c#2\let\short@caption\shortcenter@caption\fi
1937 \if r#2\let\short@caption\shortright@caption\fi
1938 }
1939
1940 % \end{macrocode}
1941 % \end{macro}
1942 % \end{macro}
1943 % \end{macro}
1944 %
1945 % Define the default value for caption style, which is offset-style,
1946 % left-aligned.
1947 % \begin{macrocode}
1948 %% SET DEFAULT CAPTION STYLE: CAPTION ID OFFSET FOR LONG CAPTIONS,
1949 %% SHORT CAPTIONS LEFT ALIGNED
1950 \captionStyle{o}{l}
1951
1952 % \end{macrocode}
1953 %
1954 % \begin{macro}{\killtableofcontents}
1955 % Kills subsequent calls for the Table of Contents by renewing the
1956 % command as null.
1957 % \begin{macrocode}
1958 \newcommand\killtableofcontents{%
1959 \renewcommand\tableofcontents{}%
1960 }
1961
1962 % \end{macrocode}
1963 % \end{macro}
1964 %
1965 % \begin{macro}{lofInvocations}
1966 % \begin{macro}{lofprints}
1967 % \begin{macro}{\oldlistoffigures}
1968 % Set up for \textit{lof} handling, by preparing to count invocations of
1969 % \textit{lof}, the number of times the \textit{lof} is printed, and by
1970 % saving prevailing definition of |\listoffigures|.
1971 % \begin{macrocode}
1972 %%LIST OF FIGURES HANDLING:
1973 \newcounter{lofInvocations} \setcounter{lofInvocations}{0}
1974 \newcounter{lofPrints} \setcounter{lofPrints}{0}
1975 \let\oldlistoffigures\listoffigures
1976
1977 % \end{macrocode}
1978 % \end{macro}
1979 % \end{macro}
1980 % \end{macro}
1981 %
1982 % \begin{macro}{\killlistoffigures}
1983 % Kills subsequent calls for List of Figures by renewing the command (and
1984 % redefining the saved command) as null.
1985 % \begin{macrocode}
1986 \newcommand\killlistoffigures{%
1987 \def\oldlistoffigures {}%
1988 \renewcommand\listoffigures{}%
1989 }
1990
1991 % \end{macrocode}
1992 % \end{macro}
1993 %
1994 % \begin{macro}{\holdlistoffigures}
1995 % To put the \textit{lof} ``on hold,'' we merely redefine
1996 % |\listoffigures| to increment the |lofInvocations| counter.
1997 % \begin{macrocode}
1998 \newcommand\holdlistoffigures{%
1999 \renewcommand\listoffigures{\addtocounter{lofInvocations}{1}}%
2000 }
2001
2002 % \end{macrocode}
2003 % \end{macro}
2004 %
2005 % \begin{macro}{\clearlistoffigures}
2006 % This routine will clear (i.e., print) the List of Figures the number of
2007 % times it was invoked while ``on hold'' (most likely 0 or 1 time). It
2008 % does this by incrementing |lofPrints| until it reaches a value of
2009 % |lofInvocations|.
2010 % \begin{macrocode}
2011 \newcommand\clearlistoffigures{%
2012 \whiledo{\arabic{lofPrints} < \arabic{lofInvocations}}{%
2013 \addtocounter{lofPrints}{1}%
2014 \oldlistoffigures%
2015 }%
2016 }
2017
2018 % \end{macrocode}
2019 % \end{macro}
2020 %
2021 % \begin{macro}{lotInvocations}
2022 % \begin{macro}{lotPrints}
2023 % \begin{macro}{\oldlistoftables}
2024 % \begin{macro}{\killlistoftables}
2025 % \begin{macro}{\holdlistoftables}
2026 % \begin{macro}{\clearlistoftables}
2027 % List of Tables handling is wholly analogous to List of Figures handling
2028 % just described.
2029 % \begin{macrocode}
2030 %%LIST OF TABLES HANDLING:
2031 \newcounter{lotInvocations} \setcounter{lotInvocations}{0}
2032 \newcounter{lotPrints} \setcounter{lotPrints}{0}
2033 \let\oldlistoftables\listoftables
2034
2035 \newcommand\killlistoftables{%
2036 \def\oldlistoftables {}%
2037 \renewcommand\listoftables{}%
2038 }
2039
2040 \newcommand\holdlistoftables{%
2041 \renewcommand\listoftables{\addtocounter{lotInvocations}{1}}%
2042 }
2043
2044 \newcommand\clearlistoftables{%
2045 \whiledo{\arabic{lotPrints} < \arabic{lotInvocations}}{%
2046 \addtocounter{lotPrints}{1}%
2047 \oldlistoftables%
2048 }%
2049 }
2050
2051 % \end{macrocode}
2052 % \end{macro}
2053 % \end{macro}
2054 % \end{macro}
2055 % \end{macro}
2056 % \end{macro}
2057 % \end{macro}
2058 %
2059 % \begin{macro}{\hyperactive}
2060 % Prepare corrections if the \textsf{hyperref} package is being used.
2061 % Set default caption treatment in \textsf{boxhandler} to |\caption|.
2062 % Define alternate caption treatment as |\hyper@cap|. If |\hyperactive|
2063 % is invoked, redefine caption treatment as |\hyper@cap|. The optional
2064 % argument to |\hyperactive| is the downward-shift to be applied to the
2065 % caption, relative to the caption label.
2066 % \begin{macrocode}
2067 %% \hyperactive PROVIDES A CORRECTIVE CAPTION SHIFT WHEN USING THE
2068 %% hyperref PACKAGE; OPTIONAL ARGUMENT IS SHIFT LENGTH
2069 \let\bx@caption\caption
2070 \newlength\hyper@shift
2071 \newcommand\hyper@cap[1]{\caption{\vspace*{\hyper@shift}#1}}%
2072 \newcommand\hyperactive[1][-1.55ex]{%
2073 \setlength\hyper@shift{#1}\let\bx@caption\hyper@cap}
2074
2075 % \end{macrocode}
2076 % \end{macro}
2077 %
2078 % \begin{macro}{arltable}
2079 % \begin{macro}{arlfigure}
2080 % To retain backward compatibility to the simpler predecessor of the
2081 % \boxhandler package, the vestigial commands |\arltable|
2082 % and |\arlfigure| are provided. Their definitions are directly
2083 % linked to |\bxtable| and |\bxfigure|.
2084 % \begin{macrocode}
2085 %% TO RETAIN BACKWARD COMPATIBILITY WITH THE PREDECESSOR TO boxhandler,
2086 %% THE FOLLOWING ASSIGNMENTS ARE MADE.
2087 \let\arltable\bxtable
2088 \let\arlfigure\bxfigure
2089
2090 % \end{macrocode}
2091 % \end{macro}
2092 % \end{macro}
2093 % We are done now.
2094 % \begin{macrocode}
2095 %</package>
2096 % \end{macrocode}
2097 %
2098 % \Finale
2099 \endinput
2100 %
2101 %End of file `boxhandler.dtx'.