boxhandler (19oct12)

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

1 files changed, 55 insertions, 17 deletions

diff --git a/Master/texmf-dist/source/latex/boxhandler/boxhandler.dtx b/Master/texmf-dist/source/latex/boxhandler/boxhandler.dtx
index 48aa1324028..e25bcc3cf79 100644
--- a/Master/texmf-dist/source/latex/boxhandler/boxhandler.dtx
+++ b/Master/texmf-dist/source/latex/boxhandler/boxhandler.dtx
@@ -1,4 +1,4 @@
-% \CheckSum{930}
+% \CheckSum{948}
 % \iffalse
 %%
 %% boxhandler.sty
@@ -10,7 +10,7 @@
 %% arlcaptions.sty.
 %%
 %<package>\ProvidesPackage{boxhandler}
-%<package>[2011/02/16 v1.22
+%<package>[2012/10/18 v1.30
 %<package> Tools for Optimizing Captions, Presentation, and
 %<package> Placement of Tables and Figures]
 %<package>\NeedsTeXFormat{LaTeX2e}
@@ -34,6 +34,8 @@
 % V1.20-added support for figure and table wrappers
 % V1.21-modified documentation slightly
 % V1.22-changed [h] default specifiers to [ht] to avoid warnings
+% V1.30-Corrected errors in manual (\theClearedTable example)
+%      -Added support for use with hyperref package
 \documentclass{ltxdoc}
 \usepackage{boxhandler}
 \DisableCrossrefs
@@ -51,7 +53,7 @@
    \title{The \textsf{boxhandler} Package\\
          \rule{0em}{0.7em}\small\fileinfo}
    \author{Steven B. Segletes\\
-           steven@arl.army.mil}
+           steven.b.segletes.civ@mail.mil}
    \date{\filedate\\
          \fileversion}
    \maketitle
@@ -121,12 +123,14 @@
 % |\limitCaptionWidth[|\iq len\uq|]|\\
 % |\constrainCaptionWidth[|\iq len\uq|]{|\iq len\uq|}|\\
 % |\captionStyle{|\iq offset type\uq|}{|\iq alignment type\uq|}|\\
+% |\hyperactive[|\iq len\uq|]|\\
 % \end{verse}
 % \DescribeMacro{\bxtable}
 % \DescribeMacro{\bxfigure}
 % The routines |\bxtable| and |\bxfigure| will actually produce the
 % complete table or figure, including caption.  In these two routines,
