summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/boxhandler/boxhandler.dtx
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2012-10-19 22:06:16 +0000
committerKarl Berry <karl@freefriends.org>2012-10-19 22:06:16 +0000
commitcdbc45c8e13872e3fd8515046f37efcc36f14919 (patch)
tree72943ff3b92d318860048a4fbd223e03ded4ed02 /Master/texmf-dist/source/latex/boxhandler/boxhandler.dtx
parent2daba66c685de3f2d9b7abd7e526c627aa1e9379 (diff)
boxhandler (19oct12)
git-svn-id: svn://tug.org/texlive/trunk@28031 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/latex/boxhandler/boxhandler.dtx')
-rw-r--r--Master/texmf-dist/source/latex/boxhandler/boxhandler.dtx72
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