path: root/macros/latex/contrib/rotfloat/rotfloat.dtx

% \iffalse meta-comment
%
% Copyright (c) 1995-2004 Axel Sommerfeldt (rotfloat@sommerfeldt.net)
%
% This file is part of the rotfloat package.
% ------------------------------------------
%
% It 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
% \CheckSum{215}
%
% \iffalse
%<*driver>
\NeedsTeXFormat{LaTeX2e}[1994/12/01]
\documentclass{ltxdoc}
\setlength{\parindent}{0pt}
\setlength{\parskip}{\smallskipamount}
\begin{document}
  \DocInput{rotfloat.dtx}
\end{document}
%</driver>
% \fi
%
% \newcommand*{\purerm}[1]{{\upshape\mdseries\rmfamily #1}}
% \newcommand*{\puresf}[1]{{\upshape\mdseries\sffamily #1}}
% \newcommand*{\purett}[1]{{\upshape\mdseries\ttfamily #1}}
%
% \changes{v1.0}{30 Mar 95}{First release}
% \changes{v1.1}{ 2 Feb 02}{Revised and adapted to new versions of float and rotating}
% \changes{v1.1a}{20 Feb 02}{Minor cosmetic changes}
% \changes{v1.2}{4 Jan 04}{Revised and support of [H] implemented}
%
% \GetFileInfo{rotfloat.sty}
% \def\fileversion{1.2}
% \def\filedate{2004/01/04}
% \title{The \puresf{rotfloat} package\thanks{This package has version number
%        \fileversion, last revised \filedate.}}
% \author{Axel Sommerfeldt\\\texttt{rotfloat@sommerfeldt.net}}
% \date{2004/01/04}
% \maketitle
%
% \begin{abstract}
% The \textsf{float} package~\cite{float} provides commands to define new floats
% of various styles (|plain|, |boxed|, |ruled|, and userdefined ones);
% the \textsf{rotating} package~\cite{rotating} provides new environments (|sidewaysfigure|
% and |sidewaystable|) which are rotated by $90^\circ$ or $270^\circ$.
% But what about new rotated floats, e.g.\ a rotated ruled one?
% This package makes this possible; it builds a bridge between both packages
% and extend the commands from the \textsf{float} package to define rotated
% versions of the new floats, too.
% \end{abstract}
%
% \section{The user interface}
% To use this package just put the line
% \begin{quote}
%   |\usepackage|\oarg{options}|{rotfloat}|
% \end{quote}
% into the preamble of your document. The options are exactly the same as
% for the \textsf{rotating} package, because all options will be passed to
% the \textsf{rotating} package.
% (The \textsf{rotfloat} package hasn't got any own options at all).
%
% \DescribeMacro{\newfloat}
% \DescribeMacro{\restylefloat}
% The commands |\newfloat| and |\restylefloat| from the \textsf{float} package
% (re)define the float type \meta{type} and now additionally a rotated one called
% \meta{\purett{sideways}type}:
% \begin{quote}
%   |\newfloat|\marg{type}\marg{placement}\marg{ext}\oarg{within}\\
%   |\restylefloat|\marg{type}
% \end{quote}
%
% \begin{minipage}[t]\textwidth
% E.g.\ the code
% \begin{quote}
%   |\floatstyle{ruled}|\\
%   |\floatname{program}{Program}|\\
%   |\newfloat{program}{tbp}{lop}[section]|
% \end{quote}
% defines the new floating environments |program|, |program*|,
% |sidewaysprogram|, and |sidewaysprogram*|
% which behave equivalent to |figure|, |figure*|,
% |sidewaysfigure|, and |sidewaysfigure*|.
% (Note that |sidewaysfigure*| has been introduced to version $2.10$ of the \puresf{rotating}
% package, therefore you only get a |sidewaysprogram*| environment if you use this or a newer
% version of the \puresf{rotating} package.)
% \end{minipage}
%
% \begin{minipage}[t]\textwidth
% The code
% \begin{quote}\nopagebreak%
%   |\floatstyle{boxed}|\\
%   |\restylefloat{table}|
% \end{quote}
% will restyle the environments |table|, |table*|, |sidewaystable|, and |sidewaystable*|.
% \end{minipage}
%
% Please take a look at the \textsf{float} package for a complete description
% of these commands.
% Additionally an example file is provided with this package.
%
% \section{What has changed since version {1.0}?}
% Version $1.0$ of this package was a quick \& dirty hack. The
% version $1.1$ took it all more serious, it patched less code from
% the float package and especially it let the |[H]| code for the
% not-sideways floats intact. Furthermore it was adapted to the new
% version 1.3 of the float and 2.10 of the rotating package.
%
% This version $1.2$ is a further step in this direction. It was revised again
% to make it even more compatible to different versions of the float package.
% As an effect of this |[H]| for sideways floats is now fully supported
% (this could be desirable when used in cooperation with the \puresf{afterpage} package),
% furthermore a bug was fixed that caused problems if the \puresf{rotfloat}
% package was used together with the \puresf{color} package.
%
% \section{A final note}
% This package was tested with the versions $1.2$, $1.2c$, $1.2d$, $1.2e$, $1.3c$,
% and $1.3d$ of the \textsf{float} package and version $2.6$, $2.9$, $2.10$, $2.12$,
% and $2.13$ of the \textsf{rotating} package.
%
% You should \emph{not} use this package together with older versions of them!
% Future versions of these packages may make some trouble, but I hope they will not.
% If they do please don't hesitate to send me a bug report including a simple non-working
% example and the log file produced by \LaTeX.
%
% \section{Further reading}
% 
% I recommend the following documents for further reading:
% 
% \begin{itemize}
% \item
%   The \TeX\ FAQ - Frequently asked questions about \TeX\ and \LaTeX :
%   \begin{quote}\texttt{http://faq.tug.org/}\end{quote}
%
% \item
%   A French FAQ can be found at
%   \begin{quote}\texttt{http://www.grappa.univ-lille3.fr/FAQ-LaTeX/}\end{quote}
%
% \item
%   A German FAQ can be fount at
%   \begin{quote}\texttt{http://www.dante.de/faq/de-tex-faq/}\end{quote}
%
% \item
%   \textsf{epslatex} from Keith Reckdahl contains many tips around
%   graphics in \LaTeXe. You will find this document in the directory
%   \begin{quote}\texttt{ftp://ftp.ctan.org/pub/tex/info/}\end{quote}
%   as \texttt{epslatex.ps} and \texttt{epslatex.pdf}.
%
%   There is also a french translation available at
%   \begin{quote}\texttt{ftp://ftp.ctan.org/pub/tex/info/fepslatex.ps}\end{quote}
%
% \item
%   \emph{``Gleitobjekte -- die richtige Schmierung''} from Axel Reichert
%   is a German documentation about floating environments in general.
%   You will find it here:
%   \begin{quote}\texttt{ftp://ftp.ctan.org/pub/tex/info/german/gleitobjekte/}\end{quote}
% \end{itemize}
% 
% 
% \section{Thanks}
% 
% I would like to thank Katja Melzner, Anselm Lingnau, Sebastian Rahtz,
% and \hbox{Wojciech} \hbox{Pietron}.
%
% \StopEventually{
%   \begin{thebibliography}{9}
%   \bibitem{float}
%   Anselm Lingnau:
%   \textsl{An Improved Environment for Floats},
%   2001/11/08
%   \bibitem{rotating}
%   Sebastian Rahtz and Leonor Barroca:
%   \textsl{A style option for rotated objects in \LaTeX},
%   1997/09/26
%   \end{thebibliography}
% }
% \setlength{\parskip}{0pt plus 1pt}
%
% \DoNotIndex{\@ifnextchar,\@ifundefined,\@namedef,\@nameuse}
% \DoNotIndex{\bgroup,\columnwidth,\csname,\def,\edef,\egroup,\else,\endcsname}
% \DoNotIndex{\empty,\expandafter,\fi,\global,\ifx,\let,\newcommand,\noexpand}
% \DoNotIndex{\renewcommand,\setbox,\textheight,\typeout,\undefined,\vbox}
% \DoNotIndex{\CurrentOption,\DeclareOption,\ExecuteOptions,\NeedsTeXFormat}
% \DoNotIndex{\PassOptionsToPackage,\ProcessOptions,\ProvidesPackage,\RequirePackage}
%
% \iffalse
%<*package>
% \fi
%
% \section{The code}
%
% \emph{Note:}
% If you really want to know what's exactly going on here, you have to study the
% code from the packages \textsf{float} and \textsf{rotating} first!
%
% \subsection{The identification part}
%
%    \begin{macrocode}
\NeedsTeXFormat{LaTeX2e}[1995/12/01]
\ProvidesPackage{rotfloat}[2004/01/04 v1.2 Combining float+rotating package (AS)]
%    \end{macrocode}
%
% \subsection{The package loading part}
%
% Of course this package needs the \textsf{float} and the \textsf{rotating}
% package, so we load them both here.
% (The \textsf{rotfloat} package hasn't got any own options, so we just pass
% everything we get to the \textsf{rotating} package.)
% \changes{v1.1a}{19 Feb 02}{Use \cs{RequirePackageWithOptions} for rotating}
%
%    \begin{macrocode}
\RequirePackage{float}[1994/06/20]      % >= version 1.2
\RequirePackageWithOptions{rotating}%[1995/01/06]  % >= version 2.6
%    \end{macrocode}
%
% \subsection{Adaption of the float package}
% \changes{v1.0a}{1 Apr 95}{Blew \cs{float@end} up}
%
% We have different code for version $1.2$ and version $1.3$ of
% the \textsf{float} package. If |\@float@HH| is not defined we assume
% version $1.2$, otherwise version $1.3$.
% \changes{v1.1a}{19 Feb 02}{\cs{wlog} changed to \cs{PackageInfo}}
%
%    \begin{macrocode}
\ifx\@float@HH\undefined
  \PackageInfo{rotfloat}{float package v1.2 detected}
%    \end{macrocode}
%
% First the code for version $1.2$ of the float package:
%
% \begin{macro}{\restylefloat}
% \changes{v1.0a}{1 Apr 95}{Extra |\bgroup| removed}
% \changes{v1.1}{1 Feb 02}{We define a *-sideways float as well}
%
% The new code for |\restylefloat| behaves like the old one, but it defines
% a sideways float as well.
% If |\@rotdblfloat| is defined we have loaded \textsf{rotating} version $2.10$
% or newer. In this case we can define a star form as well.
%
%    \begin{macrocode}
  \let\rotfloat@restyle\restylefloat
  \renewcommand*\restylefloat[1]{%
    \rotfloat@restyle{#1}%
    \@namedef{sideways#1}{\rotfloat@float{#1}}%
    \expandafter\let\csname endsideways#1\endcsname\float@end
    \ifx\@rotdblfloat\@undefined
    \else
      \@namedef{sideways#1*}{\rotfloat@dblfloat{#1*}}%
      \expandafter\let\csname endsideways#1*\endcsname\float@dblend
    \fi}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\rotfloat@float}
% \changes{v1.2}{29 Dec 03}{We use the original definitions via |\@namedef| now}
%
% What differs sideways floats from `normal' ones?
% \begin{enumerate}
% \item
%   |\hsize|, |\textwidth|, and |\columnwidth| are set to |\textheight|.
%   Usually this is done in |\@xrotfloat| (\puresf{rotating} package)
%   but this time we have to do it for ourself because the \puresf{float}
%   package handles floats differently:
%
%   It collects its contents ($=$ |\@currbox|) first, so it can build up a new
%   float contents (including the current one) later on.
%   This step is neccessary because the \puresf{float} package will take care
%   of the placement of the |\caption|. Furthermore it can add rules, boxes and
%   so on here, whatever the actual float style wants to.
%   (This is done in |\float@makebox|.)
%
%   Note that we don't set |\hsize| here, because |\@xfloat| (part of \LaTeX)
%   will set |\hsize| to |\columnwidth| anyway.
%
% \item
%   We build up the float contents with |\rotfloat@makebox| (instead of
%   |\float@makebox|) which rotates the contents additionally.
% \end{enumerate}
%
%    \begin{macrocode}
  \newcommand\rotfloat@float{%
    \textwidth\textheight
    \columnwidth\textheight
    \let\rotfloat@@makebox\float@makebox
    \let\float@makebox\rotfloat@makebox
    \@nameuse}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\rotfloat@dblfloat}
%
% For double column floats we use |\rotdblfloat@makebox| here.
%
%    \begin{macrocode}
  \newcommand\rotfloat@dblfloat{%
    \textwidth\textheight
    \columnwidth\textheight
    \let\rotfloat@@makebox\float@makebox
    \let\float@makebox\rotdblfloat@makebox
    \@nameuse}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@HHfloat}
% \changes{v1.1}{1 Feb 02}{Leave H-code intact for normal floats}
% \changes{v1.2}{29 Dec 03}{Leave H-code intact for sideways floats, too}
%
% For sideways floats with a placement specifier |[H]| the original code
% of |\@HHfloat| from the \puresf{float} package is sufficient.
% But we have to take care that at the end of the float |\rotfloat@endH|
% will be called instead of |\float@endH| so we can handle them correctly
% later on.
%
%    \begin{macrocode}
  \let\rotfloat@HH\@HHfloat
  \def\@HHfloat#1{%
    \expandafter\let\csname endsideways#1\endcsname\rotfloat@endH
%   \expandafter\let\csname endsideways#1*\endcsname\rotfloat@dblendH
    \let\end@float\relax
    \rotfloat@HH{#1}}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\rotfloat@endH}
%
% The \puresf{float} package defines this command to close a floating
% environment with a |[H]| placement specifier:
% \begin{quote}
% |\newcommand\float@endH{%|\\
% |  \egroup| (\emph{or} |\@endfloatbox|)\\
% |  \vskip\intextsep|\\
% |  \if@flstyle\float@makebox\egroup\else\box\@currbox\fi|\\
% |  \vskip\intextsep\relax}|
% \end{quote}
%
% The |\egroup| (or |\@endfloatbox|) will close the |\@currbox| first.
% Afterwards the contents of the float will be typeset HERE, surrounded by
% some extra skip.
% If the float was defined with |\newfloat| or |\restylefloat|,
% |\float@makebox| will be used to build up the float contents.
% (An extra |\egroup| is needed to finish off the |\bgroup| that
%  precedes the |\@nameuse| in the |\begin{|\meta{float}|}| commands.
%  See the code documentation of the \puresf{float} package $v1.2$ for
%  details.)
% Otherwise the vanilla |\@currbox| will be used.
%
% Here comes our version:
% If the float was defined with |\newfloat| or |\restylefloat|
% (that means |\if@flstyle| is true)
% we can use the original code from the \puresf{float} package
% because |\float@makebox| was replaced with |\rotfloat@makebox| anyway.
% (See our definition of |\rotfloat@float| for details.)
%
% But if this is not the case (that means |\if@flstyle| is false)
% we have to close the rotated float first.
% This is usually done with |\end@rotfloat| (which is part of the
% \puresf{rotating} package) but there is a caveat: |\end@rotfloat|
% uses |\end@float| which normally closes a floating environment.
% But we don't want to support floating here (well, that's why the user
% has specified the placement |[H]|), so we re-define |\end@float| to
% |\relax| which does simply nothing.
% (Note that this re-definition takes place in |\@HHfloat| because
% |\end@rotfloat| closes some environments first, so our re-definition
% would get lost if we would make it here.)
% Afterwards the original code from the \puresf{float} package
% ($=$ |\float@endH|) is sufficient again.
%
%    \begin{macrocode}
  \newcommand\rotfloat@endH{%
    \if@flstyle
    \else
%     \let\end@float\relax
      \end@rotfloat
    \fi
    \float@endH}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\rotfloat@makebox}
%
% Finally: The typesetting of a (re-styled) rotated float.
%
% This is quite simple: We put the |\float@makebox| inside
% a rotated environment. For this purpose we use |\@rotfloat|
% and |\end@rotfloat| which usually begin and end a rotated floating
% environment; they are provided by the \puresf{rotating} package.
% But we have to keep the floating stuff outside, so
% we define |\@float| (which is used by |\@rotfloat|) and
% |\end@float| (which is used by |\end@rotfloat|) to do nothing.
%
%    \begin{macrocode}
  \newcommand\rotfloat@makebox{%
    \vbox{%
      \def\@float##1[##2]{}\let\end@float\relax
      \@rotfloat{}[]%
        \rotfloat@@makebox
      \end@rotfloat}}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\rotdblfloat@makebox}
%
% Well, this is quite the same as |\rotfloat@makebox| but we use the
% appropriate macros for the star-variants of floating environments here.
%
%    \begin{macrocode}
  \newcommand\rotdblfloat@makebox{%
    \vbox{%
      \def\@float##1[##2]{}\let\end@dblfloat\relax
      \@rotdblfloat{}[]%
        \rotfloat@@makebox
      \end@rotdblfloat}}
%    \end{macrocode}
% \end{macro}
%
% So far the code for the version $1.2$ of the float package.
%
%    \begin{macrocode}
\else
%    \end{macrocode}
%
% Now the code for the \puresf{float} package version $1.3$:
%
% It is mainly the same, so we only tell you the small differences compared to
% the code inside the branch for the \puresf{float} package version $1.2$ here.
%
%    \begin{macrocode}
  \PackageInfo{rotfloat}{float package v1.3 detected}
%    \end{macrocode}
%
% \begin{macro}{\float@restyle}
% We have to extend |\float@restyle| instead of |\restylefloat| here,
% so |\restylefloat*| will still work.
%    \begin{macrocode}
  \let\rotfloat@restyle\float@restyle
  \renewcommand*\float@restyle[1]{%
    \rotfloat@restyle{#1}%
    \@namedef{sideways#1}{\rotfloat@float{#1}}%
    \expandafter\let\csname endsideways#1\endcsname\float@end
    \ifx\@rotdblfloat\@undefined
    \else
      \@namedef{sideways#1*}{\rotfloat@dblfloat{#1*}}%
      \expandafter\let\csname endsideways#1*\endcsname\float@dblend
    \fi}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\rotfloat@float}
% \begin{macro}{\rotfloat@dblfloat}
% These two don't have to be changed.
%    \begin{macrocode}
  \newcommand\rotfloat@float{%
    \textwidth\textheight
    \columnwidth\textheight
    \let\rotfloat@@makebox\float@makebox
    \let\float@makebox\rotfloat@makebox
    \@nameuse}
  \newcommand\rotfloat@dblfloat{%
    \textwidth\textheight
    \columnwidth\textheight
    \let\rotfloat@@makebox\float@makebox
    \let\float@makebox\rotdblfloat@makebox
    \@nameuse}
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
% \begin{macro}{\@float@HH}
% We have to extend |\@float@HH| instead of |\@HHfloat| here.
%    \begin{macrocode}
  \let\rotfloat@HH\@float@HH
  \def\@float@HH#1{%
    \expandafter\let\csname endsideways#1\endcsname\rotfloat@endH
%   \expandafter\let\csname endsideways#1*\endcsname\rotfloat@dblendH
    \let\end@float\relax
    \rotfloat@HH{#1}}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\rotfloat@endH}
% This one hasn't to be changed.
%    \begin{macrocode}
  \newcommand\rotfloat@endH{%
    \if@flstyle
    \else
%     \let\end@float\relax
      \end@rotfloat
    \fi
    \float@endH}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\rotfloat@makebox}
% \begin{macro}{\rotdblfloat@makebox}
% |\float@makebox| has a parameter here which will be set to |\columnwidth| or
% |\textwidth|. (In the \puresf{float} package $v1.2$ the |\columnwidth| was
% hard wired into |\float@makebox|.) So we have to pass this parameter through
% the original version of |\float@makebox| which we have saved to
% |\rotfloat@@makebox| within |\rotfloat@float|.)
%    \begin{macrocode}
  \newcommand*\rotfloat@makebox[1]{%
    \vbox{%
      \def\@float##1[##2]{}\let\end@float\relax
      \@rotfloat{}[]%
        \rotfloat@@makebox{#1}%
      \end@rotfloat}}
  \newcommand*\rotdblfloat@makebox[1]{%
    \vbox{%
      \def\@float##1[##2]{}\let\end@dblfloat\relax
      \@rotdblfloat{}[]%
        \rotfloat@@makebox{#1}%
      \end@rotdblfloat}}
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
% That's all folks.
%
%    \begin{macrocode}
\fi
%    \end{macrocode}
%
% \iffalse
%</package>
% \fi
% \Finale
%
\endinput