From c1748f388233d142b9d27c4e12aaf592b2f38b09 Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Sun, 11 Oct 2020 20:51:37 +0000 Subject: swfigure (11oct20) git-svn-id: svn://tug.org/texlive/trunk@56637 c570f23f-e606-0410-a88d-b1316a301751 --- .../texmf-dist/source/latex/swfigure/swfigure.dtx | 855 +++++++++++++++++++++ 1 file changed, 855 insertions(+) create mode 100644 Master/texmf-dist/source/latex/swfigure/swfigure.dtx (limited to 'Master/texmf-dist/source') diff --git a/Master/texmf-dist/source/latex/swfigure/swfigure.dtx b/Master/texmf-dist/source/latex/swfigure/swfigure.dtx new file mode 100644 index 00000000000..d848cae2fae --- /dev/null +++ b/Master/texmf-dist/source/latex/swfigure/swfigure.dtx @@ -0,0 +1,855 @@ +% \iffalse +% !TEX encoding = UTF-8 Unicode +% !TEX TS-program = pdflatex +%<*internal> +\begingroup +\input docstrip.tex +\keepsilent +\preamble + + Copyright (C) 2020 Claudio Beccari all rights reserved. + License information appended + +\endpreamble + +\postamble + +Distributable under the LaTeX Project Public License, +version 1.3c or higher (your choice). The latest version of +this license is at: http://www.latex-project.org/lppl.txt + +This work is "maintained" + +This work consists of files swfigure.dtx and READEME.txt, and the derived +files swfigure.sty and swfigure.pdf + +\endpostamble +\askforoverwritefalse + +\generate{\file{swfigure.sty}{\from{swfigure.dtx}{package}}} +%\generate{\file{README.txt}{\from{swfigure.dtx}{readme}}} + +\def\tmpa{plain} +\ifx\tmpa\fmtname\endgroup\expandafter\bye\fi +\endgroup +% +% \fi +% +% \iffalse +%<*package> +%\NeedsTeXFormat{LaTeX2e}[2020/01/01] +% +%<*driver> +\ProvidesFile{swfigure.dtx}% +% +%<+package>\ProvidesPackage{swfigure}% +%<+readme>File README.txt for package swfigure +%<*package|readme> + [2020-10-11 v.0.9.07 Managing large and spread wide figures] +% +%<*driver> +\documentclass[a4paper]{ltxdoc}\errorcontextlines=9 +\hfuzz 10pt +\usepackage[utf8]{inputenc} +\usepackage{lmodern,textcomp,multicol,enumitem,mflogo,xcolor} +\usepackage{swfigure} + +\providecommand*\diff{\mathop{}\!\mathrm{d}} +\renewcommand\meta[1]{{\normalfont\textlangle\textit{#1}\textrangle}} +\renewcommand\marg[1]{\texttt{\{\meta{#1}\}}} +\providecommand\Marg{} +\renewcommand\Marg[1]{\texttt{\{#1\}}} +\providecommand\oarg{} +\renewcommand\oarg[1]{\texttt{[\meta{#1}]}} +\providecommand\Oarg{} +\renewcommand\Oarg[1]{\texttt{[#1]}} +\providecommand\aarg{} +\renewcommand*\aarg[1]{\texttt{<\meta{#1}>}} +\providecommand\Aarg{} +\renewcommand\Aarg[1]{\texttt{<#1>}} +\providecommand\parg{} +\renewcommand\parg[1]{\texttt{(\meta{#1})}} +\providecommand\Parg{} +\renewcommand\Parg[1]{\texttt{(#1)}} +\providecommand\eTeX{} +\newbox\SWsynt +\renewcommand\eTeX{\lower0.5ex\hbox{$\varepsilon\!$}\TeX} + +\newenvironment{medaglione}% +{\par\medskip\fboxrule=0.8pt\fboxsep6pt\relax +\begin{lrbox}{\SWsynt}\minipage{\dimexpr\linewidth-2\fboxsep-2\fboxrule}}% +{\endminipage\end{lrbox}\noindent\fbox{\box\SWsynt}\par\medskip} + +\newenvironment{ttsyntax}{\medaglione\raggedright\ttfamily\obeylines}{\endmedaglione} + +\providecommand\setfontsize{} +\DeclareRobustCommand\setfontsize[2][1.2]{% +\linespread{#1}\fontsize{#2}{#2}\selectfont} + +\GetFileInfo{swfigure.dtx} +\title{The \texttt{swfigure} package\\ +Managing large and spread wide figures} +\author{Claudio Beccari\thanks{E-mail: \texttt{claudio dot beccari at gmail dot com}}} +\date{Version \fileversion~---~ Last revised \filedate} + +\begin{document}\errorcontextlines=100 +\maketitle +\columnseprule=0.4pt +\begin{multicols}{2} + \tableofcontents + \end{multicols} + \DocInput{swfigure.dtx} +\end{document} +% +% \fi +%^^A \CheckSum{10}^^A Doesn't this work any more? +% +% \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 +% 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. +% This documentation is accompanied by another file +% |swfigure-examples.pdf| containing examples of this package several +% uses. +% \end{abstract} +% +%^^A \DFimage[SW]{SWfakeimage}{A large fake image}[fig:SWfake] +%^^A It does not work with the page design of this document. +% +%^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%\section{Introduction} +%^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% Sometimes it is necessary to insert in a given document very large +% images; either they are larger than a spread, or they do not exceed +% the width of a spread. In the first case it is necessary to use +% to large sheets of paper folded in the proper way and inserted in the +% printed document as special inserts; or for documents to be read on +% the screen such large sheets have to be attached to the document as +% separate files to be viewed in windows different from that where the +% document is being read. +% +% 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 five 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 +% 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. +%\item +% The landscape display mode 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 +%\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 +% the caption in the right page external margin. +%\item +% The slim screen-wide image is similar to the previous mode, but since +% the figure is slim, it is set at the top of two facing pages, with text +% underneath; the caption is under the right figure half in the right +% 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 +%\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 five +% described display modes; after examining the document daft the +% user might chose another display mode, and it suffices to change +% the optional argument, without changing the whole code. +% +% \bigskip +% +% \noindent\fbox{\textcolor{red}{WARNING}}\quad This package performs +% well with documents typeset in \texttt{twoside} mode, and with a page +% design where the internal margins of both the odd and even pages +% are equal (symmetrical page design). For example, it does not work +% with this document designed to work in \texttt{oneside} mode and +% where the the left page margin is always larger than the right one +% of each page; this page design is functional to the documentation +% of the \TeX\ system software. +% +%^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%\section{Installation} +%^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% +% This package is already installed with any complete and up to date +% \TeX\ system distribution, \TeX\ Live or MiK\TeX. +% +% 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 +% the document main or single document file or, for a general use, in +% the user personal |texmf| tree; it is possible that the user should +% directly create this personal tree; how to do it is described in the +% documentation of the user \TeX\ system distribution. +% +% The same holds true if the user employs a vintage \TeX\ system +% distribution; this package requires the \LaTeX3 modern language +% functionalities, therefore a \LaTeX\ kernel with a date after +% 2019-01-01. Lacking this modern kernel, the package is strongly +% limited, because packages |xparse| and |xfp| are used for its +% internal workings. +% +% +%^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%\section{Usage}\label{sec:Usage} +%^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% This package defines a single user command, |DFimage| to be used +% with the following syntax: +%\begin{ttsyntax} +%\cs{DFimage}\oarg{display mode}\marg{image file name}\oarg{lof entry}\marg{caption}\oarg{label}\% +%\qquad\parg{heigth correction}\aarg{line correction} +%\end{ttsyntax} +% 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), and \texttt{VS} (Vertical Slim image). +%\item[\meta{image fie 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 argument of the +% \cs{label} command; of course, if this argument is not specified, +% the figure number and its page cannot be referenced with \cs{ref}, +% \cs{pageref} and other similar commands. +%\item[\meta{height correction}] +% This normal parenthesis delimited optional argument 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. +%\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 increase or decrease the +% vertical space by any (integer) number of lines. +%\end{description} +% +%^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% \section{Display mode peculiarities} +%^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% Each of the listed display modes has its own pros and cons. +% In the following the phrase “aspect ratio” refers to the “height +% over width” ratio either of the image or of the available space +% where to put the image and possibly its caption. +%\begin{description}[noitemsep] +% +%\item[\texttt{NF}] +% This display mode is convenient when the image +% aspect ratio is close to the text block one. Of course the user +% does not know in advance the vertical space occupied by the caption, +% therefore the optional \meta{height correction} comes handy for +% small adjustments; this display mode is fully and freely floating, +% although its positioning is fixed to~|[p]|. +% +%\item[\texttt{RF}] +% This display mode is convenient when the image +% aspect ratio is close to the reciprocal of the text block one. This +% mode accepts the \meta{height correction} in order to leave space +% to the caption. It is a fully and freely floating object with the +% same pros and cons as the \texttt{NF} display mode. +% +%\item[\texttt{SW}] +% This display mode is convenient when a really large +% image requires two pages to display all its details; its aspect ratio +% should be close to the two page aspect ratio of the total space +% available for the two page spread; depending on the page design this +% total space approximate value probably is close to~0.5. +% The object to be included in the document should start on an even +% page, therefore it moves to the first even page available; this +% implies that the last document page before the spread wide image +% may be blank or may be shorter than the other text pages; the user +% then should help the automatic positioning by choosing very carefully +% where to insert the \cs{DFfigure} command in the source text; it can +% even set it within a paragraph and the command provides a new page +% just after the line that contains the \cs{DFfigure} command; +% therefore if the paragraph is close to the end of an odd page and +% the position of \cs{DFfigure} command is properly positioned within this +% paragraph, the spread wide insertion would not disturb the quality +% of the typeset document. +% +%\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} +% apply also to this mode. +% +%\item[\texttt{VS}] +% This mode is convenient for tall and slim figures with aspect ratio +% not lower than~2; but for obvious reasons, it should not be too +% large, let's say not higher than about~3. As always this depends on +% the page design and the caption size. The limitations of the +% underlying of the |wrapfig| package forbids its usage too close to +% section headings, explicit lists and texts typeset in special modes +% with different measure than normal text. Again it is up to the user +% to chose where to insert the \cs{DFfigure} command. If the aspect +% ratio of the image to include is lower than~2, this message is printed +% in the document where the image should appear (of course with |#2| replaced by the actual image file name): +%\begin{verbatim} +% =========================================== +% Figure #2 is not tall enough. +% Consider using a display mode different +% from VS; may be NF or RF are better suited. +% =========================================== +% Nothing done! +% =========================================== +%\end{verbatim} +%^^A +%\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 +% 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 +% that he was “just” a tester. He was precious and I warmly thank him. +% +%^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%\begin{thebibliography}{9} +%\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}. +%\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}. +%\bibitem{bib:Int3} The \LaTeX3 Project, \emph{The \LaTeX3 interfaces}. Release date 2020-09-24. PDF Document readable with \texttt{texdoc interface3}. +%\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}. +%\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}. +%\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}. +%\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}. +%\bibitem{bib:wrapfig} D. Arseneau, \emph{The \texttt{wrapfig} package}. Version 3.6 released on 2003-01-31. +%\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}. +%\end{thebibliography} +% +% \StopEventually{} +% +%^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% \section{The code} +%^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% The required \TeX\ format and is date, and the identification of this +% package have already ben inserted by the initial commands of this +% documented file. +% +% Here we call the initial required packages and, since the necessary +% software to define some \LaTeX3 (L3) language “functions” are already +% part of the \LaTeX\ kernel, we just use them in order to define a +% robust \LaTeXe/L3 interface to create a testing macro that accepts +% many logical operators that act on items that, besides being boolean +% 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. +% +% The syntax of the new testing macro is the following: +%\begin{ttsyntax} +%\cs{fptest}\marg{test}\marg{true}\marg{false} +%\end{ttsyntax} +% The logical operators that are usable in the \meta{text} phrase +% 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 +% as~|!<|. +% +% The |trace| package is still present in this beta version of the +% package; it will not be present in the next 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, this operation must be done +% \emph{before} loading this package. +%\iffalse +%<*package> +%\fi +% \begin{macrocode} +\RequirePackage{etoolbox} +\RequirePackage{xparse} +\RequirePackage{xfp} + +\ExplSyntaxOn +\AtBeginDocument{% +\ProvideExpandableDocumentCommand\fptest{m m m}{% + \fp_compare:nTF{#1}{#2}{#3}} +} +\ExplSyntaxOff + +\RequirePackage{trace} + +\RequirePackage{graphicx} +\RequirePackage{afterpage} +\RequirePackage{wrapfig} + +% \end{macrocode} +% We define some dimension and some counter registers; to some dimensions +% 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. +% \begin{macrocode} +\newdimen\internalmargin +\internalmargin=\dimexpr\oddsidemargin+1in+1bp\relax +\newdimen\spreadwidth +\spreadwidth=\dimexpr 2\textwidth+2\internalmargin\relax +% +\newdimen\DFwidth +\newdimen\DFheight +\newdimen\DFhalfwidth +\newdimen\DFheight +\newdimen\FigSpace +\newsavebox\DFtotalimage +\newsavebox\DFimageI +\newsavebox\DFimageII +\newsavebox\RFbox +\newdimen\VS@textwidth +\newcount\VS@lines + +% \end{macrocode} +% The following caption-like command recompiles the captions within +% a zero height vertical box and deals with the mandatory and optional +% arguments according to the following syntax: +%\begin{ttsyntax} +%\cs{DFcaption}\oarg{lof entry}\marg{caption}\oarg{label} +%\end{ttsyntax} +% Notice that the ]lof entry defaults to the full caption text if +% a different text is not explicitly entered. +% This command is specific those those display modes that compose +% the caption in vertical mode, therefore the measure is the +% |\textheight|. +% \begin{macrocode} +\NewDocumentCommand\DFcaption{O{#2} m o}{\refstepcounter{figure}% + \vtop to 0pt{\hsize=\textheight\parindent=0pt\leavevmode + Figure \thefigure\quad #2\vss}% + \addcontentsline{lof}{figure}{\protect\numberline{\thefigure}#1} + \IfValueT{#3}{\label{#3}}\relax% +} + +% \end{macrocode} +% The |\cleartoevenpage| command may already exist in the document class. +% We prefer to make an absolute redefinition so as to be sure that it +% performs as we need in this package. We tested with the |memoir| +% class that already has such a command, and no problems were found +% +% \begin{macrocode} +\DeclareRobustCommand\cleartoevenpage{% + \clearpage\ifodd\value{page}\null\clearpage\fi} +% \end{macrocode} +% +% Now we define the “real” user macro necessary to chose the +% \meta{display mode} and the various parameters necessary for the +% desired one. See section~\ref{sec:Usage} on page\pageref{sec:Usage} +% 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 +% 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 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. +% \begin{macrocode} +\NewDocumentEnvironment{DFimage}{O{SW} m O{#4} m o D(){0.8} D<>{0}}{% +\ifstrequal{#1}{SW}% + {% + \SWfigure{#2}[#3]{#4}[#5]% + }% + {\ifstrequal{#1}{NF}% + {% + \NFfigure{#2}[#3]{#4}[#5](#6)% + }% + {\ifstrequal{#1}{RF}% OK + {% + \RFfigure{#2}[#3]{#4}[#5]% + }% + {\ifstrequal{#1}{VS}% + {% + \VSfigure{#2}[#3]{#4}[#5](#6)<#7>% + }% + {\ifstrequal{#1}{HS} + {% + \HSfigure{#2}[#3]{#4}[#5](#6)% + }% + {\PackageWarning{swfigure}% + {% + **************************************\MessageBreak + Option #1\space is not valid \MessageBreak + Nothing done \MessageBreak + Image #2\space was not processed \MessageBreak + **************************************\MessageBreak}% + }% + }% + }% + }% + }% +}% + +% \end{macrocode} +% In the following subsection the five specific display mode macros +% are examined and commented. +%^^A===================================== +% \subsection{The specific \cs{SWfigure} macro for Spread Wide images} +%^^A===================================== +%The specific macro for spread-wide images has the following syntax: +%\begin{ttsyntax} +%\cs{SWfigure}\marg{image file name}\oarg{lof entry}\marg{caption}\oarg{label} +%\end{ttsyntax} +% The various arguments have already been described; as you see the +% \meta{display mode} argument is not there anymore, as well as the +% last two optional arguments of |\DFfigure|. +% +% The working strategy is the following: first the typesetting mode is +% tested and, in case, a filling of the current line is +% performed and, by means of a |\vadjust| \TeX\ native macro, a +% |\newpage| command is executed; in any case a |\cleartoevenpapge| +% is executed so as to be sure to start any action while an even page +% is being processed. Then the initial image to be divided in two +% halves is stored in a box; this box is examined in order +% to find its total width and heigh, so as to be able to compute the +% aspect ratio. All other dimensions are examined to have available +% all the necessary data to display the image halves in the requested +% way. +% +% Notice that the |trim| option to |\includegraphics|, used to +% divide the initial image in two exact halves, (apparently) must +% be used without specifying other options; but, most important, +% it requires real numbers, not macros; therefore we have to make +% use of the usual dirty trick of defining an expanded macro +% |\x| within a group that the macro itself closes upon its +% expansion; in this way the principal part of the |\includegraphics| +% macro contains only keywords and numbers and may be executed +% without errors. +% +% Let $W$ be the total spread width and $w$ be the initial image +% width; let $H$ be the text height and $h$ the initial image height; +% compute the $A_\mathrm{W}$ to be the aspect ratio of the spread +% available space $H/W$. Similarly let $A_\mathrm{fig}$ aspect +% ratio of the initial image; we have to scale the image with a +% scaling factor such that the image keeps its aspect ratio, but +% its scaled height does not exceed the text block height, and +% its scaled width does not exceed the spread width; of course the +% aim is to maintain the scaled image as large as possible therefore +% we have to chose the most suited of the two scaling factors that +% can be computed from the given data and the inequalities +% described above. +% In mathematical terms we have to chose the initial image scaling +% factor $S$ such that: +%\begin{equation} +%S= \left\{ +% \begin{array}{lll} +% w/W &\mathrm{if}& A_\mathrm{fig} \leq A_\mathrm{W}\\ +% h/H &\mathrm{if}& A_\mathrm{fig} > A_\mathrm{W} +% \end{array} +%\right. +%\label{equ:ScalingFactor} +%\end{equation} +% This choice is made by testing the various ratios by means of +% the L3 |\fptest| macro, that computes such ratios and compares them. +% The commented line below shows exactly which lengths are used to +% compute the ratios, and which comparison is executed. Once the +% scaling factors are found the boxes containing the half figures +% are scaled and further on are inserted in floating figure +% environments; we use another dirty trick of matrioska dolls; this +% metaphor describes nested |\makeboxe|s 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. +% \begin{macrocode} +\NewDocumentCommand\SWfigure{m O{#3} m o}{% +\unless\ifvmode + \csuse{@bsphack}% + \vadjust{\vspace{0pt plus1fill}\csuse{@esphack}\newpage}% +\fi +\cleartoevenpage +\setbox\DFtotalimage=\hbox{\includegraphics{#1}}% +\DFwidth=\wd\DFtotalimage \DFhalfwidth=0.5\DFwidth +\DFheight=\ht\DFtotalimage +\FigSpace=\dimexpr\textwidth+\internalmargin\relax +% +\setbox\DFimageI\hbox{\bgroup +\edef\x{\egroup\noexpand\includegraphics*[% +trim = 0 0 \the\DFhalfwidth\space 0]}\x{#1}}% +% +\setbox\DFimageII\hbox{\bgroup +\edef\x{\egroup\noexpand\includegraphics*[% +trim = \the\DFhalfwidth\space 0 0 0]}\x{#1}}% +% +% h/w > H/W +\fptest{\DFheight/\DFhalfwidth > \textheight/\FigSpace}% + {\edef\DFscalefactor{\fpeval{\textheight/\DFheight}}}% + {\edef\DFscalefactor{\fpeval{\FigSpace/\DFhalfwidth}}}% +% +\setbox\DFimageI=\hbox{\scalebox{\DFscalefactor}{\usebox{\DFimageI}}}% +\setbox\DFimageII=\hbox{\scalebox{\DFscalefactor}{\usebox{\DFimageII}}}% +% +\begin{figure}[p]% +\vbox to\textheight{\vss\hsize=\textwidth%\ +\makebox[\hsize][l]{\makebox[\FigSpace][r]{\box\DFimageI}}\vss}% +\end{figure}\clearpage +% +\begin{figure}[p]% +\vbox to\textheight{\vss\hsize=\textwidth +\makebox[\hsize][r]{\makebox[\FigSpace][l]{\box\DFimageII}% +% Rotated caption in the right page +\makebox(0,0)[lb]{\hspace*{1em}\raisebox{0.5\textheight}{% +\rotatebox[origin=tc]{90}{\DFcaption[#2]{#3}[#4]% +% +}}}}\vss}% +\end{figure}\clearpage} + +% \end{macrocode} +%^^A======================================== +%\subsection{The specific \cs{NFfigure} macro for normal full +% page figures} +%^^A======================================== +% This code is without surprises, except that it receives from the +% |DFimage| steering macro five arguments, the last (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 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 +% complex caption. +% \begin{macrocode} +\NewDocumentCommand\NFfigure{m O{#3} m o d()}{% + \begin{figure}[p] + \includegraphics[width=\linewidth,height=#5\textheight, + keepaspectratio]{#1}% + \caption[#2]{#3}% + \IfValueT{#4}{\label{#4}}\relax + \end{figure} +} + +% \end{macrocode} +%^^A======================================== +% \subsection{The specific \cs{RFfigure} macro for rotated figures} +%^^A======================================== +% There are no new comments to make about this almost standard +% 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 +% 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. +% \begin{macrocode} +%\NewDocumentCommand\RFfigure{m o m o}{% +\NewDocumentCommand\RFfigure{m O{#3} m o}{% + \dimen8=\textwidth\dimen10=\textheight + \figure[p]\setbox\RFbox=\hbox{% + \rotatebox[origin=cc]{90}{\parbox[b][\dimen8][c]{\dimen10}% + {\centering\includegraphics[width=\dimen10, height=\dimen8, + keepaspectratio]{#1}% + \caption[#2]{#3}% + \IfValueT{#4}{\label{#4}}\relax% + }}}% + \edef\RFx{\fpeval{\ht\RFbox/\textheight}}% + \edef\RFy{\fpeval{\wd\RFbox/\textwidth}}% + \fptest{\RFx > \RFy}% + {\scalebox{\RFx}{\box\RFbox}}% + {\scalebox{\RFy}{\box\RFbox}}% + \endfigure} + +% \end{macrocode} +%^^A======================================== +% \subsection{The specific \cs{VSfigure} macro for tall and slim figures} +%^^A======================================== +% This is the most troublesome macro, because it needs to depend +% on the |wrapfig| package, in order to set the image with its +% caption on the external side of the text block, with the text flowing +% around it. Package |wrapfig| has several limitations concerning +% the text that flows around the image. Nevertheless with a “normal” +% textual contents of the text block the result may be very good. +% +% 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 +% text should be indented; by playing with both corrections +% good results may be obtained. +% +% Notice that only with this macro a test on the initial image +% aspect ratio is performed; should this image have an aspect ratio +% smaller than~2, the process is aborted and a message is printed +% in the output document that informs the user and recommends to +% use another \meta{display mode} acronym. +% +% \begin{macrocode} +\NewDocumentCommand\VSfigure{m O{#3} m o d() D<>{0}}{% + \setbox\DFtotalimage=\hbox{\includegraphics{#1}} + \DFwidth=\wd\DFtotalimage \DFheight=\ht\DFtotalimage + \edef\VS@aspectratio{\fpeval{\DFheight/\DFwidth}} + \fptest{ \VS@aspectratio < 2 }% + {\begin{center}\ttfamily + ===========================================\\ + Figure #2 is not tall enough.\\ + Consider using a display mode different\\ + from VS; may be NF or RF are better suited.\\ + ===========================================\\ + Nothing done!\\ + =========================================== + \end{center} + }% + {\edef\VS@factor{\fpeval{#5\textheight/\DFheight}}% + \setbox\DFtotalimage= + \hbox{\scalebox{\VS@factor}{\box\DFtotalimage}}% + \edef\VS@width{\fpeval{\VS@factor*\DFwidth}\p@}% + \setbox\DFtotalimage=\vbox{\hsize=\VS@width% + \def\@captype{figure}\box\DFtotalimage + \caption[#2]{#3}% + \IfValueT{#4}{\label{#4}}\relax} + \VS@lines= + \fpeval{round(\ht\DFtotalimage/\baselineskip,0)+#6}% + \begin{wrapfigure}[\VS@lines]{O}[0pt]{\VS@width}% + \box\DFtotalimage + \end{wrapfigure}}% +} + +% \end{macrocode} +% +%^^A===================================== +% \subsection{The specific \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 +% 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. +% +% Since the right half of the figure contains also the caption +% it is necessary to box again the left page box so as to have +% the same hight and depth as the right page one. +% \begin{macrocode} +\NewDocumentCommand\HSfigure{m o m o d()}{% + \unless\ifvmode + \csuse{@bsphack}% + \vadjust{\vspace{0pt plus1fill}\csuse{@esphack}\newpage}% + \fi + \cleartoevenpage + \setbox\DFtotalimage=\hbox{\includegraphics{#1}} + \DFwidth=\wd\DFtotalimage \DFhalfwidth=0.5\DFwidth + \FigSpace=0.5\spreadwidth% W +% + \setbox\DFimageI\hbox{\bgroup + \edef\x{\egroup\noexpand\includegraphics*[% + trim = 0 0 \the\DFhalfwidth\space 0]}\x{#1}}% +% + \setbox\DFimageII\hbox{\bgroup + \edef\x{\egroup\noexpand\includegraphics*[% + trim = \the\DFhalfwidth\space 0 0 0]}\x{#1}}% +% + \edef\DFscalefactor{\fpeval{\FigSpace/\DFhalfwidth}}% +% + \setbox\DFimageI=\hbox{% + \scalebox{\DFscalefactor}{\usebox{\DFimageI}}}% + \setbox\DFimageII=\hbox{% + \scalebox{\DFscalefactor}{\usebox{\DFimageII}}}% + \setbox\DFimageII= + \hbox{\dimen10=\linewidth\dimen8\internalmargin + \vbox{\hsize\DFhalfwidth\parindent\z@ + \box\DFimageII\par + \leavevmode\hspace*{\dimen8}% + \vtop{\hsize\dimen10\parindent\z@ + \textwidth=\hsize + \DFcaption[#2]{#3}[#4]% + }% + }% + }% + \setbox\DFimageI=\vbox to\ht\DFimageII{\box\DFimageI\vss}% +% + \begin{figure}[t] + \makebox[\textwidth][l]{% + \makebox[\DFhalfwidth][l]{\box\DFimageI}}% + \end{figure} + \afterpage{% + \begin{figure}[t] + \makebox[\textwidth][r]{% + \makebox[\DFhalfwidth][r]{\box\DFimageII}}% + \end{figure}% + } +} +% \end{macrocode} +%\begin{center}\setfontsize{15mm} +%\color{red} HAPPY \LaTeX-ING +%\end{center} +%\endinput +%\iffalse +% +%\fi +%\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 +% +%\fi \ No newline at end of file -- cgit v1.2.3