From e94c1bb676f5054f55d4410bae611f0df8777fe0 Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Fri, 13 Mar 2009 23:28:23 +0000 Subject: mcaption 3.0 (13mar09) git-svn-id: svn://tug.org/texlive/trunk@12384 c570f23f-e606-0410-a88d-b1316a301751 --- Master/texmf-dist/doc/latex/mcaption/CHANGES | 49 ++ Master/texmf-dist/doc/latex/mcaption/README | 4 +- Master/texmf-dist/doc/latex/mcaption/example.tex | 50 +- Master/texmf-dist/doc/latex/mcaption/mcaption.pdf | Bin 123188 -> 137292 bytes .../texmf-dist/source/latex/mcaption/mcaption.dtx | 654 ++++++++++++++------- Master/texmf-dist/tex/latex/mcaption/mcaption.sty | 165 ++++-- 6 files changed, 645 insertions(+), 277 deletions(-) create mode 100644 Master/texmf-dist/doc/latex/mcaption/CHANGES diff --git a/Master/texmf-dist/doc/latex/mcaption/CHANGES b/Master/texmf-dist/doc/latex/mcaption/CHANGES new file mode 100644 index 00000000000..cbbff0f38d8 --- /dev/null +++ b/Master/texmf-dist/doc/latex/mcaption/CHANGES @@ -0,0 +1,49 @@ +--------------- +v3.0 2009/03/13 +--------------- +New: + * Obey \caption and \label commands inside margincap + (at last!). + * Macro \margincapalign is deprecated (no longer + necessary for tabular declarations). + * New compatibility option `v2.2'. + +Incompatible changes: + * Environment margincap has no arguments. A + compatibility option exists, that restores the old + syntax with caption arguments. + * The mcaption package requires package changepage to be + installed (instead of chngpage). + * Complete revision of the vertical alignment mechanism. + Paragraph-breaking might be affected (hopefully only + to the better). + +Fixed: + * In one-sided documents chngpage/changepage's even/odd + page detection was subtly broken by the mcaption + package. + + +--------------- +v2.2 2005/09/30 +--------------- +New: + * New package options `bottom' and `top'. + +Fixed: + * In one-sided documents captions were put into the wrong + margin. + + +--------------- +v2.1 2005/09/29 +--------------- +New: + * Works with standard classed. + + +--------------- +v2.0 2005/09/26 +--------------- +New: + * Prepare DTX package. diff --git a/Master/texmf-dist/doc/latex/mcaption/README b/Master/texmf-dist/doc/latex/mcaption/README index a82ea2e3cd0..04a8697194a 100644 --- a/Master/texmf-dist/doc/latex/mcaption/README +++ b/Master/texmf-dist/doc/latex/mcaption/README @@ -2,13 +2,13 @@ % http://www.ctan.org/tex-archive/help/Catalogue/licenses.lppl.html % for the details of that license. -package: mcaption v2.2 2005/09/30 +package: mcaption v3.0 2009/03/13 author: Stephan Hennig (stephanhennig@arcor.de) Description This package provides a margincap environment to put figure -or table captions in the margin. See the documentation to +or table captions into the margin. See the documentation to learn more about this package. diff --git a/Master/texmf-dist/doc/latex/mcaption/example.tex b/Master/texmf-dist/doc/latex/mcaption/example.tex index 14b56874d4b..d7af58e0960 100644 --- a/Master/texmf-dist/doc/latex/mcaption/example.tex +++ b/Master/texmf-dist/doc/latex/mcaption/example.tex @@ -25,53 +25,79 @@ \usepackage{wrapfig} \usepackage[top]{mcaption} \usepackage[ - font={footnotesize,it}, - labelfont=bf, - justification=raggedright] +font={footnotesize,it}, +labelfont=bf, +justification=raggedright] {caption}[2005/06/28] \usepackage[english]{babel} \usepackage{blindtext} \begin{document} \setlength{\margincapsep}{3\columnsep} + +\author{Stephan Hennig} +\title{mcaption test file} +\maketitle +\listoffigures +\listoftables + \chapter{Demonstration of the mcaption package} -\section{This is one column mode} +\section{This is one-column mode} \blindtext[1] \begin{wrapfigure}{o}{5cm} - \begin{margincap}{A wrapfigure caption in the outer margin.} + \begin{margincap} \rule{5cm}{2cm} + \caption{A wrapfigure caption in the outer margin.} + \label{fig:wrapOneCol} \end{margincap} \end{wrapfigure} \blindtext[1] \begin{table} - \begin{margincap}{A table caption in the outer margin.} + \begin{margincap} \centering -%%% Note the alignment specifier! - \begin{tabular}[\margincapalign]{@{}lr@{}} + \begin{tabular}{@{}lr@{}} foo & 7\\ bar & 21 \\ baz & 23 \\ \end{tabular} + \caption{A table caption in the outer margin.} + \label{tab:shorttab} \end{margincap} \end{table} \twocolumn -\section{This is two column mode} +\section{This is two-column mode} \blindtext[1] \begin{wrapfigure}{o}{2cm} - \begin{margincap}{Another wrapfigure caption in the outer margin. - Note, we are in the outer column. And we're hanging!} + \begin{margincap} \rule{2cm}{1cm} + \caption[A hanging wrapfigure caption.]{Another wrapfigure caption + in the outer margin. Note, we are in the outer column. And we're + hanging!} + \label{fig:wrapTwoCol} \end{margincap} \end{wrapfigure} \blindtext[5] \begin{figure*} - \begin{margincap}{A figure caption in the outer margin.} + \begin{margincap} \centering \rule{10cm}{2cm} + \caption{A figure caption in the outer margin.} + \label{fig:figure*} \end{margincap} \end{figure*} + +Let's reference all figures and tables: + +\newcommand*{\pref}[1]{\ref{#1} & \pageref{#1}} +\begin{tabular}{ll} + float & page\\\hline + figure~\pref{fig:wrapOneCol}\\ + table~\pref{tab:shorttab}\\ + figure~\pref{fig:wrapTwoCol}\\ + figure~\pref{fig:figure*}\\ +\end{tabular} \end{document} \endinput %% diff --git a/Master/texmf-dist/doc/latex/mcaption/mcaption.pdf b/Master/texmf-dist/doc/latex/mcaption/mcaption.pdf index 3413c65e9bc..3aa563f0126 100644 Binary files a/Master/texmf-dist/doc/latex/mcaption/mcaption.pdf and b/Master/texmf-dist/doc/latex/mcaption/mcaption.pdf differ diff --git a/Master/texmf-dist/source/latex/mcaption/mcaption.dtx b/Master/texmf-dist/source/latex/mcaption/mcaption.dtx index eec0b552d17..8a607027a88 100644 --- a/Master/texmf-dist/source/latex/mcaption/mcaption.dtx +++ b/Master/texmf-dist/source/latex/mcaption/mcaption.dtx @@ -1,4 +1,4 @@ -% \CheckSum{112} +% \CheckSum{220} % % \iffalse meta-comment % @@ -23,7 +23,7 @@ % %\ProvidesPackage{mcaption} %<*dtx|package> - [2005/09/30 v2.2 Put captions in margin (SH)] + [2009/03/13 v3.0 Put captions into the outer document margin (SH)] % %\NeedsTeXFormat{LaTeX2e}[1999/12/01] % @@ -45,53 +45,79 @@ \usepackage{wrapfig} \usepackage[top]{mcaption} \usepackage[ - font={footnotesize,it}, - labelfont=bf, - justification=raggedright] +font={footnotesize,it}, +labelfont=bf, +justification=raggedright] {caption}[2005/06/28] \usepackage[english]{babel} \usepackage{blindtext} \begin{document} \setlength{\margincapsep}{3\columnsep} + +\author{Stephan Hennig} +\title{mcaption test file} +\maketitle +\listoffigures +\listoftables + \chapter{Demonstration of the mcaption package} -\section{This is one column mode} +\section{This is one-column mode} \blindtext[1] \begin{wrapfigure}{o}{5cm} - \begin{margincap}{A wrapfigure caption in the outer margin.} + \begin{margincap} \rule{5cm}{2cm} + \caption{A wrapfigure caption in the outer margin.} + \label{fig:wrapOneCol} \end{margincap} \end{wrapfigure} \blindtext[1] \begin{table} - \begin{margincap}{A table caption in the outer margin.} + \begin{margincap} \centering -%%% Note the alignment specifier! - \begin{tabular}[\margincapalign]{@{}lr@{}} + \begin{tabular}{@{}lr@{}} foo & 7\\ bar & 21 \\ baz & 23 \\ \end{tabular} + \caption{A table caption in the outer margin.} + \label{tab:shorttab} \end{margincap} \end{table} \twocolumn -\section{This is two column mode} +\section{This is two-column mode} \blindtext[1] \begin{wrapfigure}{o}{2cm} - \begin{margincap}{Another wrapfigure caption in the outer margin. - Note, we are in the outer column. And we're hanging!} + \begin{margincap} \rule{2cm}{1cm} + \caption[A hanging wrapfigure caption.]{Another wrapfigure caption + in the outer margin. Note, we are in the outer column. And we're + hanging!} + \label{fig:wrapTwoCol} \end{margincap} \end{wrapfigure} \blindtext[5] \begin{figure*} - \begin{margincap}{A figure caption in the outer margin.} + \begin{margincap} \centering \rule{10cm}{2cm} + \caption{A figure caption in the outer margin.} + \label{fig:figure*} \end{margincap} \end{figure*} + +Let's reference all figures and tables: + +\newcommand*{\pref}[1]{\ref{#1} & \pageref{#1}} +\begin{tabular}{ll} + float & page\\\hline + figure~\pref{fig:wrapOneCol}\\ + table~\pref{tab:shorttab}\\ + figure~\pref{fig:wrapTwoCol}\\ + figure~\pref{fig:figure*}\\ +\end{tabular} \end{document} % % \fi @@ -116,152 +142,151 @@ % \GetFileInfo{mcaption.dtx} % % -% \title{The \textsf{mcaption} package\thanks{This document -% corresponds to \textsf{mcaption}~\fileversion, dated -% \filedate.}} +% \title{The \textsf{mcaption} package\thanks{This document corresponds +% to \textsf{mcaption}~\fileversion, dated \filedate.}} % \author{Stephan Hennig\\ \texttt{stephanhennig@arcor.de}} % % \maketitle % % \begin{abstract} -% This package provides a |margincap| environment for putting -% captions in the outer document margin with either a top or -% bottom alignment. +% This package provides a |margincap| environment for putting captions +% into the outer document margin with either a top or bottom +% alignment. % \end{abstract} % % % \section{Package options}\label{sec:options} % -% Margin captions can be either top or bottom aligned. That is, the -% first or last line of the caption is aligned with the top or -% bottom of a figure or table. In case a caption is higher than a -% figure it will hang or grow in the margin beneath running text. -% You can control the alignment by loading the package with options -% |bottom|, which is the default, or |top|, \emph{e.\,g.}: -% -% \begin{verbatim} -%\usepackage[top]{mcaption} -% \end{verbatim} +% The \textsf{mcaption} package provides the following options: % +% \smallskip +% \begin{tabular}{lll} +% option & brief description & page\\\hline +% |bottom| & vertical caption alignment & \pageref{sec:alignv}\\ +% |top| & vertical caption alignment & \pageref{sec:alignv}\\ +% |v2.2| & compatibility option & \pageref{sec:usage}\\ +% \end{tabular} % -% \section{Usage} % -% Place the |margincap|\DescribeEnv{margincap}{} environment inside -% a |figure| or any other floating environment. Then put the stuff -% you want to have a margin caption inside the |margincap| -% environment, including commands for horizontal alignment, -% \emph{e.\,g.}, |\centering| (see file |example.tex|, which has -% been generated during package installation). Placing those -% commands before |margincap| would likely lead to unwanted output. +% \section{Usage}\label{sec:usage} % -% Arguments to the |margincap| environment are the same as to the -% |\caption| command, \emph{i.\,e.}, the mandatory caption text and -% one optional alternative list entry. A sample declaration of a -% figure with a margin caption looks like this\footnote{Currently, -% references to figures with margin captions are not supported.}: +% The |margincap|\DescribeEnv{margincap}\ environment places its +% contents into a box whose width matches the current line witdh and +% attaches a caption (with an optional label) next to the box in the +% outer margin. Caption text and the label are taken from |\caption| +% and |\label| commands within the environment. A typical use-case is +% to put the |margincap| environment into a float, such as a |figure| or +% |tabular| environment: % % \begin{verbatim} %\begin{figure} -% \begin{margincap}[short caption]{margin caption} +% \begin{margincap} % \centering % \includegraphics{picture} +% \caption[short caption text]{long caption text} +% \label{fig:pic} % \end{margincap} %\end{figure} % \end{verbatim} % -% The |margincap| environment even works inside a -% |wrapfigure|\DescribeEnv{wrapfigure}{} environment that is -% provided by the |wrapfig| package as long as the figure or table -% appears in the outer margin, \emph{e.\,g.}, by specifying a -% parameter `o' or `O' to the |wrapfigure| environment (see the -% \emph{Known Problems} section below). This even works in two -% column mode. +% The |margincap| environment also works with the +% |wrapfigure|\DescribeEnv{wrapfigure}\ environment provided by the +% |wrapfig| package. Note, wrapped figures or tables have to appear in +% the outer margin, \emph{i.\,e.}, parameters `o' or `O' have to be +% applied to the |wrapfigure| environment. This even works in +% two-column mode. See file |example.tex| for an example. +% +% Up to \textsf{mcaption}~v2.2\marginpar{\raggedleft\fbox{v2.2}} the +% |margincap| environment had a different syntax. Macros |\caption| and +% |\label| haven't been recognized inside the environment. Instead, +% short and long caption texts had to be given as optional and mandatory +% arguments to the |margincap| environment. To apply a label to a +% |margincap| environment, the |\label| command had to passed as part of +% the long caption text. The \textsf{mcaption} package provides a +% compatibility option |v2.2|\marginpar{\raggedleft |v2.2|} that enables +% the old behaviour. This option is disabled by default. % % % \section{Caption Format} % -% \subsection{Vertical alignment} -% Vertical alignment of margin caption can be controlled by package -% options |bottom| or |top| (see section~\ref{sec:options}). As an -% alternative, you can |\renewcommand| macro -% |\margincapalign|\DescribeMacro{\margincapalign}{} to either |b| -% or |t|. This way you can adjust the alignment of single captions -% in the document. Although, there might be situations where this -% could be useful, the author suggests one document wide alignment -% setting. The true reason macro |\margincapalign| is provided for -% is explained in section~\ref{sec:tables}. +% \subsection{Vertical alignment}\label{sec:alignv} +% Vertical alignment of margin captions can be controlled by package +% options |top|\marginpar{\raggedleft |top|} or +% |bottom|\marginpar{\raggedleft |bottom|}. +% +% Option |top| aligns the top-most line of the caption to the top of the +% |margincap| environment's contents (an image, tabular, \emph{etc.}) +% Similarly, option |bottom| aligns the bottom-most line of the caption +% to the bottom of the |margincap| environment's contents. In case a +% caption has a larger height or depth than a figure, it will hang or +% grow beneath the running text. Option |bottom| is the default. +% +% Up to \textsf{mcaption}~v2.2\marginpar{\raggedleft\fbox{v2.2}}, the +% vertical alignment of captions required some user-interaction. For +% tabulars, the baseline alignment had to match that of the caption. +% For that reason a macro +% |\margincapalign|\DescribeMacro{\margincapalign}\ had been provided +% that had to be passed as an alignment specifier to all tabular +% declarations. Newer versions of \textsf{mcaption} don't need this +% alignment specifier. For backwards compatibility macro +% |\margincapalign| is still provided, but it's use is deprecated. +% Legacy documents, that use |\margincapalign| in tabular declarations, +% should still compile as soon as \textsf{mcaption} is loaded with +% package option |v2.2| (see section~\ref{sec:usage}). % % \subsection{Horizontal alignment} -% Horizontal space between a |margincap| environment's contents and -% the caption can be adjusted by setting length -% |\margincapsep|\DescribeMacro{\margincapsep}{} to the desired -% value. This has to be done after |\begin{document}| or via -% |\AtBeginDocument| in the preamble. Although changes of -% |\margincapsep| will affect all further |margincap| environments -% you should use one document wide setting to get a consistent look -% throughout the document. Default value is |\marginparsep|. +% Horizontal spacing between a |margincap| environment's contents and +% the caption can be adjusted by the length +% |\margincapsep|\DescribeMacro{\margincapsep}{}. This has to be done +% after |\begin{document}| or via |\AtBeginDocument| in the preamble. +% Since changing |\margincapsep| will affect all further |margincap| +% environments, the author suggests one document wide setting to get a +% consistent look throughout the document. Default value is +% |\marginparsep|. % % \subsection{Further tweaks} -% To get visually pleasing results you should provide wide enough -% outer margins. To further smoothen line breaking consider using a -% smaller caption font and setting captions ragged. The author -% suggests using the |caption| package to format captions. -% \emph{E.\,g.}, issuing the following line in the document preamble +% To get visually pleasing results you should provide wide enough outer +% margins. To further smoothen line breaking consider using a smaller +% caption font and setting captions ragged. The author suggests using +% the \textsf{caption} package to format captions. \emph{E.\,g.}, +% issuing the following line in the document preamble % % \begin{verbatim} %\usepackage[font=footnotesize,justification=raggedright]{caption} % \end{verbatim} -% will type set all further captions at a smaller font size and -% flush left. The |RaggedRight| option might be useful here, too, to -% allow for hyphenation inside ragged text. -% +% will typeset all further captions at a smaller font size and flush +% left. The |RaggedRight| option might be useful here, too, to allow +% for hyphenation inside ragged text. % -% \section{Tables}\label{sec:tables} % -% When using a |tabular| environment inside the |margincap| -% environment an alignment parameter has to be passed to |tabular| -% to get proper vertical alignment of the caption. This parameter -% should be either |b| or |t|. Since the parameter should also match -% margin captions' alignment, it is recommended to pass parameter -% |\margincapalign|\DescribeMacro{\margincapalign}{} to a |tabular| -% declaration. Omitting this parameter causes captions to appear -% near the vertical center of a tabular. A typical table declaration -% should look like this: -% -% \begin{verbatim} -%\begin{table} -% \begin{margincap}{margin caption} -% \centering -% \begin{tabular}[\margincapalign]{...} -% ... -% \end{tabular} -% \end{margincap} -%\end{table} -% \end{verbatim} -% -% -% \section{Known Problems} +% \section{Known Problems}\label{sec:problems} % % \begin{enumerate} % -% \item The label\slash{}reference mechanism doesn't work for margin -% captions, currently. -% -% \item Captions can appear in the wrong margin sometimes. Running -% \LaTeX{} again should solve that problem. +% \item Captions may appear in the wrong margin, sometimes. Running +% \LaTeX\ twice should solve that problem. \emph{Background:} For +% robustness, \textsf{mcaption} relies on the \textsf{changepage} +% package with option |strict| to detect left- and right-hand pages. +% This requires two \LaTeX-passes. The behaviour can be changed with +% macro |\easypagecheck| (see package |changepage|). % -% \item When changing the font size of captions they may be slightly -% vertically misaligned. -% -% \item When using the |wrapfig| package the auto sizing feature of -% the |wrapfigure| environment won't work when putting a -% |margincap| environment in. You'll have to specify the width of -% a |wrapfigure| manually. +% \item Captions are positioned slightly too high. This is because +% |margincap| doesn't reliably know the contents' exact bottom-most +% base line. Additional artificial zero height lines are used to +% align environment contents and caption text. For that reason, the +% true depth of both are not taken into account. \emph{Todo:} Provide +% means for vertical fine-tuning of captions. +% +% \item When using the |wrapfig| package the auto sizing feature of the +% |wrapfigure| environment won't work when putting a |margincap| +% environment in. You'll have to specify the width of a |wrapfigure| +% manually. % \end{enumerate} -% +% +% % \section{Bugs} % -% If you find bugs feel free to contact me at +% If you find bugs, feel free to contact me at % \texttt{stephanhennig@arcor.de}. % % @@ -279,35 +304,71 @@ % \fi % \section{Implementation} % -% Make sure the |ifthen| and |chngpage| packages are loaded. +% \changes{v3.0}{2009/03/07}{Complete revision of vertical alignment +% mechanism.} +% +% Make sure the |changepage| package is loaded. +% \changes{v3.0}{2009/03/12}{Replace package \textsf{chngpage} by +% newer \textsf{changepage}.} % \begin{macrocode} -\RequirePackage{ifthen} -\RequirePackage{chngpage} +\RequirePackage[strict]{changepage} % \end{macrocode} % -% \begin{macro}{\margincapalign} -% Provide this macro to store the vertical alignment specifier for -% user access (see section~\ref{sec:tables}). +% \begin{macro}{\mcaption@alignv} +% This macro is used by options |bottom| and |top|. % \begin{macrocode} -\newcommand*{\margincapalign}{} +\newcommand*{\mcaption@alignv}{} % \end{macrocode} % \end{macro} % -% Declare options |bottom| and |top| to determine vertical alignment -% of a caption. Default package option is |bottom|. -% \changes{v2.2}{2005/09/29}{Provide package options `bottom' and `top'.} +% Declare options |bottom| and |top| to determine vertical alignment of +% a caption. Default package option is |bottom|. +% \changes{v2.2}{2005/09/29}{New package options `bottom' and `top'.} % \begin{macrocode} -\DeclareOption{top}{\renewcommand*{\margincapalign}{t}} -\DeclareOption{bottom}{\renewcommand*{\margincapalign}{b}} +\DeclareOption{top}{\renewcommand*{\mcaption@alignv}{t}} +\DeclareOption{bottom}{\renewcommand*{\mcaption@alignv}{b}} \ExecuteOptions{bottom} +% \end{macrocode} +% +% Declare compatibility option |v2.2|, that restores the behaviour of +% \textsf{mcaption}~v2.2 for the |margincap| environment. +% \changes{v3.0}{2009/03/10}{New package option `v2.2'.} +% \begin{macrocode} +\DeclareOption{v2.2}{% + \AtEndOfPackage{% +% \end{macrocode} +% +% Activate |margincap| with optional and mandatory caption argument. +% \begin{macrocode} + \let\margincap\mcaption@mcIIdotII% + \let\endmargincap\endmcaption@mcIIdotII% +% \end{macrocode} +% +% \begin{macro}{\margincapalign} +% Macro |\margincapalign| is deprecated (cf. macro +% |\mcaption@alignv|). It is only provided for backwards +% compatibility. +% \changes{v3.0}{2009/03/08}{Deprecated.} +% \begin{macrocode} + \newcommand*{\margincapalign}{\mcaption@alignv} +% \end{macrocode} +% \end{macro} +% +% \begin{macrocode} + }% +}% +% \end{macrocode} +% +% Process the options. +% \begin{macrocode} \ProcessOptions\relax % \end{macrocode} % % \begin{macro}{\margincapsep} -% Length |\margincapsep| determines the horizontal distance between -% contents and caption and can be adjusted by the user. This length -% has to be set only after |\begin{document}| and equals -% |\marginparsep| by default. +% Length |\margincapsep| determines the horizontal distance between +% contents and caption and can be adjusted by the user. This length +% has to be set only after |\begin{document}| and equals +% |\marginparsep| by default. % \begin{macrocode} \newlength{\margincapsep} \AtBeginDocument{% @@ -316,6 +377,19 @@ % \end{macrocode} % \end{macro} % +% Declare macros for storing long and short caption text and a flag. +% \begin{macrocode} +\newcommand*{\mcaption@CaptionLong}{} +\newcommand*{\mcaption@CaptionShort}{} +\newcommand*{\mcaption@CaptionFlag}{} +% \end{macrocode} +% +% Declare macros for storing a label and a flag. +% \begin{macrocode} +\newcommand*{\mcaption@Label}{} +\newcommand*{\mcaption@LabelFlag}{} +% \end{macrocode} +% % Declare boxes to store the contents and caption of a |margincap| % environment. % \begin{macrocode} @@ -323,121 +397,271 @@ \newsavebox{\mcaption@CaptionBox} % \end{macrocode} % -% Declare lengths that are used for vertical positioning of contents -% and caption and a temporary one. Could one use a global temporary -% length instead? +% +% \begin{environment}{mcaption@mcIIdotII} +% Declare a template for the traditional |margincap| environment as of +% \textsf{mcaption}~v2.2, that takes an optional and a mandatory +% caption text argument, \emph{cf.} environment |mcaption@mcIIIdot|. +% \changes{v2.1}{2005/09/29}{Now works with standard classes.} % \begin{macrocode} -\newlength{\mcaption@ObjectHeight} -\newlength{\mcaption@ObjectRaise} -\newlength{\mcaption@CaptionRaise} -\newlength{\mcaption@tempdima} +\newenvironment{mcaption@mcIIdotII}[2][\mcaption@DefaultOpt]{% % \end{macrocode} % -% \begin{environment}{margincap} -% Provide margincap environment. -% \changes{v2.1}{2005/09/29}{Now works with standard classes.} +% Call |\caption| with or without optional argument. Trick taken from +% UK-\TeX-FAQ, question 286: `Optional arguments like |\section|'. % \begin{macrocode} -\newenvironment{margincap}[2][\mcaption@DefaultOpt]{% + \def\mcaption@DefaultOpt{#2}% % \end{macrocode} % -% Call |\caption| with or without optional argument. Trick taken -% from UK-\TeX-FAQ, question 286: `Optional arguments like -% |\section|'. +% Store optional and mandatory caption arguments for later processing. +% Flag a caption without label. +% \changes{v3.0}{2009/03/10}{Delay caption handling.} % \begin{macrocode} - \def\mcaption@DefaultOpt{#2}% + \def\mcaption@CaptionShort{#1}% + \def\mcaption@CaptionLong{#2}% + \gdef\mcaption@CaptionFlag{t}% + \gdef\mcaption@LabelFlag{f}% % \end{macrocode} % -% Put caption in box |\mcaption@CaptionBox| with requested alignment -% for later use. +% Collect environment contents in a box |\mcaption@ObjectBox| of width +% |\linewidth|. % \begin{macrocode} - \begin{lrbox}{\mcaption@CaptionBox}% - \setlength{\mcaption@tempdima}{\marginparsep}% - \addtolength{\mcaption@tempdima}{\marginparwidth}% - \addtolength{\mcaption@tempdima}{-\margincapsep}% - \begin{minipage}[\margincapalign]{\mcaption@tempdima}% - \caption[#1]{#2}% + \begin{lrbox}{\mcaption@ObjectBox}% + \begin{minipage}{\linewidth}% +}{% \end{minipage}% \end{lrbox}% % \end{macrocode} % -% Put user stuff into box |\mcaption@ObjectBox| of width -% |\linewidth| with requested alignment. +% Call the working macros. +% \begin{macrocode} + \mcaption@align@boxes% + \mcaption@output@boxes% +% \end{macrocode} +% +% We're done. +% \begin{macrocode} +}% +% \end{macrocode} +% \end{environment} +% +% +% \begin{environment}{mcaption@mcIIIdot} +% Declare a template for the new |margincap| environment as of +% \textsf{mcaption}~v3.0, that accepts |\caption| and |\label| +% arguments inside the environment, \emph{cf.} environment +% |mcaption@mcIIdotII|. +% \changes{v3.0}{2009/03/10}{Recognize \texttt{\textbackslash caption} +% and \texttt{\textbackslash label} commands.} +% \begin{macrocode} +\newenvironment{mcaption@mcIIIdot}{% +% \end{macrocode} +% +% Replace |\caption| and |\label| commands by custom variants and unset +% flags. +% \begin{macrocode} + \let\mcaption@origcaption\caption% + \let\caption\mcaption@caption% + \gdef\mcaption@CaptionFlag{f}% + \let\mcaption@origlabel\label% + \let\label\mcaption@label% + \gdef\mcaption@LabelFlag{f}% +% \end{macrocode} +% +% Collect environment contents in a box |\mcaption@ObjectBox| of width +% |\linewidth|. % \begin{macrocode} \begin{lrbox}{\mcaption@ObjectBox}% - \begin{minipage}[\margincapalign]{\linewidth}% + \begin{minipage}{\linewidth}% }{% \end{minipage}% \end{lrbox}% % \end{macrocode} % -% Depending on requested alignment of the caption, \emph{i.\,e.} -% |\margincapalign| is |b| or |t|, do some calculations about how -% much to raise contents and caption: -% \begin{center} -% \begin{tabular}{c@{\hspace{3em}}ccc} -% alignment & raise contents & raise caption & new height of contents\\\hline -% |bottom| & 0 & 0 & natural height\\ -% |top| & $-$natural height & height of |\strutbox| & 0\\ -% \end{tabular} -% \end{center} -% Furthermore, height and depth of a caption are set to zero to -% allow them to hang into or grow beneath running text. -% \begin{macrocode} - \settoheight{\mcaption@ObjectHeight}{\usebox{\mcaption@ObjectBox}}% - \ifthenelse{\equal{\margincapalign}{t}}{% - \setlength{\mcaption@ObjectRaise}{-\mcaption@ObjectHeight}% - \setlength{\mcaption@ObjectHeight}{0pt}% - \settoheight{\mcaption@CaptionRaise}{\strut}% - }{% - \setlength{\mcaption@ObjectRaise}{0pt}% - \setlength{\mcaption@CaptionRaise}{0pt}% +% Restore original |\caption| and |\label| definitions. +% \begin{macrocode} + \let\caption\mcaption@origcaption% + \let\label\mcaption@origlabel% +% \end{macrocode} +% +% Call the working macros. +% \begin{macrocode} + \mcaption@align@boxes% + \mcaption@output@boxes% +% \end{macrocode} +% +% We're done. +% \begin{macrocode} +}% +% \end{macrocode} +% \end{environment} +% +% +% \begin{environment}{margincap} +% Provide the |margincap| environment. +% \begin{macrocode} +\newenvironment{margincap}{}{}% +% \end{macrocode} +% +% Activate the new behaviour for the |margincap| environment. +% \begin{macrocode} +\let\margincap\mcaption@mcIIIdot% +\let\endmargincap\endmcaption@mcIIIdot% +% \end{macrocode} +% \end{environment} +% +% +% Define auxillary macros and environments. +% +% These macros are used for saving the original |\caption| and |\label| +% definitions. +% \begin{macrocode} +\newcommand*{\mcaption@origcaption}{} +\newcommand*{\mcaption@origlabel}{} +% \end{macrocode} +% +% Declare an auxillary macro for storing the \emph{unexpanded} optional +% |\caption| argument. +% \begin{macrocode} +\newcommand*{\mcaption@DefaultOpt}{} +% \end{macrocode} +% +% \begin{macro}{\mcaption@caption} +% This |\caption| replacement macro just stores its arguments in +% |\mcaption@CaptionShort| and |\mcaption@CaptionLong| for later +% reference and sets a flag. +% \begin{macrocode} +\newcommand*{\mcaption@caption}[2][\mcaption@DefaultOpt]{% + \gdef\mcaption@DefaultOpt{#2}% + \gdef\mcaption@CaptionShort{#1}% + \gdef\mcaption@CaptionLong{#2}% + \gdef\mcaption@CaptionFlag{t}% + \ignorespaces +}% +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\mcaption@label} +% This |\label| replacement macro just stores its arguments in +% |\mcaption@Label| for later reference and sets a flag. +% \begin{macrocode} +\newcommand*{\mcaption@label}[1]{% + \gdef\mcaption@Label{#1}% + \gdef\mcaption@LabelFlag{t}% + \ignorespaces +}% +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\mcaption@align@boxes} +% This macro prepares and aligns contents and caption boxes. +% \begin{macrocode} +\newcommand*{\mcaption@align@boxes}{% +% \end{macrocode} +% +% If the user issued a |\caption| command, put the caption text into box +% |\mcaption@CaptionBox|. Else prepare an empty box. +% \changes{v3.0}{2009/03/07}{Use temporary \LaTeX\ length.} +% \begin{macrocode} + \begin{lrbox}{\mcaption@CaptionBox}% + \setlength{\@tempdima}{\marginparwidth}% + \addtolength{\@tempdima}{\marginparsep}% + \addtolength{\@tempdima}{-\margincapsep}% + \begin{minipage}{\@tempdima}% + \if\mcaption@CaptionFlag t% + \setlength{\abovecaptionskip}{0pt}% + \setlength{\belowcaptionskip}{0pt}% + \caption[\mcaption@CaptionShort]{\strut\mcaption@CaptionLong\strut}% + \fi% + \if\mcaption@LabelFlag t% + \label{\mcaption@Label}% + \fi% + \end{minipage}% + \end{lrbox}% +% \end{macrocode} +% +% Wrap contents into zero height top and bottom lines to get the desired +% reference point. Then use |\vtop| or |\vbox| for aligning boxes. +% \begin{macrocode} +\sbox{\mcaption@ObjectBox}{% + \if\mcaption@alignv t\vtop + \else\vbox + \fi + {% + \vskip0pt% + \hbox{\usebox{\mcaption@ObjectBox}}% + \vskip0pt% + }% +}% +\sbox{\mcaption@CaptionBox}{% + \if\mcaption@alignv t\vtop + \else\vbox + \fi + {% + \vskip0pt% + \hbox{\usebox{\mcaption@CaptionBox}}% + \vskip0pt% }% +}% +}% % \end{macrocode} +% \end{macro} +% % -% Now check, if we have a two sided document. If so, check if we're -% on an even or odd page. If the document is one sided, treat every -% page like an odd page. -% \changes{v2.2}{2005/09/29}{Captions were put in wrong margin in one sided documents. Fixed.} +% \begin{macro}{\mcaption@output@oddpage} +% This macro first outputs the contents and then the caption box. % \begin{macrocode} - \if@twoside% - \checkoddpage% - \else% - \cpoddpagetrue% - \fi% +\newcommand*{\mcaption@output@oddpage}{% + \makebox[\linewidth][l]{% + \usebox{\mcaption@ObjectBox}% + \hspace*{\margincapsep}% + \smash{\usebox{\mcaption@CaptionBox}}% + }% +}% % \end{macrocode} +% \end{macro} % -% Finally, output contents and caption. On odd pages, output -% contents first, and then caption. On even pages, the order is -% reversed. -% \begin{macrocode} - \ifcpoddpage% - \makebox[\linewidth][l]{% - \raisebox{\mcaption@ObjectRaise}[\mcaption@ObjectHeight]{% - \usebox{\mcaption@ObjectBox}% - }% - \hspace*{\margincapsep}% - \raisebox{\mcaption@CaptionRaise}[0pt][0pt]{% - \usebox{\mcaption@CaptionBox}% - }% - }% - \else% - \makebox[\linewidth][r]{% - \raisebox{\mcaption@CaptionRaise}[0pt][0pt]{% - \usebox{\mcaption@CaptionBox}% - }% - \hspace*{\margincapsep}% - \raisebox{\mcaption@ObjectRaise}[\mcaption@ObjectHeight]{% - \usebox{\mcaption@ObjectBox}% - }% - }% - \fi% +% \begin{macro}{\mcaption@output@evenpage} +% This macro first outputs the caption and then the contents box. +% \begin{macrocode} +\newcommand*{\mcaption@output@evenpage}{% + \makebox[\linewidth][r]{% + \smash{\usebox{\mcaption@CaptionBox}}% + \hspace*{\margincapsep}% + \usebox{\mcaption@ObjectBox}% + }% +}% % \end{macrocode} +% \end{macro} % -% We're done. + +% \begin{macro}{\mcaption@output@boxes} +% This macro outputs contents and caption boxes in the correct order. % \begin{macrocode} +\newcommand*{\mcaption@output@boxes}{% +% \end{macrocode} +% +% In two-sided documents check for odd and even pages. In one-sided +% documents treat every page as an odd page. +% \changes{v2.2}{2005/09/29}{Fixed: In one-sided documents captions were +% put into the wrong margin.} +% \changes{v3.0}{2009/03/12}{Fixed: In one-sided documents +% \textsf{chngpage/changepage}'s even/odd page detection was subtly +% broken by \textsf{mcaption}.} +% \begin{macrocode} + \if@twoside% + \checkoddpage% + \ifoddpage% + \mcaption@output@oddpage% + \else% + \mcaption@output@evenpage% + \fi% + \else% + \mcaption@output@oddpage% + \fi% }% % \end{macrocode} -% \end{environment} +% \end{macro} % % \iffalse % diff --git a/Master/texmf-dist/tex/latex/mcaption/mcaption.sty b/Master/texmf-dist/tex/latex/mcaption/mcaption.sty index 0095e1c53fc..b54881da4a8 100644 --- a/Master/texmf-dist/tex/latex/mcaption/mcaption.sty +++ b/Master/texmf-dist/tex/latex/mcaption/mcaption.sty @@ -21,74 +21,143 @@ %% 1999/12/01 or later. %% \ProvidesPackage{mcaption} - [2005/09/30 v2.2 Put captions in margin (SH)] + [2009/03/13 v3.0 Put captions into the outer document margin (SH)] \NeedsTeXFormat{LaTeX2e}[1999/12/01] -\RequirePackage{ifthen} -\RequirePackage{chngpage} -\newcommand*{\margincapalign}{} -\DeclareOption{top}{\renewcommand*{\margincapalign}{t}} -\DeclareOption{bottom}{\renewcommand*{\margincapalign}{b}} +\RequirePackage[strict]{changepage} +\newcommand*{\mcaption@alignv}{} +\DeclareOption{top}{\renewcommand*{\mcaption@alignv}{t}} +\DeclareOption{bottom}{\renewcommand*{\mcaption@alignv}{b}} \ExecuteOptions{bottom} +\DeclareOption{v2.2}{% + \AtEndOfPackage{% + \let\margincap\mcaption@mcIIdotII% + \let\endmargincap\endmcaption@mcIIdotII% + \newcommand*{\margincapalign}{\mcaption@alignv} + }% +}% \ProcessOptions\relax \newlength{\margincapsep} \AtBeginDocument{% \setlength{\margincapsep}{\marginparsep}% } +\newcommand*{\mcaption@CaptionLong}{} +\newcommand*{\mcaption@CaptionShort}{} +\newcommand*{\mcaption@CaptionFlag}{} +\newcommand*{\mcaption@Label}{} +\newcommand*{\mcaption@LabelFlag}{} \newsavebox{\mcaption@ObjectBox} \newsavebox{\mcaption@CaptionBox} -\newlength{\mcaption@ObjectHeight} -\newlength{\mcaption@ObjectRaise} -\newlength{\mcaption@CaptionRaise} -\newlength{\mcaption@tempdima} -\newenvironment{margincap}[2][\mcaption@DefaultOpt]{% +\newenvironment{mcaption@mcIIdotII}[2][\mcaption@DefaultOpt]{% \def\mcaption@DefaultOpt{#2}% - \begin{lrbox}{\mcaption@CaptionBox}% - \setlength{\mcaption@tempdima}{\marginparsep}% - \addtolength{\mcaption@tempdima}{\marginparwidth}% - \addtolength{\mcaption@tempdima}{-\margincapsep}% - \begin{minipage}[\margincapalign]{\mcaption@tempdima}% - \caption[#1]{#2}% + \def\mcaption@CaptionShort{#1}% + \def\mcaption@CaptionLong{#2}% + \gdef\mcaption@CaptionFlag{t}% + \gdef\mcaption@LabelFlag{f}% + \begin{lrbox}{\mcaption@ObjectBox}% + \begin{minipage}{\linewidth}% +}{% \end{minipage}% \end{lrbox}% + \mcaption@align@boxes% + \mcaption@output@boxes% +}% +\newenvironment{mcaption@mcIIIdot}{% + \let\mcaption@origcaption\caption% + \let\caption\mcaption@caption% + \gdef\mcaption@CaptionFlag{f}% + \let\mcaption@origlabel\label% + \let\label\mcaption@label% + \gdef\mcaption@LabelFlag{f}% \begin{lrbox}{\mcaption@ObjectBox}% - \begin{minipage}[\margincapalign]{\linewidth}% + \begin{minipage}{\linewidth}% }{% \end{minipage}% \end{lrbox}% - \settoheight{\mcaption@ObjectHeight}{\usebox{\mcaption@ObjectBox}}% - \ifthenelse{\equal{\margincapalign}{t}}{% - \setlength{\mcaption@ObjectRaise}{-\mcaption@ObjectHeight}% - \setlength{\mcaption@ObjectHeight}{0pt}% - \settoheight{\mcaption@CaptionRaise}{\strut}% - }{% - \setlength{\mcaption@ObjectRaise}{0pt}% - \setlength{\mcaption@CaptionRaise}{0pt}% + \let\caption\mcaption@origcaption% + \let\label\mcaption@origlabel% + \mcaption@align@boxes% + \mcaption@output@boxes% +}% +\newenvironment{margincap}{}{}% +\let\margincap\mcaption@mcIIIdot% +\let\endmargincap\endmcaption@mcIIIdot% +\newcommand*{\mcaption@origcaption}{} +\newcommand*{\mcaption@origlabel}{} +\newcommand*{\mcaption@DefaultOpt}{} +\newcommand*{\mcaption@caption}[2][\mcaption@DefaultOpt]{% + \gdef\mcaption@DefaultOpt{#2}% + \gdef\mcaption@CaptionShort{#1}% + \gdef\mcaption@CaptionLong{#2}% + \gdef\mcaption@CaptionFlag{t}% + \ignorespaces +}% +\newcommand*{\mcaption@label}[1]{% + \gdef\mcaption@Label{#1}% + \gdef\mcaption@LabelFlag{t}% + \ignorespaces +}% +\newcommand*{\mcaption@align@boxes}{% + \begin{lrbox}{\mcaption@CaptionBox}% + \setlength{\@tempdima}{\marginparwidth}% + \addtolength{\@tempdima}{\marginparsep}% + \addtolength{\@tempdima}{-\margincapsep}% + \begin{minipage}{\@tempdima}% + \if\mcaption@CaptionFlag t% + \setlength{\abovecaptionskip}{0pt}% + \setlength{\belowcaptionskip}{0pt}% + \caption[\mcaption@CaptionShort]{\strut\mcaption@CaptionLong\strut}% + \fi% + \if\mcaption@LabelFlag t% + \label{\mcaption@Label}% + \fi% + \end{minipage}% + \end{lrbox}% +\sbox{\mcaption@ObjectBox}{% + \if\mcaption@alignv t\vtop + \else\vbox + \fi + {% + \vskip0pt% + \hbox{\usebox{\mcaption@ObjectBox}}% + \vskip0pt% + }% +}% +\sbox{\mcaption@CaptionBox}{% + \if\mcaption@alignv t\vtop + \else\vbox + \fi + {% + \vskip0pt% + \hbox{\usebox{\mcaption@CaptionBox}}% + \vskip0pt% + }% +}% +}% +\newcommand*{\mcaption@output@oddpage}{% + \makebox[\linewidth][l]{% + \usebox{\mcaption@ObjectBox}% + \hspace*{\margincapsep}% + \smash{\usebox{\mcaption@CaptionBox}}% }% +}% +\newcommand*{\mcaption@output@evenpage}{% + \makebox[\linewidth][r]{% + \smash{\usebox{\mcaption@CaptionBox}}% + \hspace*{\margincapsep}% + \usebox{\mcaption@ObjectBox}% + }% +}% + +\newcommand*{\mcaption@output@boxes}{% \if@twoside% \checkoddpage% + \ifoddpage% + \mcaption@output@oddpage% + \else% + \mcaption@output@evenpage% + \fi% \else% - \cpoddpagetrue% - \fi% - \ifcpoddpage% - \makebox[\linewidth][l]{% - \raisebox{\mcaption@ObjectRaise}[\mcaption@ObjectHeight]{% - \usebox{\mcaption@ObjectBox}% - }% - \hspace*{\margincapsep}% - \raisebox{\mcaption@CaptionRaise}[0pt][0pt]{% - \usebox{\mcaption@CaptionBox}% - }% - }% - \else% - \makebox[\linewidth][r]{% - \raisebox{\mcaption@CaptionRaise}[0pt][0pt]{% - \usebox{\mcaption@CaptionBox}% - }% - \hspace*{\margincapsep}% - \raisebox{\mcaption@ObjectRaise}[\mcaption@ObjectHeight]{% - \usebox{\mcaption@ObjectBox}% - }% - }% + \mcaption@output@oddpage% \fi% }% \endinput -- cgit v1.2.3