-% \iq loc \uq is an optional argument.  It can take on a value of: |h|,
+% \iq loc \uq is an optional argument.  It can take on a value of:
+% |ht|, |hb|,
 % |t|, |b|, or |p|.  This parameter refers to the same location argument
 % that goes with the \LaTeX{} float environments, to help \LaTeX{}
 % determine the placement of the item on your page. |h| is `here', |t| is
@@ -275,6 +279,19 @@
 % justification can, however, be altered, as described later by the
 % |\CaptionJustification| parameter.
 %
+% \DescribeMacro{\hyperactive}
+% |\hyperactive| was added in v1.22 to provide compatibility with the
+% \textsf{hyperref} package, which is known to redefine many \LaTeX{} 
+% variables, including |\caption|.  It was found, when the
+% \textsf{hyperref} package was active, offset captions experienced a 
+% vertical gap between the caption label and the caption text.  The
+% command |\hyperactive| should be invoked only if the \textsf{hyperref}
+% package is being utilized. The optional argument to this command is
+% the length that boxhandler will shift the caption text downward, so
+% as to achieve alignment with the caption label.  The default value is
+% -1.55ex, which was the required corrective shift observed for some
+% applications, when the \textsf{hyperref} package was active.
+%
 % \subsection {Additional User Parameters}
 %
 % In addition to the above commands, there are a variety of
@@ -367,11 +384,6 @@
 % Use |\def\CaptionJustification{}| to reset subsequent captions for full
 % flushing.%
 %
-% Figure~\ref{fig:ragged} is provided to demonstrate some of these
-% features including:  caption justification (|\raggedright|), caption gap
-% (2.5~ex), caption font size (|\scriptsize|), LR figure placement 
-% (|flushright|), |abovecaptionskipterm| (3), and a value for
-% |\FigureDeadMargin| of 1em.
 % \clearpage%
 % \captionStyle{o}{l}%
 % \setlength\captionGap{2.5ex}%
@@ -413,6 +425,12 @@
 %   \put(-31,59){\makebox(20,0)[l]%
 %          {\small (1em on left; 1em on right)}}%
 % \end{picture}%
+% Figure~\ref{fig:ragged} is provided to demonstrate some of these
+% features including:  caption justification (|\raggedright|), caption gap
+% (2.5~ex), caption font size (|\scriptsize|), LR figure placement 
+% (|flushright|), |abovecaptionskipterm| (3), and a value for
+% |\FigureDeadMargin| of 1em.
+%
 % \section{Figure and Table ``Wrappers''}
 %
 % With \boxhandler v1.20, figure and table wrappers have been added.
@@ -443,8 +461,9 @@
 % default, the |\Wrapper{}| command should be used within the second
 % mandatory argument of the call to |\bxtable| or |\bxfigure|.  That is
 % to say, the call to |\Wrapper| should be included within the argument
-% where the actual figure or table contents are defined. Here is an
-% example
+% where the actual figure or table contents are defined. 
+%
+% \clearpage Here is an example:
 %
 % \begin{verse}
 % |\bxfigure[ht]{Widget details for the XMC-7936}%|\\
@@ -718,7 +737,7 @@
 % 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|,
+% The optional argument specifies the location on the page (|ht|, |hb|, |t|,
 % |b| or |p|) where the
 % table or figure should appear, consistent with \LaTeX{} convention.
 %
@@ -891,7 +910,7 @@
 % Reciting stored tables or figures is accomplished by way of
 % |\ReciteTable| and |\ReciteFigure|.  As the [optional] first of their
 % four arguments, they take the location directive for placement on the
-% page (e.g., |h|, |t|, |b|, or |p|).  Both the caption and the caption
+% page (e.g., |ht|, |hb|, |t|, |b|, or |p|).  Both the caption and the caption
 % width arguments may be specified directly, or indirectly by way of a
 % stored string and length variable, respectively.  The command argument
 % to these macros must be the bin for the saved box object that
@@ -920,7 +939,7 @@
 % command is defined by \boxhandler as:
 %
 %| |\\
-%|\newcommand\theClearedTable[4][ht]{|\\
+%|\newcommand\theClearedTable[6][ht]{|\\
 %|  \vspace*{\fill}|\\
 %|  \ReciteTable[#1]{#2}{#3}{#4}{#5}{#6}|\\
 %|  \vspace*{\fill}|\\
@@ -936,7 +955,7 @@
 %
 %| |\\
 %|\newcounter{toggle} \setcounter{toggle}{0}|\\
-%|\renewcommand\theClearedTable[4][ht]{|\\
+%|\renewcommand\theClearedTable[6][ht]{|\\
 %|  \addtocounter{toggle}{1}|\\
 %|  \ifnum \arabic{toggle} = 2 \setcounter{toggle}{0} \fi|\\
 %|  \ifnum \arabic{toggle} = 1|\\
@@ -1440,7 +1459,7 @@
           \rule{\@DataBoxOffset}{0in}\\%
         \fi
         \rule{\@CaptionBoxOffset}{0em}%
-        \parbox{\CaptionBoxWidth}{\caption{#2}}%
+        \parbox{\CaptionBoxWidth}{\bx@caption{#2}}%
         \rule{\@CaptionBoxOffset}{0em}%
         \par%
         \rule{\@DataBoxOffset}{0in}% 
@@ -1620,7 +1639,7 @@
         \rule{\@DataBoxOffset}{0in}%
         \par%
         \rule{\@CaptionBoxOffset}{0em}%
-        \parbox{\CaptionBoxWidth}{\caption{#2}}%
+        \parbox{\CaptionBoxWidth}{\bx@caption{#2}}%
         \rule{\@CaptionBoxOffset}{0em}%
         \if T#6%
           \rule{\@DataBoxOffset}{0in}\\%
@@ -2037,6 +2056,25 @@
 %   \end{macro}
 % \end{macro}
 %
+% \begin{macro}{\hyperactive}
+% Prepare corrections if the \textsf{hyperref} package is being used.
+% Set default caption treatment in \textsf{boxhandler} to |\caption|.
+% Define alternate caption treatment as |\hyper@cap|.  If |\hyperactive|
+% is invoked, redefine caption treatment as |\hyper@cap|.  The optional
+% argument to |\hyperactive| is the downward-shift to be applied to the
+% caption, relative to the caption label.
+%    \begin{macrocode}
+%% \hyperactive PROVIDES A CORRECTIVE CAPTION SHIFT WHEN USING THE
+%% hyperref PACKAGE; OPTIONAL ARGUMENT IS SHIFT LENGTH
+\let\bx@caption\caption
+\newlength\hyper@shift
+\newcommand\hyper@cap[1]{\caption{\vspace*{\hyper@shift}#1}}%
+\newcommand\hyperactive[1][-1.55ex]{%
+  \setlength\hyper@shift{#1}\let\bx@caption\hyper@cap}
+
+%    \end{macrocode}
+% \end{macro}
+%
 % \begin{macro}{arltable}
 %   \begin{macro}{arlfigure}
 % To retain backward compatibility to the simpler predecessor of the