summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2006-01-11 23:54:57 +0000
committerKarl Berry <karl@freefriends.org>2006-01-11 23:54:57 +0000
commit791005a5052ab94b6019b561549dac222d878168 (patch)
treeee44fee6980f85e7e488b5093b358fab157a867e
parentc4a9f63c16525f3182bed5b373b816f6b49d6041 (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.dtx445
-rw-r--r--Master/texmf-dist/source/latex/mcaption/mcaption.ins62
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