path: root/macros/latex/required/graphics/rotating.dtx

%
% \iffalse
%
%
% File: rotating.dtx
%% Copyright (C) 1995-1999 Sebastian Rahtz and Leonor Barroca
%% Copyright (C) 2001-2003,2007-2009 Robin Fairbairns
%% Copyright (C) 2016-2022 LaTeX Project
%% The LaTeX Project and any individual authors listed elsewhere
%% in this file.
%
% This work may be distributed and/or modified under the
% conditions of the LaTeX Project Public License, either version 1.3c
% of this license or (at your option) any later version.
% The latest version of this license is in
%   https://www.latex-project.org/lppl.txt
% and version 1.3c or later is part of all distributions of LaTeX
% version 2005/12/01 or later.
%
% This work has the LPPL maintenance status `maintained'.
%
%
% This work consists of the file rotating.dtx
% and the derived file rotating.sty, and testing material
% rotex.tex and cat.eps
%
%    \begin{macrocode}
\NeedsTeXFormat{LaTeX2e}
%<*dtx>
\ProvidesFile{rotating.dtx}%
%</dtx>
%<package>\ProvidesPackage{rotating}%
    [2016/08/11 v2.16d
%<package>  rotated objects in LaTeX%
%<*dtx>
            rotating package source file%
%</dtx>
        ]
%<*dtx>
\documentclass{ltxdoc}
\GetFileInfo{rotating.dtx}
\begin{document}
 \title{A package for rotated objects in \LaTeX\thanks{This file has
        version number \fileversion, last revised \filedate}}
    \author{Robin Fairbairns
      \and Sebastian Rahtz \and Leonor Barroca}
 \date{printed \today}
 \MaintainedByLaTeXTeam{graphics}
 \maketitle
 \tableofcontents
%  \listoffigures
%  \listoftables
 \DocInput{rotating.dtx}
\end{document}
%</dtx>
% \fi
%
% \begin{abstract}
% This article documents a \LaTeX\ package, `rotating.sty',
% which performs most sorts of
% rotation one might like, including rotation of complete floating
% figures and tables.
% \end{abstract}
%
% \section{Introduction}
%
% The package provides:
% \begin{itemize}
% \item two new environments, \texttt{sidewaystable} and
%   \texttt{sidewaysfigure}, each of which produces a single page-size
%   float with contents rotated $\pm90$\,degrees; and
% \item a variety of other rotation-related commands and environments.
% \end{itemize}
%
% Note that the package uses rotation facilities from the
% \textsf{graphicx} package.  When generating DVI output, users should
% note that rotation is typically \emph{not} visible in a DVI viewer:
% conversion to, and viewing, PostScript or PDF is necessary.
%
% \section{Usage}
%
% \subsection{Package options}
%
% Sideways figures and tables always take up the whole page. In
% single-sided documents, they may be rotated so that the bottom of
% the figures is on the left (package option
% `\texttt{counterclockwise}') or the right (package option
% `\texttt{clockwise}').  The default is to turn so that the bottom is
% on the right (option `\texttt{clockwise}').
%
% Option `\texttt{anticlockwise}' is an alias for
% `\texttt{counterclockwise}'.
%
% If the `\texttt{twoside}' option has been given to the main document
% class (either explicitly, or implicitly as in the default for book
% class), the package will rotate sideways figures according to the
% page number (this requires at least two passes through \LaTeX{}).
% If you want the `\texttt{twoside}' option, but want the figures
% always in one direction, use the `\texttt{figuresright}' or
% `\texttt{figuresleft}' options to the package.
%
% The package can produce a lot of logging information; the
% amount of information is controlled by the package options
% `\texttt{quiet}' (fewest messages; default), `\texttt{log}' and
% `\texttt{chatter}' (most messages).
%
% All other options are passed to the \textsf{graphicx} package when
% it is loaded to provide rotation functions.
%
% \subsection{Float environments}
%
% The environments \texttt{sidewaystable} and \texttt{sidewaysfigure}
% introduce landscape-form floating tables and figures, respectively.
% (Each of the environments has a ``starred'' version, such as
% \texttt{sidewaystable*}, for a single-column float in a double-column
% area of the document.)
%
% New rotated environments may be declared using the combined
% facilities of the float and rotfloat packages.
%
% \subsection{Other environments and commands}
% The package provides other \LaTeX\ environments:
% \begin{description}
% \item[\mdseries\ttfamily sideways] prints the contents of the
%   environment turned through 90 degrees counterclockwise;
% \item[\mdseries\ttfamily turn] prints the contents turned through an
%   arbitrary angle (the argument to the environment);
% \item[\mdseries\ttfamily rotate] prints the contents turned through
%   an arbitrary angle but does \emph{not} leave any space for the result
% \end{description}
%
% The command \cs{turnbox}\marg{angle}\marg{matter to turn} is a macro
% version of the \texttt{rotate} environment.
%
% A set of examples is given in the file \texttt{rotex.tex}
%
% \subsection{Positioning}
%
% Floats appear one to a page, and are positioned by spacer skips that
% appear (logically) above and below the floating object.  The skips,
% \cs{rotFPtop} and \cs{rotFPbot}, are initialised from the standard
% \LaTeX{} (internal) \cs{@fptop} and \cs{@fpbot} skips.  As a result,
% by default, rotated floats appear horizontally centred on their
% float pages.
%
% Some sensible values for the registers are:
% \par\noindent
% \begin{tabular}{@{}llp{3in}@{}}
%   \cs{rotFPtop} & \cs{rotFPbot} & Effect \\
%   \hline
%   0pt plus 1fil & 0pt plus 1fil & figure/table appears in middle
%                                   (default value)               \\
%   0pt           & 0pt plus 1fil & figure/table appears with its top
%                                   nearest the edge of the page   \\
%   0pt plus 1fil & 0pt plus 2fil & figure/table's bottom appears
%                                   twice as far from the edge as the
%                                   top does
% \end{tabular}
%
% \MaybeStop{}
%
% \section{Setup}
% Now we present the documented code.  First, package options.
%
% Note that the \texttt{clockwise} and \texttt{counterclockwise}
% options are present for compatibility only.
%    \begin{macrocode}
%<*package>
\DeclareOption{clockwise}{%
 \AtBeginDocument{\setkeys{Grot}{units=360}}%
}
\DeclareOption{counterclockwise}{%
 \AtBeginDocument{\setkeys{Grot}{units=-360}}%
}
\DeclareOption{anticlockwise}{\ds@counterclockwise}
%    \end{macrocode}
% Control figure orientation
%    \begin{macrocode}
\DeclareOption{figuresleft}{%
  \@rot@twosidefalse
  \def\rot@LR{0}%
}
\DeclareOption{figuresright}{%
 \@rot@twosidefalse
 \def\rot@LR{-1}%
}
%    \end{macrocode}
%
% control messages:
%    \begin{macrocode}
\newif\ifrot@messages
\DeclareOption{quiet}{%
  \rot@messagesfalse
  \let\rot@message\@gobble % pro tem -- should suppress altogether
}
\DeclareOption{log}{%
  \rot@messagestrue
  \def\rot@message{\PackageInfo{rotating}}%
}
\DeclareOption{chatter}{%
  \rot@messagestrue
  \def\rot@message{\PackageWarning{rotating}}%
}
%    \end{macrocode}
%
% \begin{macro}{\if@rot@twoside}
% \begin{macro}{\rot@LR}
% A couple of commands for passing rotation direction around
%    \begin{macrocode}
\newif\if@rot@twoside
\if@twoside
  \@rot@twosidetrue
\else
  \@rot@twosidefalse
\fi
\def\rot@LR{-1}
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
% Pass any unknown options to the \textsf{graphicx} package, and
% set up defaults and process the options.
%    \begin{macrocode}
\DeclareOption*{\PassOptionsToPackage{\CurrentOption}{graphicx}}
\ExecuteOptions{clockwise,quiet}
\ProcessOptions
%    \end{macrocode}
%
% Other initialisation
%    \begin{macrocode}
\RequirePackage{graphicx}
\RequirePackage{ifthen}
%    \end{macrocode}
%
% \begin{macro}{\rotdriver}
% The command \cs{rotdriver} allows a user to specify an initialisation file,
% a sort of non-automatically-loaded driver (in the graphics, hyperref
% sense).
%    \begin{macrocode}
\def\rotdriver#1{\makeatletter\input{#1.def}\makeatother}
%    \end{macrocode}
% \end{macro}
%
% The \texttt{r@tfl@t} counter is used when generating `labels' for
% determining what side of the page the float is on, in twoside mode.
%    \begin{macrocode}
\newcounter{r@tfl@t}
\setcounter{r@tfl@t}{0}
%    \end{macrocode}
%
% Positioning skips (see above).
%    \begin{macrocode}
\newskip\rotFPtop \rotFPtop=\@fptop
\newskip\rotFPbot \rotFPbot=\@fpbot
%    \end{macrocode}
%
% \section{Turning and rotation environments}
% \begin{macro}{sideways}
% Environment to turn the contents through 90 degrees.
%    \begin{macrocode}
\def\sideways{%
  \Grot@setangle{90}%
  \setbox\z@\color@hbox\ignorespaces}
\def\endsideways{%
  \unskip\color@endbox
  \Grot@x\z@
  \Grot@y\z@
  \Grot@box
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{turn}
% Rotate the contents of the environment, leaving the appropriate space
%    \begin{macrocode}
\def\turn#1{%
  \Grot@setangle{#1}%
  \setbox\z@\color@hbox\ignorespaces}
\def\endturn{%
  \unskip\color@endbox
  \Grot@x\z@
  \Grot@y\z@
  \Grot@box
}
%    \end{macrocode}
% \end{macro}
% \begin{macro}{rotate}
% Rotate the contents of the environment, leaving \emph{no space}.
%    \begin{macrocode}
\def\rotate#1{%
  \Grot@setangle{#1}%
  \setbox\z@\color@hbox\ignorespaces}
\def\endrotate{%
  \unskip\color@endbox
  \Grot@x\z@
  \Grot@y\z@
  \wd0\z@\dp0\z@\ht0\z@
  \Grot@box
}
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\turnbox}
% A macro version of the `rotate' environment.
%    \begin{macrocode}
\def\turnbox#1#2{%
  \Grot@setangle{#1}%
%    \end{macrocode}
% Note: grouping within the box makes \cs{color@hbox} unnecessary, I think.
%    \begin{macrocode}
  \setbox\z@\hbox{{#2}}%
  \Grot@x\z@\Grot@y\z@
  \wd0\z@\dp0\z@\ht0\z@
  \Grot@box
}
%    \end{macrocode}
% \end{macro}
% \section{Sideways figures and tables}
% Now for the macros to provide a complete
% environment for sideways figures and tables.
% We define two environments |sidewaysfigure| and
% |sidewaystable| that
% fit in with the normal table and figure floats. These are `fixed'
% environments that  just do 90 degree rotation, but it would be easy
% to parameterize this to do other rotations if needed (the mind
% boggles\ldots)
%
% \begin{macro}{\@rotfloat}
% \begin{macro}{\@xrotfloat}
% \begin{macro}{\rot@float@box}
% First a generalised `rotfloat' environment. We need to intercept
% \LaTeX's float macros, in order to change the assumed width of a
% float being |\columnwidth|. We want it to work on a width of
% |\textheight| so that when we rotate the float, it comes out
% the right height. This is not actually very satisfactory, since what
% we \emph{really} want is for rotated floats to occupy the space they
% actually \emph{use}. The captions are a problem --- since they can
% precede the figure or table, we cannot set them in a box of the
% right width (ie the \emph{height} of the forthcoming object), because
% it has not happened yet. The result of these difficulties is that
% rotated figures  always end up as full page figures.
%    \begin{macrocode}
\newsavebox\rot@float@box
\def\@rotfloat#1{%
  \@ifnextchar[%
    {\@xrotfloat{#1}}%
    {\edef\@tempa{\noexpand\@xrotfloat{#1}[\csname fps@#1\endcsname]}\@tempa}%
}
\def\@xrotfloat#1[#2]{%
  \@float{#1}[#2]%
%    \end{macrocode}
% Set the float contents in
% a box of width \cs{textheight} instead of \cs{columnwidth}.
%    \begin{macrocode}
  \begin{lrbox}\rot@float@box
  \begin{minipage}\textheight
 }
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
%
% \begin{macro}{\end@rotfloat}
% We call \LaTeX's \cs{end@float} macro having previously rotated
% the box \cs{@currbox}.
% The rotation is either clockwise or
% anti-clockwise, depending on whether the page is odd or even;
% in oneside mode it is always odd.
%    \begin{macrocode}
\def\end@rotfloat{%
%    \end{macrocode}
% If we are going to know whether pages are odd or even,
% we need to use the a variant \cs{pageref} mechanism and our own
% specialised labels.
%    \begin{macrocode}
   \end{minipage}\end{lrbox}%
   \stepcounter{r@tfl@t}%
   \rot@label{RF\ther@tfl@t}%
   \rot@pageref{RF\ther@tfl@t}{\R@@page}%
   \edef\@tempa{Adding sideways \@captype\space on page \R@@page\space}
   \rot@mess@toks\expandafter{\@tempa}
   \wd\rot@float@box\z@
   \ht\rot@float@box\z@
   \dp\rot@float@box\z@
   \vbox to \textheight{%
%    \end{macrocode}
% We need to know for sure which direction rotation is going to
% be in, so locally reset the graphics units.
%    \begin{macrocode}
    \setkeys{Grot}{units=360}%
    \if@rot@twoside
    \else
      \let\R@@page\rot@LR
    \fi
    \ifthenelse{\isodd{\R@@page}}{%
      \if@rot@twoside
        \rot@mess@toks\expandafter{\the\rot@mess@toks (right hand page)}%
      \fi
      \vfill
      \@@line{%
        \hskip\rotFPtop
        \rotatebox{90}{\box\rot@float@box}%
        \hskip\rotFPbot
      }%
    }{%
      \if@rot@twoside
        \rot@mess@toks\expandafter{\the\rot@mess@toks (left hand page)}%
      \fi
      \@@line{%
        \hskip\rotFPbot
        \rotatebox{-90}{\box\rot@float@box}%
        \hskip\rotFPtop
      }%
      \vfill
    }%
    \rot@message{\the\rot@mess@toks}
  }%
  \end@float
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\sidewaysfigure}
% \begin{macro}{\endsidewaysfigure}
% \begin{macro}{\sidewaystable}
% \begin{macro}{\endsidewaystable}
% The following definitions set up two environments,
% \texttt{sidewaystable} and \texttt{sidewaysfigure}, which uses this
% type of float. Naturally, users may need to change these to suit
% their local style. Both contribute to the normal lists of figures
% and tables.
%    \begin{macrocode}
\def\sidewaysfigure{\@rotfloat{figure}}
%
\let\endsidewaysfigure\end@rotfloat
%
\def\sidewaystable{\@rotfloat{table}}
\let\endsidewaystable\end@rotfloat
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
%
% \begin{macro}{\@rotdblfloat}
% \begin{macro}{\end@rotdblfloat}
% Handling double column floats
%    \begin{macrocode}
\def\@rotdblfloat{%
  \if@twocolumn\expandafter\@rotdbflt\else\expandafter\@rotfloat\fi
}
\def\@rotdbflt#1{\@ifnextchar[{\@rotxdblfloat{#1}}{\@rotxdblfloat{#1}[tp]}}
\def\@rotxdblfloat#1[#2]{%
  \@float{#1}[#2]%
  \hsize\textwidth\linewidth\textwidth
  \begin{lrbox}\rot@float@box
  \begin{minipage}\textheight
}
\def\end@rotdblfloat{%
%    \end{macrocode}
% If we are going to know whether pages are odd or even,
% we need to use the \cs{pageref} mechanism, and labels. But
% Labels won't work \emph{unless} the user has put in a
% caption. Beware!
%    \begin{macrocode}
  \end{minipage}\end{lrbox}%
  \stepcounter{r@tfl@t}%
  \rot@label{RF\ther@tfl@t}%
  \rot@pageref{RF\ther@tfl@t}{\R@@page}%
  \edef\@tempa{Adding sideways \@captype\space on page \R@@page\space}
  \rot@mess@toks\expandafter{\@tempa}
  \@tempdima\ht\rot@float@box
  \advance\@tempdima by \dp\rot@float@box
%   \ifrot@messages
%     \rot@message{BOX wd: \the\wd\rot@float@box,
%       ht: \the\ht\rot@float@box, dp: \the\dp\rot@float@box:
%       so shift by .5 of \the\@tempdima}%
%   \fi
  \wd\rot@float@box\z@
  \ht\rot@float@box\z@
  \dp\rot@float@box\z@
  \vbox to \textheight{%
%    \end{macrocode}
% We need to know for sure which direction rotation is going to
% be in, so locally reset the graphics units.
%    \begin{macrocode}
    \setkeys{Grot}{units=360}%
    \if@rot@twoside
    \else
      \let\R@@page\rot@LR
    \fi
    \ifthenelse{\isodd{\R@@page}}{%
      \ifrot@messages
        \if@rot@twoside
	  \rot@mess@toks\expandafter{\the\rot@mess@toks (right hand page)}%
	\fi
      \fi
      \vfill
      \@@line{%
        \hskip\rotFPtop
        \rotatebox{90}{\box\rot@float@box}%
        \hskip\rotFPbot
      }%
    }{%
      \ifrot@messages
        \if@rot@twoside
	  \rot@mess@toks\expandafter{\the\rot@mess@toks (left hand page)}%
	\fi
      \fi%
      \@@line{%
        \hskip\rotFPbot
        \rotatebox{-90}{\box\rot@float@box}%
        \hskip\rotFPtop
      }%
      \vfill
    }%
    \rot@message{\the\rot@mess@toks}%
  }%
  \end@dblfloat
}
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
% \begin{environment}{sidewaysfigure*}
% \begin{environment}{sidewaystable*}
%    \begin{macrocode}
\newenvironment{sidewaystable*}
               {\@rotdblfloat{table}}
               {\end@rotdblfloat}
\newenvironment{sidewaysfigure*}
               {\@rotdblfloat{figure}}
               {\end@rotdblfloat}

%    \end{macrocode}
% \end{environment}
% \end{environment}
%
% \begin{macro}{\rot@label}
% \begin{macro}{\rot@thepage}
% \begin{macro}{\rot@pageref}
% \begin{macro}{\rot@protected@write}
% \begin{macro}{\if@rot@refundefined}
% Note that we used \cs{rot@label}, not \cs{label}; this
% variant writes (just) the \emph{true} page number, not the
% value of \cs{thepage}; this ``true'' value then needs special
% treatment in \cs{protected@write}, just as
% \cs{thepage} already has.
% \cs{rot@pageref}\marg{generated label name}\marg{cs to set to
% pageno} then returns the labelled page's number (or 0 if label not
% yet defined).  If label not defined, flags using
% \cs{rot@refundefinedtrue} for end-document to pick up.  (later...)
%    \begin{macrocode}
\def\rot@thepage{\@arabic\c@page}
\def\rot@label#1{\@bsphack
  \rot@protected@write{\@auxout}{}%
         {\string\newlabel{#1}{\rot@thepage}}%
  \@esphack}
\def\rot@pageref#1#2{%
  \expandafter\ifx\csname r@#1\endcsname\relax
    \global\@rot@refundefinedtrue
    \def#2{0}%
  \else
    \edef#2{\csname r@#1\endcsname}%
  \fi
}
\long\def\rot@protected@write#1#2#3{%
  \begingroup
    \let\rot@thepage\relax
    #2%
    \let\protect\@unexpandable@protect
    \edef\reserved@a{\write#1{#3}}%
    \reserved@a
  \endgroup
  \if@nobreak\ifvmode\nobreak\fi\fi
}
\newif\if@rot@refundefined
\global\@rot@refundefinedfalse
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
%
% \begin{macro}{\rot@mess@toks}
% A token register to build up debugging messages
%    \begin{macrocode}
\newtoks\rot@mess@toks
%    \end{macrocode}
% \end{macro}
%
% \subsection{Rotated captions only}
%
% \begin{macro}{\rotcaption}
% \begin{macro}{\@makerotcaption}
% Sometimes you may find that the rotation of complete figures does
% not give quite the right result, since they always take up the whole
% page. You may prefer to rotate the caption and the float contents
% separately within a conventional figure. Here we offer a suggestion
% for a \cs{rotcaption} command, which inserts the caption rotated
% by 90 degrees. It is essentially a copy of the normal captioning
% code.
% Packages which define the \cs{@makecaption} command may also need
% to define \cs{@makerotcaption}.
%    \begin{macrocode}
\def\rotcaption{\refstepcounter\@captype\@dblarg{\@rotcaption\@captype}}
\long\def\@rotcaption#1[#2]#3{%
  \addcontentsline{\csname ext@#1\endcsname}{#1}{%
    \protect\numberline{\csname the#1\endcsname}{\ignorespaces #2}}%
  \par
  \begingroup
    \@parboxrestore
    \normalsize
    \@makerotcaption{\csname fnum@#1\endcsname}{#3}%
  \endgroup}
  \long\def\@makerotcaption#1#2{%
    \setbox\@tempboxa\color@hbox#1: #2\color@endbox
    \ifdim \wd\@tempboxa > .8\vsize
      \rotatebox{90}{%
        \begin{minipage}{.8\textheight}#1: #2\end{minipage}%
      }%
    \else%
      \rotatebox{90}{\box\@tempboxa}%
    \fi
  \nobreak
  \hspace{12pt}%
}
%</package>
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
% \section{Last-minute infrastructure}
%
% \begin{macro}{\color@hbox}
% \begin{macro}{\color@endbox}
% These macros aren't provided in \LaTeX{}, by default (I seem to have
% assumed that they were\dots)
%    \begin{macrocode}
\AtBeginDocument{%
  \providecommand\color@hbox{\hbox\bgroup}%
  \providecommand\color@vbox{\vbox\bgroup}%
  \providecommand\color@endbox{\egroup}%
}
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
% \section{History}
%
% Version 2.0 is a complete re-write, with most of the work now
% being done by the \LaTeXe\ graphics package.
%
% Version 2.1 provides a `clockwise' option to reinstate the behaviour
% described in the `\LaTeX\ Companion'
%
% Version 2.2 just intercepts the standard float macros instead
% of copying and changing the. The `twoside' option is obeyed.
%
% Version 2.5 corrects problems in sideways figures.
%
% Version 2.6 is a rewrite of the sideways floats via Frank Mittelbach
% (to whom many thanks for looking at the  mangy code).
%
% Version 2.7 is checked for \LaTeX\ of December 94, and adds the option
% of twoside behaviour independent of the general twoside.
%
% Version 2.8 cleans up some mistakes pointed out by Harald Axel
% Sommerfeldt.
%
% Version 2.9 cleans up some (more) mistakes pointed out by Harald
% Axel Sommerfeldt.
%
% Version 2.13a permits positioning of rotated floats in the same way
% as they are positioned in `normal' floats.
%
% Version 2.14 is the first to be published anywhere as the outcome of
% maintenance by Robin Fairbairns.
%
% Version 2.15 deals with page-numbering bug for auto-float-rotation,
% and tidying of messages; published to ctan
%
% Version 2.16 uses colour boxes as necessary; published to ctan.
% Version 2.16a provides the colour box commands \cs{AtBeginDocument}.
%
% \Finale
\endinput
%