% \iffalse
%% File: sidecap.dtx Copyright (C) 1997-98 Rolf Niepraschk/Hubert G"a"slein
%%
%
%<package>\NeedsTeXFormat{LaTeX2e}
%<package>\ProvidesPackage{sidecap}
%<package>         [1999/05/11 v1.4d SideCap Package (RN/HjG)] 
%
%<*driver>
\documentclass{ltxdoc}
\usepackage{sidecap}
\GetFileInfo{sidecap.sty}
\begin{document}
   \DocInput{sidecap.dtx}
\end{document}
%</driver>
%
% Copyright  1999 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{243}
%
%% \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.4d",
%%     date            = "05 June 1998",
%%     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".
%%  }
%% ===================================================================
%% \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)}{1999/05/11}{New License}
%
%  \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.}
%
% ^^A -----------------------------
%
%  \title{\unskip
%           The \textsf{sidecap} package^^A
%        }
%  \author{Rolf Niepraschk {(\normalsize \texttt{niepraschk@ptb.de})}\and 
%          Hubert G\"a{\ss}lein {(\normalsize \texttt{gaesslein@bned.com})}}

%  \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.
%
%  \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#: caption is always on the
%                         left.\\[.25\baselineskip]
%                       & #rightcaption#: caption is always on the
%                         right.\\[.25\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}
% ^^A -----------------------------
%
%  \section{Required packages}
%
%  The package requires the standard \LaTeX\ package \textsf{ifthen}.
%
% ^^A -----------------------------
%
%  \iffalse
%  \section{Supported packages}
%
%  The 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}
%
%    \begin{macrocode}
%<*package>
%    \end{macrocode}
%
%    \begin{macrocode}
\typeout{Package: SideCap v1.4d <1999/05/11> (RN/HjG)}

\RequirePackage{ifthen}

\newlength{\SC@BOXWD} \newlength{\SC@CAPWD}
\newcounter{SC@C}
\newsavebox{\SC@BOX} \newcommand\SC@FLOAT{}

\newcommand\SC@LABEL{SC@LABEL:\number\value{SC@C}}

%    \end{macrocode}  
% \begin{macro}{\SC@FLOAT}
%   Has three parameters. The first is the label that determines if the current
%   page is odd or even. This parameter is only used with the options
%   #outercaption# or #innercaption#. The second 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}  
\DeclareOption{innercaption}{%
  \renewcommand\SC@FLOAT[3]{\ifthenelse{\isodd{\pageref{#1}}}
    {{#2}\hspace{\columnsep}{#3}} {{#3}\hspace{\columnsep}{#2}}}}

\DeclareOption{outercaption}{%
  \renewcommand\SC@FLOAT[3]{\ifthenelse{\isodd{\pageref{#1}}}
    {{#3}\hspace{\columnsep}{#2}} {{#2}\hspace{\columnsep}{#3}}}}

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

\DeclareOption{leftcaption}{%
  \renewcommand\SC@FLOAT[3]{{#2}\hspace{\columnsep}{#3}}}

\ExecuteOptions{outercaption} \ProcessOptions

%    \end{macrocode}
% \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{macro}{\SC@float}
% The new float environment, similar\slash analogous to \LaTeX's #@float#
% environment.
% Syntax:
%
%  #\SC@float[#\meta{vpos}#]{#\meta{name}#}[#\meta{relwd}#][#\meta{fps}#]#
%
% Parameter~1 (optional) is the vertical positioning of the caption.
% Parameter~2 (required) is the name of the `original' \LaTeX\ floating
% environment (e.g., `figure' or `table').
% \iffalse
% ; or one defined with the
% #newfloat# package.
% \fi
% Parameter~3 (optional) is the desired relative width of the caption.
% Parameter~4 (optional) is the usual \LaTeX\ float positioning specifier.
%
% The usual `cascading' programming style is applied
% (cf.\ \LaTeX's #\@float#).
%
% Initially, the first optional parameter is checked for.
%    \begin{macrocode}
\def\SC@float{\@ifnextchar[\SC@xfloat{\SC@xfloat[c]}}
%    \end{macrocode}  
% 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}  
% 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}  
% Finally, here is the macro that does all the work.
%    \begin{macrocode}
\def\SC@zfloat#1#2#3[#4]{%
  \def\SC@pos{#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 saved and redefined.
%    \begin{macrocode}  
  \let\SC@caption\caption \let\SC@label\label%
  \let\SC@CAPtext\@empty \let\SC@OPTCAPtext\@empty \let\SC@LABtext\@empty% 
  \renewcommand\caption[2][]{\gdef\SC@OPTCAPtext{##1}\gdef\SC@CAPtext{##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}
%
% \begin{macro}{\endSC@float}
% Outputs the figure or table (or whatever) and the caption.
%    \begin{macrocode} 
\def\endSC@float{%   
  \end{lrbox}%
%<+debug>  \typeout{onecolumn}%
    \def\@FLOAT{\@float}\def\end@FLOAT{\end@float}\endSC@FLOAT{\columnwidth}}%
%    \end{macrocode}  
%    \begin{macrocode} 
\def\endSC@dblfloat{%   
  \end{lrbox}%
%<+debug>  \typeout{twocolumn}%
    \def\@FLOAT{\@dblfloat}\def\end@FLOAT{\end@dblfloat}\endSC@FLOAT{\textwidth}}%
%    \end{macrocode}
% Sets the caption width. If caption width plus figure\slash table width is too
% large then the caption width is set equal to the remaining width. 
%    \begin{macrocode}
\def\endSC@FLOAT#1{%   
  \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>#1}}%
    {\addtolength\SC@CAPWD{-\@tempdima}%
     \addtolength\SC@CAPWD{#1}}{}%
%    \end{macrocode}  
% Calls the \LaTeX\ float command with the two minipages inside a main minipage.

%    \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@LABEL}%
    \begin{minipage}[b]{#1}%
      \centering% 
      \SC@FLOAT{\SC@LABEL}%
        {\begin{minipage}[\SC@pos]{\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@pos]{\SC@BOXWD}% 
           \offinterlineskip%
           \kern0pt\relax
           \usebox{\SC@BOX}%
         \end{minipage}}%
    \end{minipage}%  
  \end@FLOAT%
}
%</package>
%    \end{macrocode}
%  \end{macro}
% ^^A -----------------------------
%
%  \Finale
