diff options
author | Karl Berry <karl@freefriends.org> | 2006-01-11 23:54:57 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2006-01-11 23:54:57 +0000 |
commit | 791005a5052ab94b6019b561549dac222d878168 (patch) | |
tree | ee44fee6980f85e7e488b5093b358fab157a867e | |
parent | c4a9f63c16525f3182bed5b373b816f6b49d6041 (diff) |
trunk/Master/texmf-dist/source/latex/mcaption
git-svn-id: svn://tug.org/texlive/trunk@376 c570f23f-e606-0410-a88d-b1316a301751
-rw-r--r-- | Master/texmf-dist/source/latex/mcaption/mcaption.dtx | 445 | ||||
-rw-r--r-- | Master/texmf-dist/source/latex/mcaption/mcaption.ins | 62 |
2 files changed, 507 insertions, 0 deletions
diff --git a/Master/texmf-dist/source/latex/mcaption/mcaption.dtx b/Master/texmf-dist/source/latex/mcaption/mcaption.dtx new file mode 100644 index 00000000000..eec0b552d17 --- /dev/null +++ b/Master/texmf-dist/source/latex/mcaption/mcaption.dtx @@ -0,0 +1,445 @@ +% \CheckSum{112} +% +% \iffalse meta-comment +% +% Copyright (C) 2005 by Stephan Hennig <stephanhennig@arcor.de> +% ------------------------------------------------------------- +% +% This file 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. +% +% \fi +% +% \iffalse +%<*dtx> +\ProvidesFile{mcaption.dtx} +%</dtx> +%<package>\ProvidesPackage{mcaption} +%<*dtx|package> + [2005/09/30 v2.2 Put captions in margin (SH)] +%</dtx|package> +%<package>\NeedsTeXFormat{LaTeX2e}[1999/12/01] +% +%<*driver> +\documentclass{ltxdoc} +\EnableCrossrefs +\CodelineIndex +\RecordChanges +\begin{document} + \DocInput{mcaption.dtx} + \PrintChanges + \PrintIndex +\end{document} +%</driver> +% +%<*example> +\listfiles +\documentclass{book} +\usepackage{wrapfig} +\usepackage[top]{mcaption} +\usepackage[ + font={footnotesize,it}, + labelfont=bf, + justification=raggedright] +{caption}[2005/06/28] +\usepackage[english]{babel} +\usepackage{blindtext} +\begin{document} +\setlength{\margincapsep}{3\columnsep} +\chapter{Demonstration of the mcaption package} +\section{This is one column mode} +\blindtext[1] + +\begin{wrapfigure}{o}{5cm} + \begin{margincap}{A wrapfigure caption in the outer margin.} + \rule{5cm}{2cm} + \end{margincap} +\end{wrapfigure} +\blindtext[1] +\begin{table} + \begin{margincap}{A table caption in the outer margin.} + \centering +%%% Note the alignment specifier! + \begin{tabular}[\margincapalign]{@{}lr@{}} + foo & 7\\ + bar & 21 \\ + baz & 23 \\ + \end{tabular} + \end{margincap} +\end{table} + +\twocolumn +\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!} + \rule{2cm}{1cm} + \end{margincap} +\end{wrapfigure} +\blindtext[5] +\begin{figure*} + \begin{margincap}{A figure caption in the outer margin.} + \centering + \rule{10cm}{2cm} + \end{margincap} +\end{figure*} +\end{document} +%</example> +% \fi +% +% \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 \~} +% +% +% \GetFileInfo{mcaption.dtx} +% +% +% \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. +% \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} +% +% +% \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. +% +% 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.}: +% +% \begin{verbatim} +%\begin{figure} +% \begin{margincap}[short caption]{margin caption} +% \centering +% \includegraphics{picture} +% \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. +% +% +% \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{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|. +% +% \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 +% +% \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. +% +% +% \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} +% +% \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 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. +% \end{enumerate} +% +% \section{Bugs} +% +% If you find bugs feel free to contact me at +% \texttt{stephanhennig@arcor.de}. +% +% +% \DoNotIndex{\begin,\end,\def,\RequirePackage,\else,\fi,\equal,\relax} +% +% +% \StopEventually{\PrintChanges} +% +% +% \changes{v2.0}{2005/09/20}{Prepared .dtx package.} +% +% +% \iffalse +%<*package> +% \fi +% \section{Implementation} +% +% Make sure the |ifthen| and |chngpage| packages are loaded. +% \begin{macrocode} +\RequirePackage{ifthen} +\RequirePackage{chngpage} +% \end{macrocode} +% +% \begin{macro}{\margincapalign} +% Provide this macro to store the vertical alignment specifier for +% user access (see section~\ref{sec:tables}). +% \begin{macrocode} +\newcommand*{\margincapalign}{} +% \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'.} +% \begin{macrocode} +\DeclareOption{top}{\renewcommand*{\margincapalign}{t}} +\DeclareOption{bottom}{\renewcommand*{\margincapalign}{b}} +\ExecuteOptions{bottom} +\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. +% \begin{macrocode} +\newlength{\margincapsep} +\AtBeginDocument{% + \setlength{\margincapsep}{\marginparsep}% +} +% \end{macrocode} +% \end{macro} +% +% Declare boxes to store the contents and caption of a |margincap| +% environment. +% \begin{macrocode} +\newsavebox{\mcaption@ObjectBox} +\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{macrocode} +\newlength{\mcaption@ObjectHeight} +\newlength{\mcaption@ObjectRaise} +\newlength{\mcaption@CaptionRaise} +\newlength{\mcaption@tempdima} +% \end{macrocode} +% +% \begin{environment}{margincap} +% Provide margincap environment. +% \changes{v2.1}{2005/09/29}{Now works with standard classes.} +% \begin{macrocode} +\newenvironment{margincap}[2][\mcaption@DefaultOpt]{% +% \end{macrocode} +% +% Call |\caption| with or without optional argument. Trick taken +% from UK-\TeX-FAQ, question 286: `Optional arguments like +% |\section|'. +% \begin{macrocode} + \def\mcaption@DefaultOpt{#2}% +% \end{macrocode} +% +% Put caption in box |\mcaption@CaptionBox| with requested alignment +% for later use. +% \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}% + \end{minipage}% + \end{lrbox}% +% \end{macrocode} +% +% Put user stuff into box |\mcaption@ObjectBox| of width +% |\linewidth| with requested alignment. +% \begin{macrocode} + \begin{lrbox}{\mcaption@ObjectBox}% + \begin{minipage}[\margincapalign]{\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}% + }% +% \end{macrocode} +% +% 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{macrocode} + \if@twoside% + \checkoddpage% + \else% + \cpoddpagetrue% + \fi% +% \end{macrocode} +% +% 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% +% \end{macrocode} +% +% We're done. +% \begin{macrocode} +}% +% \end{macrocode} +% \end{environment} +% +% \iffalse +%</package> +% \fi +% \Finale diff --git a/Master/texmf-dist/source/latex/mcaption/mcaption.ins b/Master/texmf-dist/source/latex/mcaption/mcaption.ins new file mode 100644 index 00000000000..a37eac64a0b --- /dev/null +++ b/Master/texmf-dist/source/latex/mcaption/mcaption.ins @@ -0,0 +1,62 @@ +%% +%% Copyright (C) 2005 by Stephan Hennig <stephanhennig@arcor.de> +%% +%% This file 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. +%% + +\input docstrip.tex +\keepsilent + +\usedir{tex/latex/mcaption} + +\preamble + +This is a generated file. + +Copyright (C) 2005 by Stephan Hennig <stephanhennig@arcor.de> + +This file 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. + +\endpreamble + +\generate{% + \file{mcaption.sty}{\from{mcaption.dtx}{package}}% + \file{example.tex}{\from{mcaption.dtx}{example}}% +} + +\obeyspaces +\Msg{*************************************************************} +\Msg{* *} +\Msg{* To finish the installation you have to move the following *} +\Msg{* file into a directory searched by TeX: *} +\Msg{* *} +\Msg{* mcaption.sty *} +\Msg{* *} +\Msg{* To produce the documentation run *} +\Msg{* *} +\Msg{* latex mcaption.dtx *} +\Msg{* makeindex -s gind.ist -o mcaption.ind mcaption.idx *} +\Msg{* makeindex -s gglo.ist -o mcaption.gls mcaption.glo *} +\Msg{* latex mcaption.dtx *} +\Msg{* *} +\Msg{* Happy TeXing! *} +\Msg{* *} +\Msg{*************************************************************} + +\endbatchfile |