summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/swfigure/swfigure.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/swfigure/swfigure.dtx')
-rw-r--r--macros/latex/contrib/swfigure/swfigure.dtx653
1 files changed, 488 insertions, 165 deletions
diff --git a/macros/latex/contrib/swfigure/swfigure.dtx b/macros/latex/contrib/swfigure/swfigure.dtx
index 671502d36d..54fc18ba64 100644
--- a/macros/latex/contrib/swfigure/swfigure.dtx
+++ b/macros/latex/contrib/swfigure/swfigure.dtx
@@ -43,7 +43,7 @@ files swfigure.sty and swfigure.pdf
%</driver>
%<+package>\ProvidesPackage{swfigure}%
%<*package>
- [2020-11-10 v.0.9.14 Managing large and spread wide figures]
+ [2020-12-23 v.0.9.18 Managing large and spread wide figures]
%</package>
%<*driver>
\documentclass[a4paper]{ltxdoc}\errorcontextlines=9
@@ -69,8 +69,10 @@ files swfigure.sty and swfigure.pdf
\renewcommand\parg[1]{\texttt{(\meta{#1})}}
\providecommand\Parg{}
\renewcommand\Parg[1]{\texttt{(#1)}}
-\providecommand\eTeX{}
+\providecommand\barg{}
+\renewcommand\barg[1]{\texttt{\char`|\meta{#1}\char`|}}
\newbox\SWsynt
+\providecommand\eTeX{}
\renewcommand\eTeX{\lower0.5ex\hbox{$\varepsilon\!$}\TeX}
\newcommand\Benv[1]{\cs{begin}\Marg{#1}}
\newcommand\Eenv[1]{\cs{end}\Marg{#1}}
@@ -105,12 +107,12 @@ Managing large and spread wide figures}
%</driver>
% \fi
%
-% \CheckSum{10}
+% \CheckSum{1040}
%
% \begin{abstract}
% This package defines a single command that with different options can
% insert large images into the document; those that occupy an entire
-% spread s get split into two halves that are inserted on
+% spread get split into two halves that are inserted on
% two facing pages in such a way that they merge when the document is read
% on the screen (set to double page view) or is printed in a well sewn
% book so that facing pages join correctly at the spine.
@@ -140,26 +142,24 @@ Managing large and spread wide figures}
%
% In the other case it is possible to manage such large figures in
% different ways; we define a single command that, according to
-% different settings, can insert such figures in six different display
+% different settings, can insert such figures in eight different display
% modes.
%\begin{enumerate}[noitemsep]
% \item
-% The normal \LaTeX\ kernel full page display mode, but using
-% the |figure| environment with the |[p]| placing option. Apparently
+% The normal \LaTeX\ kernel full page display mode, but setting the placement option to |[p]| to the figure environment. Apparently
% there is no need to define a new command for this display mode, except
% the advantage of using the same command as the other modes and a few
-% small further functionalities that the new command has available.
+% small further functionalities provided by this the new command.
%\item
-% The landscape display mode available with the |lscape| package
+% The landscape display mode is available with the |lscape| package
% and other similar ones. Again this display mode appears superfluous,
-% but the advantage is to use the same command as with the other
-% display modes
+% but the advantage is to use the same command as the other display modes.
%\item
% The screen-wide display mode, where two facing pages display a large
% figure divided in two halves, each one set in its page shifted to the
% spine so as to occupy on each page the text width plus the internal
-% margin width; with suitable aspect ratio, both facing pages are
-% practically full. No other text appears in this display mode, except
+% margin; with suitable aspect ratio, both facing pages are practically
+% full. No other text appears on the page with this display mode, except
% the caption in the right page external margin.
%\item
% The slim screen-wide image is similar to the previous mode, but since
@@ -168,29 +168,45 @@ Managing large and spread wide figures}
% page, and the left text block height is set so that that the first
% lines of both text blocks are aligned.
%\item
-% The slim tall image is set to the side of the text block that wraps
-% it. Recurse is made to the |wrapfig| package, therefore the software
-% might sometimes hick-up a little bit, because of the idiosyncrasies of
-% |wrapfig| that performs very well in most but not all circumstances;
-% see that package documentation for such |wrapfig| limitations. With
-% this |wsfigure| package we limit the use of this display mode to
-% images that have a “height over width” ratio not lower than~2; we
-% provide also some option arguments so as to correct small imperfections
-% in the sizing of the text indention
+% The slim tall image is set to the side of the text block with text
+% wrapping it. Recurse is made to the |wrapfig| package, therefore the
+% software might sometimes hick-up a little bit, because of the
+% idiosyncrasies of |wrapfig| that performs very well in most but not
+% all circumstances; see that package documentation for such |wrapfig|
+% limitations. With this |wsfigure| package we limit the use of this
+% display mode to images that have a “height over width” aspect ratio
+% not lower than~2; we provide also some option arguments so as to correct
+% small imperfections in the sizing of the text indention
%\item
-% A very large image, typically A3 sized, that occupies a full spread
+% A very large image, typically A3 sized, occupies a full spread
% including the lateral margins; it is a solution to inputting, for
% example, a line drawing of a technical device, that otherwise
% should be attached as a separate document; a very large table
-% that does not fit the usual A4 paper and that cannot be reduced
-% by means of |longtable| or scaled down to unreadable font sizes.
+% that does not fit the usual A4 paper and that cannot be split in chunks
+% by means of |longtable|, and cannot be scaled down to unreadable font
+% sizes.
+%\item
+% A rather tall not so slim image can be typeset in the total height
+% mode; this height is the paper (trimmed page) height; the image
+% appears in a textless page, shifted to the spine, taking into
+% account if the page is an odd or even numbered one. The image
+% is scaled so that leaves on it side the external margin plus a part
+% of the text width, generally sufficient for a side caption; it reaches the
+% top and the bottom limits of the trimmed page. Should this space
+% be to narrow for a decently typeset caption, a warning
+% message is issued but the compilation is not stopped. It is up
+% to the user to control how bad is the caption typesetting and
+% possibly to provide a different display mode in order to get a
+% better result.
+% \item
+% Anothe display mode, that we call Total Width
%\end{enumerate}
%
% In any case, depending on the page geometry and the image aspect
% ratio, it is very handy to have available a single command that
% changes the display mode by just changing a single input optional
-% argument. In facts the user might start with one of the six
-% described display modes; after examining the document daft the
+% argument. In facts the user might start with one of the eight
+% described display modes; after examining the document draft the
% user might chose another display mode, and it suffices to change
% the optional argument, without changing the whole code.
%
@@ -215,7 +231,7 @@ Managing large and spread wide figures}
% Should the user have available a basic or a partial \TeX\ system
% installation, the simplest way to install this package is to download
% the |swfigure.zip| file from the Comprehensive \TeX\ Archive Network
-% (CTAN), and decompress it either in the very folder where there is
+% (CTAN), to 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 |texmf| personal tree; it might be necessary that the user
% should directly create this personal tree; how to do it is described
@@ -244,56 +260,65 @@ Managing large and spread wide figures}
%\begin{ttsyntax}
%\cs{DFimage}\oarg{display mode}\marg{image file name}\%
%\qquad \oarg{lof entry}\marg{caption}\oarg{label}\%
-%\qquad\parg{height correction}\aarg{line correction}|\meta{width test}|!\meta{precaption}!
+%\qquad\parg{height correction}\aarg{line correction}\barg{width test}!\meta{precaption}!
%\vspace{0.5\baselineskip}
%or
%\vspace{0.5\baselineskip}
% \Benv{DFimage}\oarg{display mode}\marg{image file name}\%
%\qquad \oarg{lof entry}\marg{caption}\oarg{label}\%
-%\qquad\parg{height correction}\aarg{line correction}|\meta{width test}|!\meta{precaption}!
+%\qquad\parg{height correction}\aarg{line correction}\barg{width test}!\meta{precaption}!
%\meta{environment textual contents}
%\Eenv{DFimage}
%\end{ttsyntax}
% \noindent where:
%\begin{description}[noitemsep]
+%
%\item[\meta{display mode}]
% is one of the following uppercase acronyms:
% \texttt{NF} (Normal Figure), \texttt{RF} (Rotated Figure),
% \texttt{SW} (Spread Wide image), \texttt{HS} (Horizontal Spread-wide
-% image), \texttt{VS} (Vertical Slim image), and \texttt{FS}
-% (Full Spread image).
+% image), \texttt{VS} (Vertical Slim image), \texttt{FS}
+% (Full Spread image), \texttt{TH} (Total Height image), and \texttt{TW} (Total Width image).
+%
%\item[\meta{image file name}]
% 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
% specify the extension, but it is not forbidden.
+%
%\item[\meta{lof entry}]
% is the optional entry to the List Of Figures; it defaults to the
% \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.
+%
%\item[\meta{label}]
% 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 or color}]
% is a round parenthesis delimited optional argument; as a
% \emph{height correction} 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.
+% by others. In the total height mode, it can be used to scale the
+% captions width.
+%
%\item[\meta{line correction}] is an angle bracket delimited optional
% argument preset to zero. It is relevant only with the slim
% vertical image display mode. Sometimes the |wrapfig| package
% indents the wrapping text in such a way as to leave to much or too
% little vertical space around the image and its caption; by examining
-% the document drafts it is possible to correct the predetermined
-% number of lines by increasing or decreasing the vertical space by
-% any (integer) number of lines.
-%\item[\meta{width test}] this further vertical bars-delimited argument
+% the document draft it is possible to correct the predetermined
+% number of indented lines by increasing or decreasing the vertical
+% space by any (integer) number of lines.
+%
+%\item[\meta{width test}] this further vertical bar-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 below the
@@ -303,12 +328,14 @@ Managing large and spread wide figures}
% \meta{width test} fraction is \texttt{0.25}, but the user can specify
% a different value, even zero; with the zero value this width test is
% skipped.
-%\item[\meta{precaption}] is an optional color declaratio delimited by
+%
+%\item[\meta{precaption}] is an optional color declaration delimited by
% exclamation points; the default value is ‘empty’; it is used only
% by the \texttt{FS} display mode in order to typeset a caption, for
% example, with a contrasting color over the background image average
% color, and/or with a displacement of the first or only caption line,
% and/or with a different font.
+%
%\end{description}
%
%^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@@ -326,9 +353,9 @@ 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 option is fixed to~|[p]|, an only-float page.
-% Therefore don't use it it the image is not really such as to occupy
-% most of text block area.
+% although its positioning option is fixed to~|[p]|, a float-only page.
+% Therefore don't use it if the image is not really such as to occupy
+% most of the text block area.
%
%\item[\texttt{RF}]
% This display mode is convenient when the image
@@ -354,7 +381,7 @@ Managing large and spread wide figures}
% If the aspect ratio of the image to include is lower than~2, the
% following message is printed in the document where the image
% should appear (of course with |#1| replaced by the actual image
-% file name):\\
+% file name):\\[2ex]
%\begin{minipage}{0.7\textwidth}
%\begin{verbatim}
% ===========================================
@@ -382,13 +409,16 @@ Managing large and spread wide figures}
% then should help the automatic positioning by choosing very carefully
% 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.
+% The command or the environment may be used even within a source file
+% paragraph; with a little attention: there should be no space between
+% the end document command and the first character of the following text.
%
%\item[\texttt{HS}]
% This display mode is convenient when the initial image aspect
% ratio is very small; if it is smaller than~0.3 its insertion
% leaves enough space beneath the two image halves (plus caption)
% so that normal text can fill the space under such spread wide
-% slim figure. The constrains described for display mode \texttt{SW}
+% slim figure. The constraints described for display mode \texttt{SW}
% apply also to this mode.
%
% \item[\texttt{FS}]
@@ -399,24 +429,64 @@ Managing large and spread wide figures}
% without scaling down its contents. With this full occupation of both
% facing pages, there is no room for any caption; therefore the actual
% image, besides occupying an A3 page, should have a minimum white
-% margin around, so that a caption can be superimposed to the white
+% margin around, so that a caption can be superimposed to the image white
% part if its original bottom margin that, upon rotation, becomes the
-% right one. If the original image has no margins, the caption may be
-% typeset with contrasting different color from the default black one.
-%
+% right one, is large nough. If the original image has no margins, the
+% caption is typeset ove the image, but it may be colored with contrasting
+% color compared to the average background one.
+%
+% \item[\texttt{TH}]
+% This mode is suited for tall figures that do not show well when their
+% height is scaled to the text height; the upper and lower margins are
+% available for a larger scale factor; even the internal margin is
+% helpful to gain some space. In this case, though, the page header and
+% footer should be avoided and the figure caption should be set at the
+% image side, without any rotation; the little problem that arises in
+% this case is that the caption, always close to the external margin,
+% should not be rotated and its measure should be adapted in order to
+% properly use the horizontal space left on the page. If this space is
+% too narrow the figure, in spite if being taller then wide, is too
+% wide: it has an aspect ratio higher than one but not enough. This
+% display mode requires that the image has an aspect ratio greater
+% than, say, $\sqrt2$, otherwise the caption measure becomes too short.
+% A warning message is issued if the total space left on the page is
+% smaller than the external margin, where the caption would have the
+% same measure as a marginal note. In spite if this fact, compilation
+% goes on, and the attentive user not only evaluates the result,
+% and examines the \texttt{.log} file where he finds the explanation
+% of the possibly too bad result.
+% \item[\texttt{TW}]
+% A another Total Width mode is is defined such that the scaled
+% image and its (side) caption occupy the upper part of the page/paper.
+% The given image is scaled to occupy the internal margin plus 80\%
+% of the text block width; the remaining horizontal space is provided
+% for a side caption and its lateral spaces, If the aspect ratio
+% of the original image is not smaller than text block and internal
+% margin widths divided by the paper height, the scaling might produce
+% a scaled image too tall to fit into the paper. No tests are made
+% in this sense, but it is up to the user the best choice for
+% displaying a given image. On an A4 paper, depending on the page
+% design, the aspect ratio available should be approximately 1.8,
+% therefore this design accommodates a large number of different
+% aspect ratio images, from a not so slim tall portrait image to
+% a landscape image. A square image, scaled as described above,
+% may occupy approximately the upper half of the page.
+% The caption is always well typedset in the adjacent free space,
+% and it is possible to slightly modify its measure by using an
+% optional argument.
%\end{description}
%
%^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% \section{Acknowlegements}
%^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
-% This package would not exist if Heinrich Flech did not need
-% to insert several types of large images in his documents; he asked
+% This package would not exist if Heinrich Fleck did not need
+% to insert several large images in his documents; he asked
% me to create suitable commands and/or environments and he tested
% all the series of progressive developments of this package; believing
% that this package might be useful to other \TeX\ users, he invited
% me to submit the result to the \TeX\ community, and here it is.
-% Heinrich did not want his name as an author, because he insists
+% Heinrich did not want his name as a co-author, because he insists
% that he was “just” a tester. He was precious and I warmly thank him.
%
% Thanks also to Benedict Wilde who spotted some errors and suggested
@@ -429,6 +499,12 @@ Managing large and spread wide figures}
% different formats and page designs; but this was not my aim: I wanted
% something possibly independent from the document class and not
% requiring any particular printer.
+% The seventh display mode came to our minds when we found tall figures
+% that did not show well scaled to the \emph{text block} height, but could
+% show better if scaled to \emph{paper} height, with the caption at their
+% side; actually we found that it was better to scale the image to a
+% width of the internal margin plus 80\% of the text width, and placing
+% the image flush to the upper paper border and to the spine. The eighth display mode is a varinat of the preceding one and allows to place some text beneath the image and caption block.
%
%^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%\newpage
@@ -456,7 +532,7 @@ Managing large and spread wide figures}
%\iffalse
%<*package>
%\fi
-% The required \TeX\ format and is date, and the identification of this
+% The required \TeX\ format with is date, and the identification of this
% package have already ben inserted by the initial commands of this
% documented file.
%
@@ -468,7 +544,7 @@ Managing large and spread wide figures}
% variables, are also numerical expressions connected with relation
% operators; for further details it suffices to examine the
% |interface3.pdf| file, that is integral part of any recent \TeX\
-% system distribution. We neede also some commands to compare strings
+% system distribution. We needed also some commands to compare strings
% or to check if a given string was included into an L3 sequence
% (list) of strings.
%
@@ -480,14 +556,15 @@ Managing large and spread wide figures}
% are \verb+||+ (\texttt{OR}), \verb+&&+ (\texttt{and}), and \verb+!+
% (\texttt{NOT}), plus other less common ones; the \verb+!+ negates the
% status of boolean variables, but also the numerical relation operators;
-% these, on turn, may be paired so that, for example |>=| is the same
+% these, on turn, may be paired so that, for example |>=| behaves as
% as~|!<|.
+%
% The comparisons of strings with the following syntax
%\begin{ttsyntax}
%\cs{CompStrings}\marg{string\ped{1}}\marg{string\ped{2}}
%\end{ttsyntax}
-%Produces a boolean result that may be used as a \meta{test} argument
-% to |\fptest|
+% Produces a boolean result that may be used as a \meta{test} argument
+% to |\fptest|.
% The |\SetList| macro defines a named L3 sequence variable containing
% the reference list of valid display modes, while the |\TestList| is
% an L3 function that tests if a given string is listed in a named
@@ -496,16 +573,14 @@ Managing large and spread wide figures}
%\cs{SetList}\marg{list name}\marg{comma separated string list}
% \cs{TestList}\meta{string}\marg{list name}\marg{true}\marg{false}
%\end{ttsyntax}
-% The fields \meta{true} and \meta{false}, as usual, are the action
+% The fields \meta{true} and \meta{false}, as usual, are the actions
% to be executed if the test is true or false; the test is true if
% \meta{string} is listed into the \meta{named list}.
%
-% The |trace| package is still present in this beta version of the
-% package; it will not be present any more in the future stable versions.
% Packages |graphicx|, |afterpage|, and |wrapfig| are functional
-% for this package. In order to avoid “Option Clash” messages, such
-% packages are loaded without any option; should the user load some
-% or all of them with options, the user should load them
+% for this package. In order to avoid “Option Clash” error messages,
+% such packages are loaded without any option; should the user load
+% some or all of them with options, the user should load them
% \emph{before} loading this package. This particular documentation
% does not require the |graphicx| package, because it is already
% loaded by |swfigure|.
@@ -529,8 +604,6 @@ Managing large and spread wide figures}
\ExplSyntaxOff
-\RequirePackage{trace}
-
\RequirePackage{graphicx}
\RequirePackage{afterpage}
\RequirePackage{wrapfig}
@@ -540,13 +613,15 @@ Managing large and spread wide figures}
% we assign parameters relating to the page design. We also compute
% the dimensions of the available spread space so as to have available
% the elements to compare the aspect ratios of the images and of the
-% available spaces. The |\if@SWtmode| switch is used only by the |SW|
-% display mode in order to save the typesetting mode that was active
-% when the |\DFimage| command was used in the source file; if it was
-% in text mode, the switch is set to |true| and no spaces should be
-% present after the last argument of that macro; the result is that
-% the |\SWfigure| service macro shifts to vertical mode, but as soon
-% as it is completed the switch test restores the text mode.
+% available spaces. The |\if@SWtmode| switch is used by all text modes
+% in order to save the typesetting mode that was active when the
+% |\DFimage| command or the homonymous environment was used in the source
+% file; if it was in text mode, the switch is set to |true| and no spaces
+% should be present after the last argument of that macro or after the
+% closing environment statement; the result is that every service macro
+% shifts to vertical mode, but as soon as it is completed the switch test
+% restores the text mode. A blank line, though, after the command or the
+% environment starts a new paragraph.
%
% \begin{macrocode}
\newdimen\internalmargin
@@ -562,6 +637,7 @@ Managing large and spread wide figures}
\newdimen\DFheight
\newdimen\DFhalfheight
\newdimen\FigSpace
+\newdimen\TScaptionwidth
\def\SWcaptionShift{1em}%
\def\FScaptionShift{2em}%
\newsavebox\DFtotalimage
@@ -577,12 +653,13 @@ Managing large and spread wide figures}
% a zero height vertical box and deal with the mandatory and optional
% arguments according to the following syntax:
%\begin{ttsyntax}
-%\cs{DFcaption}\oarg{lof entry}\marg{caption}\oarg{label}
+%\cs{DFcaption}\oarg{lof entry}\marg{caption}\oarg{label}\\[1ex]
+%\cs{DFcaptionP}\oarg{lof entry}\marg{caption}\oarg{label}
%\end{ttsyntax}
% Notice that the \meta{lof entry} defaults to the full caption text if
% a different text is not explicitly entered.
-% This commands are specific to those display modes that compose
-% the caption in vertical mode, therefore the caption measure is the
+% These commands are specific to those display modes that compose
+% the caption in vertical direction, therefore the caption measure is the
% |\textheight|.
% \begin{macrocode}
\NewDocumentCommand\DFcaption{O{#2} m o}{\refstepcounter{figure}%
@@ -591,7 +668,7 @@ Managing large and spread wide figures}
\addcontentsline{lof}{figure}{\protect\numberline{\thefigure}#1}
\IfValueT{#3}{\label{#3}}\relax%
}
-\NewDocumentCommand\DFcaptionP{O{#2} m o D!!{black}}%
+\NewDocumentCommand\DFcaptionP{O{#2} m o D!!{\color{black}}}%
{\refstepcounter{figure}%
\vbox to 0pt{\vss\hsize=\textheight\parindent=0pt\leavevmode
#4\relax Figure \thefigure\quad #2}%
@@ -609,6 +686,9 @@ Managing large and spread wide figures}
% after complete expansion. This is useful, especially for spread wide
% display modes, to chose the most suitable place in the source file to
% place the |\DFimage| command with its arguments.
+% The |\cleartoeven| possibly inserts an empty page if the new page
+% is odd numbered; the |\cleartopage| simply clears the current page,
+% but it does not insert any empty page.
%
% \begin{macrocode}
@@ -617,7 +697,7 @@ Managing large and spread wide figures}
\@SWtmodefalse
\else
\unskip\@SWtmodetrue\linebreak
- \vadjust{\vspace{0pt plus1fill}\newpage}%
+ \vadjust{\vspace{0pt plus1fill}\par}%
\fi}
\newcommand\reset@tmode{\if@SWtmode\expandafter\noindent\ignorespaces\fi}
@@ -627,31 +707,36 @@ Managing large and spread wide figures}
\ifodd\c@page\afterpage{#1}\else#1\fi%
}
+\newcommand\cleartopage{\set@tmode@newpage\clearpage}
+
% \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}
% for its syntax and the other necessary arguments. Notice that only
% two arguments are mandatory: the \meta{image file name} and the
-% \meta{caption} text. All the other five optional parameters are
+% \meta{caption} text. All the other eight optional parameters are
% delimited by various delimiters; the first one, \meta{display mode}
% has as default setting the acronym \texttt{SW} for a “Spread-Wide”
% display mode; this mode was the one this package was initially
% conceived for, and its initials recall this priority. All other
-% modes came afterwards. the other optional parameters may have a
-% default value, but they are ignored by certain modes that don use
-% those parameters. As for the previous macro |\DFimage|, here
+% modes came afterwards. The other optional parameters may have a
+% default value, but they are ignored by certain modes that don't use
+% those parameters. As for the previous macro, for |\DFimage|
% the \meta{lof entry} defaults to the full \meta{caption} text.
%
% Actually \cs{DFimage} just examines the \meta{display mode}, and
% accordingly passes the necessary parameters to the actual macros
% that implement the various mode displays. It outputs an error
% message if the \meta{display mode} acronym was misspelt.
+% The |\DFimage| command (and environment) needs the full list
+% of arguments, whileand the |DFwarning| macros requires just
+% the two arguments it is going to actually use.
% \begin{macrocode}
\NewDocumentEnvironment{DFimage}%
- {O{SW} m O{#4} m o D(){0.8} D<>{0} D||{0.25} D!!{}}%
+ { O{SW} m O{#4} m o D(){0.8} D<>{0} D||{0.25} D!!{} }%
{%
- \SetList{\DisplayModeList}{SW,HS,VS,FS,NF,RF}%
+ \SetList{\DisplayModeList}{SW,HS,VS,FS,NF,RF,TH,TW}%
\TestList{\DisplayModeList}{#1}%
{\csuse{#1figure}{#2}[#3]{#4}[#5](#6)<#7>|#8|!#9!%
\fptest{\CompStrings{\@currenv}{DFimage}}{}{\reset@tmode}%
@@ -664,19 +749,18 @@ Managing large and spread wide figures}
\aftergroup\reset@tmode
}%
-\NewDocumentCommand\DFwarning{ o m o m o d() d<> d|| d!!}%
-{\PackageWarning{swfigure}%
+\NewDocumentCommand\DFwarning{ o m o m }{%
+\PackageWarning{swfigure}%
{********************************************\MessageBreak
Option #1\space is not valid. Nothing done \MessageBreak
\MessageBreak
Image #2 was not processed \MessageBreak
- *******************************************\MessageBreak
+ ********************************************\MessageBreak
}%
}
-
% \end{macrocode}
-% In the following subsections the six specific display mode macros
+% In the following subsections the eight specific display mode macros
% are examined and commented.
%^^A=====================================
% \subsection{The \cs{SWfigure} macro for Spread Wide images}
@@ -688,10 +772,10 @@ 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|.Notice that the
+% 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
+% to initialise the \meta{lof entry}, so that if the user does not
+% specify such short caption entry, the default is identical to the
% full caption. Notice the the last arguments are not actually used;
% they are needed in the definition due to the way |DFimage| transfers
% its arguments to the called macros.
@@ -713,8 +797,8 @@ Managing large and spread wide figures}
% 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;
+% Let $W$ be the total spread width and $w$ be the original image
+% width; let $H$ be the text height and $h$ the original image height;
% compute the $A_\mathrm{W}$ to be the aspect ratio of the spread
% available space $H/W$. Similarly let $A_\mathrm{fig}$ be the initial
% image aspect ratio; we have to scale the image with a
@@ -743,8 +827,8 @@ Managing large and spread wide figures}
% 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 une of the dirty tricks: the matrioska dolls; this
-% metaphor describes nested |\makeboxe|s used to mask their actual
+% environments; we use one of the dirty tricks: the matrioska dolls; this
+% metaphor describes nested |\makebox|es used to mask their actual
% 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.
@@ -783,7 +867,7 @@ trim = \the\DFhalfwidth\space 0 0 0]}\x{#1}}%
\begin{figure}[p]%
\vbox to\textheight{\vss\hsize=\textwidth
\makebox[\hsize][r]{\makebox[\FigSpace][l]{\box\DFimageII}%
-% Rotated caption in the right page
+% Rotated caption in the right odd-numbered page
\makebox(0,0)[lb]{\hspace*{\SWcaptionShift}\raisebox{0.5\textheight}{%
\rotatebox[origin=tc]{90}{\DFcaption[#2]{#3}[#4]%
%
@@ -797,10 +881,10 @@ trim = \the\DFhalfwidth\space 0 0 0]}\x{#1}}%
% page figures}
%^^A========================================
% This code is without surprises, except that it receives from the
-% |DFimage| steering macro five usable arguments (plus three more
+% |DFimage| selector macro five usable arguments (plus three more
% ones that are not actually used); the fifth (optional) one
% being delimited by round parentheses; by default, it contains the
-% value 0.8, but the user can pass to the steering macro a different
+% value 0.8, but the user can pass to the selector macro a different
% value in order to reduce the actual image size so as to leave
% enough space beneath it for the caption; the user, in facts, does
% not know in advance how many lines would occupy a structured
@@ -823,11 +907,11 @@ trim = \the\DFhalfwidth\space 0 0 0]}\x{#1}}%
% way of displaying a large figure, except, perhaps, the fact
% the instead of invoking the |lscape| package, the whole figure
% is rotated by means of rotating the very box that was used
-% to contain the scaled image; the steering macro does not pass
+% to contain the scaled image; the selector macro does not pass
% any \meta{height correction} argument to this macro, because
% it automatically scales the box containing the image and
% the caption so as to fill up the height or the width of the
-% text block. Of course the macro signature includes also
+% text block. Of course the macro L3 signature includes also
% the descriptors of unused arguments.
% \begin{macrocode}
\NewDocumentCommand\RFfigure{m o m o d() d<> d|| d!!}{%
@@ -858,20 +942,20 @@ trim = \the\DFhalfwidth\space 0 0 0]}\x{#1}}%
% textual contents of the text block the result may be very good.
%
% The user is recommended to attentively read the |wrapfig|
-% documentation because it has several limitations. here we suggest
+% documentation because it has several limitations. Here we suggest
% the user to open the environment just before a paragraph and
% close it after several paragraphs; remember that since the opening
% and the closing statements are far away from one another, it is
-% possible to forget this situation and insert another such environment
-% within the former one ,or a |\DFimage| command, and this will
-% produce undesirable effects; never ever nest two |Dfimage|
-% environments and never ever insert a |\DFimage| command within
-% an environment.
+% possible to forget this situation and insert another such
+% environment, or a |\DFimage| command, within the former one
+% and this will produce undesirable effects; never ever nest two
+% |Dfimage| environments and never ever insert a |\DFimage| command
+% within an environment.
%
% The user should help a little bit the correct performance of
% this macro; for this reason, besides the \meta{height correction}
-% factor, the steering macro may pass to it also the \meta{line
-% correction} in order to correct the amount of lines the surrounding
+% factor, the selector macro may pass to it also the \meta{line
+% correction} in order to correct the amount of lines the wrapping
% text should be indented; by playing with both corrections
% good results may be obtained.
%
@@ -890,7 +974,7 @@ trim = \the\DFhalfwidth\space 0 0 0]}\x{#1}}%
% its delimiting tokens are two vertical bars, \verb+| |+, and its
% default value is \texttt{0.25}. This means that if the scaled
% image becomes narrower than this coefficient times the text width,
-% an other message is typeset in place of the figure. Depending of the
+% an other message is typeset in place of the figure. Depending on the
% various elements that influence these tests, the user can try
% different values for this coefficient, even reaching the value zero,
% that eliminates such test on the scaled image width.
@@ -902,22 +986,22 @@ trim = \the\DFhalfwidth\space 0 0 0]}\x{#1}}%
\DFwidth=\wd\DFtotalimage \DFheight=\ht\DFtotalimage
\edef\VS@aspectratio{\fpeval{\DFheight/\DFwidth}}
\fptest{ \VS@aspectratio < 2 }%
- {\begin{center}\ttfamily
+ {\begin{center}\ttfamily\relax
===========================================\\
- Image \textit{#1} is not tall enough.\\
- Consider using a display mode different\\
+ Image #1 is not tall enough. \\
+ Consider using a display mode different \\
from VS; may be NF or RF are better suited.\\
===========================================\\
- Nothing done!\\
+ Nothing done! \\
===========================================
\end{center}
}%
{\edef\VS@factor{\fpeval{#5\textheight/\DFheight}}%
\fptest{\VS@factor>1 || \VS@factor\DFwidth < #7\textwidth}%
{%
- \begin{center}\ttfamily
+ \begin{center}\ttfamily\relax
=================================================\\
- The scaled image \textit{#1} is too slim. \\
+ The scaled image #1 is too slim. \\
Maybe directly using the wrapfig package might \\
solve this problem. \\
=================================================\\
@@ -944,14 +1028,13 @@ trim = \the\DFhalfwidth\space 0 0 0]}\x{#1}}%
% \end{macrocode}
%
%^^A=====================================
-% \subsection{The \cs{HSfigure} macro for spread wide slim
-% figures}
+% \subsection{The \cs{HSfigure} macro for spread wide slim figures}
%^^A=====================================
%
% The beginning of the macro is not so different from that used
% for the |SWfigure| macro. But this time there is no alternative
-% to scale the image taking into account only its width and the
-% spread width. The new little problem, now, is to match the total
+% to scale the image because only its width and the spread width are
+% significant. The new little problem, now, is to match the total
% height of the two halves of the original wide and slim image,
% so that the texts of the two facing pages have their respective
% first lines perfectly aligned.
@@ -1001,7 +1084,9 @@ trim = \the\DFhalfwidth\space 0 0 0]}\x{#1}}%
}%
}%
}
+
% \end{macrocode}
+%
%^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%\subsection{The \cs{FSfigure}~macro for Full Spread figures}
%^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@@ -1010,9 +1095,9 @@ trim = \the\DFhalfwidth\space 0 0 0]}\x{#1}}%
% advanced printers that use different sized papers, this package aims
% to be independent form any class and any printer; it is limited to
% the ordinary default paper size A4, as it is usual in Europe, but
-% letter paper is also valid); ideally it would typeset an A3 sized
-% image on a full spread, i.e. by using also the space of all the
-% margins.
+% letter paper is also valid; ideally it would typeset an A3 sized
+% image on a full spread, i.e. by filling also the space of all the
+% lateral margins.
%
% Actually with American paper sizes there is not a series of sizes
% that behaves as the ISO A series, but this macro tries to adjust the
@@ -1024,12 +1109,12 @@ trim = \the\DFhalfwidth\space 0 0 0]}\x{#1}}%
% two identically sized halves, and sets them on two facing pages joining
% them at the spine but covering the greatest part of both pages, so
% as to avoid exceeding either the paper height or twice the paper width.
-% If the image has an aspect ratio close to $\sqrt{1/2}$, it does the
-% same, except rotating the image.
+% If the image has an landscape aspect ratio close to $\sqrt{1/2}$, it
+% does the same, except rotating the image.
%
% In any case the user creates a separate PDF file to be imported into
% the document that is supposed to contain it; it is better if this PDF
-% is of vectorial type, i.e. any drawing and all fonts should should be
+% is of vectorial type, i.e. any drawing and all fonts should be
% vectorial; this PDF might contain photos or similar images of
% rasterised type, but the pixel density should be suitably high in
% order to preserve the image quality.
@@ -1041,9 +1126,9 @@ trim = \the\DFhalfwidth\space 0 0 0]}\x{#1}}%
% therefore if a caption is needed, it is overprinted on the image;
% in case $(a)$ there are no problems because the caption goes over
% the white right margin (rotated 90° counterclockwise); while in
-% case $(b)$ the caption is over printed un the right side of the
+% case $(b)$ the caption is over printed on the right side of the
% image; depending on the image “background” a different color
-% might be more suited compared to black (the default color).
+% might be more suited compared to the the default color (black).
% The last macro argument takes care of inserting before the caption
% any declaration that may involve color, displacement, font encoding
% (seldom necessary), family, series, shape and size;
@@ -1053,7 +1138,7 @@ trim = \the\DFhalfwidth\space 0 0 0]}\x{#1}}%
% optional arguments in a different way:
%\begin{ttsyntax}\setfontsize{9.25}%
%\cs{FSimage}\marg{image file name}\oarg{lof entry}\marg{caption text}\oarg{label string}
-%\qquad\parg{height correction}\aarg{line correction}|\meta{width text|!\meta{precaption}!
+%\qquad\parg{height correction}\aarg{line correction}\barg{width text}!\meta{precaption}!
%\end{ttsyntax}
% The above is the full definition, but the fifth, sixth and seventh
% arguments are not used; they are necessary for the special
@@ -1062,33 +1147,33 @@ trim = \the\DFhalfwidth\space 0 0 0]}\x{#1}}%
%
% Moreover, since the included image overlaps the top and bottom
% margins, if these contain the header and footer such elements
-% would show if the image is not opaque enough; in any case the
+% would show if the image is not sufficiently opaque; in any case the
% footer would show because it overlaps the image. Since most
-% images are not opaque at all it is better to locally use the
+% images are not really opaque it is better to locally use the
% \texttt{empty} page style, but without using the |\thispagestyle|
-% command, because it hold for just one page, while the spread
-% occupies two pages. The macro provides this setting but it has
+% command, because it holds for just one page, while the spread
+% occupies two pages. The macro provides this setting but it has
% to create a group in case the |\DFimage| command is used, while
% it is not necessary when using the |DFimage| environment,
% therefore the current environment is tested and the opening
-% |\bgroup| and closing |\egroup| commands are used onlY if the
+% |\bgroup| and closing |\egroup| commands are used only if the
% code is used without the environment.
%
% Therefore the code steps are the following:
%\begin{enumerate}[noitemsep]
%\item
% The initial figure is loaded into a box from which the necessary
-% measures are taken; in particular the its width and its height in
+% measures are taken; in particular its width and its height in
% order to check the aspect ratio, or better, which dimension is greater
% than the other. If the height is smaller than the width the image is
-% sort of panoramic and we proceed splitting the total image box into
+% sort of landscape and we proceed splitting the total image box into
% two equal halves, with a vertical cut in the middle.
%\item
% Otherwise the image is as a portrait, and we split the total image
% block into two halves with an horizontal cut in the middle; such two
% boxes need a rotation of 90° anticlockwise due to the horizontal cut of
-% an original higher than wide image. With this operation we simulate a
-% rotation of the original image, because it is not allowed to
+% an original that was higher than wide image. With this operation we
+% simulate a rotation of the original image, because it is not allowed to
% simultaneously rotate and trim the original image; the trimming
% action apparently cannot be executed together with any other one
% among the many other that the |\includegraphics| command can
@@ -1101,7 +1186,7 @@ trim = \the\DFhalfwidth\space 0 0 0]}\x{#1}}%
% equal halves with the aspect ratio of the paper. If the former
% aspect ratio is higher than the latter, the scaling factor is
% based on the heights, otherwise on the widths, so as to resize
-% both half picture boxes to fit within the page.
+% both half picture boxes to fit within the paper.
%\item
% The |\cleartoeven| command allows to use the main macro even within
% a paragraph; in any case it possibly inserts a blanc page and restarts
@@ -1122,7 +1207,7 @@ trim = \the\DFhalfwidth\space 0 0 0]}\x{#1}}%
% Eventually a |\clearpage| flushes out everything that is still in
% the figure stack and possibly restores the vertical or horizontal
% typesetting mode depending on the status that was in force when
-% the |\DFimage| command or the |DFimage| environment started its
+% the |\DFimage| command or the |DFimage| environment started their
% expansion.
% Due to the size of the images that completely fill up all the
% margins, probably the best way to output such huge images is at
@@ -1192,11 +1277,276 @@ trim = \the\DFhalfwidth\space 0 0 0]}\x{#1}}%
}\clearpage
\fptest{\CompStrings{\@currenv}{DFimage}}{}{\egroup}%
\reset@tmode}
+
+% \end{macrocode}
+%
+%^^A========================================
+%\subsection{The \cs{THfigure} macro for the Total Height figure}
+%^^A========================================
+% This Total Height display mode exploit the total paper height to
+% scale a figure and sets the image close to the spine independently
+% from the fact that the spine ins on the right of even numbered
+% pages, and on the left on odd numbered ones; a test is made on the
+% page parity, that in any case is going to contain only the figure
+% with its caption and nothing else. For this reason the macro provides
+% a \cs{cleartopage} at the beginning and another similar command on the
+% end. As usual this macro is not supposed to be used by the user,
+% who should use the command \cs{DFimage}; using the environment
+% is recommended if it is used within a paragraph, but it should not
+% include any text.
+%
+% The full syntax is the following:
+%\begin{ttsyntax}\setfontsize{9.25}%
+%\cs{FSimage}\marg{image file name}\oarg{lof entry}\marg{caption text}\oarg{label string}
+%\qquad\parg{caption width percent}\aarg{line correction}\barg{width text}!\meta{precaption}!
+%\end{ttsyntax}
+% although the last three arguments are not used.
+%
+% All the code before the first \cs{cleartopage} command is used to
+% examine the dimensions of the original image, and to perform the
+% necessary assignments to the various dimensions and boxes. The
+% test on the relationship between the \cs{DFwidth} image width and
+% the sum of the text and internal margin widths is to compute the
+% caption measure and assign the result to the dimension
+% register \cs{TScaptionwidth}; this width is tested to control if it
+% is too small; in case a warning message is issued.
+%
+% The following question is natural: When is this display mode
+% convenient? After all, also the \texttt{VS} display mode applies
+% to tall and slim images, so this \texttt{TH} mode and the other
+% \texttt{VS} mode are in competition. In a way they are, but their
+% results are very different; The latter mode produces images non
+% larger than half the test block and not taller than the text block.
+% The former mode produces images that are taller than the text block
+% and possibly larger than the text block. Therefore this is one of
+% the possible criteria to chose which display mode is more suitable
+% for a given image. another other criterion deals with the image aspect
+% ratio and the available space aspect ratio; since the height of the
+% \texttt{TH} scaled image is fixed, the user should pay attention to
+% its width; the scaled image width, in facts, should not exceed the
+% sum of the internal margin width and the test block one, otherwise
+% the space for the caption becomes too small and a warning message
+% is issued. At the same time if the scaled image width is smaller
+% than approximately one half of the text width plus the internal
+% margin one, the space remaining for the caption becomes too large.
+%
+% After that the |figure| environment is coded starting with
+% the control on the page parity; depending on this parity different
+% dirty tricks with several kinds of boxes are performed so as to
+% set into the page a huge block that fills all the available vertical
+% space on the paper; the parity influences the order in which the various
+% embedded boxes interact with one another, but the main point is
+% that the box containing the caption must be on the external side
+% of the box containing the image; its measure may be fine tuned
+% (increased or reduced) with respect to available white space; the
+% argument \meta{caption width percent} delimited by round parentheses
+% by default equals 0.8, but the user can specify a different value
+% to the selector macro, so that the caption measure is that specified
+% percentage of the computed caption width.
+%
+% After closing the |figure| environment a final \cs{clearpage} is
+% issued so that the figures stack remains completely empty; in
+% particular the current figure is output, but the initial typesetting
+% mode is restored, so that if the environment was specified in the
+% middle of a paragraph the paragraph continues to be typeset without
+% problems; of course if the environment is followed by a blanc line,
+% such settings become ineffective because a new paragraph is started.
+% The end of the \cs{DFimage} command provides to close the group,
+% therefore all the assignments to the various registers are restored.
+% \begin{macrocode}
+\NewDocumentCommand\THfigure{m o m o d() d<> d|| d!!}{%
+ \setbox\DFtotalimage=\hbox{\includegraphics{#1}}%
+ \DFheight=\ht\DFtotalimage \DFwidth=\wd\DFtotalimage
+ \edef\DFscalefactor{\fpeval{\paperheight/\DFheight}}
+ \setbox\DFimageI\hbox{%
+ \scalebox{\DFscalefactor}{\usebox{\DFtotalimage}}}%
+ \DFwidth=\wd\DFimageI
+ \ifdim\dimexpr\paperwidth-\DFwidth < 2\externalmargin\relax
+ \PackageWarning{swfigure}{%
+ *******************************************\MessageBreak
+ Figure #1 is too wide to be set in a \MessageBreak
+ Total Height display mode. \MessageBreak
+ There is not enough space for its caption. \MessageBreak
+ Expect questionable results. \MessageBreak
+ *******************************************\MessageBreak}%
+ \fi
+ \FigSpace=\DFwidth
+ \dimen10=\dimexpr\topmargin+1in-(\paperheight-\headsep-\headheight
+ -\textheight-\footskip)/2\relax
+ \TScaptionwidth=\dimexpr\paperwidth-\FigSpace-3\columnsep\relax
+ \cleartopage
+ \thispagestyle{empty}%
+ \begin{figure}
+ \ifodd\c@page\relax% odd page
+ \begin{minipage}[c][\textheight][t]{\textwidth}% minibox1
+ \vspace*{\dimen10}%
+ \makebox[\textwidth][l]{\hspace*{-\internalmargin}% hbox2
+ \vbox to\textheight{\vss% vbox3
+ \hbox to\paperwidth{% hbox4
+ \parbox{\FigSpace}{\box\DFimageI}%
+ \hspace{\columnsep}%
+ \makebox[\TScaptionwidth]{%
+ \parbox{#5\TScaptionwidth}{%
+ \caption[#2]{#3}\IfValueT{#4}{\label{#4}}\relax}%
+ }%
+ }% end hbox4
+ \vss}% end vbox3
+ }% end hbox2
+ \end{minipage}% end minibox1
+ \else % even page
+ \begin{minipage}[c][\textheight][t]{\textwidth}
+ \vspace*{\dimen10}%
+ \makebox[\textwidth][l]{\kern-\externalmargin
+ \vbox to\textheight{\vss
+ \hbox to\paperwidth{\hss
+ \hbox to\TScaptionwidth{\hss
+ \parbox{#5\TScaptionwidth}{%
+ \caption[#2]{#3}\IfValueT{#4}{\label{#4}}\relax}%
+ }\hspace{\columnsep}%
+ \parbox{\FigSpace}{\box\DFimageI}%
+ }\vss
+ }%
+ }%
+ \end{minipage}%
+ \fi
+ \end{figure}%
+ \clearpage\reset@tmode
+}
% \end{macrocode}
+%
+%^^A========================================
+%\subsection{The \texttt{TW} for the Total Width
+% image plus its side caption}
+%^^A========================================
+% This particular mode is a variant of the \texttt{FH} full height mode,
+% where scaling of a not sufficiently narrow image, may produce a figure
+% that does not exceed the page dimesions, but that might leave such a
+% small narrow strip of white space to typeset the caption that it comes
+% out as a very poorly typeset object. This other \texttt{TW} does not
+% have this drawback, but it might produce figures that exceed the paper
+% height in order to remain within the preset limits foreseen for a nicely
+% typeset side caption.
+%
+% Some details are pretty delicate, but let us start from the beginning.
+% The seven code lines afterthe first one, are the usual lines similar
+% to those at the beginning of the other macros; The original image is
+% stored in a box, from which all possible metric informations are derived
+% and the scaling factor is computed; afterward the boc is scaled
+% according to the computed scaling factor, and re-stored into the
+% same box.
+%
+% Command |\cleartopage| behaves as usual and sets the |\if@SWtmode|
+% so as to be able to restore the typesetting modo (horizontal or
+% vertical) at the end of this macro expansion. This means, also,
+% that for this display mode both the command and the homonymous
+% environment |DFimage| may be used.
+%
+% The page style is set to |empty|, so that the full width block may
+% be set flush to the top of the paper, without overwriting any page
+% decoration; even the possible folio in the bottom margin is not
+% overwritten onto the image.
+%
+% The test for the parity of the folio number is taken; the true and
+% the false branches are very similar, bat the actions that differ
+% because depend on the folio parity are interspersed between the
+% other code lines. This is why two |figure|environments are defined,
+% even if their contents is pretty similar.
+%
+% We comment the true branch for odd numbered figures, and with slight
+% changes they equal those for the even numbered page; Therefore we
+% omit the latter.
+%
+% We box the figure and the caption into an |\hbox| named |\DFimageII|;
+% the image box |\DFimageI| si typeset inside a |\parbox| were the measure
+% is specified as the boxed image width. The |\parbox| as well as the
+% following |minipage| environment are but vertically centred, so that
+% we are sure that the caption median will coincide with that of the
+% boxed image. As you see the caption is at the right of the boxed
+% image, and in an odd numbered page the caption is close and partially
+% over the external margin; the opposite takes place for the even
+% numbered pages, and again the caption is close or over such page
+% external margin.
+%
+% We can now measure the various geometric properties of the image-caption
+% block; notice that his block is large as the internal margin plus
+% spaces plus the caption for a total of |\paperwidth|. We should
+% keep this in mind in order to re-box the block into a |\textwidth|
+% wide box with the necessary stretch and shrink horizontal glue
+% in oder to let it fit the paper width wich is larger that the
+% text width
+
+% Moreover we measure the upper white margin, that is white, because
+% of the |empty| page style, but the header box, its separator from
+% the text, the |\topmargin| with its 1~inch offset, in order to raise
+% the image-caption box to be flush to the upper paper border.
+% Now we can fill up a vertical box of the computed height; this box
+% is inside the text block, but it must overlap the upper vertical
+% space so the real height of this box is smaller than its contents
+% and a vertical stretch and shrink glue is necessary.
+% Eventually with these nestes vertical and horizontal boxes we can
+% output the whole contents and the result is as we expected.
+% \begin{macrocode}
+\NewDocumentCommand\TWfigure{m o m o d() d<> d|| d!!}{%
+ \setbox\DFtotalimage=\hbox{\includegraphics{#1}}%
+ \DFheight=\ht\DFtotalimage \DFwidth=\wd\DFtotalimage
+ \FigSpace=\dimexpr\internalmargin+0.80\textwidth\relax
+ \TScaptionwidth=\dimexpr\paperwidth-\FigSpace-2\columnsep\relax
+ \edef\DFscalefactor{\fpeval{\FigSpace/\DFwidth}}
+ \setbox\DFimageI=\hbox{\scalebox{\DFscalefactor}{\box\DFtotalimage}}
+ \DFwidth=\wd\DFimageI \DFheight\ht\DFimageI
+ \cleartopage
+ \thispagestyle{empty}%
+ \ifodd\value{page}% odd numbered page
+ \begin{figure}
+ \setbox\DFimageII=\hbox{%
+ \parbox{\FigSpace}{\box\DFimageI}\hspace{\columnsep}%
+ \begin{minipage}{\TScaptionwidth}\centering
+ \parbox{#5\hsize}{\caption[#2]{#3}%
+ \IfValueT{#4}{\label{#4}}\relax}%
+ \end{minipage}
+ }%
+ \DFheight=\ht\DFimageII \dimen8=\dp\DFimageII
+ \advance\DFheight by\dp\DFimageII
+ \dp\DFimageII=\z@ \ht\DFimageII=\DFheight
+ \dimen10=\fpeval{\topskip+1in+\headheight+\headsep}\p@
+ \advance\dimen8 by\baselineskip
+ \advance\DFheight by-\dimen10\relax
+ \vbox to\DFheight{\vss
+ \hbox{\raise \dimen8\hbox to\textwidth{%
+ \hspace{-\internalmargin}\box\DFimageII\hss}}%
+ }%
+ \end{figure}
+ \else% even numbered page
+ \begin{figure}
+ \setbox\DFimageII=\hbox{%
+ \begin{minipage}{\TScaptionwidth}\centering
+ \parbox{#5\hsize}{\caption[#2]{#3}%
+ \IfValueT{#4}{\label{#4}}\relax}%
+ \end{minipage}
+ \hspace{\columnsep}%
+ \parbox{\FigSpace}{\box\DFimageI}
+ }%
+ \DFheight=\ht\DFimageII \dimen8=\dp\DFimageII
+ \advance\DFheight by\dp\DFimageII
+ \dp\DFimageII=\z@ \ht\DFimageII=\DFheight
+ \dimen10=\fpeval{\topskip+1in+\headheight+\headsep}\p@
+ \advance\dimen8 by\baselineskip
+ \advance\DFheight by-\dimen10\relax
+ \vbox to\DFheight{\vss
+ \hbox{\raise \dimen8\hbox to\textwidth{\hss%
+ \box\DFimageII\hspace{-\internalmargin}}}%
+ }%
+ \hbox to\textwidth{\hspace{-\internalmargin}\box\DFimageII\hss}
+ \end{figure}%
+ \fi
+ \reset@tmode
+}
+
+% \end{macrocode}
+%
%\vspace*{2\baselineskip}
%\noindent\makebox[\textwidth]{\setfontsize{10mm}
%\color{red} HAPPY \LaTeX-ing}
-%\endinput
%\iffalse
%</package>
%\fi
@@ -1205,31 +1555,4 @@ trim = \the\DFhalfwidth\space 0 0 0]}\x{#1}}%
%
%\endinput
%
-%\iffalse
-%<*readme>
-%\fi
-% \begin{macrocode}
-This bundle contains file the swfigure.dtx and README.txt files.
-This file README.txt contains the licence, the status, and some
-general information. Save both in a .../source/latex/swfigure
-folder either in the main TeX system tree or in your personal
-tree.
-
-This swfigure.dtx file is a self extracting documented one.
-Run pdfLaTeX at least twice on this file in order to get all
-references correct, and you obtain the swfigure.pdf and the
-swfigure.sty files. After extraction move the .sty file to
-the .../tex/latex/swfigure folder, and move the .pdf file to
-the .../doc/latex/swfigure folder. From the original folder
-.../source/latex/swfigure move all files, except the .dtx and
-the .txt files, to the bin.
-
-The author disclaims any liability from every possible inconvenience
-deriving from the use of this software; you use it at your own risk.
-
-% \end{macrocode}
-%\iffalse
-%</readme>
-%\fi
%
-% \ No newline at end of file