path: root/Master/texmf-dist/source/latex/ncctools/nccfloats.dtx

% \iffalse
%%
%% File: nccfloats.dtx Copyright (C) 2002--2004 by Alexander I. Rozhenko
%%
%<package>\NeedsTeXFormat{LaTeX2e}
%<package>\ProvidesPackage{nccfloats}
%<package>         [2004/12/05 v1.1 More Float Management (NCC)]
%
% \changes{v1.00}{2002/03/23}{This version is uploaded to CTAN}
% \changes{v1.01}{2002/05/17}{Handling of side floats improved}
% \changes{v1.1}{2004/12/05}{Width parameters can have units now}
% \changes{v1.1}{2004/12/05}{Documentation was prepared}
%
%<*driver>
\documentclass{ltxdoc}
\usepackage{desclist,nccfloats}
\GetFileInfo{nccfloats.sty}
\begin{document}
\title{The \textsf{nccfloats} package\thanks{This file
        has version number \fileversion, last
        revised \filedate.}}
\author{Alexander I. Rozhenko\\rozhenko@oapmg.sscc.ru}
\date{\filedate}
\maketitle
\DocInput{nccfloats.dtx}
\end{document}
%</driver>
% \fi
%
% The standard \LaTeX\ floating environments, namely |figure|
% and |table|, allow user to place floating material in a
% document. But they do not introduce a style in which this
% material must be prepared. In this package, envelop commands are
% developed which join a style with a float and more
% features are introduced, namely
% mini-figures, mini-tables, side-figures, and side-tables.
%
% \section{Basic Commands}
%
% \DescribeMacro{\FloatingStyle}
% The |\FloatingStyle|\marg{style} command sets a style of
% floats in the document. It affects on the material prepared with
% commands described below. The default style is
% \begin{quote}
%     |\FloatingStyle{\footnotesize\centering}|
% \end{quote}
% This command is available in the preamble only.
%
% \DescribeMacro{\minifig}
% \DescribeMacro{\minitabl}
% We start with the basic commands, namely |\minifig| and
% |\minitabl|. They prepare a material in a minipage and allow
% using the |\caption| command in the body. Their syntax is
% similar to the |\parbox| command:
% \begin{quote}
% |\minifig |\oarg{pos}\oarg{height}\oarg{inner-pos}\marg{width}\marg{body}\\
% |\minitabl|\oarg{pos}\oarg{height}\oarg{inner-pos}\marg{width}\marg{body}
% \end{quote}
% The \meta{pos} is a vertical alignment parameter for
% minipage (|t|, |b|, or |c|) with respect to
% surrounding text; the \meta{height} is a minipage height
% required; the \meta{inner-pos} is a vertical alignment
% of text inside the minipage (|t|, |b|, |c|, or |s|);
% and the \meta{width} is the minipage width.
% The \meta{body} is prepared in the style specified by the
% |\FloatingStyle| command and can contain the |\caption| command inside.
%
% All other floating extension commands are based on
% these two commands.
%
% \section{Side Figures and Tables}
%
% For small figures and tables, it is preferable to insert them
% inside a text instead of using floating mechanism. The
% typographic rules usually require an illustrative material to
% occupy an outer side of page. In two-side mode, this means
% figure and tables should be on the right side if a page number is
% odd and on the left side if page number is even. In one-side
% mode, figures and tables must occupy the right side of page.
%
% \DescribeMacro{\sidefig}
% \DescribeMacro{\sidetabl}
% The following commands support such a placement:
% \begin{quote}
% |\sidefig|\oarg{pos}|(|$w_1$|)(|$w_2$|)|\marg{figure}\marg{text}\\
% |\sidefig*|\oarg{pos}|(|$w_1$|)(|$w_2$|)|\marg{figure}\marg{text}\\
% |\sidetabl|\oarg{pos}|(|$w_1$|)(|$w_2$|)|\marg{table}\marg{text}\\
% |\sidetabl*|\oarg{pos}|(|$w_1$|)(|$w_2$|)|\marg{table}\marg{text}
% \end{quote}
% For simplicity, we further use the term \textit{minifloat\/} for the
% small illustrating material (figure or table), however
% taking into account that it is not a float at all. It is inserted in
% the main flow next to a paragraph box specified in the last
% parameter of above described commands.
%
% The no-star forms of above described commands place a minifloat
% next to the specified text on the outer side of page (to the
% right for odd page and to the left for even page). In two-column
% or one-side mode, minifloat is always posed to the right. The
% star-forms provide the reverse placement. By default, minifloat
% is vertically centered with respect to the text and the
% |\strut| command is inserted at the beginning and at the end
% of the \meta{text} to provide normal baseline
% distances of the first and last lines of the text from
% surrounding text lines.
%
% All parameters in square and round brackets are optional and mean
% the following:
% \begin{desclist}{}{}[\meta{pos}]
% \item[\meta{pos}] specifies minifloat alignment (|t|,
% |b|, or |c|; default is |c|) with respect to text
% box and can contain additional chars controlling the text body
% preparation: |j| means the last line of the text to be
% justified to the right and |n| means suppressing of struts
% insertion (they should be inserted manually if necessary);
%
% \item[$w_1$] is the width of minifloat; and
%
% \item[$w_2$] is the width of the text box.
% \end{desclist}
%
% You can omit units in the width parameters. In this case,
% the width value is considered as a multiple of |\unitlength|
% (similarly to the use of length dimensions in the picture environment).
%
% If both width parameters are absent, the widths are calculated as\linebreak
% |(\linewidth-1.5em)/2|. If $w_2$ is absent, the text body
% width is calculated as |\linewidth-|$w_1$|-1.5em|.
%
% The placement of side-floats in the document consists in the following
% steps:
% \begin{enumerate}
% \item Decide where you want to insert a side-float;
% \item Insert a |\sidefig| or |\sidetabl| command after a word that finishes
%       the line before the future side-float position;
% \item Specify a width of float in its parameter and set the top alignment
%       as the \meta{pos} parameter (e.g.\ |\sidefig[t](|$w_1$|)|);
% \item Prepare the side-float in the first mandatory parameter of the command
%       (e.g.\ |\sidefig[t](|$w_1$|)|\marg{figure});
% \item Enclose enough text going after the command in braces;
% \item Translate the document;
% \item Find what part of the text is redundant in the \meta{text} parameter;
% \item Move it after the close brace;
% \item If the same paragraph continues after the close brace, add the |j|
%       letter to the \meta{pos} parameter. Also change the top alignment
%       to the centered alignment;
% \item Translate the document once more;
% \item If the side-float has a wrong placement (this can appear when paragraph
%       with a side-float begins at the end of page), insert the star after
%       the side-float command.
% \end{enumerate}
%
% \DescribeMacro{\ifleftsidefloat}
% While preparing a side-float, it is sometimes necessary to
% provide conditional placement depending on the side a minifloat
% is posed. The command
% \begin{quote}
% |\ifleftsidefloat|\marg{left-clause}\marg{right-clause}
% \end{quote}
% provides this. It is useful in parameters of |\sidefig| or
% |\sidetabl| and processes \meta{left-clause} if the
% minifloat is posed to the left and \meta{right-clause}
% otherwise.
%
% Side-floats can be also used within floating environments to pos
% a caption near a figure or table.
%
% \section{Floating Figures and Tables}
%
% \DescribeMacro{\fig}
% \DescribeMacro{\tabl}
% The following commands envelop floating
% environments:
% \begin{quote}
% |\fig|\oarg{placement}|(|$w$|)|\marg{body}\\
% |\fig*|\oarg{placement}|(|$w$|)|\marg{body}\\
% |\tabl|\oarg{placement}|(|$w$|)|\marg{body}\\
% |\tabl*|\oarg{placement}|(|$w$|)|\marg{body}
% \end{quote}
% The \meta{placement} is a float placement parameter
% describing places where a float can appear. The default value is
% |ht| (here or at the top of page).
% The optional $w$ parameter defines a
% width of box occupied by the float (the width of nested
% |\minifig| or |\minitabl|). If it
% is omitted, the float has the maximum width equal to the
% |\linewidth|.
%
% The |\fig| and |\tabl| commands envelop the |figure|
% and |table| environments respectively. Their star-forms
% envelop corresponding starred |figure*| or |table*| environments.
%
% \section{Two Floating Figures or Tables Side by Side}
%
% \DescribeMacro{\figs}
% \DescribeMacro{\tabls}
% The following commands place two figures or tables side by side.
% \begin{quote}
% |\figs|\oarg{placement}|(|$w_1$|)(|$w_2$|)|\marg{body1}\marg{body2}\\
% |\figs*|\oarg{placement}|(|$w_1$|)(|$w_2$|)|\marg{body1}\marg{body2}\\
% |\tabls|\oarg{placement}|(|$w_1$|)(|$w_2$|)|\marg{body1}\marg{body2}\\
% |\tabls*|\oarg{placement}|(|$w_1$|)(|$w_2$|)|\marg{body1}\marg{body2}
% \end{quote}
% The \meta{body1} is a body of the left figure or table and
% the \meta{body2} is a body of the right figure or table.
% Other parameters are optional. The meaning and default value of
% the \meta{placement} parameter is the same as described
% above. The $w_1$ and $w_2$ parameters are
% widths of left and right boxes. If
% they both are omitted, the left and right boxes will have the
% width equal to |(\linewidth-1em)/2|. If $w_2$
% is omitted, the right box will occupy the rest of horizontal space
% minus |1em|. If both parameters are specified, the rest
% space is inserted between boxes. If the total width of left and
% right floats exceeds the |\linewidth|, the floats will overlap
% at the middle (a negative horizontal space is inserted between them).
%
% In the |\tabls| command, boxes of the left and right bodies are
% top-aligned, but, in the |\figs| command, the bottom alignment is
% used. The star-forms of this commands are based on the corresponding
% starred |figure*| or |table*| environments.
% \StopEventually{}
%
% \section{The Implementation}
%
% The package uses some commands of the |nccboxes| package.
% Load it here:
%    \begin{macrocode}
%<*package>
\RequirePackage{nccboxes}[2002/03/20]
%    \end{macrocode}
%
% \begin{macro}{\FloatStyle}
% \begin{macro}{\minifig}
% \begin{macro}{\minitabl}
% At the first, we define the basic commands.
%    \begin{macrocode}
\newcommand*{\FloatStyle}[1]{\def\NCC@fltstyle{#1}}
\@onlypreamble\FloatStyle
\newcommand{\minifig}{\begingroup\def\@captype{figure}\NCC@minifloat}
\newcommand{\minitabl}{\begingroup\def\@captype{table}\NCC@minifloat}
\newcommand*\NCC@minifloat[1][c]{%
  \@ifnextchar[{\NCC@mflt{#1}}{\NCC@@mflt{#1}\relax[s]}}
\def\NCC@mflt#1[#2]{%
  \@ifnextchar[{\NCC@@mflt{#1}{#2}}{\NCC@mflt{#1}{#2}[#1]}}
\long\def\NCC@@mflt#1#2[#3]#4#5{%
  \@iiiminipage{#1}{#2}[#3]{#4}\normalfont
  \NCC@fltstyle #5\endminipage\endgroup
}
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
%
% \begin{macro}{\NCC@pair}
% The |\NCC@pair|\marg{c1}\marg{c2}\marg{def-dist}\marg{def-place}|*|\oarg{place}|(|$w_1$|)(|$w_2$|)|
% command executes \meta{c1}\marg{place}|{|$w_1$|}{|$w_2$|}| if star is absent or
% \meta{c2}\marg{place}|{|$w_1$|}{|$w_2$|}| if star presents.
% Four first parameters are mandatory. Others a optional.
% The \meta{def-dist} parameter contains a default distance
% value. It is saved in the |\@tempdimc| register.
% The \meta{def-place} parameter contains the default value for
% the \meta{place} parameter. If the last one is omitted,
% the \meta{def-place} is used instead.
%    \begin{macrocode}
\def\NCC@pair#1#2#3#4{\setlength\@tempdimc{#3}%
  \@ifstar{\NCC@pair@{#2}{#4}}{\NCC@pair@{#1}{#4}}}
\def\NCC@pair@#1#2{\@ifnextchar[{\NCC@pair@@{#1}}{\NCC@pair@@{#1}[#2]}}
\def\NCC@pair@@#1[#2]{\def\@tempa{#1{#2}}%
  \@ifnextchar({\NCC@pair@@@}{\NCC@@pair()()}}
\def\NCC@pair@@@(#1){\@ifnextchar({\NCC@@pair(#1)}{\NCC@@pair(#1)()}}
\def\NCC@@pair(#1)(#2){\@tempa{#1}{#2}}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\NCC@setwidth}
% The |\NCC@setwidth|\marg{register}\marg{width} command sets
% the given \meta{width} to the dimen \meta{register}. If units
% in \meta{width} are omitted, the |\unitlength| unit is used.
% In other words, if \meta{width} is a real number, it is considered
% as a multiple of |\unitlength|.
%    \begin{macrocode}
\def\NCC@setwidth#1#2{%
  \afterassignment\NCC@setwidth@#1#2\unitlength\relax
}
\def\NCC@setwidth@#1\relax{}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\NCC@wcalc}
% The |\NCC@wcalc{|$w_1$|}{|$w_2$|}| calculates widths
% of left and right boxes in the |\@tempdima| and |\@tempdimb|
% registers. The distance between boxes must be specified in
% |\@tempdimc| register before the call. The algorithm:
% \begin{itemize}
% \item If $w_1$ is empty, |\@tempdima:=(\linewidth-\@tempdimc)/2|,
%       otherwise, |\@tempdima:=|$w_1$;
% \item If $w_2$ is empty, |\@tempdimb:=\linewidth-\@tempdima-\@tempdimc|,
%       otherwise, |\@tempdimb:=|$w_2$;
% \item If $w_2$ is nonempty,
%       |\@tempdimc:=\linewidth-\@tempdima-\@tempdimb|.
% \end{itemize}
%    \begin{macrocode}
\def\NCC@wcalc#1#2{%
  \if!#1!\@tempdima .5\linewidth \advance\@tempdima -.5\@tempdimc
  \else  \NCC@setwidth\@tempdima{#1}%
  \fi
  \if!#2!\@tempdimb \linewidth \advance\@tempdimb -\@tempdima
         \advance\@tempdimb -\@tempdimc
  \else  \NCC@setwidth\@tempdimb{#2}%
         \@tempdimc \linewidth \advance\@tempdimc -\@tempdima
         \advance\@tempdimc -\@tempdimb
  \fi
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\ifleftsidefloat}
% This command is used in parameters of |\sidefig| or |\sidetabl|.
%    \begin{macrocode}
\newif\ifNCC@smfltleft
\newcommand{\ifleftsidefloat}{%
  \ifNCC@smfltleft
    \expandafter\@firstoftwo
  \else
    \expandafter\@secondoftwo
  \fi
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\sidefig}
% \begin{macro}{\sidetabl}
% The implementation of these commands is based
% on the |\NCC@pair| command that parses all optional
% parameters. Finally the |\NCC@smflt| command is
% executed.
%    \begin{macrocode}
\newcommand{\sidefig}{\NCC@sidemfloat{\minifig}}
\newcommand{\sidetabl}{\NCC@sidemfloat{\minitabl}}
\def\NCC@sidemfloat#1{%
  \NCC@smfltleftfalse
  \if@twocolumn \else
    \if@twoside
      \ifodd\c@page \else \NCC@smfltlefttrue \fi
    \fi
  \fi
  \NCC@pair{\NCC@smflt{#1}}%
    {\ifNCC@smfltleft \NCC@smfltleftfalse \else \NCC@smfltlefttrue\fi
     \NCC@smflt{#1}}%
    {1.5em}{}%
}
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
% \begin{macro}{\NCC@smflt}
% The |\NCC@smflt|\marg{command}\marg{pos}|{|$w_1$|}{|$w_2$|}|\marg{minifloat}\marg{text}
% prepares a side-float. The \meta{command} parameter contains
% a |\minifig| or |\minitabl| command. The \meta{pos} parameter
% specifies vertical alignment and additional flags. The
% $w_1$ and $w_2$ parameters (if present) specify widthes of
% \meta{minifloat} and \meta{text} boxes. The |\@tempdimc| register
% contains the default distance between the minifloat and text.
%    \begin{macrocode}
\long\def\NCC@smflt#1#2#3#4#5#6{%
%    \end{macrocode}
% Parse the \meta{pos} parameter. Create a |\NCC@|\meta{letter}
% command with empty content for every \meta{letter} from the \meta{pos}.
%    \begin{macrocode}
  \let\NCC@t\relax \let\NCC@b\relax \let\NCC@j\relax \let\NCC@n\strut
  \@tfor\@tempa :=#2\do {%
    \expandafter\let\csname NCC@\@tempa\endcsname\@empty}%
%    \end{macrocode}
% Define the vertical alignment letter in the |\NCC@c| command.
%    \begin{macrocode}
  \ifx\NCC@t\@empty \def\NCC@c{t}\else
   \ifx\NCC@b\@empty \def\NCC@c{b}\else
    \def\NCC@c{c}%
   \fi
  \fi
%    \end{macrocode}
% Define a justification hook in the |\NCC@j| command.
%    \begin{macrocode}
  \ifx\NCC@j\@empty \def\NCC@j{\parfillskip\z@skip}\fi
%    \end{macrocode}
% Define the text starting hook in the |\NCC@t| command.
% It will contain the |\parindent| setting command and
% the optional |\noindent| command.
%    \begin{macrocode}
  \edef\NCC@t{\parindent\the\parindent\ifvmode\else\noindent\fi}%
%    \end{macrocode}
% Complete the current paragraph and leave the horizontal mode.
%    \begin{macrocode}
  \ifvmode\else
    \unskip{\parfillskip\rightskip\par}\vskip -\parskip
  \fi
%    \end{macrocode}
% Prepare the side-float in |\@tempboxa|:
%    \begin{macrocode}
  \setbox\@tempboxa\vbox{\hsize\linewidth\noindent
%    \end{macrocode}
% Calculate widthes of left and right boxes and distance
% between them in |\@tempdima|, |\@tempdimb|, and |\@tempdimc|.
%    \begin{macrocode}
    \NCC@wcalc{#3}{#4}%
%    \end{macrocode}
% Conditionally put a side-float to the left:
%    \begin{macrocode}
    \ifNCC@smfltleft
      \jparbox{\Strut}[\NCC@c]\@tempdima{#1\@tempdima{#5}}%
      \nobreak\hskip\@tempdimc
    \fi
%    \end{macrocode}
% Put a text box:
%    \begin{macrocode}
    \jparbox{\NCC@n\Strut}[\NCC@c]\@tempdimb{%
      \everypar{\NCC@n\everypar{}}\NCC@t#6%
      \ifvmode \else \unskip\NCC@n\NCC@j\fi}%
%    \end{macrocode}
% Conditionally put a side-float to the right:
%    \begin{macrocode}
    \ifNCC@smfltleft \else
      \nobreak\hskip\@tempdimc
      \jparbox{\Strut}[\NCC@c]\@tempdima{#1\@tempdima{#5}}%
    \fi
  }%
%    \end{macrocode}
% Games with height and depth the |\@temboxa| allow us
% produce right line spacing with surrounding text.
%    \begin{macrocode}
  \@tempdima\dp\@tempboxa \advance\@tempdima\lineskip
  \dp\@tempboxa\@tempdima
  \@tempdima\ht\@tempboxa \advance\@tempdima -\ht\strutbox
  \noindent \raise-\@tempdima\box\@tempboxa
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\fig}
% \begin{macro}{\tabl}
% The implementation of these commands is quite simple:
%    \begin{macrocode}
\newcommand{\fig}{\NCC@float{figure}}
\newcommand{\tabl}{\NCC@float{table}}
\def\NCC@float#1{\@ifstar{\NCC@flt{#1*}}{\NCC@flt{#1}}}
\def\NCC@flt#1{\@ifnextchar[{\NCC@flt@{#1}}{\NCC@flt@{#1}[ht]}}
\def\NCC@flt@#1[#2]{\begin{#1}[#2]\centering
 \@ifnextchar({\NCC@@flt{#1}}{\NCC@@flt{#1}()}}
\long\def\NCC@@flt#1(#2)#3{%
  \if!#2!\@tempdima\linewidth \else \NCC@setwidth\@tempdima{#2}\fi
  \begingroup\NCC@minifloat[c]\@tempdima{#3}%
  \end{#1}%
}
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
% \begin{macro}{\figs}
% \begin{macro}{\tabls}
% The implementation of these commands is based
% on the |\NCC@pair| command that parses all optional
% parameters. Finally the |\NCC@flts| command is
% executed.
%    \begin{macrocode}
\newcommand{\figs}{\NCC@floats{figure}b}
\newcommand{\tabls}{\NCC@floats{table}t}
\def\NCC@floats#1#2{%
  \NCC@pair{\NCC@@flts{#1}{#2}}{\NCC@@flts{#1*}{#2}}{1em}{ht}}
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
% \begin{macro}{\NCC@flts}
% The |\NCC@flts|\marg{env}\marg{pos}\marg{placement}|{|$w_1$|}{|$w_2$|}|\marg{body1}\marg{body2}
% command prepares a pair of floats within \meta{env} environment.
% The \meta{pos} contains relative alignment of floats.
% The $w_1$ and $w_2$ parameters (if present) specify widthes of
% floats. The |\@tempdimc| register contains the default distance
% between floats.
%    \begin{macrocode}
\long\def\NCC@@flts#1#2#3#4#5#6#7{%
  \begin{#1}[#3]\NCC@wcalc{#4}{#5}%
    \begingroup\NCC@minifloat[#2]\@tempdima{#6}%
    \nobreak\hskip\@tempdimc
    \begingroup\NCC@minifloat[#2]\@tempdimb{#7}%
  \end{#1}%
}
%    \end{macrocode}
% \end{macro}
%
% Defaults:
%    \begin{macrocode}
\FloatStyle{\footnotesize\centering}
%</package>
%    \end{macrocode}
\endinput