% \CheckSum{220}
%
% \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>
  [2009/03/13 v3.0 Put captions into the outer document 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}

\author{Stephan Hennig}
\title{mcaption test file}
\maketitle
\listoffigures
\listoftables

\chapter{Demonstration of the mcaption package}
\section{This is one-column mode}
\blindtext[1]

\begin{wrapfigure}{o}{5cm}
  \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}
    \centering
    \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}
\blindtext[1]

\begin{wrapfigure}{o}{2cm}
  \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}
    \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}
%</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
%   into the outer document margin with either a top or bottom
%   alignment.
% \end{abstract}
%
%
% \section{Package options}\label{sec:options}
%
% 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}\label{sec:usage}
%
% 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}
%    \centering
%    \includegraphics{picture}
%    \caption[short caption text]{long caption text}
%    \label{fig:pic}
%  \end{margincap}
%\end{figure}
% \end{verbatim}
%
% 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}\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 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 \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 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{Known Problems}\label{sec:problems}
% 
% \begin{enumerate}
%
% \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 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
% \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}
%
% \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[strict]{changepage}
%    \end{macrocode}
%
% \begin{macro}{\mcaption@alignv}
%   This macro is used by options |bottom| and |top|.
%    \begin{macrocode}
\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}{New package options `bottom' and `top'.}
%    \begin{macrocode}
\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.
%    \begin{macrocode}
\newlength{\margincapsep}
\AtBeginDocument{%
  \setlength{\margincapsep}{\marginparsep}%
}
%    \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}
\newsavebox{\mcaption@ObjectBox}
\newsavebox{\mcaption@CaptionBox}
%    \end{macrocode}
%
%
% \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}
\newenvironment{mcaption@mcIIdotII}[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}
%
% 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@CaptionShort{#1}%
  \def\mcaption@CaptionLong{#2}%
  \gdef\mcaption@CaptionFlag{t}%
  \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}{\linewidth}%
}{%
    \end{minipage}%
  \end{lrbox}%
%    \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}{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}{\linewidth}%
}{%
    \end{minipage}%
  \end{lrbox}%
%    \end{macrocode}
%
% 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}
%
%
% \begin{macro}{\mcaption@output@oddpage}
%   This macro first outputs the contents and then the caption box.
%    \begin{macrocode}
\newcommand*{\mcaption@output@oddpage}{%
  \makebox[\linewidth][l]{%
    \usebox{\mcaption@ObjectBox}%
    \hspace*{\margincapsep}%
    \smash{\usebox{\mcaption@CaptionBox}}%
  }%
}%  
%    \end{macrocode}
% \end{macro}
%
% \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}
%

% \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{macro}
%
% \iffalse
%</package>
% \fi
% \Finale