% \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
