% \iffalse
%% File: sidecap.dtx 
%%
%
%<package>\NeedsTeXFormat{LaTeX2e}
%<package>\ProvidesPackage{sidecap}
%<package>         [2000/02/04 v1.5d SideCap Package (RN/HjG)] 
%
%<*driver>
\documentclass{ltxdoc}
\usepackage{sidecap}
\GetFileInfo{sidecap.sty}
\begin{document}
   \DocInput{sidecap.dtx}
\end{document}
%</driver>
%
% Copyright  1997--2000 Rolf Niepraschk and Hubert G"a"slein. 
% This program can be redistributed and/or modified under the terms
% of the LaTeX Project Public License Distributed from CTAN
% archives in directory macros/latex/base/lppl.txt; either
% version 1 of the License, or any later version.
%
% \fi
%
% \CheckSum{390}
%
%% \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         \~}
%%
%% \iffalse meta-comment
%% ===================================================================
%%  @LaTeX-package-file{
%%     author          = {Rolf Niepraschk, Hubert G\"{a}\ss{}lein}
%%     version         = "1.5d",
%%     date            = "04 February 2000",
%%     filename        = "sidecap.sty",
%%     email           = "niepraschk@ptb.de (INTERNET)",
%%     codetable       = "ISO/ASCII",
%%     keywords        = "LaTeX2e, sideways caption, \SCfigure, \SCtable",
%%     supported       = "yes",
%%     docstring       = "LaTeX package which defines new environments
%%                        for easy typesetting sideways captions and
%%                        wide floats".
%%  }
%% ===================================================================
%% \fi
%
%  \changes{v1.0}{1997/01/04}{New}
%  \changes{v1.1}{1997/05/01}{First public version}
%  \changes{v1.2 (HjG)}{1998/01/29}{Proposal for amendments}
%  \changes{v1.3 (RN/HjG)}{1998/01/29}{Unsuccessful attempt to make
%               star-forms work}
%  \changes{v1.4c (HjG)}{1998/06/05}{Successful (?) attempt to make
%               star-forms work, plus some amendments}
%  \changes{v1.4d (RN)} {1998/06/05}{New (LPPL) license}
%  \changes{v1.5a (RN)}{1999/07/18}{New Option `wide', some small changes}
%  \changes{v1.5b (RN)}{1999/10/31}{New Option `raggedright' as suggested by 
%               James Kilfiger <mapdn@csv.warwick.ac.uk>}
%  \changes{v1.5c (RN)}{1999/11/06}{New option `wide'}
%  \changes{v1.5d (RN/HjG)}{2000/02/04}{Compatibility with `hyperref',
%               thanks to Heiko Oberdiek}
%  \changes{v1.5d (RN/HjG)}{2000/03/16}{Slight amendments to documentation.}
%
%  \MakeShortVerb{\#}
%  \setlength\parindent{0pt}
%
%  \IndexPrologue{^^A
%     \section*{Index}^^A
%     \markboth{Index}{Index}^^A
%     Numbers written in \emph{italic} refer to the page where the
%     corresponding entry is described, the ones
%     \underline{underlined} to the definition, the rest to the places
%     where the entry is used.}
%
%  \GlossaryPrologue{^^A
%     \section*{Index}^^A
%     \markboth{Index}{Index}^^A
%     Numbers written in \emph{italic} refer to the page where the
%     corresponding entry is described, the ones
%     \underline{underlined} to the definition, the rest to the places
%     where the entry is used.}
%
% ^^A -----------------------------
%
%  \title{\unskip
%           The \textsf{sidecap} package^^A
%        }
%  \author{Rolf Niepraschk {\normalsize (\texttt{niepraschk@ptb.de})}\and 
%          Hubert G\"a{\ss}lein}

%  \date{\fileversion\ -- \filedate}
%  \maketitle
%
%
% ^^A -----------------------------
%
%
%  \begin{abstract}
%     This package defines the new environments #SCfigure# and #SCtable#,
%     analogous to #figure# and #table#, which make it easy to 
%     typeset captions sideways.
%
%     Additionally, a #wide# environment is defined; it allows to use
%     the margin area, e.\,g., for figures wider than #\textwidth#.
%
%  \iffalse
%     (???)
%     Support for other types of floating environments is provided,
%     e.\,g., as available by the #newfloat# package.
%  \fi
%  \end{abstract}
%
%  \pagestyle{headings}
%
% ^^A -----------------------------
%
% ^^A \tableofcontents
%
% ^^A -----------------------------
%
%  \section{Introduction}
%
%  In some cases it may be useful to typeset the caption aside the figure or
%  the table. For this purpose the package \textsf{sidecap} defines the new 
%  environments #SCfigure# and #SCtable#. The figure or the table and the 
%  caption are put into two minipages that are positioned side by side and
%  centered as a whole. The space between the minipages is #\columnsep#. The 
%  correct positioning with respect to left and right pages requires at least 
%  two compilation runs.
%
% ^^A -----------------------------
%
%  \section{Usage}
%
%  #\usepackage[#\meta{option}#]{sidecap}#
%
%  \smallskip  
%
%  #\begin{SCtable}  [#\meta{relwidth}#][#\meta{float}#] ... # 
%  #\end{SCtable}#
%
%  #\begin{SCfigure} [#\meta{relwidth}#][#\meta{float}#] ... #
%  #\end{SCfigure}#
%
%  \smallskip
%  #\begin{SCtable*} [#\meta{relwidth}#][#\meta{float}#] ... # 
%  #\end{SCtable*}#
%
%  #\begin{SCfigure*}[#\meta{relwidth}#][#\meta{float}#] ... #
%  #\end{SCfigure*}#
%
%  \medskip
%  \begin{center}
%  \begin{tabular}{r@{~}p{.75\linewidth}}
%    \meta{option} --   & #outercaption# (default): Caption appears left on 
%                         left pages and right on right 
%                         pages. \\[.25\baselineskip]
%                       & #innercaption#: Caption appears right on left pages 
%                         and left on right pages.\\[.25\baselineskip]
%                       & #leftcaption#, #rightcaption#: Caption is always on the
%                         left or right, respectively.\\[.25\baselineskip]
%                       & #wide#: The floating objects may extend into the
%                         margin area.                       
%                         \\[.25\baselineskip]
%                       & #raggedright#: Better justification for small captions. 
%                         The \textsf{ragged2e} package is used if available.
%                         \\[.5\baselineskip]
%    \meta{relwidth} -- & optional; caption width relative to the width of the 
%                         figure or table. A large value (e.g., 50) reserves
%                         the maximum width that is possible. 
%                         Default is 1.0\,.\\[.5\baselineskip]
%    \meta{float} --    & optional; like the floating position parameter of the
%                         original table\slash figure environments. 
%  		          Default is #tbp#. 		          
%  \end{tabular}
%  \end{center}
%
%  \medskip
%  #\begin{wide} ... \end{wide}#
%
%  The #wide# environment may be used inside #figure# and #table#
%  environments as well as in the normal text.
%
% ^^A -----------------------------
%
%  \section{Required packages}
%
%  This package requires the standard \LaTeX\ package \textsf{ifthen}.
%
% ^^A -----------------------------
%
%  \section{Supported packages}
%
%  This package is compatible \LaTeX\ package \textsf{hyperref}
%  (tested with version 6.69c as of 2000/01/22).
%
%  If the #raggedright# package option has been given, then captions
%  will be set with ragged right margin. The \textsf{ragged2e} package
%  will be used if it can be found.
%
%  \iffalse
%  This package supports the \LaTeX\ package \textsf{newfloat},
%  coming soon \dots\ (?)
%  \fi
%
% ^^A -----------------------------
%
%  \StopEventually{^^A
%     \PrintIndex\PrintChanges
%     ^^A Make sure that the index is not printed twice
%     ^^A (ltxdoc.cfg might have a second \PrintIndex command)
%     \let\PrintChanges\relax
%     \let\PrintIndex\relax
%     }
%
% ^^A -----------------------------
%
%  \section{The implementation}
%
%  \subsection{Register allocation and auxiliary macros}
%
%    \begin{macrocode}
%<*package>

\RequirePackage{ifthen}

\newlength{\SC@BOXWD} \newlength{\SC@CAPWD} \newlength{\SC@tempdim}
\newcounter{SC@C} \newsavebox{\SC@BOX} \newcommand*{\SC@FLOAT}{}
\newcommand*{\SC@IDENT}{SC@\number\value{SC@C}}

\newcommand*{\isSC@WIDEi}[2]{#2}  %default: false
\newcommand*{\isSC@WIDEii}[2]{#2} %default: false

\let\SC@caption=\caption \let\SC@label=\label%

\let\SC@justify=\relax
%    \end{macrocode}  
%
%  \subsection{Package \textsf{hyperref} compatibility}
%
%  The following work-around for \textsf{hyperref}
%  is due to Heiko Oberdiek.
%    \begin{macrocode}  
%% From Heiko Oberdiek, 2000/01/24  
\newcommand*\@getsecondarg{}% LaTeX-check if already defined
\long\def\@getsecondarg#1#2#3\@nil{#2}  

\providecommand*{\getpagenumber}[1]{%
  \expandafter\@getpagenumber\csname r@#1\endcsname{#1}%
}

\newcommand*{\@getpagenumber}[2]{%
  \ifx#1\relax
    \protect\G@refundefinedtrue % LaTeX: rerun warning
    \@latex@warning{Reference `#2' on page \thepage\space
      undefined}%
    0%
  \else
    \expandafter\@getsecondarg#1\@nil
  \fi
}
%%---------------------------------------
%    \end{macrocode}
% Note: The #\pageref# doesn't work with \textsf{hyperref} \dots \mbox{:-(}
%    \begin{macrocode}
\newcommand*{\isSC@ODD}[2]{%
%  \ifthenelse{\isodd{\pageref{\SC@IDENT}}}{#1}{#2}}  
 \ifthenelse{\isodd{\getpagenumber{\SC@IDENT}}}{#1}{#2}}  
%    \end{macrocode}  
%
%
%  \subsection{Option processing}
%
%    \begin{macrocode}  
\DeclareOption{innercaption}{\renewcommand*{\SC@FLOAT}[2]{%
  \isSC@ODD{{#1}\hspace{\columnsep}{#2}} {{#2}\hspace{\columnsep}{#1}}}}

\DeclareOption{outercaption}{%
  \renewcommand*{\SC@FLOAT}[2]{%
  \isSC@ODD{{#2}\hspace{\columnsep}{#1}} {{#1}\hspace{\columnsep}{#2}}}}

\DeclareOption{rightcaption}{%
  \renewcommand*{\SC@FLOAT}[2]{{#2}\hspace{\columnsep}{#1}}}

\DeclareOption{leftcaption}{%
  \renewcommand*{\SC@FLOAT}[2]{{#1}\hspace{\columnsep}{#2}}}
  
\DeclareOption{wide}{%
   \renewcommand*{\isSC@WIDEi}[2]{\if@twocolumn #2\else #1\fi}
   \renewcommand*{\isSC@WIDEii}[2]{#1}}

\DeclareOption{raggedright}{%
   \let\SC@justify=\raggedright}

\ExecuteOptions{outercaption} 

\ProcessOptions

\ifx\SC@justify\raggedright
  \IfFileExists{ragged2e.sty}{%
    \RequirePackage[OriginalCommands]{ragged2e}%
    \let\SC@justify=\RaggedRight
    }{} 
\fi

%    \end{macrocode}
%
%
%  \subsection{User-level macros (environments)}
%
% \begin{environment}{SCfigure}
% Simply passes the first (optional) parameter and the required one,
% in this case `figure', to #SC@float#\,.
% The figure caption should be bottom aligned.
%    \begin{macrocode}

\newenvironment{SCfigure}{\SC@float[b]{figure}}{\endSC@float}
\newenvironment{SCfigure*}{\SC@dblfloat[b]{figure}}{\endSC@dblfloat}

%    \end{macrocode}
% \end{environment}
%
% \begin{environment}{SCtable}
% Simply passes the first (optional) parameter and the required one,
% in this case `table', to #SC@float#\,.
% The table caption should be top aligned.
%    \begin{macrocode}

\newenvironment{SCtable}{\SC@float[t]{table}}{\endSC@float}
\newenvironment{SCtable*}{\SC@dblfloat[t]{table}}{\endSC@dblfloat}

%    \end{macrocode} 
% \end{environment}
%
% \begin{environment}{wide}
% This is an environment that allows to extend the width of the
% text body (or of a floating environment) by using the margin space.
%
% It shouldn't be used in twocolumn text.
%    \begin{macrocode} 

\newenvironment{wide}%
{%
  \setlength{\@tempdima}{\linewidth}
  \addtolength{\@tempdima}{\marginparwidth}%
  \addtolength{\@tempdima}{\marginparsep}%  
  \begin{lrbox}{\SC@BOX}% ???
    \begin{minipage}{\@tempdima}% ???
}%
{% 
    \end{minipage}% ???
  \end{lrbox}% ???
  \stepcounter{SC@C}\SC@label{\SC@IDENT}% 
  \isSC@ODD{\def\SC@hpos{l}}{\def\SC@hpos{r}}%	
  \noindent\makebox[\linewidth][\SC@hpos]{\usebox{\SC@BOX}}% 
}

%    \end{macrocode}
% \end{environment}
%
%
%  \subsection{Internal macros}
%
%  \subsubsection{Collecting arguments}
%
% The new internal float environment, similar\slash analogous to
% \LaTeX's #@float# environment.
%
% \smallskip
% Syntax:
%  #\SC@float[#\meta{vpos}#]{#\meta{name}#}[#\meta{relwd}#][#\meta{fps}#]#
%
% \begin{itemize}
% \item
%    Parameter \meta{vpos} (optional) is the vertical positioning of the
%    caption.
% \item
%    Parameter \meta{name} (required) is the name of the `original' \LaTeX\
%    floating environment (e.g., `figure' or `table').
%  \iffalse
%    ; or one defined with the
%    #newfloat# package.
%  \fi
% \item
%    Parameter \meta{relwd} (optional) is the desired relative width of the
%    caption.
% \item
%    Parameter \meta{fps} (optional) is the usual \LaTeX\ float positioning
%    specifier.
% \end{itemize}
%
% The usual `cascading' programming style is applied
% (cf.\ \LaTeX's #\@float#).
%
% \begin{macro}{\SC@float}
% Initially, the first optional parameter is checked for.
%    \begin{macrocode}
\def\SC@float{\@ifnextchar[\SC@xfloat{\SC@xfloat[c]}}
%    \end{macrocode}  
% \end{macro}
% \begin{macro}{\SC@xfloat}
% Then the first and second parameters are consumed and the third one is
% checked for.
%    \begin{macrocode}
\def\SC@xfloat[#1]#2{\@ifnextchar[%
  {\SC@yfloat{#1}{#2}}%
  {\SC@zfloat{#1}{#2}{1.0}[\@nameuse{fps@#2}]}}
%    \end{macrocode}  
% \end{macro}
% \begin{macro}{\SC@yfloat}
% Again, the fourth (and last) parameter is checked for.
%    \begin{macrocode}
\def\SC@yfloat#1#2[#3]{\@ifnextchar[%
  {\SC@zfloat{#1}{#2}{#3}}%
  {\SC@zfloat{#1}{#2}{#3}[\@nameuse{fps@#2}]}}
%    \end{macrocode}  
% \end{macro}
%
%
%  \subsubsection{Capturing the float's contents}
%
% \begin{macro}{\SC@zfloat}
% Finally, here is the macro that does all the work.
%    \begin{macrocode}
\def\SC@zfloat#1#2#3[#4]{%
  \def\SC@vpos{#1}%
  \expandafter\edef\csname fps@#2\endcsname{#4}%
  \def\SC@captype{#2}%
  \ifx#3\@empty\def\SC@fraction{1}\else\def\SC@fraction{#3}\fi%
%    \end{macrocode}  
% The #\caption# and #\label# commands must be redefined.
%    \begin{macrocode}  
  \let\SC@CAPtext\@empty \let\SC@OPTCAPtext\@empty \let\SC@LABtext\@empty% 
  \renewcommand\caption[2][]{\gdef\SC@OPTCAPtext{##1}%
  \gdef\SC@CAPtext{\SC@justify##2}}%
  \renewcommand\label[1]{\gdef\SC@LABtext{##1}}% 
  \@namedef{fnum@#2}{\mbox{\@nameuse{#2name}~\@nameuse{the#2}}}%
%    \end{macrocode}  
% Save the figure or table (or whatever) in a box.
%    \begin{macrocode}  
  \begin{lrbox}{\SC@BOX}%
}%

%    \end{macrocode} 
% \end{macro}
%
% \begin{macro}{\SC@dblfloat}
% Analogous to \LaTeX's #\@dblfloat#.
%    \begin{macrocode}
\def\SC@dblfloat{%
  \if@twocolumn\let\reserved@a\SC@dbflt\else\let\reserved@a\SC@float\fi
  \reserved@a}
\def\SC@dbflt{\SC@float}  
%    \end{macrocode} 
% \end{macro}
%
%
%  \subsubsection{Output the float's contents}
%
% \begin{macro}{\endSC@float}
% Outputs the figure or table (or whatever) and the caption. 
%    \begin{macrocode} 
\def\endSC@float{%   
  \end{lrbox}%
%<+debug>  \typeout{onecolumn}%
  \let\isSC@WIDE\isSC@WIDEi%
  \def\@FLOAT{\@float}\def\end@FLOAT{\end@float}%
  \isSC@WIDE%
    {\setlength{\@tempdima}{\textwidth}%
     \addtolength{\@tempdima}{\marginparwidth}%
     \addtolength{\@tempdima}{\marginparsep}}%
    {\setlength{\@tempdima}{\columnwidth}}
  \endSC@FLOAT{\@tempdima}}%
%    \end{macrocode} 
% \end{macro} 
% \begin{macro}{\endSC@dblfloat}
% Ditto for #*#\mbox{-}forms of floats.
%    \begin{macrocode} 
\def\endSC@dblfloat{%   
  \end{lrbox}%
%<+debug>  \typeout{twocolumn}%
  \let\isSC@WIDE\isSC@WIDEii%
  \def\@FLOAT{\@dblfloat}\def\end@FLOAT{\end@dblfloat}%
  \isSC@WIDE%
    {\setlength{\@tempdima}{\textwidth}%
     \addtolength{\@tempdima}{\marginparwidth}% 
     \addtolength{\@tempdima}{\marginparsep}}%
    {\setlength{\@tempdima}{\textwidth}}
  \endSC@FLOAT{\@tempdima}}%
%    \end{macrocode}
% \end{macro} 
% \begin{macro}{\endSC@FLOAT}
% Sets the caption width. If caption width plus figure\slash table width
% (plus separation space) is too large then the caption width is set equal
% to the remaining width. 
%    \begin{macrocode}
\def\endSC@FLOAT#1{% 
  \setlength\SC@tempdim{#1}%
  % Kann man auf dieses Laengenregister verzichten? (RN) <****>
  \settowidth\SC@BOXWD{\usebox\SC@BOX}% 
  \setlength\SC@CAPWD{\SC@fraction\SC@BOXWD}%
  \setlength\@tempdima{\SC@BOXWD}%
  \addtolength\@tempdima{\SC@CAPWD}%
  \addtolength\@tempdima{\columnsep}%      
  \ifthenelse{\lengthtest{\@tempdima>\SC@tempdim}}%
    {\addtolength\SC@CAPWD{-\@tempdima}\addtolength\SC@CAPWD{\SC@tempdim}}{}%
%    \end{macrocode}  
% \begin{macro}{\@FLOAT}
% Calls the \LaTeX\ float command with the two minipages inside a main minipage.
% \end{macro}
%    \begin{macrocode}      
  \@FLOAT{\SC@captype}% 
    \abovecaptionskip\z@skip
    \belowcaptionskip\z@skip
%    \end{macrocode}  
% Creates a label for each figure or table (etc.)\ for later determination if
% the page is odd or even. The counter #SC@C# must be incremented before.
%    \begin{macrocode}    
    \stepcounter{SC@C}\SC@label{\SC@IDENT}%
%    \end{macrocode}
% \begin{macro}{\isSC@WIDE}
% ^^A ???
% \end{macro}
%    \begin{macrocode} 
    \isSC@WIDE%
      {\ifthenelse{\lengthtest{\@tempdima>\textwidth}}%
        {\isSC@ODD{\def\SC@hpos{l}}{\def\SC@hpos{r}}}%
        {\def\SC@hpos{c}}%
       \setlength{\@tempdimc}{\textwidth}}%
      {\setlength{\@tempdimc}{\SC@tempdim}\def\SC@hpos{c}}%   
%    \end{macrocode}
% ^^A ??? 
%    \begin{macrocode} 
    \makebox[\@tempdimc][\SC@hpos]{%
%    \end{macrocode}
% \begin{macro}{\SC@FLOAT}
%   Has two parameters. The first parameter is the minipage with the caption 
%   text inside and the last parameter is the minipage with the body of the figure 
%   or table ^^A (or whatever floating environment object) 
%   inside.
% \end{macro}
%    \begin{macrocode} 
      \SC@FLOAT%
        {\begin{minipage}[\SC@vpos]{\SC@CAPWD}%
           \ifthenelse{\equal{\SC@OPTCAPtext}{\@empty}}%
             {\SC@caption{\expandafter\protect\SC@CAPtext}}% 
             {\SC@caption[\expandafter\protect\SC@OPTCAPtext]%
                            {\expandafter\protect\SC@CAPtext}}%
           \unskip%
           \ifthenelse{\equal{\SC@LABtext}{\@empty}}%
             {}{\SC@label{\expandafter\protect\SC@LABtext}}%  
         \end{minipage}}%
        {\begin{minipage}[\SC@vpos]{\SC@BOXWD}% 
           \offinterlineskip%
           \kern0pt\relax
           \usebox{\SC@BOX}%
         \end{minipage}}%
    }% 
  \end@FLOAT%
}
%</package>
%    \end{macrocode}
% \end{macro} 
%
% ^^A -----------------------------
%
%  \Finale
