From 5c86817e60f4e9a307477a8521ddcc4ab7acd578 Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Mon, 14 Aug 2006 16:32:27 +0000 Subject: boxhandler update (31jul06) git-svn-id: svn://tug.org/texlive/trunk@1954 c570f23f-e606-0410-a88d-b1316a301751 --- .../source/latex/boxhandler/boxhandler.dtx | 273 +++++++++++++++++---- 1 file changed, 220 insertions(+), 53 deletions(-) (limited to 'Master/texmf-dist/source/latex') diff --git a/Master/texmf-dist/source/latex/boxhandler/boxhandler.dtx b/Master/texmf-dist/source/latex/boxhandler/boxhandler.dtx index 0bdf9b34289..c9f692b48cf 100644 --- a/Master/texmf-dist/source/latex/boxhandler/boxhandler.dtx +++ b/Master/texmf-dist/source/latex/boxhandler/boxhandler.dtx @@ -1,3 +1,4 @@ +% \CheckSum{726} % \iffalse %% %% boxhandler.sty @@ -9,12 +10,22 @@ %% arlcaptions.sty. %% %\ProvidesPackage{boxhandler} -%[2006/04/24 v1.03 +%[2006/07/29 v1.10 % Flexible Captioning Styles and Deferred Box/List Printing] %\NeedsTeXFormat{LaTeX2e} %<*driver> -% V1.02 Corrected minor grammar issue in documentation. -% V1.03 Changed some tabs into spaces that were screwing up appearance +% V1.02-Corrected minor grammar issue in documentation. +% V1.03-Changed some tabs into spaces that were screwing up appearance +% but not function of sty file. +% V1.04-Reset one of the parameters left set in Fig.6, which +% inadvertantly affected appearance of Tables 3 and 4. +% -Minor grammar correction. +% -Added \CharacterTable & \CheckSum features to dtx file. +% -Added Acknowledgments (belatedly... mea culpa) +% V1.10-added features \nextTable and \nextFigure for clearing +% a single table or figure at a time. +% -explained in documentation how to handle captions with +% citations in boxhandler environment. \documentclass{ltxdoc} \usepackage{boxhandler} \DisableCrossrefs @@ -26,6 +37,7 @@ \def\bs{\char'134}% BACKSLASH "\" WHEN INVOKED IN \tt FONT \let\iq\itshape% SHORTHAND FOR ITALIC FONT \let\uq\upshape% SHORTHAND FOR UPSHAPE FONT +\newcommand\boxhandler{\textsf{boxhandler}~} \GetFileInfo{boxhandler.sty} \begin{document} \title{The \textsf{boxhandler} Package\\ @@ -41,22 +53,27 @@ % \fi % \parskip 1ex % \begin{abstract} -% This package was developed as a tool to manage the handling of \LaTeX{} +% This package facilitates the handling of \LaTeX{} % tables and figures, especially for conditionally compiled documents. % With these tools, not only can one conveniently define table and figure % captions with a wide variety of stylistic appearances, but one can -% create a single \LaTeX{} document that can, with a single line change +% create a single \LaTeX{} document that can, with a single-line change % in the source code, produce an output that has vastly different layout -% from the baseline configuration, not only in terms of caption style, -% but also in terms of the locations where figures, tables and lists -% appear (or not) in the document. +% from the baseline configuration, both in terms of caption style, +% and in terms of the locations where figures, tables and lists +% appear (or not) in the document. The deferral routines also allow +% one to keep all figure and table data in a separate file, which +% nonetheless produces a document with figures and tables appearing +% in the proper location in the document. +% % \end{abstract} % +% \vspace{-.55em} % \tableofcontents\rule[.2em]{4.5in}{.3mm}\vspace{-1.5em} % % \section {Introduction} % -% The commands described in the |boxhandler| style accomplish a number of +% The commands described in the \boxhandler style accomplish a number of % useful functions. Even without the use of a conditionally-compiled % document: % \begin{enumerate} @@ -122,12 +139,12 @@ % have their references automatically available to the List of Tables and % List of Figures, respectively. % -% One of the differences between the |boxhandler| style and \LaTeX{}'s -% default captioning environments is the default caption width. Whereas +% One of the differences between the \boxhandler style and \LaTeX{}'s +% default captioning environment is the default caption width. Whereas % \LaTeX{} defaults to a full margin-to-margin caption width, -% |boxhandler| defaults to a caption width equal to and aligned with the +% \boxhandler defaults to a caption width equal to and aligned with the % width of the box being captioned. However, this caption-width default -% within |boxhandler| can be changed to any arbitrary value, including +% within \boxhandler can be changed to any arbitrary value, including % full-width, if desired. The caption width, through the use of the % ``dead margin,'' can also be conveniently set to a fixed offset from % the table or figure width. For example, all table captions could be @@ -354,10 +371,13 @@ % (|flushright|), |abovecaptionskipterm| (3), and a value for % |\FigureDeadMargin| of 1em. % -% \captionStyle{o}{l}\setlength\captionGap{2.5ex} -% \def\CaptionJustification{\raggedright}\let\CaptionFontSize\scriptsize +% \captionStyle{o}{l} +% \setlength\captionGap{2.5ex} +% \def\CaptionJustification{\raggedright} +% \let\CaptionFontSize\scriptsize % \setcounter{abovecaptionskipterm}{3} -% \def\LRFigurePlacement{flushright}\setlength\FigureDeadMargin{1em} +% \def\LRFigurePlacement{flushright} +% \setlength\FigureDeadMargin{1em} % \bxfigure[t]{Here is one example of a caption that has been set for % a ragged right justification. Justification, or ``flushing,'' % is different than caption alignment, which is specified @@ -375,16 +395,19 @@ % \hfill \hfill $\downarrow$~~~} % } % } -% \def\CaptionJustification{}\setlength\captionGap{2.5ex} -% \let\CaptionFontSize\small \setcounter{abovecaptionskipterm}{10} -% \def\LRFigurePlacement{center}\setlength\FigureDeadMargin{0em} +% \setlength\captionGap{1ex} +% \def\CaptionJustification{} +% \let\CaptionFontSize\small +% \setcounter{abovecaptionskipterm}{10} +% \def\LRFigurePlacement{center} +% \setlength\FigureDeadMargin{0em} % % \section{Box and List Deferral/Preemption} % % \subsection{Description of Problem} % % For those using conditional compilation to create various versions of -% the same basic document, the |boxhandler| package can provide great +% the same basic document, the \boxhandler package can provide great % utility. The package has been designed to permit the deferral and % preemption of certain aspects of the document, such as figures, tables % and lists. With such a capability, one has the capacity to not only @@ -440,9 +463,15 @@ % (\textit{toc}), and perhaps not a List of Tables (\textit{lot}) either. % % Arranging for such options to unfold from a single input source file is -% cumbersome without a special treatment. The |boxhandler| style +% cumbersome without a special treatment. The \boxhandler style % provides routines to expedite and ease this cumbersome process. % +% The \boxhandler style also conveniently allows for another useful +% scenario, in which figure and table data may be kept in a separate +% file from the document text, but nonetheless be made to print out with +% figures and tables appearing in the proper location in the text. The +% |\nextTable| and |\nextFigure| commands aid in this approach. +% % \subsection{Deferral and Preemption Commands} % % For figure and table deferral, and/or list deferral/preemption, the @@ -460,6 +489,8 @@ % |\holdlistoffigures|\\ % |\clearlistoftables|\\ % |\clearlistoffigures|\\ +% |\nextTable[|\iq loc\uq|]|\\ +% |\nextFigure[|\iq loc\uq|]|\\ % \end{verse} % % \DescribeMacro{\holdTables} @@ -471,7 +502,7 @@ % for example. % % While the calculated width of the caption is saved at the time of call -% to |\bxtable| and |\bxfigure| based upon the |boxtable| parameters at +% to |\bxtable| and |\bxfigure| based upon the \boxhandler parameters at % the time of the |\bx...| call, the caption format (i.e., [no]offset, % center/left alignment, caption justification) is not set until the % figure/table is later printed as part of a |\clear...| command (the @@ -479,6 +510,27 @@ % course of the document, thus alleviating the need to store this data % for each figure and table). % +% The one potential pitfall with the use of these commands +% is the situation when a citation is made within +% the caption of a deferred table or figure. In this case, the citation +% is numbered based on when the table or figure is finally displayed, +% not when it was created. +% Thus, if |\holdTables| and/or |\holdFigures| is used to prevent the +% printing of tables and/or figures until the end of the document, +% then any unique citation defined in a table or figure +% caption will receive a higher citation number than even a citation +% appearing in the last line of document text. +% +% There is, however, an easy solution to this predicament. That is, +% when a figure or table is employed which contains a citation, the +% main text of the document should invoke |\nocite{|\iq key\_list\uq|}| +% to the same reference. This occurance of |\nocite| should be +% placed in the main document (\textit{i.e.}, outside of |bxtable| +% or |bxfigure|) at the point where the table or figure is actually +% being invoked. In this manner, the citation gets added to the +% \textit{.aux} file at the proper spot, regardless of when the table +% or figure is actually printed out. +% % \DescribeMacro{\clearTables} % \DescribeMacro{\clearFigures} % |\clearTables| and |\clearFigures| directs that any tables or figures @@ -595,13 +647,56 @@ % \textbf{With the change of a single line of code, a vastly different % document layout has been achieved!} % +% \DescribeMacro{\nextTable} +% \DescribeMacro{\nextFigure} +% The deferral commands described to this point have been cast in terms +% of tools to aid in printing out multiple vastly different versions +% of a document from a single source file. With \boxhandler v1.10, the +% commands |\nextTable| and |\nextFigure| have been introduced. These +% commands, while somewhat similar in function to |\clearTables| and +% |\clearFigures|, are useful in a completely different regard. In the +% case of |\nextTable| and |\nextFigure|, only a single table or figure +% is cleared. Unlike |\clearTables| and |\clearFigures|, the table or +% figure is not printed on a page by itself, but inline the document. +% The optional argument specifies the location on the page (|h|, |t|, +% |b| or |p|) where the +% table or figure should appear, consistent with \LaTeX{} convention. +% +% The unique utility of the |\nextTable| and |\nextFigure| commands +% is in allowing one to define all the document's figures and tables +% "up front," at the beginning of the document, perhaps even in a +% seperate file that is |\input| into the document. Then, when a table +% or figure is referred to in the text, all that need be included in +% the main document is an occurance of |\nextTable| or |\nextFigure|. +% +% In this manner, all the tables and figures can be printed out in the +% document at their appropriate location, while logically, the document +% can be organized during preparation to keep the figure and table +% matter separate from the text matter of the document. +% +% If one wishes to incorporate conditional compiliation +% (as in Table~\ref{tbl:bxcode}) while simultaneously keeping table +% and figure definition in a separate file |\input| at the beginning +% of the document, this can be done, too. The tables and figures would +% be added after the |\begin{document}| command and invocation would +% be accomplished by way of |\nextTable| and |\nextFigure| as described +% here. However, in the |\MANUSCRIPT| preamble (using the nomenclature +% of Table~\ref{tbl:bxcode}), |\nextTable| and |\nextFigure| would be +% nullified as:\\ +% | \renewcommand\nextTable[1][]{}|\\ and\\ +% | \renewcommand\nextFigure[1][]{}|.\\ +% In this manner, for the |\MANUSCRIPT| report type, tables and figures +% would be made to not appear until the final invocations of +% |\clearTables| and |\clearFigures|. +% +% % \section {Advanced Use (DANGER!)} % % Additionally, there are certain lower level, yet accessible, counters, % macros and lengths, which are intended for advanced use only. It is % possible to get into difficulty if not thinking through their use % thoroughly. Pitfalls will be laid out, where known. These accessible -% hooks into the inner workings of the |boxhandler| package include: +% hooks into the inner workings of the \boxhandler package include: % % \begin{verse} % \underline{Lengths:}\\ @@ -657,14 +752,15 @@ % boxed object without printing it, regardless of whether a |\hold...| % command has been issued. The saved information will consist of three % pointers necessary to recreate the table or figure. These pointers -% will be named according to |boxhandler|'s internal naming convention. +% will be named according to \textsf{boxhandler}'s internal naming +% convention. % % At this point, it is worth noting the naming convention of the pointers -% used by |boxhandler| to store the variables for figures and tables. +% used by \boxhandler to store the variables for figures and tables. % The saved information resulting from a |\StoreTable| or |\StoreFigure| % command will consist of a pointer to a saved box, a pointer to the % caption text, and a pointer to the calculated width of the caption box -% (based on the state of the |boxhandler| parameters at the time of the +% (based on the state of the \boxhandler parameters at the time of the % function call). % % The counters |TableIndex| and |FigureIndex| are used to create a unique @@ -681,13 +777,13 @@ % correspond to the actual Table or Figure number (i.e., `4') appearing % in the caption ID label. However, it is wise to remember, % \begin{enumerate} -% \item when creating tables or figures outside of the |boxhandler| style; +% \item when creating tables or figures outside of the \boxhandler style; % \item when bypassing the |\Store...| commands and going straight to the % lower level |\SaveCBox| command; or % \item when using the |\Recite...| commands to print multiple occurances % of a box; % \end{enumerate} -% that the internal numbering of |boxhandler| tables and figures will +% that the internal numbering of \boxhandler tables and figures will % likely be out of syncronization with the Table and Figure counters. % % \DescribeMacro{\SaveCBox} @@ -706,7 +802,7 @@ % \DescribeMacro{\CaptionBoxWidth} % In addition to saving the boxed object in the specified command bin, % the width of the associated caption is calculated, based upon the -% prevailing |boxhandler| parameters at the time of call. One such +% prevailing \boxhandler parameters at the time of call. One such % parameter that is used to calculate the caption width, is the dead % margin. |\SaveCBox|, being a low-level routine, is used for both % tables and figures. As such, the appropriate variable to set, in order @@ -746,13 +842,13 @@ % |\theClearedTable| and |\theClearedFigure| macros. These are the % routines which are repeatedly called by |\clearTables| and % |\clearFigures|, respectively, to print out all tables and figures -% which have been ``on hold.'' The manner in which |boxhandler| clears +% which have been ``on hold.'' The manner in which \boxhandler clears % them is one per page, vertically centered. It is easy to envision % applications in which the method of clearing would take on a different % appearance than this. To change the appearance by which tables and/or % figures are cleared, these commands need to be redefined by the user by % way of a |\renewcommand|. For reference, the |\theClearedTable| -% command is defined by |boxhandler| as: +% command is defined by \boxhandler as: % %| |\\ %|\newcommand\theClearedTable[4][h]{|\\ @@ -831,24 +927,25 @@ %%| |\\ %%|\ReciteFigure[h]{\figcapii}{\figii}{\figcapwdthii} |\\ %% +% \vspace{-1em} % \section {Vestigials} % % \DescribeMacro{\arltable} % \DescribeMacro{\arlfigure} % In order to retain backward compatibility with the predecessor to the -% |boxhandler| package, the vestigial commands |\arltable| and +% \boxhandler package, the vestigial commands |\arltable| and % |\arlfigure| are defined in this package, and are equivalent to % |\bxtable| and |\bxfigure|, respectively. % -% As an historical note, the genesis of the |boxhandler| package was a +% As an historical note, the genesis of the \boxhandler package was a % requirement to comply with my organization's caption style (``offset'' % style, ``left'' aligned) specified for its technical reports. Various -% kludges were out there to handle it, requiring a fair amount of -% case-specific hand-holding and babysitting, depending on the specifics -% of the figure/table box and the caption. |boxhandler| was intended to -% simplify and generalize the approach. +% piecemeal approaches were out there to handle it, requiring +% case-specific decisions on the part of the author, depending on the +% specifics of the figure/table box and the caption. \boxhandler was +% intended to simplify and generalize the approach. % -% The figure/table deferral features of |boxhandler| were borne of my own +% The figure/table deferral features of \boxhandler were borne of my own % laziness. I just didn't relish keeping two different versions of the % same document up to date... one for my organization, and the other as a % manuscript for possible journal submission. The |\bx...| commands @@ -856,17 +953,43 @@ % clearing of boxes than did any attempt to muck with the underlying % |Figure| and |Table| environments of \LaTeX{}. % -% \section {Salutations} -% That's it for a description of |boxhandler|! I hope the package -% provides you some utility. The only thing left is the code listing -% itself. +% \section {Acknowledgments/Salutations} +% That's it for a description of \textsf{boxhandler}! I would like to thank +% a number of colleagues for their consultive assistance. Several were +% instrumental in getting me over early bumps in my \LaTeX{} learning +% curve, including Mike Scheidler, Stephen Schraml, Brian Krzewinski, +% and Paul Tanenbaum, all of the USARL. I am particularly grateful +% to Fred Brundick (also of ARL) for sharing his extensive knowledge +% of \LaTeX{} with me. He clued me in to the sticky quirks of offset +% captions, and shared his methods for dealing with the different cases. +% He also pointed me in the right direction for the systematic saving +% of \LaTeX{} box objects, which contributed to the section of this +% package dealing with object deferral. +% +% I hope this package provides you some utility. The only thing left +% is the code listing itself. +%% \CharacterTable +%% {Upper-case \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z +%% Lower-case \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z +%% Digits \0\1\2\3\4\5\6\7\8\9 +%% Exclamation \! Double quote \" Hash (number) \# +%% Dollar \$ Percent \% Ampersand \& +%% Acute accent \' Left paren \( Right paren \) +%% Asterisk \* Plus \+ Comma \, +%% Minus \- Point \. Solidus \/ +%% Colon \: Semicolon \; Less than \< +%% Equals \= Greater than \> Question mark \? +%% Commercial at \@ Left bracket \[ Backslash \\ +%% Right bracket \] Circumflex \^ Underscore \_ +%% Grave accent \` Left brace \{ Vertical bar \| +%% Right brace \} Tilde \~} % \StopEventually{} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % \vspace{-0.8em} % \begin{macro}{boxhandler.sty} % \section{Code Listing} % I'll try to lay out herein -% the workings of the |boxhandler| style package. I apologize if +% the workings of the \boxhandler style package. I apologize if % the code fails in some way to conform to \LaTeX{} programming % conventions. I am but an enthusiastic novice. % \begin{macrocode} @@ -875,8 +998,8 @@ % \end{macro} % % \begin{macro}{pbox} -% This package makes use of the |pbox| style package to aid in the -% boxing of captions. +% This package makes use of the \textsf{pbox} style package to aid +% in the boxing of captions. % \begin{macrocode} \usepackage{pbox} % \end{macrocode} @@ -959,7 +1082,7 @@ % \end{macrocode} % \end{macro} % \end{macro} -% +% % \begin{macro}{\@minCaptionBoxWidth} % \begin{macro}{\@minCaptionBoxWidthDefault} % \begin{macro}{\@maxCaptionBoxWidth} @@ -1054,7 +1177,6 @@ % \end{macrocode} % \end{macro} % -%\vspace{2em} % \begin{macro}{\DeadMargin} % \begin{macro}{\CaptionBoxWidth} % \begin{macro}{\@DataBoxWidth} @@ -1201,6 +1323,31 @@ % \end{macrocode} % \end{macro} % +% \begin{macro}{\nextTable} +% This routine will clear a single table, if there are any that have +% not yet been printed as a result of a previously invoked \holdTables +% command. It assumes FIFO logic. The optional argument is the location +% on the page where the table is to be printed, in accordance with +% standard \LaTeX{} logic. If there are no uncleared tables left to +% format, then the command has no effect. +% \begin{macrocode} +\newcommand\nextTable[1][h]{ + \ifnum \arabic{TableClearedIndex} < \arabic{TableIndex}{ + \addtocounter{TableClearedIndex}{1} +%% \TableBoxLabel : tbli, tblii, tbliii, tbliv, etc. +%% \TableCaptionLabel : tblcapi, tblcapii, tblcapiii, tblcapiv, etc. +%% \TblCaptionWidthLabel: tblcapwdthi, tblcapwdthii, tblcapwdthiii,etc. + \def\TableBoxLabel{tbl\roman{TableClearedIndex}} + \def\TableCaptionLabel{tblcap\roman{TableClearedIndex}} + \def\TblCaptionWidthLabel{tblcapwdth\roman{TableClearedIndex}} + \ReciteTable[#1]{\csname\TableCaptionLabel\endcsname} + {\csname\TableBoxLabel\endcsname} + {\csname\TblCaptionWidthLabel\endcsname} + }\fi +} + +% \end{macrocode} +% \end{macro} % \begin{macro}{\clearTables} % This routine will clear all stored tables that have not yet been % printed. It assumes a FIFO logic. It starts by clearing the page and @@ -1323,6 +1470,26 @@ % \end{macrocode} % \end{macro} % +% \begin{macro}{\nextFigure} +% This routine is analogous to |\nextTable| in every way. +% \begin{macrocode} +\newcommand\nextFigure[1][h]{ + \ifnum \arabic{FigureClearedIndex} < \arabic{FigureIndex}{ + \addtocounter{FigureClearedIndex}{1} +%% \FigureBoxLabel: : figi, figii, figiii, figiv, etc. +%% \FigureCaptionLabel : figcapi, figcapii, figcapiii, figcapiv, etc. +%% \FigCaptionWidthLabel: figcapwdthi, figcapwdthii, figcapwdthiii,etc. + \def\FigureBoxLabel{fig\roman{FigureClearedIndex}} + \def\FigureCaptionLabel{figcap\roman{FigureClearedIndex}} + \def\FigCaptionWidthLabel{figcapwdth\roman{FigureClearedIndex}} + \ReciteFigure[#1]{\csname\FigureCaptionLabel\endcsname} + {\csname\FigureBoxLabel\endcsname} + {\csname\FigCaptionWidthLabel\endcsname} + }\fi +} + +% \end{macrocode} +% \end{macro} % \begin{macro}{\clearFigures} % This routine is analogous to |\clearTables| in every way. % \begin{macrocode} @@ -1423,7 +1590,6 @@ % \end{macrocode} % \end{macro} % -%\vspace{1em} % \begin{macro}{\SaveCBox} % Low-level routine to save box data in an |sbox|. Also, calculates data % box width and associated caption box width. @@ -1477,6 +1643,7 @@ % \end{macrocode} % \end{macro} % +% \clearpage % \begin{macro}{\set@BoxOffsets} % Calculate |\DataBoxSurplus| which holds the excess width of the data % box with respect to the associated caption box. Use it to set @@ -1542,6 +1709,7 @@ % \end{macro} % \end{macro} % +% \clearpage % \begin{macro}{\new@makecaption} % Define the new |@makecaption| code, which is defined in terms of % long- and short-caption definitions, that can be changed on the fly. @@ -1629,7 +1797,6 @@ % \end{macrocode} % \end{macro} % -%\vspace{2em} % \begin{macro}{\holdlistoffigures} % To put the \textit{lof} ``on hold,'' we merely redefine % |\listoffigures| to increment the |lofInvocations| counter. @@ -1698,11 +1865,11 @@ % \begin{macro}{arltable} % \begin{macro}{arlfigure} % To retain backward compatibility to the simpler predecessor of the -% |boxtable| package, the vestigial commands |\arltable| and |\arlfigure| -% are provided. Their definitions are directly linked to |\bxtable| and -% |\bxfigure|. +% \boxhandler package, the vestigial commands |\arltable| +% and |\arlfigure| are provided. Their definitions are directly +% linked to |\bxtable| and |\bxfigure|. % \begin{macrocode} -%% TO RETAIN BACKWARD COMPATIBILITY WITH THE PREDECESSOR TO boxtable, +%% TO RETAIN BACKWARD COMPATIBILITY WITH THE PREDECESSOR TO boxhandler, %% THE FOLLOWING ASSIGNMENTS ARE MADE. \let\arltable\bxtable \let\arlfigure\bxfigure -- cgit v1.2.3