From b43e7047dad500959df8b9f82d6dd51142fb5724 Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Sun, 18 Oct 2020 20:51:07 +0000 Subject: swfigure (18oct20) git-svn-id: svn://tug.org/texlive/trunk@56695 c570f23f-e606-0410-a88d-b1316a301751 --- .../texmf-dist/source/latex/swfigure/swfigure.dtx | 183 +++++++++++---------- 1 file changed, 93 insertions(+), 90 deletions(-) (limited to 'Master/texmf-dist/source/latex/swfigure') diff --git a/Master/texmf-dist/source/latex/swfigure/swfigure.dtx b/Master/texmf-dist/source/latex/swfigure/swfigure.dtx index 4629fb398ce..5da66dfc6f4 100644 --- a/Master/texmf-dist/source/latex/swfigure/swfigure.dtx +++ b/Master/texmf-dist/source/latex/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] % %<*driver> \documentclass[a4paper]{ltxdoc}\errorcontextlines=9 @@ -102,7 +102,7 @@ Managing large and spread wide figures} \end{document} % % \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*[% -- cgit v1.2.3