summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/oberdiek/hypcap.dtx
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2006-01-11 23:55:42 +0000
committerKarl Berry <karl@freefriends.org>2006-01-11 23:55:42 +0000
commitc93827540c8875c270e3b91434ce97ce5d0d80a9 (patch)
treecfc0454dc2124a98873d3a5d6f631221ce52ea14 /Master/texmf-dist/source/latex/oberdiek/hypcap.dtx
parent3c80959f183b98603d5637301189f1d53cd136b2 (diff)
trunk/Master/texmf-dist/source/latex/oberdiek
git-svn-id: svn://tug.org/texlive/trunk@421 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/latex/oberdiek/hypcap.dtx')
-rw-r--r--Master/texmf-dist/source/latex/oberdiek/hypcap.dtx347
1 files changed, 347 insertions, 0 deletions
diff --git a/Master/texmf-dist/source/latex/oberdiek/hypcap.dtx b/Master/texmf-dist/source/latex/oberdiek/hypcap.dtx
new file mode 100644
index 00000000000..e43a8755f6c
--- /dev/null
+++ b/Master/texmf-dist/source/latex/oberdiek/hypcap.dtx
@@ -0,0 +1,347 @@
+% \iffalse meta-comment
+%
+% hypcap.dtx
+%
+% This file is part of the package `hypcap' for use with LaTeX2e.
+%
+% Function: Adjusting anchors of captions.
+%
+% Copyright (C) 1999-2001 Heiko Oberdiek.
+%
+% This program may be distributed and/or modified under
+% the conditions of the LaTeX Project Public License,
+% either version 1.2 of this license or (at your option)
+% any later version. The latest version of this license
+% is in
+% http://www.latex-project.org/lppl.txt
+% and version 1.2 or later is part of all distributions
+% of LaTeX version 1999/12/01 or later.
+%
+% Please send error reports and suggestions for improvements to
+% Heiko Oberdiek <oberdiek@uni-freiburg.de>.
+%
+%<*dtx>
+\ProvidesFile{hypcap.dtx}
+%</dtx>
+%<package>\ProvidesPackage{hypcap}
+%<driver>\ProvidesFile{hypcap.drv}
+% \fi
+% \ProvidesFile{hypcap.dtx}
+ [2001/08/27 v1.3 Adjusting anchors of captions (HO)]
+%
+% \GetFileInfo{hypcap.dtx}
+% \CheckSum{131}
+%
+%% \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 \~}
+%%
+% \iffalse
+%<*driver>
+\documentclass{ltxdoc}
+\usepackage{holtxdoc}
+\begin{document}
+ \DocInput{hypcap.dtx}
+\end{document}
+%</driver>
+% \fi
+%
+% \DoNotIndex{\else,\fi,\csname,\endcsname}
+% \DoNotIndex{\def,\edef,\long,\begingroup,\endgroup}
+% \DoNotIndex{\the,\relax,\expandafter}
+%
+% \SetupTitle{hyperref, caption, anchor, TeX}
+% \maketitle
+%
+% \begin{abstract}
+% This package tries a solution of the problem with
+% hyperref, that links to floats points below the
+% caption and not at the beginning of the float.
+% Therefore this package divides the task into two
+% part, the link setting with \cmd{\capstart} or
+% automatically at the beginning of a float and
+% the rest in the \cmd{\caption} command.
+% \end{abstract}
+%
+% \tableofcontents
+%
+% \section{Usage}
+% The package \Package{hypcap} requires that \Package{hyperref}
+% is loaded first:
+% \begin{quote}
+% |\usepackage[...]{hyperref}|\\
+% |\usepackage[...]{hypcap}|
+% \end{quote}
+%
+% \subsection{Package options}
+% The names of the four float environments |figure|, |figure*|,
+% |table|, or |table*| can be used as option. Then the package
+% overloads the environment in order to insert \cmd{\capstart}
+% (see below) in the beginning of the environment automatically.
+%
+% Option |all| enables the overloading of all four
+% float environments. For other environments see
+% the user command \cmd{\hypcapredef}.
+%
+% \subsection{User commands}
+% \begin{description}
+% \item[\cmd{\capstart}:]\DescribeMacro{\capstart}
+% First it increments the counter (\cmd{\@captype}). Then it
+% makes an anchor for package \Package{hyperref}.
+% At last \cmd{\caption} is redefined to remove the
+% anchor setting part from \Package{hyperref}'s \cmd{\caption}.
+%
+% The package expects the following structure of a float
+% environment:
+% \begin{quote}
+% |\begin{|\textit{|float|}|}...|\\
+% |\capstart|\\
+% |...|\\
+% |\caption{...}|\\
+% |...|\\
+% |\end{|\textit{|float|}|}|
+% \end{quote}
+% There can be several \cmd{\caption} commands. For these
+% you need \cmd{\capstart} again:
+% \begin{quote}
+% |\capstart ... \caption... \capstart ... \caption...|
+% \end{quote}
+% And the \cmd{\caption} command itself can be put in a group.
+%
+% The options, described above, safe writing the
+% first \cmd{\capstart} in the float environment.
+% But also there must be a \cmd{\caption} in every
+% environment of this type.
+% \item[\cmd{\hypcapspace}:]\DescribeMacro{\hypcapspace}
+% Because it looks poor, if the link points exactly at top of
+% the figure, there is additional space: \cmd{\hypcapspace},
+% the default is |0.5\baselineskip|, examples:
+% \begin{quote}
+% |\renewcommand{\hypcapspace}{0pt}| removes the space\\
+% |\renewcommand{\hypcapspace}{1pt}| sets a fix value
+% \end{quote}
+% \item[\cmd{\hypcapredef}:]\DescribeMacro{\hypcapredef}
+% If there are other float environments, that
+% should automatically execute \cmd{\capstart}, then
+% a redefinition with \cmd{\hypcapredef} can be tried:
+% \begin{quote}
+% |\hypcapredef{myfloat}|
+% \end{quote}
+% Only environments with one optional parameter are
+% supported.
+% \end{description}
+%
+% \subsection{Limitations}
+% \begin{itemize}
+% \item Package \Package{subfigure} does not work.
+% \item Packages that redefine \cmd{\caption} or
+% \cmd{\@caption}.
+% \end{itemize}
+%
+% \Installation
+%
+% \StopEventually{}
+%
+% \section{Implementation}
+% \begin{macrocode}
+%<*package>
+% \end{macrocode}
+% The package identification is done at the top of the |.dtx| file
+% in order to use only one identification string.
+%
+% For unique command names this package uses |hc@| as prefix
+% for internal command names.
+%
+% First we check, if package \Package{hyperref} is loaded:
+% \begin{macrocode}
+\@ifundefined{hyper@@anchor}{%
+ \PackageError{hypcap}{You have to load 'hyperref' first}\@ehc
+ \endinput
+}{}
+% \end{macrocode}
+%
+% \begin{macro}{\hc@org@caption}
+% Save the original meaning of \cmd{\caption}:
+% \begin{macrocode}
+\newcommand*\hc@org@caption{}
+\let\hc@org@caption\caption
+% \end{macrocode}
+% \end{macro}
+%
+% \newcommand*{\BeginMacro}[1]{\expandafter\DoBeginMacro\csname#1\endcsname}
+% \newcommand*{\DoBeginMacro}[1]{\begin{macro}{#1}}
+% \newcommand*{\Cmd}[1]{\expandafter\cmd\csname#1\endcsname}
+% \BeginMacro{if@capstart}
+% The switch \Cmd{if@capstart} helps to detect
+% \cmd{\capstart} commands with missing \cmd{\caption} macros.
+% Because \cmd{\caption} can occur inside a group, assignments
+% to the switch have to be made global.
+% \begin{macrocode}
+\newif\if@capstart
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\hypcapspace}
+% The anchor is raised.by \cmd{\hypcapspace}.
+% \begin{macrocode}
+\newcommand*\hypcapspace{.5\baselineskip}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\capstart}
+% The macro \cmd{\capstart} contains the first part of
+% the \cmd{\caption} command: Incrementing the counter
+% and setting the anchor.
+% \begin{macrocode}
+\newcommand*\capstart{%
+ \H@refstepcounter\@captype % first part of caption
+ \hyper@makecurrent\@captype
+ \vspace*{-\hypcapspace}%
+ \begingroup
+ \let\leavevmode\relax
+ \hyper@@anchor\@currentHref\relax
+ \endgroup
+ \vspace*{\hypcapspace}%
+ \let\caption\hc@caption
+ \global\@capstarttrue
+}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\hc@caption}
+% The new \cmd{\caption} command without the first part
+% is defined in the macro \cmd{\hc@caption}.
+% \begin{macrocode}
+\def\hc@caption{%
+ \@dblarg{\hc@@caption\@captype}%
+}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\hc@@caption}
+% This is a copy of package \Package{hyperref}'s \cmd{\@caption}
+% macro without making the anchor, because this is already done
+% in \cmd{\capstart}.
+% \begin{macrocode}
+\long\def\hc@@caption#1[#2]#3{%
+ \let\caption\hc@org@caption
+ \global\@capstartfalse
+ \hyper@makecurrent\@captype
+ \par\addcontentsline{%
+ \csname ext@#1\endcsname}{#1}{%
+ \protect\numberline{%
+ \csname the#1\endcsname
+ }{\ignorespaces #2}%
+ }%
+ \begingroup
+ \@parboxrestore
+ \normalsize
+ \@makecaption{\csname fnum@#1\endcsname}{%
+ \ignorespaces#3%
+ }%
+ \par
+ \endgroup
+}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\hypcapredef}
+% The macro \cmd{\hypcapredef} prepares the call of
+% \cmd{\hc@redef} that will redefine the environment
+% that is given in the argument.
+% \begin{macrocode}
+\def\hypcapredef#1{%
+ \expandafter\hc@redef\csname hc@org#1\expandafter\endcsname
+ \csname hc@orgend#1\expandafter\endcsname
+ \expandafter{#1}%
+}
+% \end{macrocode}
+% \end{macro}
+% \begin{macro}{\hc@redef}
+% The old meaning of the environment is saved. Then
+% \cmd{\capstart} is appended in the begin part.
+% The end part contains a check
+% that produces an error message in case of \cmd{\capstart}
+% without \cmd{\capstart} (\cmd{\capstart} has incremented
+% the counter).
+% \begin{macrocode}
+\def\hc@redef#1#2#3{%
+ \newcommand#1{}%
+ \expandafter\let\expandafter#1\csname#3\endcsname
+ \expandafter\let\expandafter#2\csname end#3\endcsname
+ \renewenvironment*{#3}[1][]{%
+ \ifx\\##1\\%
+ #1\relax
+ \else
+ #1[##1]%
+ \fi
+ \capstart
+ }{%
+ \if@capstart
+ \PackageError{hypcap}{You have forgotten to use \string\caption}%
+ \global\@capstartfalse
+ \else
+ \fi
+ #2%
+ }%
+}
+% \end{macrocode}
+% \end{macro}
+%
+% At last the options are defined and processed.
+% \begin{macrocode}
+\DeclareOption{figure}{\hypcapredef{\CurrentOption}}
+\DeclareOption{figure*}{\hypcapredef{\CurrentOption}}
+\DeclareOption{table}{\hypcapredef{\CurrentOption}}
+\DeclareOption{table*}{\hypcapredef{\CurrentOption}}
+\DeclareOption{all}{%
+ \hypcapredef{figure}%
+ \hypcapredef{figure*}%
+ \hypcapredef{table}%
+ \hypcapredef{table*}%
+}
+\ProcessOptions\relax
+% \end{macrocode}
+%
+% \begin{macrocode}
+%</package>
+% \end{macrocode}
+%
+% \StartHistory
+% \HistVersion{1999/02/13 v1.0}
+% \begin{itemize}
+% \item A beginning version.
+% \end{itemize}
+% \HistVersion{2000/08/14 v1.1}
+% \begin{itemize}
+% \item Global assignments of |\if@capstart|
+% in order to allow |\caption| in groups.
+% \item Option |all| added.
+% \end{itemize}
+% \HistVersion{2000/09/07 v1.2}
+% \begin{itemize}
+% \item Package in dtx format.
+% \end{itemize}
+% \HistVersion{2001/08/27 v1.3}
+% \begin{itemize}
+% \item Bug fix with hyperref's pdfmark driver\\
+% (\verb|\leavevmode| in
+% \verb|\hyper@@anchor|/\verb|\pdf@rect|).
+% \end{itemize}
+%
+% \PrintIndex
+%
+% \Finale
+\endinput