summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/swfigure/swfigure.dtx
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2020-10-19 03:01:17 +0000
committerNorbert Preining <norbert@preining.info>2020-10-19 03:01:17 +0000
commit3fdf82ec77f470d0bf97c17c3085ef2fd58ea65f (patch)
treeb5a02fdc2b644489adba7459ebbf1d5d2f2739f5 /macros/latex/contrib/swfigure/swfigure.dtx
parent94b94cfd7a578d12bd5335c40e5f43400140c3f4 (diff)
CTAN sync 202010190301
Diffstat (limited to 'macros/latex/contrib/swfigure/swfigure.dtx')
-rw-r--r--macros/latex/contrib/swfigure/swfigure.dtx183
1 files changed, 93 insertions, 90 deletions
diff --git a/macros/latex/contrib/swfigure/swfigure.dtx b/macros/latex/contrib/swfigure/swfigure.dtx
index 4629fb398c..5da66dfc6f 100644
--- a/macros/latex/contrib/swfigure/swfigure.dtx
+++ b/macros/latex/contrib/swfigure/swfigure.dtx
@@ -4,7 +4,7 @@
%<*internal>
\begingroup
\input docstrip.tex
-\keepsilent
+%\keepsilent
\preamble
Copyright (C) 2020 Claudio Beccari all rights reserved.
@@ -45,7 +45,7 @@ files swfigure.sty and swfigure.pdf
%<+package>\ProvidesPackage{swfigure}%
%<+readme>File README.txt for package swfigure
%<*package|readme>
- [2020-10-13 v.0.9.08 Managing large and spread wide figures]
+ [2020-10-18 v.0.9.11 Managing large and spread wide figures]
%</package|readme>
%<*driver>
\documentclass[a4paper]{ltxdoc}\errorcontextlines=9
@@ -102,7 +102,7 @@ Managing large and spread wide figures}
\end{document}
%</driver>
% \fi
-%^^A \CheckSum{10}^^A Doesn't this work any more?
+% \CheckSum{10}^^A Doesn't this work any more?
%
% \begin{abstract}
% This package defines a single command that with different options can
@@ -116,8 +116,6 @@ Managing large and spread wide figures}
% uses.
% \end{abstract}
%
-%^^A \DFimage[SW]{SWfakeimage}{A large fake image}[fig:SWfake]
-%^^A It does not work with the page design of this document.
%
%^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%\section{Introduction}
@@ -203,7 +201,7 @@ Managing large and spread wide figures}
% the |swfigure.zip| file from the Comprehensive \TeX\ Archive Network
% (CTAN), and decompress it either in the very folder where there is
% the document main or single document file or, for a general use, in
-% the user personal |texmf| tree; it is possible that the user should
+% the user |texmf| personal tree; it is possible that the user should
% directly create this personal tree; how to do it is described in the
% documentation of the user \TeX\ system distribution.
%
@@ -232,7 +230,7 @@ Managing large and spread wide figures}
% \texttt{SW} (Spread Wide image), \texttt{HS} (Horizontal Spread-wide
% image), and \texttt{VS} (Vertical Slim image).
%\item[\meta{image fie name}]
-% Is the name of the image graphic file; remember that the \LaTeX based
+% is the name of the image graphic file; remember that the \LaTeX based
% \TeX\ system typesetting programs accept graphic files in the formats
% with extensions \texttt{.pdf}, \texttt{.eps}, \texttt{.jpg},
% \texttt{.png}, and few other less common ones. It is not necessary to
@@ -242,14 +240,14 @@ Managing large and spread wide figures}
% \meta{caption} text, but if the latter is sort of lengthy, it is
% better to enter a shorter text in that list.
%\item[\meta{caption}]
-% is the caption text.
+% is the caption text.
%\item[\meta{label}]
-% this optional argument is the string that forms the argument of the
-% \cs{label} command; of course, if this argument is not specified,
-% the figure number and its page cannot be referenced with \cs{ref},
-% \cs{pageref} and other similar commands.
+% this optional argument is the string that forms the \cs{label} command
+% argument; of course, if this argument is not specified, the figure
+% number and its page cannot be referenced with \cs{ref}, \cs{pageref}
+% and other similar commands.
%\item[\meta{height correction}]
-% This normal parenthesis delimited optional argument is a fractional
+% is a round parenthesis delimited optional argument; it is a fractional
% number lower than~1 (default 0.8) with which to further scale the
% scaled image height to be included; it is used by some display modes,
% and it is ignored by others.
@@ -263,7 +261,7 @@ Managing large and spread wide figures}
%\item[\meta{width test}] this further vertical bars delimited argument
% is used only when dealing with vertical slim images; when they are
% scaled down in order to fit in the available space, their width may
-% become too small to allow a decently typeset caption underneath the
+% become too small to allow a decently typeset caption below the
% image. A test is made to compare the scaled image width with a
% fraction of the text block width in order to skip the image insertion
% if the image width becomes too small; the default value for this
@@ -287,33 +285,28 @@ Managing large and spread wide figures}
% does not know in advance the vertical space occupied by the caption,
% therefore the optional \meta{height correction} comes handy for
% small adjustments; this display mode is fully and freely floating,
-% although its positioning is fixed to~|[p]|.
+% although its positioning is fixed to~|[p]|, full only-float page.
%
%\item[\texttt{RF}]
% This display mode is convenient when the image
% aspect ratio is close to the reciprocal of the text block one. This
% mode accepts the \meta{height correction} in order to leave space
-% to the caption. It is a fully and freely floating object with the
+% for the caption. It is a fully and freely floating object with the
% same pros and cons as the \texttt{NF} display mode.
%
%\item[\texttt{SW}]
% This display mode is convenient when a really large
% image requires two pages to display all its details; its aspect ratio
-% should be close to the two page aspect ratio of the total space
+% should be close to the aspect ratio of the total space
% available for the two page spread; depending on the page design this
-% total space approximate value probably is close to~0.5.
+% total space approximate value is probably around~0.5.
% The object to be included in the document should start on an even
-% page, therefore it moves to the first even page available; this
-% implies that the last document page before the spread wide image
-% may be blank or may be shorter than the other text pages; the user
+% page, therefore it floats to the first even page available; this may
+% force a page break where the current page is not fully completed and
+% may be shorter than the other text pages; the user
% then should help the automatic positioning by choosing very carefully
-% where to insert the \cs{DFfigure} command in the source text; it can
-% even set it within a paragraph and the command provides a new page
-% just after the line that contains the \cs{DFfigure} command;
-% therefore if the paragraph is close to the end of an odd page and
-% the position of \cs{DFfigure} command is properly positioned within this
-% paragraph, the spread wide insertion would not disturb the quality
-% of the typeset document.
+% where to insert the \cs{DFfigure} command in the source text; possibly
+% the user should chose an end of paragraph close to the end of a page.
%
%\item[\texttt{HS}]
% This display mode is convenient when the initial image aspect
@@ -326,13 +319,13 @@ Managing large and spread wide figures}
%\item[\texttt{VS}]
% This mode is convenient for tall and slim figures with aspect ratio
% not lower than~2; but for obvious reasons, it should not be too
-% large, let's say not higher than about~3. As always this depends on
+% large, let's say not higher than about~3 or~4. As always this depends on
% the page design and the caption size. The limitations of the
-% underlying of the |wrapfig| package forbids its usage too close to
-% section headings, explicit lists and texts typeset in special modes
-% with different measure than normal text. Again it is up to the user
-% to chose where to insert the \cs{DFfigure} command. If the aspect
-% ratio of the image to include is lower than~2, this message is printed
+% underlying |wrapfig| package forbids its usage too close to
+% explicit lists and texts typeset in special modes with a different
+% measure than normal text. Again it is up to the user to chose
+% where to insert the \cs{DFfigure} command. If the aspect ratio of
+% the image to include is lower than~2, this message is printed
% in the document where the image should appear (of course with |#1|
% replaced by the actual image file name):\\
%\begin{minipage}{0.7\textwidth}
@@ -490,16 +483,35 @@ Managing large and spread wide figures}
}
% \end{macrocode}
-% The |\cleartoevenpage| command may already exist in the document class.
+% The |\cleartoeven| command may already exist in the document class.
% We prefer to make an absolute redefinition so as to be sure that it
-% performs as we need in this package. We tested with the |memoir|
-% class that already has such a command, and no problems were found
+% performs as we need in this package. In any case this new definition
+% may be used in such a way that the |\DFimage| user command may be used
+% also while typesetting in text mode, resuming text mode after complete
+% expansion. This is useful, especially for spread wide display modes,
+% to chose the most suitable place in the suorce file to place the
+% |\DFimace| command with its arguments; only with the |SW| mode it
+% is necessary to avoid any space after the last macro argument and the
+% text that follows it.
%
% \begin{macrocode}
-\DeclareRobustCommand\cleartoevenpage{%
- \clearpage\ifodd\value{page}\null\clearpage\fi}
+\newcommand\set@tmode@newpage{%
+\ifvmode
+ \@SWtmodefalse
+\else
+ \@SWtmodetrue
+ \@bsphack\vadjust{\vspace{0pt plus1fill}\@esphack\newpage}%
+\fi}
+
+\newcommand\reset@tmode{\if@SWtmode\expandafter\noindent\ignorespaces\fi}
+
+\NewDocumentCommand\cleartoeven{ o }{%
+ \IfValueTF{#1}%
+ {\set@tmode@newpage
+ \ifodd\value{page}\afterpage{#1}\else#1\fi}%
+ {\ifodd\value{page}\null\clearpage\fi}}
+
% \end{macrocode}
-%
% Now we define the “real” user macro necessary to chose the
% \meta{display mode} and the various parameters necessary for the
% desired one. See section~\ref{sec:Usage} on page\pageref{sec:Usage}
@@ -544,9 +556,9 @@ Managing large and spread wide figures}
{\PackageWarning{swfigure}%
{%
**************************************\MessageBreak
- Option #1\space is not valid \MessageBreak
- Nothing done \MessageBreak
- Image #2\space was not processed \MessageBreak
+ Option #1\space is not valid \MessageBreak
+ Nothing done \MessageBreak
+ Image #2\space was not processed \MessageBreak
**************************************\MessageBreak}%
}%
}%
@@ -556,7 +568,7 @@ Managing large and spread wide figures}
}%
% \end{macrocode}
-% In the following subsection the five specific display mode macros
+% In the following subsections the five specific display mode macros
% are examined and commented.
%^^A=====================================
% \subsection{The \cs{SWfigure} macro for Spread Wide images}
@@ -567,35 +579,34 @@ Managing large and spread wide figures}
%\end{ttsyntax}
% The various arguments have already been described; as you see the
% \meta{display mode} argument is not there anymore, as well as the
-% last two optional arguments of |\DFfigure|.
-%
-% The working strategy is the following: first the typesetting mode is
-% tested and, in case, a filling of the current line is
-% performed and, by means of a |\vadjust| \TeX\ native macro, a
-% |\newpage| command is executed; in any case a |\cleartoevenpapge|
-% is executed so as to be sure to start any action while an even page
-% is being processed. Then the initial image to be divided in two
-% halves is stored in a box; this box is examined in order
+% last two optional arguments of |\DFfigure|.Notice that the
+% \meta{caption} text, the third argument of this macro, is used also
+% to initialise the \meta{lof entry}, so that if the user doe not
+% specify such short caption entry, the default is identica to the
+% full caption.
+%
+% The working strategy is the following: the initial image to be divided
+% in two halves is stored in a box; this box is examined in order
% to find its total width and heigh, so as to be able to compute the
% aspect ratio. All other dimensions are examined to have available
% all the necessary data to display the image halves in the requested
% way.
%
% Notice that the |trim| option to |\includegraphics|, used to
-% divide the initial image in two exact halves, (apparently) must
+% divide the initial image in two exact halves, maybe should
% be used without specifying other options; but, most important,
-% it requires real numbers, not macros; therefore we have to make
+% it requires actual numbers, not macros; therefore we have to make
% use of the usual dirty trick of defining an expanded macro
% |\x| within a group that the macro itself closes upon its
-% expansion; in this way the principal part of the |\includegraphics|
+% expansion; in this way the optional argument of the |\includegraphics|
% macro contains only keywords and numbers and may be executed
% without errors.
%
% Let $W$ be the total spread width and $w$ be the initial image
% width; let $H$ be the text height and $h$ the initial image height;
% compute the $A_\mathrm{W}$ to be the aspect ratio of the spread
-% available space $H/W$. Similarly let $A_\mathrm{fig}$ aspect
-% ratio of the initial image; we have to scale the image with a
+% available space $H/W$. Similarly let $A_\mathrm{fig}$ be the initial
+% image aspect ratio; we have to scale the image with a
% scaling factor such that the image keeps its aspect ratio, but
% its scaled height does not exceed the text block height, and
% its scaled width does not exceed the spread width; of course the
@@ -615,27 +626,21 @@ Managing large and spread wide figures}
%\label{equ:ScalingFactor}
%\end{equation}
% This choice is made by testing the various ratios by means of
-% the L3 |\fptest| macro, that computes such ratios and compares them.
-% The commented line below shows exactly which lengths are used to
-% compute the ratios, and which comparison is executed. Once the
+% the L3 |\fptest| function, that computes such ratios and compares them.
+% The \meta{test} shows exactly which lengths are used to
+% compute the ratios, and which comparison is executed; the commented
+% line over the |\fptest| macro emphasises this correspondence. Once the
% scaling factors are found the boxes containing the half figures
% are scaled and further on are inserted in floating figure
-% environments; we use another dirty trick of matrioska dolls; this
+% environments; we use une of the dirty tricks: the matrioska dolls; this
% metaphor describes nested |\makeboxe|s used to mask their actual
-% widths, but capable to push the images towards the spread
-% spine.
+% widths, but capable to push the images towards the spread spine.
% Eventually the caption is set in the right margin of the right
% spread page, rotated $90^\circ$ counterclockwise.
+% The |cleartoeven| guaranties that the first float is set into an even
+% numbered page. A final |\clearpage| ensures that both floats are output.
% \begin{macrocode}
\NewDocumentCommand\SWfigure{m O{#3} m o}{%
-\ifvmode
- \@SWtmodefalse
-\else
- \@SWtmodetrue
- \csuse{@bsphack}%
- \vadjust{\vspace{0pt plus1fill}\csuse{@esphack}\newpage}%
-\fi
-\cleartoevenpage
\setbox\DFtotalimage=\hbox{\includegraphics{#1}}%
\DFwidth=\wd\DFtotalimage \DFhalfwidth=0.5\DFwidth
\DFheight=\ht\DFtotalimage
@@ -657,20 +662,22 @@ trim = \the\DFhalfwidth\space 0 0 0]}\x{#1}}%
\setbox\DFimageI=\hbox{\scalebox{\DFscalefactor}{\usebox{\DFimageI}}}%
\setbox\DFimageII=\hbox{\scalebox{\DFscalefactor}{\usebox{\DFimageII}}}%
%
-\begin{figure}[p]%
-\vbox to\textheight{\vss\hsize=\textwidth%\
-\makebox[\hsize][l]{\makebox[\FigSpace][r]{\box\DFimageI}}\vss}%
-\end{figure}\clearpage
+\cleartoeven[%
+ \begin{figure}[p]%
+ \vbox to\textheight{\vss\hsize=\textwidth%\
+ \makebox[\hsize][l]{\makebox[\FigSpace][r]{\box\DFimageI}}\vss}%
+ \end{figure}\clearpage
%
-\begin{figure}[p]%
-\vbox to\textheight{\vss\hsize=\textwidth
-\makebox[\hsize][r]{\makebox[\FigSpace][l]{\box\DFimageII}%
+ \begin{figure}[p]%
+ \vbox to\textheight{\vss\hsize=\textwidth
+ \makebox[\hsize][r]{\makebox[\FigSpace][l]{\box\DFimageII}%
% Rotated caption in the right page
-\makebox(0,0)[lb]{\hspace*{1em}\raisebox{0.5\textheight}{%
-\rotatebox[origin=tc]{90}{\DFcaption[#2]{#3}[#4]%
-%
-}}}}\vss}%
-\end{figure}\clearpage\if@SWtmode\noindent\fi}
+ \makebox(0,0)[lb]{\hspace*{1em}\raisebox{0.5\textheight}{%
+ \rotatebox[origin=tc]{90}{\DFcaption[#2]{#3}[#4]%
+ %
+ }}}}\vss}%
+ \end{figure}%
+]\clearpage\reset@tmode}
% \end{macrocode}
%^^A========================================
@@ -830,14 +837,10 @@ trim = \the\DFhalfwidth\space 0 0 0]}\x{#1}}%
% the same hight and depth as the right page one.
% \begin{macrocode}
\NewDocumentCommand\HSfigure{m o m o d()}{%
- \unless\ifvmode
- \csuse{@bsphack}%
- \vadjust{\vspace{0pt plus1fill}\csuse{@esphack}\newpage}%
- \fi
- \cleartoevenpage
+ \cleartoeven
\setbox\DFtotalimage=\hbox{\includegraphics{#1}}
\DFwidth=\wd\DFtotalimage \DFhalfwidth=0.5\DFwidth
- \FigSpace=0.5\spreadwidth% W
+ \FigSpace=0.5\spreadwidth%
%
\setbox\DFimageI\hbox{\bgroup
\edef\x{\egroup\noexpand\includegraphics*[%