Debian Codegraph @

texmf-dist/source/latex/swfigure/swfigure.dtx

raw
1 % \iffalse
2 % !TEX encoding = UTF-8 Unicode
3 % !TEX TS-program = pdflatex
4 %<*internal>
5 \begingroup
6 \input docstrip.tex
7 \keepsilent
8 \preamble
9
10 Copyright (C) 2020-2022 Claudio Beccari all rights reserved.
11 License information appended
12
13 \endpreamble
14
15 \postamble
16
17 Distributable under the LaTeX Project Public License,
18 version 1.3c or higher (your choice). The latest version of
19 this license is at: http://www.latex-project.org/lppl.txt
20
21 This work is "maintained"
22
23 This work consists of files swfigure.dtx and README.txt, and the derived
24 files swfigure.sty and swfigure.pdf
25
26 \endpostamble
27 \askforoverwritefalse
28
29 \generate{\file{swfigure.sty}{\from{swfigure.dtx}{package}}}
30
31 \def\tmpa{plain}
32 \ifx\tmpa\fmtname\endgroup\expandafter\bye\fi
33 \endgroup
34 %</internal>
35 % \fi
36 %
37 % \iffalse
38 %<*package>
39 %<package>\NeedsTeXFormat{LaTeX2e}[2020/01/01]
40 %</package>
41 %<*driver>
42 \ProvidesFile{swfigure.dtx}%
43 %</driver>
44 %<+package>\ProvidesPackage{swfigure}%
45 %<*package>
46 [2022-04-24 v.0.9.20 Managing large and spread wide figures]
47 %</package>
48 %<*driver>
49 \documentclass[a4paper]{ltxdoc}\errorcontextlines=9
50 \hfuzz 10pt
51 \usepackage[utf8]{inputenc}
52 \usepackage{lmodern,textcomp,multicol,enumitem,mflogo,guit}
53 \usepackage{swfigure}% this already loads the graphicx package
54
55 \providecommand*\diff{\mathop{}\!\mathrm{d}}
56 \renewcommand\meta[1]{{\normalfont\textlangle\textit{#1}\textrangle}}
57 \renewcommand\marg[1]{\texttt{\string{\meta{#1}\string}}}
58 \providecommand\Marg{}
59 \renewcommand\Marg[1]{\texttt{\string{#1\string}}}
60 \providecommand\oarg{}
61 \renewcommand\oarg[1]{\texttt{[\meta{#1}]}}
62 \providecommand\Oarg{}
63 \renewcommand\Oarg[1]{\texttt{[#1]}}
64 \providecommand\aarg{}
65 \renewcommand*\aarg[1]{\texttt{<\meta{#1}>}}
66 \providecommand\Aarg{}
67 \renewcommand\Aarg[1]{\texttt{<#1>}}
68 \providecommand\parg{}
69 \renewcommand\parg[1]{\texttt{(\meta{#1})}}
70 \providecommand\Parg{}
71 \renewcommand\Parg[1]{\texttt{(#1)}}
72 \providecommand\barg{}
73 \renewcommand\barg[1]{\texttt{\char`|\meta{#1}\char`|}}
74 \newbox\SWsynt
75 \providecommand\eTeX{}
76 \renewcommand\eTeX{\lower0.5ex\hbox{$\varepsilon\!$}\TeX}
77 \newcommand\Benv[1]{\cs{begin}\Marg{#1}}
78 \newcommand\Eenv[1]{\cs{end}\Marg{#1}}
79
80 \newenvironment{medaglione}%
81 {\par\medskip\fboxrule=0.8pt\fboxsep6pt\relax
82 \begin{lrbox}{\SWsynt}\minipage{\dimexpr\linewidth-2\fboxsep-2\fboxrule}}%
83 {\endminipage\end{lrbox}\noindent\fbox{\box\SWsynt}\par\medskip}
84
85 \newenvironment{ttsyntax}{\medaglione\raggedright\ttfamily\obeylines}{\endmedaglione}
86
87 \providecommand\setfontsize{}
88 \DeclareRobustCommand\setfontsize[2][1.2]{%
89 \linespread{#1}\fontsize{#2}{#2}\selectfont}
90 \providecommand\ped[1]{\ensuremath{_{\mathrm{#1}}}}
91
92 \GetFileInfo{swfigure.dtx}
93
94 \title{The \texttt{swfigure} package\\
95 Managing large and spread wide figures}
96 \author{Claudio Beccari\thanks{E-mail: \texttt{claudio dot beccari at gmail dot com}}}
97 \date{Version \fileversion~---~Last revised \filedate}
98
99 \begin{document}\errorcontextlines=100
100 \maketitle
101 \columnseprule=0.4pt
102 \begin{multicols}{2}
103 \tableofcontents
104 \end{multicols}
105 \DocInput{swfigure.dtx}
106 \end{document}
107 %</driver>
108 % \fi
109 %
110 % \CheckSum{1046}
111 %
112 % \begin{abstract}
113 % This package defines a single command that with different options can
114 % insert large images into the document; those that occupy an entire
115 % spread get split into two halves that are inserted on
116 % two facing pages in such a way that they merge when the document is read
117 % on the screen (set to double page view) or is printed in a well sewn
118 % book so that facing pages join correctly at the spine.
119 % This documentation is accompanied by another file
120 % |swfigure-examples.pdf| containing examples of this package several
121 % uses.
122 % \end{abstract}
123 %
124 %\begin{figure}[t]
125 %\includegraphics[width=\linewidth]{DFscreenshot}
126 %\caption{Example of a large fake image that occupies a spread;
127 % screenshot of a spread view from the companion file
128 % swfigure-examples.pdf.}\label{fig:DFscreenshot}
129 %\end{figure}
130 %
131 %^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
132 %\section{Introduction}
133 %^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
134 % Sometimes it is necessary to insert in a given document very large
135 % images; either they are larger than a spread, or they do not exceed
136 % the width of a spread. In the first case it is necessary to use
137 % to large sheets of paper folded in the proper way and inserted in the
138 % printed document as special inserts; or for documents to be read on
139 % the screen such large sheets have to be attached to the document as
140 % separate files to be viewed in windows different from that where the
141 % document is being read.
142 %
143 % In the other case it is possible to manage such large figures in
144 % different ways; we define a single command that, according to
145 % different settings, can insert such figures in eight different display
146 % modes.
147 %\begin{enumerate}[noitemsep]
148 % \item
149 % The normal \LaTeX\ kernel full page display mode, but setting the placement option to |[p]| to the figure environment. Apparently
150 % there is no need to define a new command for this display mode, except
151 % the advantage of using the same command as the other modes and a few
152 % small further functionalities provided by this the new command.
153 %\item
154 % The landscape display mode is available with the |lscape| package
155 % and other similar ones. Again this display mode appears superfluous,
156 % but the advantage is to use the same command as the other display modes.
157 %\item
158 % The screen-wide display mode, where two facing pages display a large
159 % figure divided in two halves, each one set in its page shifted to the
160 % spine so as to occupy on each page the text width plus the internal
161 % margin; with suitable aspect ratio, both facing pages are practically
162 % full. No other text appears on the page with this display mode, except
163 % the caption in the right page external margin.
164 %\item
165 % The slim screen-wide image is similar to the previous mode, but since
166 % the figure is slim, it is set at the top of two facing pages, with text
167 % underneath; the caption is under the right figure half in the right
168 % page, and the left text block height is set so that that the first
169 % lines of both text blocks are aligned.
170 %\item
171 % The slim tall image is set to the side of the text block with text
172 % wrapping it. Recurse is made either to the |wrapfig| package
173 % or the newer |wrapfig2| one if the latter exists, therefore the
174 % software might sometimes hick-up a little bit, because of the
175 % idiosyncrasies of both |wrapfig| and |wrapfig2| that perform
176 % very well in most but not all circumstances; see that package
177 % documentation for such |wrapfig| and |wrapfig2|
178 % limitations. With one of these packages we limit the use of this
179 % display mode to images that have a “height over width” aspect ratio
180 % not lower than~2; we provide also some option arguments so as to correct
181 % small imperfections in the sizing of the text indention
182 %\item
183 % A very large image, typically A3 sized, occupies a full spread
184 % including the lateral margins; it is a solution to inputting, for
185 % example, a line drawing of a technical device, that otherwise
186 % should be attached as a separate document; a very large table
187 % that does not fit the usual A4 paper and that cannot be split in chunks
188 % by means of |longtable|, and cannot be scaled down to unreadable font
189 % sizes.
190 %\item
191 % A rather tall not so slim image can be typeset in the total height
192 % mode; this height is the paper (trimmed page) height; the image
193 % appears in a textless page, shifted to the spine, taking into
194 % account if the page is an odd or even numbered one. The image
195 % is scaled so that leaves on it side the external margin plus a part
196 % of the text width, generally sufficient for a side caption; it reaches the
197 % top and the bottom limits of the trimmed page. Should this space
198 % be to narrow for a decently typeset caption, a warning
199 % message is issued but the compilation is not stopped. It is up
200 % to the user to control how bad is the caption typesetting and
201 % possibly to provide a different display mode in order to get a
202 % better result.
203 % \item
204 % Anothe display mode, that we call Total Width
205 %\end{enumerate}
206 %
207 % In any case, depending on the page geometry and the image aspect
208 % ratio, it is very handy to have available a single command that
209 % changes the display mode by just changing a single input optional
210 % argument. In facts the user might start with one of the eight
211 % described display modes; after examining the document draft the
212 % user might chose another display mode, and it suffices to change
213 % the optional argument, without changing the whole code.
214 %
215 % \bigskip
216 %
217 % \noindent\fbox{\textcolor{red}{WARNING}}\quad This package performs
218 % as expected with documents typeset in \texttt{twoside} mode, and with
219 % a page design where the internal margins of both the odd and even pages
220 % are equal (symmetrical page design). For example, it does not work
221 % with this document designed to work in \texttt{oneside} mode and
222 % where the the left page margin is always larger than the right one
223 % of each page; this page design is functional to the documentation
224 % of the \TeX\ system software.
225 %
226 %^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
227 %\section{Installation}
228 %^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
229 %
230 % This package is already installed with any complete and up to date
231 % \TeX\ system distribution, \TeX\ Live or MiK\TeX.
232 %
233 % Should the user have available a basic or a partial \TeX\ system
234 % installation, the simplest way to install this package is to download
235 % the |swfigure.zip| file from the Comprehensive \TeX\ Archive Network
236 % (CTAN), to decompress it either in the very folder where there is
237 % the document main or single document file or, for a general use, in
238 % the user |texmf| personal tree; it might be necessary that the user
239 % should directly create this personal tree; how to do it is described
240 % in the documentation of the user \TeX\ system distribution.
241 %
242 % The same holds true if the user employs a vintage \TeX\ system
243 % distribution; this package requires the \LaTeX3 modern language
244 % functionalities, therefore a \LaTeX\ kernel with a date after
245 % 2019-01-01. Lacking this modern kernel, the package does not work,
246 % because packages |xparse| and |xfp| are used for its
247 % internal workings.
248 %
249 %
250 %^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
251 %\section{Usage}\label{sec:Usage}
252 %^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
253 % This package defines a single user command\slash environment,
254 % |DFimage|. The command is usable when the image fills up the page
255 % or the spread, so that it contains no text, except the caption; the
256 % environment is recommended when the large image is in a page or a
257 % spread that contains also some text.\\
258 % \fbox{\color{red} Warning!} This particular environment
259 % cannot be nested and cannot contain a |\DFimage| command.
260 %
261 % The syntax is the following:
262 %\begin{ttsyntax}
263 %\cs{DFimage}\oarg{display mode}\marg{image file name}\%
264 %\qquad \oarg{lof entry}\marg{caption}\oarg{label}\%
265 %\qquad\parg{height correction}\aarg{line correction}\barg{width test}!\meta{precaption}!
266 %\vspace{0.5\baselineskip}
267 %or
268 %\vspace{0.5\baselineskip}
269 % \Benv{DFimage}\oarg{display mode}\marg{image file name}\%
270 %\qquad \oarg{lof entry}\marg{caption}\oarg{label}\%
271 %\qquad\parg{height correction}\aarg{line correction}\barg{width test}!\meta{precaption}!
272 %\meta{environment textual contents}
273 %\Eenv{DFimage}
274 %\end{ttsyntax}
275 % \noindent where:
276 %\begin{description}[noitemsep]
277 %
278 %\item[\meta{display mode}]
279 % is one of the following uppercase acronyms:
280 % \texttt{NF} (Normal Figure), \texttt{RF} (Rotated Figure),
281 % \texttt{SW} (Spread Wide image), \texttt{HS} (Horizontal Spread-wide
282 % image), \texttt{VS} (Vertical Slim image), \texttt{FS}
283 % (Full Spread image), \texttt{TH} (Total Height image), and \texttt{TW} (Total Width image).
284 %
285 %\item[\meta{image file name}]
286 % is the name of the image graphic file; remember that the \LaTeX based
287 % \TeX\ system typesetting programs accept graphic files in the formats
288 % with extensions \texttt{.pdf}, \texttt{.eps}, \texttt{.jpg},
289 % \texttt{.png}, and few other less common ones. It is not necessary to
290 % specify the extension, but it is not forbidden.
291 %
292 %\item[\meta{lof entry}]
293 % is the optional entry to the List Of Figures; it defaults to the
294 % \meta{caption} text, but if the latter is sort of lengthy, it is
295 % better to enter a shorter text in that list.
296 %
297 %\item[\meta{caption}]
298 % is the caption text. Its number prefix is adapted to the main or the
299 % current language setting as it happens with any figure in standard
300 % \LaTeX.
301 %
302 %\item[\meta{label}]
303 % this optional argument is the string that forms the \cs{label} command
304 % argument; of course, if this argument is not specified, the figure
305 % number and its page cannot be referenced with \cs{ref}, \cs{pageref}
306 % and other similar commands.
307 %
308 %\item[\meta{height correction or color}]
309 % is a round parenthesis delimited optional argument; as a
310 % \emph{height correction} it is a fractional number lower than~1
311 % (default 0.8) with which to further scale the scaled image height
312 % to be included; it is used by some display modes, and it is ignored
313 % by others. In the total height mode, it can be used to scale the
314 % captions width.
315 %
316 %\item[\meta{line correction}] is an angle bracket delimited optional
317 % argument preset to zero. It is relevant only with the slim
318 % vertical image display mode. Sometimes the |wrapfig| package
319 % indents the wrapping text in such a way as to leave to much or too
320 % little vertical space around the image and its caption; by examining
321 % the document draft it is possible to correct the predetermined
322 % number of indented lines by increasing or decreasing the vertical
323 % space by any (integer) number of lines. With |wrapfig2| it is
324 % possible to use a final optional asterisk that changes the
325 % information relative to the number of indented lines into a
326 % correction of such number; its easier to count the missing or
327 % the extra indented lines, that the whole number of such lines.
328 %
329 %\item[\meta{width test}] this further vertical bar-delimited argument
330 % is used only when dealing with vertical slim images; when they are
331 % scaled down in order to fit in the available space, their width may
332 % become too small to allow a decently typeset caption below the
333 % image. A test is made to compare the scaled image width with a
334 % fraction of the text block width in order to skip the image insertion
335 % if the image width becomes too small; the default value for this
336 % \meta{width test} fraction is \texttt{0.25}, but the user can specify
337 % a different value, even zero; with the zero value this width test is
338 % skipped.
339 %
340 %\item[\meta{precaption}] is an optional color declaration delimited by
341 % exclamation points; the default value is ‘empty’; it is used only
342 % by the \texttt{FS} display mode in order to typeset a caption, for
343 % example, with a contrasting color over the background image average
344 % color, and/or with a displacement of the first or only caption line,
345 % and/or with a different font.
346 %
347 %\end{description}
348 %
349 %^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
350 % \section{Display mode peculiarities}
351 %^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
352 % Each of the listed display modes has its own pros and cons.
353 % In the following the phrase “aspect ratio” refers to the “height
354 % over width” ratio either of the image or of the available space
355 % where to put the image and possibly its caption.
356 %\begin{description}[noitemsep]
357 %
358 %\item[\texttt{NF}]
359 % This display mode is convenient when the image
360 % aspect ratio is close to the text block one. Of course the user
361 % does not know in advance the vertical space occupied by the caption,
362 % therefore the optional \meta{height correction} comes handy for
363 % small adjustments; this display mode is fully and freely floating,
364 % although its positioning option is fixed to~|[p]|, a float-only page.
365 % Therefore don't use it if the image is not really such as to occupy
366 % most of the text block area.
367 %
368 %\item[\texttt{RF}]
369 % This display mode is convenient when the image
370 % aspect ratio is close to the reciprocal of the text block one. This
371 % mode accepts the \meta{height correction} in order to leave space
372 % for the caption. It is a fully and freely floating object with the
373 % same pros and cons as the \texttt{NF} display mode.
374 %
375 %\item[\texttt{VS}]
376 % This mode is convenient for tall and slim figures with aspect ratio
377 % not lower than~2; but for obvious reasons, it should not be too
378 % large, let's say, not larger than about~3 or~4. As always this depends
379 % on the page design and the caption size. The limitations of the
380 % underlying |wrapfig| or |wrapfig2| packages forbid their usage too
381 % close to explicit lists and texts typeset in special modes with a
382 % different measure from normal text. Again it is up to the user to chose
383 % where to insert the |DFfigure| environment or the |\DFimage| command.
384 % The |wrapfig| or |wrapfig2| package documentation, and our experience,
385 % show that the best position is just before a new paragraph; the
386 % environment end should be placed after a suitable number of full
387 % paragraphs, even if not all of them are involved with wrapping.
388 %
389 % If the aspect ratio of the image to include is lower than~2, the
390 % following message is printed in the document where the image
391 % should appear (of course with |#1| replaced by the actual image
392 % file name):\\[2ex]
393 %\begin{minipage}{0.7\textwidth}
394 %\begin{verbatim}
395 % ===========================================
396 % Figure #1 is not tall enough.
397 % Consider using a display mode different
398 % from VS; may be NF or RF are better suited.
399 % ===========================================
400 % Nothing done!
401 % ===========================================
402 %\end{verbatim}
403 %\end{minipage}\\[2ex]
404 % A similar action and a similar message is output if the \emph{scaled}
405 % image width becomes too small.
406 %
407 %\item[\texttt{SW}]
408 % This display mode is convenient when a really large
409 % image requires two pages to display all its details; its aspect ratio
410 % should be close to the aspect ratio of the total space
411 % available for the two page spread; depending on the page design this
412 % total space approximate value is probably around~0.5.
413 % The object to be included in the document should start on an even
414 % page, therefore it floats to the first even page available; this may
415 % force a page break where the current page is not fully completed and
416 % may be shorter than the other text pages; the user
417 % then should help the automatic positioning by choosing very carefully
418 % where to insert the \cs{DFfigure} command in the source text; possibly
419 % the user should chose an end of paragraph close to the end of a page.
420 % The command or the environment may be used even within a source file
421 % paragraph; with a little attention: there should be no space between
422 % the end document command and the first character of the following text.
423 %
424 %\item[\texttt{HS}]
425 % This display mode is convenient when the initial image aspect
426 % ratio is very small; if it is smaller than~0.3 its insertion
427 % leaves enough space beneath the two image halves (plus caption)
428 % so that normal text can fill the space under such spread wide
429 % slim figure. The constraints described for display mode \texttt{SW}
430 % apply also to this mode.
431 %
432 % \item[\texttt{FS}]
433 % The \texttt{SW} mode occupies a spread without invading the lateral
434 % margins; it simply occupies only the internal margin. On the opposite,
435 % the \texttt{FS} Full Spread mode occupies also the lateral margins;
436 % typically a full spread of two A4 pages, can contain a rotated A3 page,
437 % without scaling down its contents. With this full occupation of both
438 % facing pages, there is no room for any caption; therefore the actual
439 % image, besides occupying an A3 page, should have a minimum white
440 % margin around, so that a caption can be superimposed to the image white
441 % part if its original bottom margin that, upon rotation, becomes the
442 % right one, is large enough. If the original image has no margins, the
443 % caption is typeset ove the image, but it may be coloured with
444 % contrasting color compared to the average background one.
445 %
446 % \item[\texttt{TH}]
447 % This mode is suited for tall figures that do not show well when their
448 % height is scaled to the text height; the upper and lower margins are
449 % available for a larger scale factor; even the internal margin is
450 % helpful to gain some space. In this case, though, the page header and
451 % footer should be avoided and the figure caption should be set at the
452 % image side, without any rotation; the little problem that arises in
453 % this case is that the caption, always close to the external margin,
454 % should not be rotated and its measure should be adapted in order to
455 % properly use the horizontal space left on the page. If this space is
456 % too narrow the figure, in spite if being taller then wide, is too
457 % wide: it has an aspect ratio higher than one but not enough. This
458 % display mode requires that the image has an aspect ratio greater
459 % than, say, $\sqrt2$, otherwise the caption measure becomes too short.
460 % A warning message is issued if the total space left on the page is
461 % smaller than the external margin, where the caption would have the
462 % same measure as a marginal note. In spite if this fact, compilation
463 % goes on, and the attentive user not only evaluates the result,
464 % and examines the \texttt{.log} file where he finds the explanation
465 % of the possibly too bad result.
466 % \item[\texttt{TW}]
467 % A another Total Width mode is defined such that the scaled
468 % image and its (side) caption occupy the upper part of the page/paper.
469 % The given image is scaled to occupy the internal margin plus 80\%
470 % of the text block width; the remaining horizontal space is provided
471 % for a side caption and its lateral spaces, If the aspect ratio
472 % of the original image is not smaller than text block and internal
473 % margin widths divided by the paper height, the scaling might produce
474 % a scaled image too tall to fit into the paper. No tests are made
475 % in this sense, but it is up to the user the best choice for
476 % displaying a given image. On an A4 paper, depending on the page
477 % design, the aspect ratio available should be approximately 1.8,
478 % therefore this design accommodates a large number of different
479 % aspect ratio images, from a not so slim tall portrait image to
480 % a landscape image. A square image, scaled as described above,
481 % may occupy approximately the upper half of the page.
482 % The caption is always well typeset in the adjacent free space,
483 % and it is possible to slightly modify its measure by using an
484 % optional argument.
485 %\end{description}
486 %
487 %^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
488 % \section{Acknowlegements}
489 %^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
490 %
491 % This package would not exist if Heinrich Fleck did not need
492 % to insert several large images in his documents; he asked
493 % me to create suitable commands and/or environments and he tested
494 % all the series of progressive developments of this package; believing
495 % that this package might be useful to other \TeX\ users, he invited
496 % me to submit the result to the \TeX\ community, and here it is.
497 % Heinrich did not want his name as a co-author, because he insists
498 % that he was “just” a tester. He was precious and I warmly thank him.
499 %
500 % Thanks also to Benedict Wilde who spotted some errors and suggested
501 % the use of specific settings for the PDF viewer.
502 %
503 % Thanks also to the unknown person nicknamed “dylan.bacc” on the \GuIT\
504 % forum, who induced me to work on the sixth display mode. I knew that
505 % using the |memoir| class, with suitable settings, and having available
506 % an advanced printer, it was possible to print documents with pages of
507 % different formats and page designs; but this was not my aim: I wanted
508 % something possibly independent from the document class and not
509 % requiring any particular printer.
510 % The seventh display mode came to our minds when we found tall figures
511 % that did not show well scaled to the \emph{text block} height, but could
512 % show better if scaled to \emph{paper} height, with the caption at their
513 % side; actually we found that it was better to scale the image to a
514 % width of the internal margin plus 80\% of the text width, and placing
515 % 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.
516 %
517 %^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
518 %\newpage
519 %\begin{thebibliography}{9}
520 %\bibitem{bib:xparse} The \LaTeX3 Project, \emph{The \texttt{xparse} package} --- Document command parser. Release date 2020-05-15. PDF document readable with \texttt{texdoc xparse}.
521 %\bibitem{bib:xfp} The \LaTeX3 Project, \emph{The \texttt{xfp} package} --- Floating Point Unit. Release date 2020-05-15. PDF document readable with \texttt{texdoc xfp}.
522 %\bibitem{bib:Int3} The \LaTeX3 Project, \emph{The \LaTeX3 interfaces}. Release date 2020-09-24. PDF Document readable with \texttt{texdoc interface3}.
523 %\bibitem{bib:graphics} D.P.~Carlisle and The \LaTeX3 Project, \emph{Packages in the `graphics' bundle}. Release date 2020-08-21. PDF document readable with \texttt{texdoc grfguide}.
524 %\bibitem{bib:etoolbox} P. Lehman and J Wright, \emph{the \texttt{etoolbox} Package} --- An e-TeX Toolbox for Class and Package Authors. version 2.5j, released on 2020-08-24. PDF document readable with \texttt{texdoc etoolbox}.
525 %\bibitem{bib:lscape} D.P. Carlisle, \emph{The \texttt{lscape} package}. Version 3.02 released on 2020-05-28. PDF document readable with \texttt{texdoc lscape}.
526 %\bibitem{bib:afterpage} D.P. Carlisle, \emph{The \texttt{afterpage} package}. Version 1.08 released on 2014-10-28. PDF document readable with \texttt{texdoc afterpage}.
527 %\bibitem{bib:wrapfig} D. Arseneau, \emph{The \texttt{wrapfig} package}. Version 3.6 released on 2003-01-31.
528 %\bibitem{bib:wrapfig2} C. Beccari, \emph{The \texttt{wrapfig2} package}.
529 % Versione 4.0.4 released on 2022-01-04.
530 %\bibitem{bib:memman} P. Wilson, \emph{The Memoir Class for Configurable Typesetting} ---User guide. Version 3.7m released 2020-09-10. PDF document readable with \texttt{texdoc memman}.
531 %\end{thebibliography}
532 %
533 % \StopEventually{}
534 %
535 %\clearpage
536 %
537 %^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
538 % \section{The code}
539 %^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
540 %
541 %
542 %\iffalse
543 %<*package>
544 %\fi
545 % The required \TeX\ format with is date, and the identification of this
546 % package have already ben inserted by the initial commands of this
547 % documented file.
548 %
549 % Here we call the initial required packages and, since the necessary
550 % software to define some \LaTeX3 (L3) language “functions” are already
551 % part of the \LaTeX\ kernel, we just use them in order to define a
552 % robust \LaTeXe/L3 interface to create some testing macros that accept
553 % many logical operators that act on items that, besides boolean
554 % variables, are also numerical expressions connected with relation
555 % operators; for further details it suffices to examine the
556 % |interface3.pdf| file, that is integral part of any recent \TeX\
557 % system distribution. We needed also some commands to compare strings
558 % or to check if a given string was included into an L3 sequence
559 % (list) of strings.
560 %
561 % The syntax of the new testing macro is the following:
562 %\begin{ttsyntax}
563 %\cs{fptest}\marg{test}\marg{true}\marg{false}
564 %\end{ttsyntax}
565 % The logical operators that are usable in the \meta{text} phrase
566 % are \verb+||+ (\texttt{OR}), \verb+&&+ (\texttt{and}), and \verb+!+
567 % (\texttt{NOT}), plus other less common ones; the \verb+!+ negates the
568 % status of boolean variables, but also the numerical relation operators;
569 % these, on turn, may be paired so that, for example |>=| behaves as
570 % as~|!<|.
571 %
572 % The comparisons of strings with the following syntax
573 %\begin{ttsyntax}
574 %\cs{CompStrings}\marg{string\ped{1}}\marg{string\ped{2}}
575 %\end{ttsyntax}
576 % Produces a boolean result that may be used as a \meta{test} argument
577 % to |\fptest|.
578 % The |\SetList| macro defines a named L3 sequence variable containing
579 % the reference list of valid display modes, while the |\TestList| is
580 % an L3 function that tests if a given string is listed in a named
581 % sequence list. Their syntax is the following:
582 %\begin{ttsyntax}
583 %\cs{SetList}\marg{list name}\marg{comma separated string list}
584 % \cs{TestList}\meta{string}\marg{list name}\marg{true}\marg{false}
585 %\end{ttsyntax}
586 % The fields \meta{true} and \meta{false}, as usual, are the actions
587 % to be executed if the test is true or false; the test is true if
588 % \meta{string} is listed into the \meta{named list}.
589 %
590 % Packages |graphicx|, |afterpage|, and |wrapfig| or |wrapfig2| are
591 % functional for this package. In order to avoid “Option Clash” error
592 % messages, such packages are loaded without any option; should the user
593 % load some or all of them with options, the user should load them
594 % \emph{before} loading this package. This particular documentation
595 % does not require the |graphicx| package, because it is already
596 % loaded by |swfigure|.
597 % Notice that |wrapfig2|, is loaded only if the \TeX\ system
598 % installation is sufficiently recent; if the package si not part
599 % of the installation the older |wrapfig| gets loaded. Moreover
600 % if |wrapfig| is implicitly loaded by other packages, such as
601 % |caption| or |subcaption|, that redefine some |wrapfig| internals,
602 % the newer package |wrapfig2| aborts its own loading, because those
603 % redefined internals are incompatible with it.
604 % \begin{macrocode}
605 \RequirePackage{etoolbox}
606 \RequirePackage{xfp}
607
608 \ExplSyntaxOn
609 \ProvideExpandableDocumentCommand\CompStrings{m m}{%
610 \str_if_eq_p:nn{#1}{#2}}
611
612 \ProvideExpandableDocumentCommand\fptest{m m m}{%
613 \fp_compare:nTF{#1}{#2}{#3}}
614
615 \ProvideExpandableDocumentCommand\SetList{m m}{%
616 \seq_clear_new:N #1
617 \seq_set_from_clist:Nn \DisplayModeList {#2}}
618
619 \ProvideExpandableDocumentCommand\TestList{m m m m}{%
620 \seq_if_in:NnTF #1 {#2}{#3}{#4}}
621
622 \ExplSyntaxOff
623
624 \RequirePackage{graphicx}
625 \RequirePackage{afterpage}
626 \IfFileExists{wrapfig2.sty}{%
627 \RequirePackage{wrapfig2}}{\RequirePackage{wrapfig}}
628
629 % \end{macrocode}
630 % We define some dimension and some counter registers; to some dimensions
631 % we assign parameters relating to the page design. We also compute
632 % the dimensions of the available spread space so as to have available
633 % the elements to compare the aspect ratios of the images and of the
634 % available spaces. The |\if@SWtmode| switch is used by all text modes
635 % in order to save the typesetting mode that was active when the
636 % |\DFimage| command or the homonymous environment was used in the source
637 % file; if it was in text mode, the switch is set to |true| and no spaces
638 % should be present after the last argument of that macro or after the
639 % closing environment statement; the result is that every service macro
640 % shifts to vertical mode, but as soon as it is completed the switch test
641 % restores the text mode. A blank line, though, after the command or the
642 % environment starts a new paragraph.
643 %
644 % \begin{macrocode}
645 \newdimen\internalmargin
646 \internalmargin=\dimexpr\oddsidemargin+1in+1bp\relax
647 \newdimen\externalmargin
648 \externalmargin=\dimexpr\evensidemargin+1in
649 \newdimen\spreadwidth
650 \spreadwidth=\dimexpr 2\textwidth+2\internalmargin\relax
651 %
652 \newdimen\DFwidth
653 \newdimen\DFheight
654 \newdimen\DFhalfwidth
655 \newdimen\DFheight
656 \newdimen\DFhalfheight
657 \newdimen\FigSpace
658 \newdimen\TScaptionwidth
659 \def\SWcaptionShift{1em}%
660 \def\FScaptionShift{2em}%
661 \newsavebox\DFtotalimage
662 \newsavebox\DFimageI
663 \newsavebox\DFimageII
664 \newsavebox\RFbox
665 \newdimen\VS@textwidth
666 \newcount\VS@lines
667 \newif\if@SWtmode
668
669 % \end{macrocode}
670 % The following caption-like commands recompile the captions within
671 % a zero height vertical box and deal with the mandatory and optional
672 % arguments according to the following syntax:
673 %\begin{ttsyntax}
674 %\cs{DFcaption}\oarg{lof entry}\marg{caption}\oarg{label}\\[1ex]
675 %\cs{DFcaptionP}\oarg{lof entry}\marg{caption}\oarg{label}
676 %\end{ttsyntax}
677 % Notice that the \meta{lof entry} defaults to the full caption text if
678 % a different text is not explicitly entered.
679 % These commands are specific to those display modes that compose
680 % the caption in vertical direction, therefore the caption measure is the
681 % |\textheight|.
682 % \begin{macrocode}
683 \NewDocumentCommand\DFcaption{O{#2} m o}{\refstepcounter{figure}%
684 \vtop to 0pt{\hsize=\textheight\parindent=0pt\leavevmode
685 \figurename\ \thefigure\quad #2\vss}%
686 \addcontentsline{lof}{figure}{\protect\numberline{\thefigure}#1}
687 \IfValueT{#3}{\label{#3}}\relax%
688 }
689 \NewDocumentCommand\DFcaptionP{O{#2} m o D!!{\color{black}}}%
690 {\refstepcounter{figure}%
691 \vbox to 0pt{\vss\hsize=\textheight\parindent=0pt\leavevmode
692 #4\relax \figurename\ \thefigure\quad #2}%
693 \addcontentsline{lof}{figure}{\protect\numberline{\thefigure}#1}
694 \IfValueT{#3}{\label{#3}}\relax%
695 }
696
697
698 % \end{macrocode}
699 % The |\cleartoeven| command may already exist in the document class.
700 % We prefer to make an absolute redefinition so as to be sure that it
701 % performs as we need in this package. In any case this new definition
702 % may be used in such a way that the |\DFimage| user command may be used
703 % also while typesetting in text (horizontal) mode, resuming such mode
704 % after complete expansion. This is useful, especially for spread wide
705 % display modes, to chose the most suitable place in the source file to
706 % place the |\DFimage| command with its arguments.
707 % The |\cleartoeven| possibly inserts an empty page if the new page
708 % is odd numbered; the |\cleartopage| simply clears the current page,
709 % but it does not insert any empty page.
710 %
711 % \begin{macrocode}
712
713 \newcommand\set@tmode@newpage{%
714 \ifvmode
715 \@SWtmodefalse
716 \else
717 \unskip\@SWtmodetrue\linebreak
718 \vadjust{\vspace{0pt plus1fill}\par}%
719 \fi}
720
721 \newcommand\reset@tmode{\if@SWtmode\expandafter\noindent\ignorespaces\fi}
722
723 \newcommand\cleartoeven[1]{%
724 \set@tmode@newpage\clearpage
725 \ifodd\c@page\afterpage{#1}\else#1\fi%
726 }
727
728 \newcommand\cleartopage{\set@tmode@newpage\clearpage}
729
730 % \end{macrocode}
731 % Now we define the “real” user macro necessary to chose the
732 % \meta{display mode} and the various parameters necessary for the
733 % desired one. See section~\ref{sec:Usage} on page\pageref{sec:Usage}
734 % for its syntax and the other necessary arguments. Notice that only
735 % two arguments are mandatory: the \meta{image file name} and the
736 % \meta{caption} text. All the other eight optional parameters are
737 % delimited by various delimiters; the first one, \meta{display mode}
738 % has as default setting the acronym \texttt{SW} for a “Spread-Wide”
739 % display mode; this mode was the one this package was initially
740 % conceived for, and its initials recall this priority. All other
741 % modes came afterwards. The other optional parameters may have a
742 % default value, but they are ignored by certain modes that don't use
743 % those parameters. As for the previous macro, for |\DFimage|
744 % the \meta{lof entry} defaults to the full \meta{caption} text.
745 %
746 % Actually \cs{DFimage} just examines the \meta{display mode}, and
747 % accordingly passes the necessary parameters to the actual macros
748 % that implement the various mode displays. It outputs an error
749 % message if the \meta{display mode} acronym was misspelt.
750 % The |\DFimage| command (and environment) needs the full list
751 % of arguments, whileand the |DFwarning| macros requires just
752 % the two arguments it is going to actually use.
753 % \begin{macrocode}
754 \NewDocumentEnvironment{DFimage}%
755 { O{SW} m O{#4} m o D(){0.8} D<>{0} D||{0.25} D!!{} }%
756 {%
757 \SetList{\DisplayModeList}{SW,HS,VS,FS,NF,RF,TH,TW}%
758 \TestList{\DisplayModeList}{#1}%
759 {\csuse{#1figure}{#2}[#3]{#4}[#5](#6)<#7>|#8|!#9!%
760 \fptest{\CompStrings{\@currenv}{DFimage}}{}{\reset@tmode}%
761 }%
762 {%
763 \DFwarning[#1]{#2}[#3]{#4}
764 }%
765 }%
766 {%
767 \aftergroup\reset@tmode
768 }%
769
770 \NewDocumentCommand\DFwarning{ o m o m }{%
771 \PackageWarning{swfigure}%
772 {********************************************\MessageBreak
773 Option #1\space is not valid. Nothing done \MessageBreak
774 \MessageBreak
775 Image #2 was not processed \MessageBreak
776 ********************************************\MessageBreak
777 }%
778 }
779
780 % \end{macrocode}
781 % In the following subsections the eight specific display mode macros
782 % are examined and commented.
783 %^^A=====================================
784 % \subsection{The \cs{SWfigure} macro for Spread Wide images}
785 %^^A=====================================
786 %The specific macro for spread-wide images has the following syntax:
787 %\begin{ttsyntax}
788 %\cs{SWfigure}\marg{image file name}\oarg{lof entry}\marg{caption}\oarg{label}
789 %\qquad\parg{height correction}\aarg{lines}|\meta{width thest}|!precaption!
790 %\end{ttsyntax}
791 % The various arguments have already been described; as you see the
792 % \meta{display mode} argument is not there anymore, as well as the
793 % last two optional arguments of |\DFfigure|. Notice that the
794 % \meta{caption} text, the third argument of this macro, is used also
795 % to initialise the \meta{lof entry}, so that if the user does not
796 % specify such short caption entry, the default is identical to the
797 % full caption. Notice the the last arguments are not actually used;
798 % they are needed in the definition due to the way |DFimage| transfers
799 % its arguments to the called macros.
800 %
801 % The working strategy is the following: the initial image to be divided
802 % in two halves is stored in a box; this box is examined in order
803 % to find its total width and heigh, so as to be able to compute the
804 % aspect ratio. All other dimensions are examined to have available
805 % all the necessary data to display the image halves in the requested
806 % way.
807 %
808 % Notice that the |trim| option to |\includegraphics|, that is being
809 % used to divide the initial image in two exact halves, maybe should
810 % be used without specifying other options; but, most important,
811 % it requires actual numbers, not macros; therefore we have to make
812 % use of the usual “dirty” trick of defining an expanded macro
813 % |\x| within a group that the macro itself closes upon its
814 % expansion; in this way the optional argument of the |\includegraphics|
815 % macro contains only keywords and numbers and may be executed
816 % without errors.
817 %
818 % Let $W$ be the total spread width and $w$ be the original image
819 % width; let $H$ be the text height and $h$ the original image height;
820 % compute the $A_\mathrm{W}$ to be the aspect ratio of the spread
821 % available space $H/W$. Similarly let $A_\mathrm{fig}$ be the initial
822 % image aspect ratio; we have to scale the image with a
823 % scaling factor such that the image keeps its aspect ratio, but
824 % its scaled height does not exceed the text block height, and
825 % its scaled width does not exceed the spread width; of course the
826 % aim is to maintain the scaled image as large as possible therefore
827 % we have to chose the most suited of the two scaling factors that
828 % can be computed from the given data and the inequalities
829 % described above.
830 % In mathematical terms we have to chose the initial image scaling
831 % factor $S$ such that:
832 %\begin{equation}
833 %S= \left\{
834 % \begin{array}{lll}
835 % w/W &\mathrm{if}& A_\mathrm{fig} \leq A_\mathrm{W}\\
836 % h/H &\mathrm{if}& A_\mathrm{fig} > A_\mathrm{W}
837 % \end{array}
838 %\right.
839 %\label{equ:ScalingFactor}
840 %\end{equation}
841 % This choice is made by testing the various ratios by means of
842 % the L3 |\fptest| function, that computes such ratios and compares them.
843 % The \meta{test} shows exactly which lengths are used to
844 % compute the ratios, and which comparison is executed; the commented
845 % line over the |\fptest| macro emphasises this correspondence. Once the
846 % scaling factors are found the boxes containing the half figures
847 % are scaled and further on are inserted in floating figure
848 % environments; we use one of the dirty tricks: the matrioska dolls; this
849 % metaphor describes nested |\makebox|es used to mask their actual
850 % widths, but capable to push the images towards the spread spine.
851 % Eventually the caption is set in the right margin of the right
852 % spread page, rotated $90^\circ$ counterclockwise.
853 % The |cleartoeven| guaranties that the first float is set into an even
854 % numbered page. A final |\clearpage| ensures that both floats are
855 % output.
856 % \begin{macrocode}
857 \NewDocumentCommand\SWfigure{m o m o d() d<> d|| d!!}{%
858 \setbox\DFtotalimage=\hbox{\includegraphics{#1}}%
859 \DFwidth=\wd\DFtotalimage \DFhalfwidth=0.5\DFwidth
860 \DFheight=\ht\DFtotalimage
861 \FigSpace=\dimexpr\textwidth+\internalmargin\relax
862 %
863 \setbox\DFimageI\hbox{\bgroup
864 \edef\x{\egroup\noexpand\includegraphics*[%
865 trim = 0 0 \the\DFhalfwidth\space 0]}\x{#1}}%
866 %
867 \setbox\DFimageII\hbox{\bgroup
868 \edef\x{\egroup\noexpand\includegraphics*[%
869 trim = \the\DFhalfwidth\space 0 0 0]}\x{#1}}%
870 %
871 % h/w > H/W
872 \fptest{\DFheight/\DFhalfwidth > \textheight/\FigSpace}%
873 {\edef\DFscalefactor{\fpeval{\textheight/\DFheight}}}%
874 {\edef\DFscalefactor{\fpeval{\FigSpace/\DFhalfwidth}}}%
875 %
876 \setbox\DFimageI=\hbox{\scalebox{\DFscalefactor}{\usebox{\DFimageI}}}%
877 \setbox\DFimageII=\hbox{\scalebox{\DFscalefactor}{\usebox{\DFimageII}}}%
878 %
879 \cleartoeven{%
880 \begin{figure}[p]%
881 \vbox to\textheight{\vss\hsize=\textwidth%
882 \makebox[\hsize][l]{\makebox[\FigSpace][r]{\box\DFimageI}}\vss}%
883 \end{figure}\newpage
884 %
885 \begin{figure}[p]%
886 \vbox to\textheight{\vss\hsize=\textwidth
887 \makebox[\hsize][r]{\makebox[\FigSpace][l]{\box\DFimageII}%
888 % Rotated caption in the right odd-numbered page
889 \makebox(0,0)[lb]{\hspace*{\SWcaptionShift}\raisebox{0.5\textheight}{%
890 \rotatebox[origin=tc]{90}{\DFcaption[#2]{#3}[#4]%
891 %
892 }}}}\vss}%
893 \end{figure}%
894 }\clearpage\reset@tmode}
895
896 % \end{macrocode}
897 %^^A========================================
898 %\subsection{The \cs{NFfigure} macro for normal full
899 % page figures}
900 %^^A========================================
901 % This code is without surprises, except that it receives from the
902 % |DFimage| selector macro five usable arguments (plus three more
903 % ones that are not actually used); the fifth (optional) one
904 % being delimited by round parentheses; by default, it contains the
905 % value 0.8, but the user can pass to the selector macro a different
906 % value in order to reduce the actual image size so as to leave
907 % enough space beneath it for the caption; the user, in facts, does
908 % not know in advance how many lines would occupy a structured
909 % complex caption.
910 % \begin{macrocode}
911 \NewDocumentCommand\NFfigure{m o m o d() d<> d|| d!!}{%
912 \begin{figure}[p]
913 \includegraphics[width=\linewidth, height=#5\textheight,
914 keepaspectratio]{#1}%
915 \caption[#2]{#3}%
916 \IfValueT{#4}{\label{#4}}\relax
917 \end{figure}
918 }
919
920 % \end{macrocode}
921 %^^A========================================
922 % \subsection{The \cs{RFfigure} macro for rotated figures}
923 %^^A========================================
924 % There are no new comments to make about this almost standard
925 % way of displaying a large figure, except, perhaps, the fact
926 % the instead of invoking the |lscape| package, the whole figure
927 % is rotated by means of rotating the very box that was used
928 % to contain the scaled image; the selector macro does not pass
929 % any \meta{height correction} argument to this macro, because
930 % it automatically scales the box containing the image and
931 % the caption so as to fill up the height or the width of the
932 % text block. Of course the macro L3 signature includes also
933 % the descriptors of unused arguments.
934 % \begin{macrocode}
935 \NewDocumentCommand\RFfigure{m o m o d() d<> d|| d!!}{%
936 \dimen8=\textwidth\dimen10=\textheight
937 \figure[p]\setbox\RFbox=\hbox{%
938 \rotatebox[origin=cc]{90}{\parbox[b][\dimen8][c]{\dimen10}%
939 {\centering\includegraphics[width=\dimen10, height=\dimen8,
940 keepaspectratio]{#1}%
941 \caption[#2]{#3}%
942 \IfValueT{#4}{\label{#4}}\relax%
943 }}}%
944 \edef\RFx{\fpeval{\ht\RFbox/\textheight}}%
945 \edef\RFy{\fpeval{\wd\RFbox/\textwidth}}%
946 \fptest{\RFx > \RFy}%
947 {\scalebox{\RFx}{\box\RFbox}}%
948 {\scalebox{\RFy}{\box\RFbox}}%
949 \endfigure}
950
951 % \end{macrocode}
952 %^^A========================================
953 % \subsection{The \cs{VSfigure} macro for tall and slim figures}
954 %^^A========================================
955 % This is the most critical macro (because it depends
956 % on the |wrapfig| package) in order to set the image with its
957 % caption on the external side of the text block, with the text flowing
958 % around it. Package |wrapfig| has several limitations concerning
959 % the text that flows around the image. Nevertheless with a “normal”
960 % textual contents of the text block the result may be very good.
961 %
962 % The user is recommended to attentively read the |wrapfig|
963 % documentation because it has several limitations. Here we suggest
964 % the user to open the environment just before a paragraph and
965 % close it after several paragraphs; remember that since the opening
966 % and the closing statements are far away from one another, it is
967 % possible to forget this situation and insert another such
968 % environment, or a |\DFimage| command, within the former one
969 % and this will produce undesirable effects; never ever nest two
970 % |Dfimage| environments and never ever insert a |\DFimage| command
971 % within an environment.
972 %
973 % The user should help a little bit the correct performance of
974 % this macro; for this reason, besides the \meta{height correction}
975 % factor, the selector macro may pass to it also the \meta{line
976 % correction} in order to correct the amount of lines the wrapping
977 % text should be indented; by playing with both corrections
978 % good results may be obtained.
979 %
980 % Notice that only with this macro a test on the initial image
981 % aspect ratio is performed; should this image have an aspect ratio
982 % smaller than~2, the process is aborted and a message is printed
983 % in the output document that informs the user and recommends to
984 % use another \meta{display mode} code.
985 %
986 % Furthermore, should the image be very slim and tall, the
987 % \meta{height correction} may conveniently reduce its height,
988 % but, in order to avoid changing its aspect ratio, it reduces
989 % also its width; eventually the width is reduced to the point that
990 % beneath the image there would not be enough space for a decently
991 % typeset caption. A further optional delimited argument is available:
992 % its delimiting tokens are two vertical bars, \verb+| |+, and its
993 % default value is \texttt{0.25}. This means that if the scaled
994 % image becomes narrower than this coefficient times the text width,
995 % an other message is typeset in place of the figure. Depending on the
996 % various elements that influence these tests, the user can try
997 % different values for this coefficient, even reaching the value zero,
998 % that eliminates such test on the scaled image width.
999 %
1000 %
1001 % \begin{macrocode}
1002 \NewDocumentCommand\VSfigure{m o m o d() d<> d|| d!!}{%
1003 \setbox\DFtotalimage=\hbox{\includegraphics{#1}}
1004 \DFwidth=\wd\DFtotalimage \DFheight=\ht\DFtotalimage
1005 \edef\VS@aspectratio{\fpeval{\DFheight/\DFwidth}}
1006 \fptest{ \VS@aspectratio < 2 }%
1007 {\begin{center}\ttfamily\relax
1008 ===========================================\\
1009 Image #1 is not tall enough. \\
1010 Consider using a display mode different \\
1011 from VS; may be NF or RF are better suited.\\
1012 ===========================================\\
1013 Nothing done! \\
1014 ===========================================
1015 \end{center}
1016 }%
1017 {\edef\VS@factor{\fpeval{#5\textheight/\DFheight}}%
1018 \fptest{\VS@factor>1 || \VS@factor\DFwidth < #7\textwidth}%
1019 {%
1020 \begin{center}\ttfamily\relax
1021 =================================================\\
1022 The scaled image #1 is too slim. \\
1023 Maybe directly using the wrapfig package might \\
1024 solve this problem. \\
1025 =================================================\\
1026 Nothing done!\\
1027 =================================================
1028 \end{center}
1029 }%
1030 {\setbox\DFtotalimage=
1031 \hbox{\scalebox{\VS@factor}{\box\DFtotalimage}}%
1032 \edef\VS@width{\fpeval{\VS@factor*\DFwidth}\p@}%
1033 \setbox\DFtotalimage=\vbox{\hsize=\VS@width%
1034 \def\@captype{figure}\box\DFtotalimage
1035 \caption[#2]{#3}%
1036 \IfValueT{#4}{\label{#4}}\relax}
1037 \VS@lines=
1038 \fpeval{round(\ht\DFtotalimage/\baselineskip,0)+#6}%
1039 \begin{wrapfigure}[\VS@lines]{o}[0pt]{\VS@width}%
1040 \box\DFtotalimage
1041 \end{wrapfigure}%
1042 }%
1043 }%
1044 }%
1045
1046 % \end{macrocode}
1047 %
1048 %^^A=====================================
1049 % \subsection{The \cs{HSfigure} macro for spread wide slim figures}
1050 %^^A=====================================
1051 %
1052 % The beginning of the macro is not so different from that used
1053 % for the |SWfigure| macro. But this time there is no alternative
1054 % to scale the image because only its width and the spread width are
1055 % significant. The new little problem, now, is to match the total
1056 % height of the two halves of the original wide and slim image,
1057 % so that the texts of the two facing pages have their respective
1058 % first lines perfectly aligned.
1059 %
1060 % Since the right half of the figure contains also the caption
1061 % it is necessary to box again the left page box so as to have
1062 % the same hight and depth as the right page one.
1063 % \begin{macrocode}
1064 \NewDocumentCommand\HSfigure{m o m o d() d<> d|| d!!}{%
1065 \setbox\DFtotalimage=\hbox{\includegraphics{#1}}%
1066 \DFwidth=\wd\DFtotalimage \DFhalfwidth=0.5\DFwidth
1067 \FigSpace=0.5\spreadwidth%
1068 %
1069 \setbox\DFimageI\hbox{\bgroup
1070 \edef\x{\egroup\noexpand\includegraphics*[%
1071 trim = 0 0 \the\DFhalfwidth\space 0]}\x{#1}}%
1072 %
1073 \setbox\DFimageII\hbox{\bgroup
1074 \edef\x{\egroup\noexpand\includegraphics*[%
1075 trim = \the\DFhalfwidth\space 0 0 0]}\x{#1}}%
1076 %
1077 \edef\DFscalefactor{\fpeval{\FigSpace/\DFhalfwidth}}%
1078 %
1079 \setbox\DFimageI=\hbox{%
1080 \scalebox{\DFscalefactor}{\usebox{\DFimageI}}}%
1081 \setbox\DFimageII=\hbox{%
1082 \scalebox{\DFscalefactor}{\usebox{\DFimageII}}}%
1083 \setbox\DFimageII=
1084 \hbox{\dimen10=\linewidth\dimen8\internalmargin
1085 \vbox{\hsize\DFhalfwidth\parindent\z@
1086 \box\DFimageII\par
1087 \leavevmode\hspace*{\dimen8}%
1088 \vtop{\hsize\dimen10\parindent\z@
1089 \textwidth=\hsize
1090 \DFcaption[#2]{#3}[#4]%
1091 }\vspace*{2\baselineskip}%
1092 }%
1093 }%
1094 \setbox\DFimageI=\vbox to\ht\DFimageII{\box\DFimageI\vss}%
1095 %
1096 \cleartoeven{%
1097 \hb@xt@\textwidth{%
1098 \makebox[\DFhalfwidth][l]{\box\DFimageI}\hss}%
1099 %
1100 \afterpage{\hb@xt@\textwidth{%
1101 \hss\makebox[\DFhalfwidth][r]{\box\DFimageII}}%
1102 }%
1103 }%
1104 }
1105
1106 % \end{macrocode}
1107 %
1108 %^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1109 %\subsection{The \cs{FSfigure}~macro for Full Spread figures}
1110 %^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1111 % Although using certain classes, such as |memoir|, it is possible to
1112 % typeset documents on pages of different sizes and to print them on
1113 % advanced printers that use different sized papers, this package aims
1114 % to be independent form any class and any printer; it is limited to
1115 % the ordinary default paper size A4, as it is usual in Europe, but
1116 % letter paper is also valid; ideally it would typeset an A3 sized
1117 % image on a full spread, i.e. by filling also the space of all the
1118 % lateral margins.
1119 %
1120 % Actually with American paper sizes there is not a series of sizes
1121 % that behaves as the ISO A series, but this macro tries to adjust the
1122 % large image to the available full spread; this means an image as
1123 % large as two standard pages.
1124 %
1125 % If the available image is taller than large, with an aspect ratio
1126 % around~$\sqrt2$, it turns the image 90° counterclockwise; cuts it in
1127 % two identically sized halves, and sets them on two facing pages joining
1128 % them at the spine but covering the greatest part of both pages, so
1129 % as to avoid exceeding either the paper height or twice the paper width.
1130 % If the image has an landscape aspect ratio close to $\sqrt{1/2}$, it
1131 % does the same, except rotating the image.
1132 %
1133 % In any case the user creates a separate PDF file to be imported into
1134 % the document that is supposed to contain it; it is better if this PDF
1135 % is of vectorial type, i.e. any drawing and all fonts should be
1136 % vectorial; this PDF might contain photos or similar images of
1137 % rasterised type, but the pixel density should be suitably high in
1138 % order to preserve the image quality.
1139 %
1140 % The user has two choices: $(a)$ either the image has its own margins,
1141 % or $(b)$ the image is cropped and has no white margins.
1142 %
1143 % Normally this display mode does not leave space for a caption;
1144 % therefore if a caption is needed, it is overprinted on the image;
1145 % in case $(a)$ there are no problems because the caption goes over
1146 % the white right margin (rotated 90° counterclockwise); while in
1147 % case $(b)$ the caption is over printed on the right side of the
1148 % image; depending on the image “background” a different color
1149 % might be more suited compared to the the default color (black).
1150 % The last macro argument takes care of inserting before the caption
1151 % any declaration that may involve color, displacement, font encoding
1152 % (seldom necessary), family, series, shape and size;
1153 %
1154 % With all the above constraints the syntax of this \cs{FSimage}
1155 % macro is the following; it uses one of the main macro delimited
1156 % optional arguments in a different way:
1157 %\begin{ttsyntax}\setfontsize{9.25}%
1158 %\cs{FSimage}\marg{image file name}\oarg{lof entry}\marg{caption text}\oarg{label string}
1159 %\qquad\parg{height correction}\aarg{line correction}\barg{width text}!\meta{precaption}!
1160 %\end{ttsyntax}
1161 % The above is the full definition, but the fifth, sixth and seventh
1162 % arguments are not used; they are necessary for the special
1163 % mechanism of argument transfer from the environment or command
1164 % opening statement arguments to this actual macro.
1165 %
1166 % Moreover, since the included image overlaps the top and bottom
1167 % margins, if these contain the header and footer such elements
1168 % would show if the image is not sufficiently opaque; in any case the
1169 % footer would show because it overlaps the image. Since most
1170 % images are not really opaque it is better to locally use the
1171 % \texttt{empty} page style, but without using the |\thispagestyle|
1172 % command, because it holds for just one page, while the spread
1173 % occupies two pages. The macro provides this setting but it has
1174 % to create a group in case the |\DFimage| command is used, while
1175 % it is not necessary when using the |DFimage| environment,
1176 % therefore the current environment is tested and the opening
1177 % |\bgroup| and closing |\egroup| commands are used only if the
1178 % code is used without the environment.
1179 %
1180 % Therefore the code steps are the following:
1181 %\begin{enumerate}[noitemsep]
1182 %\item
1183 % The initial figure is loaded into a box from which the necessary
1184 % measures are taken; in particular its width and its height in
1185 % order to check the aspect ratio, or better, which dimension is greater
1186 % than the other. If the height is smaller than the width the image is
1187 % sort of landscape and we proceed splitting the total image box into
1188 % two equal halves, with a vertical cut in the middle.
1189 %\item
1190 % Otherwise the image is as a portrait, and we split the total image
1191 % block into two halves with an horizontal cut in the middle; such two
1192 % boxes need a rotation of 90° anticlockwise due to the horizontal cut of
1193 % an original that was higher than wide image. With this operation we
1194 % simulate a rotation of the original image, because it is not allowed to
1195 % simultaneously rotate and trim the original image; the trimming
1196 % action apparently cannot be executed together with any other one
1197 % among the many other that the |\includegraphics| command can
1198 % do\footnote{Actually it can, provided that the trim option with
1199 % its arguments is specified before any other option.}.
1200 % Of course, with this rotation of the half pictures we have to
1201 % redefine the height and width to use for scaling.
1202 %\item
1203 % The |\fptest| is used to compare the aspect ratios of any of the two
1204 % equal halves with the aspect ratio of the paper. If the former
1205 % aspect ratio is higher than the latter, the scaling factor is
1206 % based on the heights, otherwise on the widths, so as to resize
1207 % both half picture boxes to fit within the paper.
1208 %\item
1209 % The |\cleartoeven| command allows to use the main macro even within
1210 % a paragraph; in any case it possibly inserts a blanc page and restarts
1211 % working on an even page. First is sets the left half picture box;
1212 % that complicated series of vertical and horizontal boxes of different
1213 % specified dimensions contains displacements and the material to output;
1214 % That complicated alternating set is to guarantee that no overfull
1215 % vertical or horizontal boxes are created, in spite of the fact that
1216 % an object larger than the text block is being output; at the same
1217 % time the box must be flush right in order to reach the spine.
1218 %\item
1219 % The right half is even more complicated to build, because there
1220 % is also the caption to set on the right of the page, overwriting
1221 % the right part of the image, but the idea is always to close
1222 % correctly every box putting the right spacing commands at the
1223 % beginning or at the end of each box.
1224 %\item
1225 % Eventually a |\clearpage| flushes out everything that is still in
1226 % the figure stack and possibly restores the vertical or horizontal
1227 % typesetting mode depending on the status that was in force when
1228 % the |\DFimage| command or the |DFimage| environment started their
1229 % expansion.
1230 % Due to the size of the images that completely fill up all the
1231 % margins, probably the best way to output such huge images is at
1232 % the end of a chapter, or at the end of the whole document.
1233 %\end{enumerate}
1234 % \begin{macrocode}
1235 \NewDocumentCommand\FSfigure{m o m o d() d<> d|| d!!}{%
1236 \fptest{\CompStrings{\@currenv}{DFimage}}{}{\bgroup}%
1237 \pagestyle{empty}%
1238 \setbox\DFtotalimage=\hbox{\includegraphics{#1}}%
1239 \DFwidth=\wd\DFtotalimage \DFheight=\ht\DFtotalimage
1240 \ifdim \DFheight < \DFwidth
1241 \DFhalfwidth=0.5\DFwidth
1242 \setbox\DFimageI\hbox{\bgroup
1243 \edef\x{\egroup\noexpand\includegraphics*[%
1244 trim = 0 0 \the\DFhalfwidth\space 0]}\x{#1}}%
1245 \setbox\DFimageII\hbox{\bgroup
1246 \edef\x{\egroup\noexpand\includegraphics*[%
1247 trim = \the\DFhalfwidth\space 0 0 0]}\x{#1}}%
1248 \DFwidth=\DFhalfwidth \DFheight=\ht\DFtotalimage
1249 \else
1250 \DFhalfheight=0.5\DFheight
1251 \setbox\DFimageII\hbox{\bgroup
1252 \edef\x{\egroup\noexpand\includegraphics*[%
1253 trim = 0 0 0 \the\DFhalfheight\space]}\x{#1}}% bottom half
1254 \setbox\DFimageI\hbox{\bgroup
1255 \edef\x{\egroup\noexpand\includegraphics*[%
1256 trim = 0 \the\DFhalfheight\space 0 0]}\x{#1}}% tophalf
1257 \setbox\DFimageI=\hbox{\rotatebox[origin=cc]{90}{\box\DFimageI}}
1258 \setbox\DFimageII=\hbox{\rotatebox[origin=cc]{90}{\box\DFimageII}}
1259 \DFwidth=\DFhalfheight \DFheight=\wd\DFtotalimage
1260 \fi
1261 \fptest{\DFheight/\DFwidth > \paperheight/\paperwidth}%
1262 {\edef\DFscalefactor{\fpeval{\paperheight/\DFheight}}}%
1263 {\edef\DFscalefactor{\fpeval{\paperwidth/\DFwidth}}}%
1264 \setbox\DFimageI=\hbox{\scalebox{\DFscalefactor}{\usebox{\DFimageI}}}%
1265 \setbox\DFimageII=\hbox{\scalebox{\DFscalefactor}{\usebox{\DFimageII}}}%
1266 \cleartoeven{%
1267 \begin{figure}[p]%
1268 \vbox to\textheight{\vss\hsize=\textwidth% vbox 1
1269 \hbox to\hsize{\hspace*{-\externalmargin}% hbox 1
1270 \vbox to\paperheight{\vss% vbox 2
1271 \hbox to\paperwidth{\hss\box\DFimageI}% hbox 2 end hbox 2
1272 \vss}% end vbox 2
1273 \hss}% end hbox 1
1274 \vss}% end vbox 1
1275 \end{figure}\newpage
1276 %
1277 \begin{figure}[p]%
1278 \vbox to\textheight{\vss\hsize=\textwidth% vbox 1
1279 \hbox to\hsize{\hspace*{-\internalmargin}% hbox 1
1280 \vbox to\paperheight{\vss% vbox 2
1281 \hbox to\paperwidth{% hbox 2
1282 \box\DFimageII\makebox(0,0)[lb]{% mbox 3
1283 \hspace*{-\FScaptionShift}%
1284 \raisebox{0.5\textheight}{% raisebox
1285 \rotatebox[origin=bc]{90}{% rotatebox
1286 \DFcaptionP[#2]{#3}[#4]!#8!%
1287 }% end rotatebox
1288 }% end raisebox
1289 }% end mbox 3
1290 }% end hbox 2
1291 \vss}% end vbox 2
1292 \hss}% end hbox 1
1293 \vss}% end vbox 1
1294 \end{figure}%
1295 }\clearpage
1296 \fptest{\CompStrings{\@currenv}{DFimage}}{}{\egroup}%
1297 \reset@tmode}
1298
1299 % \end{macrocode}
1300 %
1301 %^^A========================================
1302 %\subsection{The \cs{THfigure} macro for the Total Height figure}
1303 %^^A========================================
1304 % This Total Height display mode exploit the total paper height to
1305 % scale a figure and sets the image close to the spine independently
1306 % from the fact that the spine ins on the right of even numbered
1307 % pages, and on the left on odd numbered ones; a test is made on the
1308 % page parity, that in any case is going to contain only the figure
1309 % with its caption and nothing else. For this reason the macro provides
1310 % a \cs{cleartopage} at the beginning and another similar command on the
1311 % end. As usual this macro is not supposed to be used by the user,
1312 % who should use the command \cs{DFimage}; using the environment
1313 % is recommended if it is used within a paragraph, but it should not
1314 % include any text.
1315 %
1316 % The full syntax is the following:
1317 %\begin{ttsyntax}\setfontsize{9.25}%
1318 %\cs{FSimage}\marg{image file name}\oarg{lof entry}\marg{caption text}\oarg{label string}
1319 %\qquad\parg{caption width percent}\aarg{line correction}\barg{width text}!\meta{precaption}!
1320 %\end{ttsyntax}
1321 % although the last three arguments are not used.
1322 %
1323 % All the code before the first \cs{cleartopage} command is used to
1324 % examine the dimensions of the original image, and to perform the
1325 % necessary assignments to the various dimensions and boxes. The
1326 % test on the relationship between the \cs{DFwidth} image width and
1327 % the sum of the text and internal margin widths is to compute the
1328 % caption measure and assign the result to the dimension
1329 % register \cs{TScaptionwidth}; this width is tested to control if it
1330 % is too small; in case a warning message is issued.
1331 %
1332 % The following question is natural: When is this display mode
1333 % convenient? After all, also the \texttt{VS} display mode applies
1334 % to tall and slim images, so this \texttt{TH} mode and the other
1335 % \texttt{VS} mode are in competition. In a way they are, but their
1336 % results are very different; The latter mode produces images non
1337 % larger than half the test block and not taller than the text block.
1338 % The former mode produces images that are taller than the text block
1339 % and possibly larger than the text block. Therefore this is one of
1340 % the possible criteria to chose which display mode is more suitable
1341 % for a given image. another other criterion deals with the image aspect
1342 % ratio and the available space aspect ratio; since the height of the
1343 % \texttt{TH} scaled image is fixed, the user should pay attention to
1344 % its width; the scaled image width, in facts, should not exceed the
1345 % sum of the internal margin width and the test block one, otherwise
1346 % the space for the caption becomes too small and a warning message
1347 % is issued. At the same time if the scaled image width is smaller
1348 % than approximately one half of the text width plus the internal
1349 % margin one, the space remaining for the caption becomes too large.
1350 %
1351 % After that the |figure| environment is coded starting with
1352 % the control on the page parity; depending on this parity different
1353 % dirty tricks with several kinds of boxes are performed so as to
1354 % set into the page a huge block that fills all the available vertical
1355 % space on the paper; the parity influences the order in which the various
1356 % embedded boxes interact with one another, but the main point is
1357 % that the box containing the caption must be on the external side
1358 % of the box containing the image; its measure may be fine tuned
1359 % (increased or reduced) with respect to available white space; the
1360 % argument \meta{caption width percent} delimited by round parentheses
1361 % by default equals 0.8, but the user can specify a different value
1362 % to the selector macro, so that the caption measure is that specified
1363 % percentage of the computed caption width.
1364 %
1365 % After closing the |figure| environment a final \cs{clearpage} is
1366 % issued so that the figures stack remains completely empty; in
1367 % particular the current figure is output, but the initial typesetting
1368 % mode is restored, so that if the environment was specified in the
1369 % middle of a paragraph the paragraph continues to be typeset without
1370 % problems; of course if the environment is followed by a blanc line,
1371 % such settings become ineffective because a new paragraph is started.
1372 % The end of the \cs{DFimage} command provides to close the group,
1373 % therefore all the assignments to the various registers are restored.
1374 % \begin{macrocode}
1375 \NewDocumentCommand\THfigure{m o m o d() d<> d|| d!!}{%
1376 \setbox\DFtotalimage=\hbox{\includegraphics{#1}}%
1377 \DFheight=\ht\DFtotalimage \DFwidth=\wd\DFtotalimage
1378 \edef\DFscalefactor{\fpeval{\paperheight/\DFheight}}
1379 \setbox\DFimageI\hbox{%
1380 \scalebox{\DFscalefactor}{\usebox{\DFtotalimage}}}%
1381 \DFwidth=\wd\DFimageI
1382 \ifdim\dimexpr\paperwidth-\DFwidth < 2\externalmargin\relax
1383 \PackageWarning{swfigure}{%
1384 *******************************************\MessageBreak
1385 Figure #1 is too wide to be set in a \MessageBreak
1386 Total Height display mode. \MessageBreak
1387 There is not enough space for its caption. \MessageBreak
1388 Expect questionable results. \MessageBreak
1389 *******************************************\MessageBreak}%
1390 \fi
1391 \FigSpace=\DFwidth
1392 \dimen10=\dimexpr\topmargin+1in-(\paperheight-\headsep-\headheight
1393 -\textheight-\footskip)/2\relax
1394 \TScaptionwidth=\dimexpr\paperwidth-\FigSpace-3\columnsep\relax
1395 \cleartopage
1396 \thispagestyle{empty}%
1397 \begin{figure}
1398 \ifodd\c@page\relax% odd page
1399 \begin{minipage}[c][\textheight][t]{\textwidth}% minibox1
1400 \vspace*{\dimen10}%
1401 \makebox[\textwidth][l]{\hspace*{-\internalmargin}% hbox2
1402 \vbox to\textheight{\vss% vbox3
1403 \hbox to\paperwidth{% hbox4
1404 \parbox{\FigSpace}{\box\DFimageI}%
1405 \hspace{\columnsep}%
1406 \makebox[\TScaptionwidth]{%
1407 \parbox{#5\TScaptionwidth}{%
1408 \caption[#2]{#3}\IfValueT{#4}{\label{#4}}\relax}%
1409 }%
1410 }% end hbox4
1411 \vss}% end vbox3
1412 }% end hbox2
1413 \end{minipage}% end minibox1
1414 \else % even page
1415 \begin{minipage}[c][\textheight][t]{\textwidth}
1416 \vspace*{\dimen10}%
1417 \makebox[\textwidth][l]{\kern-\externalmargin
1418 \vbox to\textheight{\vss
1419 \hbox to\paperwidth{\hss
1420 \hbox to\TScaptionwidth{\hss
1421 \parbox{#5\TScaptionwidth}{%
1422 \caption[#2]{#3}\IfValueT{#4}{\label{#4}}\relax}%
1423 }\hspace{\columnsep}%
1424 \parbox{\FigSpace}{\box\DFimageI}%
1425 }\vss
1426 }%
1427 }%
1428 \end{minipage}%
1429 \fi
1430 \end{figure}%
1431 \clearpage\reset@tmode
1432 }
1433 % \end{macrocode}
1434 %
1435 %^^A========================================
1436 %\subsection{The \texttt{TW} for the Total Width
1437 % image plus its side caption}
1438 %^^A========================================
1439 % This particular mode is a variant of the \texttt{FH} full height mode,
1440 % where scaling of a not sufficiently narrow image, may produce a figure
1441 % that does not exceed the page dimesions, but that might leave such a
1442 % small narrow strip of white space to typeset the caption that it comes
1443 % out as a very poorly typeset object. This other \texttt{TW} does not
1444 % have this drawback, but it might produce figures that exceed the paper
1445 % height in order to remain within the preset limits foreseen for a nicely
1446 % typeset side caption.
1447 %
1448 % Some details are pretty delicate, but let us start from the beginning.
1449 % The seven code lines afterthe first one, are the usual lines similar
1450 % to those at the beginning of the other macros; The original image is
1451 % stored in a box, from which all possible metric informations are derived
1452 % and the scaling factor is computed; afterward the boc is scaled
1453 % according to the computed scaling factor, and re-stored into the
1454 % same box.
1455 %
1456 % Command |\cleartopage| behaves as usual and sets the |\if@SWtmode|
1457 % so as to be able to restore the typesetting modo (horizontal or
1458 % vertical) at the end of this macro expansion. This means, also,
1459 % that for this display mode both the command and the homonymous
1460 % environment |DFimage| may be used.
1461 %
1462 % The page style is set to |empty|, so that the full width block may
1463 % be set flush to the top of the paper, without overwriting any page
1464 % decoration; even the possible folio in the bottom margin is not
1465 % overwritten onto the image.
1466 %
1467 % The test for the parity of the folio number is taken; the true and
1468 % the false branches are very similar, bat the actions that differ
1469 % because depend on the folio parity are interspersed between the
1470 % other code lines. This is why two |figure|environments are defined,
1471 % even if their contents is pretty similar.
1472 %
1473 % We comment the true branch for odd numbered figures, and with slight
1474 % changes they equal those for the even numbered page; Therefore we
1475 % omit the latter.
1476 %
1477 % We box the figure and the caption into an |\hbox| named |\DFimageII|;
1478 % the image box |\DFimageI| si typeset inside a |\parbox| were the measure
1479 % is specified as the boxed image width. The |\parbox| as well as the
1480 % following |minipage| environment are but vertically centred, so that
1481 % we are sure that the caption median will coincide with that of the
1482 % boxed image. As you see the caption is at the right of the boxed
1483 % image, and in an odd numbered page the caption is close and partially
1484 % over the external margin; the opposite takes place for the even
1485 % numbered pages, and again the caption is close or over such page
1486 % external margin.
1487 %
1488 % We can now measure the various geometric properties of the image-caption
1489 % block; notice that his block is large as the internal margin plus
1490 % spaces plus the caption for a total of |\paperwidth|. We should
1491 % keep this in mind in order to re-box the block into a |\textwidth|
1492 % wide box with the necessary stretch and shrink horizontal glue
1493 % in oder to let it fit the paper width wich is larger that the
1494 % text width
1495
1496 % Moreover we measure the upper white margin, that is white, because
1497 % of the |empty| page style, but the header box, its separator from
1498 % the text, the |\topmargin| with its 1~inch offset, in order to raise
1499 % the image-caption box to be flush to the upper paper border.
1500 % Now we can fill up a vertical box of the computed height; this box
1501 % is inside the text block, but it must overlap the upper vertical
1502 % space so the real height of this box is smaller than its contents
1503 % and a vertical stretch and shrink glue is necessary.
1504 % Eventually with these nestes vertical and horizontal boxes we can
1505 % output the whole contents and the result is as we expected.
1506 % \begin{macrocode}
1507 \NewDocumentCommand\TWfigure{m o m o d() d<> d|| d!!}{%
1508 \setbox\DFtotalimage=\hbox{\includegraphics{#1}}%
1509 \DFheight=\ht\DFtotalimage \DFwidth=\wd\DFtotalimage
1510 \FigSpace=\dimexpr\internalmargin+0.80\textwidth\relax
1511 \TScaptionwidth=\dimexpr\paperwidth-\FigSpace-2\columnsep\relax
1512 \edef\DFscalefactor{\fpeval{\FigSpace/\DFwidth}}
1513 \setbox\DFimageI=\hbox{\scalebox{\DFscalefactor}{\box\DFtotalimage}}
1514 \DFwidth=\wd\DFimageI \DFheight\ht\DFimageI
1515 \cleartopage
1516 \thispagestyle{empty}%
1517 \ifodd\value{page}% odd numbered page
1518 \begin{figure}
1519 \setbox\DFimageII=\hbox{%
1520 \parbox{\FigSpace}{\box\DFimageI}\hspace{\columnsep}%
1521 \begin{minipage}{\TScaptionwidth}\centering
1522 \parbox{#5\hsize}{\caption[#2]{#3}%
1523 \IfValueT{#4}{\label{#4}}\relax}%
1524 \end{minipage}
1525 }%
1526 \DFheight=\ht\DFimageII \dimen8=\dp\DFimageII
1527 \advance\DFheight by\dp\DFimageII
1528 \dp\DFimageII=\z@ \ht\DFimageII=\DFheight
1529 \dimen10=\fpeval{\topskip+1in+\headheight+\headsep}\p@
1530 \advance\dimen8 by\baselineskip
1531 \advance\DFheight by-\dimen10\relax
1532 \vbox to\DFheight{\vss
1533 \hbox{\raise \dimen8\hbox to\textwidth{%
1534 \hspace{-\internalmargin}\box\DFimageII\hss}}%
1535 }%
1536 \end{figure}
1537 \else% even numbered page
1538 \begin{figure}
1539 \setbox\DFimageII=\hbox{%
1540 \begin{minipage}{\TScaptionwidth}\centering
1541 \parbox{#5\hsize}{\caption[#2]{#3}%
1542 \IfValueT{#4}{\label{#4}}\relax}%
1543 \end{minipage}
1544 \hspace{\columnsep}%
1545 \parbox{\FigSpace}{\box\DFimageI}
1546 }%
1547 \DFheight=\ht\DFimageII \dimen8=\dp\DFimageII
1548 \advance\DFheight by\dp\DFimageII
1549 \dp\DFimageII=\z@ \ht\DFimageII=\DFheight
1550 \dimen10=\fpeval{\topskip+1in+\headheight+\headsep}\p@
1551 \advance\dimen8 by\baselineskip
1552 \advance\DFheight by-\dimen10\relax
1553 \vbox to\DFheight{\vss
1554 \hbox{\raise \dimen8\hbox to\textwidth{\hss%
1555 \box\DFimageII\hspace{-\internalmargin}}}%
1556 }%
1557 \hbox to\textwidth{\hspace{-\internalmargin}\box\DFimageII\hss}
1558 \end{figure}%
1559 \fi
1560 \reset@tmode
1561 }
1562
1563 % \end{macrocode}
1564 %
1565 %\vspace*{2\baselineskip}
1566 %\noindent\makebox[\textwidth]{\setfontsize{10mm}
1567 %\color{red} HAPPY \LaTeX-ing}
1568 %\iffalse
1569 %</package>
1570 %\fi
1571 %
1572 % \Finale
1573 %
1574 %\endinput
1575 %
1576 %