From 7bfb587d1315fa72ce6e4b8c2b64ba06bcc61e30 Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Tue, 10 Nov 2020 22:03:34 +0000 Subject: swfigure (10nov20) git-svn-id: svn://tug.org/texlive/trunk@56906 c570f23f-e606-0410-a88d-b1316a301751 --- .../texmf-dist/source/latex/swfigure/swfigure.dtx | 671 +++++++++++++++------ 1 file changed, 495 insertions(+), 176 deletions(-) (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 index 5da66dfc6f4..671502d36d5 100644 --- a/Master/texmf-dist/source/latex/swfigure/swfigure.dtx +++ b/Master/texmf-dist/source/latex/swfigure/swfigure.dtx @@ -4,7 +4,7 @@ %<*internal> \begingroup \input docstrip.tex -%\keepsilent +\keepsilent \preamble Copyright (C) 2020 Claudio Beccari all rights reserved. @@ -27,7 +27,6 @@ files swfigure.sty and swfigure.pdf \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 @@ -43,22 +42,21 @@ files swfigure.sty and swfigure.pdf \ProvidesFile{swfigure.dtx}% % %<+package>\ProvidesPackage{swfigure}% -%<+readme>File README.txt for package swfigure -%<*package|readme> - [2020-10-18 v.0.9.11 Managing large and spread wide figures] -% +%<*package> + [2020-11-10 v.0.9.14 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} +\usepackage{lmodern,textcomp,multicol,enumitem,mflogo,guit} +\usepackage{swfigure}% this already loads the graphicx package \providecommand*\diff{\mathop{}\!\mathrm{d}} \renewcommand\meta[1]{{\normalfont\textlangle\textit{#1}\textrangle}} -\renewcommand\marg[1]{\texttt{\{\meta{#1}\}}} +\renewcommand\marg[1]{\texttt{\string{\meta{#1}\string}}} \providecommand\Marg{} -\renewcommand\Marg[1]{\texttt{\{#1\}}} +\renewcommand\Marg[1]{\texttt{\string{#1\string}}} \providecommand\oarg{} \renewcommand\oarg[1]{\texttt{[\meta{#1}]}} \providecommand\Oarg{} @@ -74,6 +72,8 @@ files swfigure.sty and swfigure.pdf \providecommand\eTeX{} \newbox\SWsynt \renewcommand\eTeX{\lower0.5ex\hbox{$\varepsilon\!$}\TeX} +\newcommand\Benv[1]{\cs{begin}\Marg{#1}} +\newcommand\Eenv[1]{\cs{end}\Marg{#1}} \newenvironment{medaglione}% {\par\medskip\fboxrule=0.8pt\fboxsep6pt\relax @@ -85,24 +85,27 @@ files swfigure.sty and swfigure.pdf \providecommand\setfontsize{} \DeclareRobustCommand\setfontsize[2][1.2]{% \linespread{#1}\fontsize{#2}{#2}\selectfont} +\providecommand\ped[1]{\ensuremath{_{\mathrm{#1}}}} \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} +\date{Version \fileversion~---~Last revised \filedate} \begin{document}\errorcontextlines=100 \maketitle \columnseprule=0.4pt \begin{multicols}{2} - \tableofcontents - \end{multicols} - \DocInput{swfigure.dtx} + \tableofcontents +\end{multicols} +\DocInput{swfigure.dtx} \end{document} % % \fi -% \CheckSum{10}^^A Doesn't this work any more? +% +% \CheckSum{10} % % \begin{abstract} % This package defines a single command that with different options can @@ -116,6 +119,12 @@ Managing large and spread wide figures} % uses. % \end{abstract} % +%\begin{figure}[t] +%\includegraphics[width=\linewidth]{DFscreenshot} +%\caption{Example of a large fake image that occupies a spread; +% screenshot of a spread view from the companion file +% swfigure-examples.pdf.}\label{fig:DFscreenshot} +%\end{figure} % %^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %\section{Introduction} @@ -127,11 +136,11 @@ Managing large and spread wide figures} % 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. +% 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 +% different settings, can insert such figures in six different display % modes. %\begin{enumerate}[noitemsep] % \item @@ -168,12 +177,19 @@ Managing large and spread wide figures} % 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 +%\item +% A very large image, typically A3 sized, that occupies a full spread +% including the lateral margins; it is a solution to inputting, for +% example, a line drawing of a technical device, that otherwise +% should be attached as a separate document; a very large table +% that does not fit the usual A4 paper and that cannot be reduced +% by means of |longtable| or scaled down to unreadable font sizes. %\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 +% argument. In facts the user might start with one of the six % 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. @@ -181,8 +197,8 @@ Managing large and spread wide figures} % \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 +% as expected 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 @@ -201,35 +217,52 @@ Managing large and spread wide figures} % the |swfigure.zip| file from the Comprehensive \TeX\ Archive Network % (CTAN), and decompress it either in the very folder where there is % the document main or single document file or, for a general use, in -% the user |texmf| personal tree; it is possible that the user should -% directly create this personal tree; how to do it is described in the -% documentation of the user \TeX\ system distribution. +% the user |texmf| personal tree; it might be necessary 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 +% 2019-01-01. Lacking this modern kernel, the package does not work, +% 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: +% This package defines a single user command\slash environment, +% |DFimage|. The command is usable when the image fills up the page +% or the spread, so that it contains no text, except the caption; the +% environment is recommended when the large image is in a page or a +% spread that contains also some text.\\ +% \fbox{\color{red} Warning!} This particular environment +% cannot be nested and cannot contain a |\DFimage| command. +% +% The syntax is the following: %\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}|\meta{width test}| +%\cs{DFimage}\oarg{display mode}\marg{image file name}\% +%\qquad \oarg{lof entry}\marg{caption}\oarg{label}\% +%\qquad\parg{height correction}\aarg{line correction}|\meta{width test}|!\meta{precaption}! +%\vspace{0.5\baselineskip} +%or +%\vspace{0.5\baselineskip} +% \Benv{DFimage}\oarg{display mode}\marg{image file name}\% +%\qquad \oarg{lof entry}\marg{caption}\oarg{label}\% +%\qquad\parg{height correction}\aarg{line correction}|\meta{width test}|!\meta{precaption}! +%\meta{environment textual contents} +%\Eenv{DFimage} %\end{ttsyntax} -% where: +% \noindent where: %\begin{description}[noitemsep] %\item[\meta{display mode}] % is one of the following uppercase acronyms: % \texttt{NF} (Normal Figure), \texttt{RF} (Rotated Figure), % \texttt{SW} (Spread Wide image), \texttt{HS} (Horizontal Spread-wide -% image), and \texttt{VS} (Vertical Slim image). -%\item[\meta{image fie name}] +% image), \texttt{VS} (Vertical Slim image), and \texttt{FS} +% (Full Spread image). +%\item[\meta{image file name}] % is the name of the image graphic file; remember that the \LaTeX based % \TeX\ system typesetting programs accept graphic files in the formats % with extensions \texttt{.pdf}, \texttt{.eps}, \texttt{.jpg}, @@ -246,19 +279,21 @@ Managing large and spread wide figures} % argument; of course, if this argument is not specified, the figure % number and its page cannot be referenced with \cs{ref}, \cs{pageref} % and other similar commands. -%\item[\meta{height correction}] -% is a round parenthesis delimited optional argument; it is a fractional -% number lower than~1 (default 0.8) with which to further scale the -% scaled image height to be included; it is used by some display modes, -% and it is ignored by others. +%\item[\meta{height correction or color}] +% is a round parenthesis delimited optional argument; as a +% \emph{height correction} it is a fractional number lower than~1 +% (default 0.8) with which to further scale the scaled image height +% to be included; it is used by some display modes, and it is ignored +% by others. %\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. -%\item[\meta{width test}] this further vertical bars delimited argument +% the document drafts it is possible to correct the predetermined +% number of lines by increasing or decreasing the vertical space by +% any (integer) number of lines. +%\item[\meta{width test}] this further vertical bars-delimited argument % is used only when dealing with vertical slim images; when they are % scaled down in order to fit in the available space, their width may % become too small to allow a decently typeset caption below the @@ -266,8 +301,14 @@ Managing large and spread wide figures} % fraction of the text block width in order to skip the image insertion % if the image width becomes too small; the default value for this % \meta{width test} fraction is \texttt{0.25}, but the user can specify -% a different value, even zero; with the zero value the width test is +% a different value, even zero; with the zero value this width test is % skipped. +%\item[\meta{precaption}] is an optional color declaratio delimited by +% exclamation points; the default value is ‘empty’; it is used only +% by the \texttt{FS} display mode in order to typeset a caption, for +% example, with a contrasting color over the background image average +% color, and/or with a displacement of the first or only caption line, +% and/or with a different font. %\end{description} % %^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% @@ -285,7 +326,9 @@ Managing large and spread wide figures} % does not know in advance the vertical space occupied by the caption, % therefore the optional \meta{height correction} comes handy for % small adjustments; this display mode is fully and freely floating, -% although its positioning is fixed to~|[p]|, full only-float page. +% although its positioning option is fixed to~|[p]|, an only-float page. +% Therefore don't use it it the image is not really such as to occupy +% most of text block area. % %\item[\texttt{RF}] % This display mode is convenient when the image @@ -294,6 +337,38 @@ Managing large and spread wide figures} % for the caption. It is a fully and freely floating object with the % same pros and cons as the \texttt{NF} display mode. % +%\item[\texttt{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 larger than about~3 or~4. As always this depends +% on the page design and the caption size. The limitations of the +% underlying |wrapfig| package forbid its usage too close to +% explicit lists and texts typeset in special modes with a different +% measure from normal text. Again it is up to the user to chose +% where to insert the |DFfigure| environment or the |\DFimage| command. +% The |wrapfig| package documentation and our experience, show that the +% best position is just before a new paragraph; the environment end +% should be placed after a suitable number of full paragraphs, even +% if not all of them are involved with wrapping. +% +% If the aspect ratio of the image to include is lower than~2, the +% following message is printed in the document where the image +% should appear (of course with |#1| replaced by the actual image +% file name):\\ +%\begin{minipage}{0.7\textwidth} +%\begin{verbatim} +% =========================================== +% Figure #1 is not tall enough. +% Consider using a display mode different +% from VS; may be NF or RF are better suited. +% =========================================== +% Nothing done! +% =========================================== +%\end{verbatim} +%\end{minipage}\\[2ex] +% A similar action and a similar message is output if the \emph{scaled} +% image width becomes too small. +% %\item[\texttt{SW}] % This display mode is convenient when a really large % image requires two pages to display all its details; its aspect ratio @@ -316,31 +391,18 @@ Managing large and spread wide figures} % 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 or~4. As always this depends on -% the page design and the caption size. The limitations of the -% underlying |wrapfig| package forbids its usage too close to -% explicit lists and texts typeset in special modes with a different -% measure than normal text. Again it is up to the user to chose -% where to insert the \cs{DFfigure} command. If the aspect ratio of -% the image to include is lower than~2, this message is printed -% in the document where the image should appear (of course with |#1| -% replaced by the actual image file name):\\ -%\begin{minipage}{0.7\textwidth} -%\begin{verbatim} -% =========================================== -% Figure #1 is not tall enough. -% Consider using a display mode different -% from VS; may be NF or RF are better suited. -% =========================================== -% Nothing done! -% =========================================== -%\end{verbatim} -%\end{minipage}\\[2ex] -% A similar action and a similar message is output if the scaled image -% width becomes too small. +% \item[\texttt{FS}] +% The \texttt{SW} mode occupies a spread without invading the lateral +% margins; it simply occupies only the internal margin. On the opposite, +% the \texttt{FS} Full Spread mode occupies also the lateral margins; +% typically a full spread of two A4 pages, can contain a rotated A3 page, +% without scaling down its contents. With this full occupation of both +% facing pages, there is no room for any caption; therefore the actual +% image, besides occupying an A3 page, should have a minimum white +% margin around, so that a caption can be superimposed to the white +% part if its original bottom margin that, upon rotation, becomes the +% right one. If the original image has no margins, the caption may be +% typeset with contrasting different color from the default black one. % %\end{description} % @@ -358,9 +420,18 @@ Managing large and spread wide figures} % that he was “just” a tester. He was precious and I warmly thank him. % % Thanks also to Benedict Wilde who spotted some errors and suggested -% the use of a specific setting for the PDF viewer. +% the use of specific settings for the PDF viewer. +% +% Thanks also to the unknown person nicknamed “dylan.bacc” on the \GuIT\ +% forum, who induced me to work on the sixth display mode. I knew that +% using the |memoir| class, with suitable settings, and having available +% an advanced printer, it was possible to print documents with pages of +% different formats and page designs; but this was not my aim: I wanted +% something possibly independent from the document class and not +% requiring any particular printer. % %^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%\newpage %\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}. @@ -375,9 +446,16 @@ Managing large and spread wide figures} % % \StopEventually{} % +%\clearpage +% %^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % \section{The code} %^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% +% +%\iffalse +%<*package> +%\fi % 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. @@ -385,12 +463,14 @@ Managing large and spread wide figures} % 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 +% robust \LaTeXe/L3 interface to create some testing macros that accept +% many logical operators that act on items that, besides 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. +% system distribution. We neede also some commands to compare strings +% or to check if a given string was included into an L3 sequence +% (list) of strings. % % The syntax of the new testing macro is the following: %\begin{ttsyntax} @@ -402,26 +482,51 @@ Managing large and spread wide figures} % 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 comparisons of strings with the following syntax +%\begin{ttsyntax} +%\cs{CompStrings}\marg{string\ped{1}}\marg{string\ped{2}} +%\end{ttsyntax} +%Produces a boolean result that may be used as a \meta{test} argument +% to |\fptest| +% The |\SetList| macro defines a named L3 sequence variable containing +% the reference list of valid display modes, while the |\TestList| is +% an L3 function that tests if a given string is listed in a named +% sequence list. Their syntax is the following: +%\begin{ttsyntax} +%\cs{SetList}\marg{list name}\marg{comma separated string list} +% \cs{TestList}\meta{string}\marg{list name}\marg{true}\marg{false} +%\end{ttsyntax} +% The fields \meta{true} and \meta{false}, as usual, are the action +% to be executed if the test is true or false; the test is true if +% \meta{string} is listed into the \meta{named list}. % % The |trace| package is still present in this beta version of the -% package; it will not be present in the next stable versions. +% package; it will not be present any more in the future stable versions. % Packages |graphicx|, |afterpage|, and |wrapfig| are functional % for this package. In order to avoid “Option Clash” messages, such % packages are loaded without any option; should the user load some -% or all of them with options, this operation must be done -% \emph{before} loading this package. -%\iffalse -%<*package> -%\fi +% or all of them with options, the user should load them +% \emph{before} loading this package. This particular documentation +% does not require the |graphicx| package, because it is already +% loaded by |swfigure|. % \begin{macrocode} \RequirePackage{etoolbox} \RequirePackage{xfp} \ExplSyntaxOn -\AtBeginDocument{% -\ProvideExpandableDocumentCommand\fptest{m m m}{% - \fp_compare:nTF{#1}{#2}{#3}} -} +\ProvideExpandableDocumentCommand\CompStrings{m m}{% + \str_if_eq_p:nn{#1}{#2}} + + \ProvideExpandableDocumentCommand\fptest{m m m}{% + \fp_compare:nTF{#1}{#2}{#3}} + + \ProvideExpandableDocumentCommand\SetList{m m}{% + \seq_clear_new:N #1 + \seq_set_from_clist:Nn \DisplayModeList {#2}} + + \ProvideExpandableDocumentCommand\TestList{m m m m}{% + \seq_if_in:NnTF #1 {#2}{#3}{#4}} + \ExplSyntaxOff \RequirePackage{trace} @@ -445,15 +550,20 @@ Managing large and spread wide figures} % % \begin{macrocode} \newdimen\internalmargin -\internalmargin=\dimexpr\oddsidemargin+1in+1bp\relax + \internalmargin=\dimexpr\oddsidemargin+1in+1bp\relax +\newdimen\externalmargin + \externalmargin=\dimexpr\evensidemargin+1in \newdimen\spreadwidth -\spreadwidth=\dimexpr 2\textwidth+2\internalmargin\relax + \spreadwidth=\dimexpr 2\textwidth+2\internalmargin\relax % \newdimen\DFwidth \newdimen\DFheight \newdimen\DFhalfwidth \newdimen\DFheight +\newdimen\DFhalfheight \newdimen\FigSpace +\def\SWcaptionShift{1em}% +\def\FScaptionShift{2em}% \newsavebox\DFtotalimage \newsavebox\DFimageI \newsavebox\DFimageII @@ -463,16 +573,16 @@ Managing large and spread wide figures} \newif\if@SWtmode % \end{macrocode} -% The following caption-like command recompiles the captions within -% a zero height vertical box and deals with the mandatory and optional +% The following caption-like commands recompile the captions within +% a zero height vertical box and deal with the mandatory and optional % arguments according to the following syntax: %\begin{ttsyntax} %\cs{DFcaption}\oarg{lof entry}\marg{caption}\oarg{label} %\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 +% Notice that the \meta{lof entry} defaults to the full caption text if +% a different text is not explicitly entered. +% This commands are specific to those display modes that compose +% the caption in vertical mode, therefore the caption measure is the % |\textheight|. % \begin{macrocode} \NewDocumentCommand\DFcaption{O{#2} m o}{\refstepcounter{figure}% @@ -481,35 +591,41 @@ Managing large and spread wide figures} \addcontentsline{lof}{figure}{\protect\numberline{\thefigure}#1} \IfValueT{#3}{\label{#3}}\relax% } +\NewDocumentCommand\DFcaptionP{O{#2} m o D!!{black}}% + {\refstepcounter{figure}% + \vbox to 0pt{\vss\hsize=\textheight\parindent=0pt\leavevmode + #4\relax Figure \thefigure\quad #2}% + \addcontentsline{lof}{figure}{\protect\numberline{\thefigure}#1} + \IfValueT{#3}{\label{#3}}\relax% +} + % \end{macrocode} % The |\cleartoeven| command may already exist in the document class. % We prefer to make an absolute redefinition so as to be sure that it % performs as we need in this package. In any case this new definition % may be used in such a way that the |\DFimage| user command may be used -% also while typesetting in text mode, resuming text mode after complete -% expansion. This is useful, especially for spread wide display modes, -% to chose the most suitable place in the suorce file to place the -% |\DFimace| command with its arguments; only with the |SW| mode it -% is necessary to avoid any space after the last macro argument and the -% text that follows it. +% also while typesetting in text (horizontal) mode, resuming such mode +% after complete expansion. This is useful, especially for spread wide +% display modes, to chose the most suitable place in the source file to +% place the |\DFimage| command with its arguments. % % \begin{macrocode} + \newcommand\set@tmode@newpage{% \ifvmode \@SWtmodefalse \else - \@SWtmodetrue - \@bsphack\vadjust{\vspace{0pt plus1fill}\@esphack\newpage}% + \unskip\@SWtmodetrue\linebreak + \vadjust{\vspace{0pt plus1fill}\newpage}% \fi} \newcommand\reset@tmode{\if@SWtmode\expandafter\noindent\ignorespaces\fi} -\NewDocumentCommand\cleartoeven{ o }{% - \IfValueTF{#1}% - {\set@tmode@newpage - \ifodd\value{page}\afterpage{#1}\else#1\fi}% - {\ifodd\value{page}\null\clearpage\fi}} +\newcommand\cleartoeven[1]{% + \set@tmode@newpage\clearpage + \ifodd\c@page\afterpage{#1}\else#1\fi% + } % \end{macrocode} % Now we define the “real” user macro necessary to chose the @@ -524,51 +640,43 @@ Managing large and spread wide figures} % 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. +% 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} D||{0.25}}{% -\ifstrequal{#1}{SW}% - {% - \SWfigure{#2}[#3]{#4}[#5]% +\NewDocumentEnvironment{DFimage}% + {O{SW} m O{#4} m o D(){0.8} D<>{0} D||{0.25} D!!{}}% +{% + \SetList{\DisplayModeList}{SW,HS,VS,FS,NF,RF}% + \TestList{\DisplayModeList}{#1}% + {\csuse{#1figure}{#2}[#3]{#4}[#5](#6)<#7>|#8|!#9!% + \fptest{\CompStrings{\@currenv}{DFimage}}{}{\reset@tmode}% }% - {\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>|#8|% - }% - {\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}% - }% - }% - }% - }% + {% + \DFwarning[#1]{#2}[#3]{#4} }% }% +{% + \aftergroup\reset@tmode +}% + +\NewDocumentCommand\DFwarning{ o m o m o d() d<> d|| d!!}% +{\PackageWarning{swfigure}% + {********************************************\MessageBreak + Option #1\space is not valid. Nothing done \MessageBreak + \MessageBreak + Image #2 was not processed \MessageBreak + *******************************************\MessageBreak + }% +} + % \end{macrocode} -% In the following subsections the five specific display mode macros +% In the following subsections the six specific display mode macros % are examined and commented. %^^A===================================== % \subsection{The \cs{SWfigure} macro for Spread Wide images} @@ -576,6 +684,7 @@ Managing large and spread wide figures} %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} +%\qquad\parg{height correction}\aarg{lines}|\meta{width thest}|!precaption! %\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 @@ -583,7 +692,9 @@ Managing large and spread wide figures} % \meta{caption} text, the third argument of this macro, is used also % to initialise the \meta{lof entry}, so that if the user doe not % specify such short caption entry, the default is identica to the -% full caption. +% full caption. Notice the the last arguments are not actually used; +% they are needed in the definition due to the way |DFimage| transfers +% its arguments to the called macros. % % The working strategy is the following: the initial image to be divided % in two halves is stored in a box; this box is examined in order @@ -592,11 +703,11 @@ Managing large and spread wide figures} % 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, maybe should +% Notice that the |trim| option to |\includegraphics|, that is being +% used to divide the initial image in two exact halves, maybe should % be used without specifying other options; but, most important, % it requires actual numbers, not macros; therefore we have to make -% use of the usual dirty trick of defining an expanded macro +% 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 optional argument of the |\includegraphics| % macro contains only keywords and numbers and may be executed @@ -638,9 +749,10 @@ Managing large and spread wide figures} % Eventually the caption is set in the right margin of the right % spread page, rotated $90^\circ$ counterclockwise. % The |cleartoeven| guaranties that the first float is set into an even -% numbered page. A final |\clearpage| ensures that both floats are output. +% numbered page. A final |\clearpage| ensures that both floats are +% output. % \begin{macrocode} -\NewDocumentCommand\SWfigure{m O{#3} m o}{% +\NewDocumentCommand\SWfigure{m o m o d() d<> d|| d!!}{% \setbox\DFtotalimage=\hbox{\includegraphics{#1}}% \DFwidth=\wd\DFtotalimage \DFhalfwidth=0.5\DFwidth \DFheight=\ht\DFtotalimage @@ -662,22 +774,22 @@ trim = \the\DFhalfwidth\space 0 0 0]}\x{#1}}% \setbox\DFimageI=\hbox{\scalebox{\DFscalefactor}{\usebox{\DFimageI}}}% \setbox\DFimageII=\hbox{\scalebox{\DFscalefactor}{\usebox{\DFimageII}}}% % -\cleartoeven[% +\cleartoeven{% \begin{figure}[p]% - \vbox to\textheight{\vss\hsize=\textwidth%\ + \vbox to\textheight{\vss\hsize=\textwidth% \makebox[\hsize][l]{\makebox[\FigSpace][r]{\box\DFimageI}}\vss}% - \end{figure}\clearpage + \end{figure}\newpage % \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}{% + \makebox(0,0)[lb]{\hspace*{\SWcaptionShift}\raisebox{0.5\textheight}{% \rotatebox[origin=tc]{90}{\DFcaption[#2]{#3}[#4]% % }}}}\vss}% \end{figure}% -]\clearpage\reset@tmode} +}\clearpage\reset@tmode} % \end{macrocode} %^^A======================================== @@ -685,7 +797,8 @@ trim = \the\DFhalfwidth\space 0 0 0]}\x{#1}}% % page figures} %^^A======================================== % This code is without surprises, except that it receives from the -% |DFimage| steering macro five arguments, the last (optional) one +% |DFimage| steering macro five usable arguments (plus three more +% ones that are not actually used); the fifth (optional) one % being delimited by round parentheses; by default, it contains the % value 0.8, but the user can pass to the steering macro a different % value in order to reduce the actual image size so as to leave @@ -693,9 +806,9 @@ trim = \the\DFhalfwidth\space 0 0 0]}\x{#1}}% % not know in advance how many lines would occupy a structured % complex caption. % \begin{macrocode} -\NewDocumentCommand\NFfigure{m O{#3} m o d()}{% +\NewDocumentCommand\NFfigure{m o m o d() d<> d|| d!!}{% \begin{figure}[p] - \includegraphics[width=\linewidth,height=#5\textheight, + \includegraphics[width=\linewidth, height=#5\textheight, keepaspectratio]{#1}% \caption[#2]{#3}% \IfValueT{#4}{\label{#4}}\relax @@ -714,10 +827,10 @@ trim = \the\DFhalfwidth\space 0 0 0]}\x{#1}}% % 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. +% text block. Of course the macro signature includes also +% the descriptors of unused arguments. % \begin{macrocode} -%\NewDocumentCommand\RFfigure{m o m o}{% -\NewDocumentCommand\RFfigure{m O{#3} m o}{% +\NewDocumentCommand\RFfigure{m o m o d() d<> d|| d!!}{% \dimen8=\textwidth\dimen10=\textheight \figure[p]\setbox\RFbox=\hbox{% \rotatebox[origin=cc]{90}{\parbox[b][\dimen8][c]{\dimen10}% @@ -744,6 +857,17 @@ trim = \the\DFhalfwidth\space 0 0 0]}\x{#1}}% % 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 is recommended to attentively read the |wrapfig| +% documentation because it has several limitations. here we suggest +% the user to open the environment just before a paragraph and +% close it after several paragraphs; remember that since the opening +% and the closing statements are far away from one another, it is +% possible to forget this situation and insert another such environment +% within the former one ,or a |\DFimage| command, and this will +% produce undesirable effects; never ever nest two |Dfimage| +% environments and never ever insert a |\DFimage| command within +% an environment. +% % 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 @@ -755,12 +879,12 @@ trim = \the\DFhalfwidth\space 0 0 0]}\x{#1}}% % 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. +% use another \meta{display mode} code. % % Furthermore, should the image be very slim and tall, the % \meta{height correction} may conveniently reduce its height, % but, in order to avoid changing its aspect ratio, it reduces -% also its width; eventually the withs is reduced to the point that +% also its width; eventually the width is reduced to the point that % beneath the image there would not be enough space for a decently % typeset caption. A further optional delimited argument is available: % its delimiting tokens are two vertical bars, \verb+| |+, and its @@ -773,7 +897,7 @@ trim = \the\DFhalfwidth\space 0 0 0]}\x{#1}}% % % % \begin{macrocode} -\NewDocumentCommand\VSfigure{m O{#3} m o d() d<> d||}{% +\NewDocumentCommand\VSfigure{m o m o d() d<> d|| d!!}{% \setbox\DFtotalimage=\hbox{\includegraphics{#1}} \DFwidth=\wd\DFtotalimage \DFheight=\ht\DFtotalimage \edef\VS@aspectratio{\fpeval{\DFheight/\DFwidth}} @@ -810,7 +934,7 @@ trim = \the\DFhalfwidth\space 0 0 0]}\x{#1}}% \IfValueT{#4}{\label{#4}}\relax} \VS@lines= \fpeval{round(\ht\DFtotalimage/\baselineskip,0)+#6}% - \begin{wrapfigure}[\VS@lines]{O}[0pt]{\VS@width}% + \begin{wrapfigure}[\VS@lines]{o}[0pt]{\VS@width}% \box\DFtotalimage \end{wrapfigure}% }% @@ -836,9 +960,8 @@ trim = \the\DFhalfwidth\space 0 0 0]}\x{#1}}% % 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()}{% - \cleartoeven - \setbox\DFtotalimage=\hbox{\includegraphics{#1}} +\NewDocumentCommand\HSfigure{m o m o d() d<> d|| d!!}{% + \setbox\DFtotalimage=\hbox{\includegraphics{#1}}% \DFwidth=\wd\DFtotalimage \DFhalfwidth=0.5\DFwidth \FigSpace=0.5\spreadwidth% % @@ -848,7 +971,7 @@ trim = \the\DFhalfwidth\space 0 0 0]}\x{#1}}% % \setbox\DFimageII\hbox{\bgroup \edef\x{\egroup\noexpand\includegraphics*[% - trim = \the\DFhalfwidth\space 0 0 0]}\x{#1}}% + trim = \the\DFhalfwidth\space 0 0 0]}\x{#1}}% % \edef\DFscalefactor{\fpeval{\FigSpace/\DFhalfwidth}}% % @@ -864,30 +987,224 @@ trim = \the\DFhalfwidth\space 0 0 0]}\x{#1}}% \vtop{\hsize\dimen10\parindent\z@ \textwidth=\hsize \DFcaption[#2]{#3}[#4]% - }% + }\vspace*{2\baselineskip}% }% }% \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}% - } + \cleartoeven{% + \hb@xt@\textwidth{% + \makebox[\DFhalfwidth][l]{\box\DFimageI}\hss}% +% + \afterpage{\hb@xt@\textwidth{% + \hss\makebox[\DFhalfwidth][r]{\box\DFimageII}}% + }% + }% } % \end{macrocode} -%\begin{center}\setfontsize{15mm} -%\color{red} HAPPY \LaTeX-ING -%\end{center} +%^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%\subsection{The \cs{FSfigure}~macro for Full Spread figures} +%^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% Although using certain classes, such as |memoir|, it is possible to +% typeset documents on pages of different sizes and to print them on +% advanced printers that use different sized papers, this package aims +% to be independent form any class and any printer; it is limited to +% the ordinary default paper size A4, as it is usual in Europe, but +% letter paper is also valid); ideally it would typeset an A3 sized +% image on a full spread, i.e. by using also the space of all the +% margins. +% +% Actually with American paper sizes there is not a series of sizes +% that behaves as the ISO A series, but this macro tries to adjust the +% large image to the available full spread; this means an image as +% large as two standard pages. +% +% If the available image is taller than large, with an aspect ratio +% around~$\sqrt2$, it turns the image 90° counterclockwise; cuts it in +% two identically sized halves, and sets them on two facing pages joining +% them at the spine but covering the greatest part of both pages, so +% as to avoid exceeding either the paper height or twice the paper width. +% If the image has an aspect ratio close to $\sqrt{1/2}$, it does the +% same, except rotating the image. +% +% In any case the user creates a separate PDF file to be imported into +% the document that is supposed to contain it; it is better if this PDF +% is of vectorial type, i.e. any drawing and all fonts should should be +% vectorial; this PDF might contain photos or similar images of +% rasterised type, but the pixel density should be suitably high in +% order to preserve the image quality. +% +% The user has two choices: $(a)$ either the image has its own margins, +% or $(b)$ the image is cropped and has no white margins. +% +% Normally this display mode does not leave space for a caption; +% therefore if a caption is needed, it is overprinted on the image; +% in case $(a)$ there are no problems because the caption goes over +% the white right margin (rotated 90° counterclockwise); while in +% case $(b)$ the caption is over printed un the right side of the +% image; depending on the image “background” a different color +% might be more suited compared to black (the default color). +% The last macro argument takes care of inserting before the caption +% any declaration that may involve color, displacement, font encoding +% (seldom necessary), family, series, shape and size; +% +% With all the above constraints the syntax of this \cs{FSimage} +% macro is the following; it uses one of the main macro delimited +% optional arguments in a different way: +%\begin{ttsyntax}\setfontsize{9.25}% +%\cs{FSimage}\marg{image file name}\oarg{lof entry}\marg{caption text}\oarg{label string} +%\qquad\parg{height correction}\aarg{line correction}|\meta{width text|!\meta{precaption}! +%\end{ttsyntax} +% The above is the full definition, but the fifth, sixth and seventh +% arguments are not used; they are necessary for the special +% mechanism of argument transfer from the environment or command +% opening statement arguments to this actual macro. +% +% Moreover, since the included image overlaps the top and bottom +% margins, if these contain the header and footer such elements +% would show if the image is not opaque enough; in any case the +% footer would show because it overlaps the image. Since most +% images are not opaque at all it is better to locally use the +% \texttt{empty} page style, but without using the |\thispagestyle| +% command, because it hold for just one page, while the spread +% occupies two pages. The macro provides this setting but it has +% to create a group in case the |\DFimage| command is used, while +% it is not necessary when using the |DFimage| environment, +% therefore the current environment is tested and the opening +% |\bgroup| and closing |\egroup| commands are used onlY if the +% code is used without the environment. +% +% Therefore the code steps are the following: +%\begin{enumerate}[noitemsep] +%\item +% The initial figure is loaded into a box from which the necessary +% measures are taken; in particular the its width and its height in +% order to check the aspect ratio, or better, which dimension is greater +% than the other. If the height is smaller than the width the image is +% sort of panoramic and we proceed splitting the total image box into +% two equal halves, with a vertical cut in the middle. +%\item +% Otherwise the image is as a portrait, and we split the total image +% block into two halves with an horizontal cut in the middle; such two +% boxes need a rotation of 90° anticlockwise due to the horizontal cut of +% an original higher than wide image. With this operation we simulate a +% rotation of the original image, because it is not allowed to +% simultaneously rotate and trim the original image; the trimming +% action apparently cannot be executed together with any other one +% among the many other that the |\includegraphics| command can +% do\footnote{Actually it can, provided that the trim option with +% its arguments is specified before any other option.}. +% Of course, with this rotation of the half pictures we have to +% redefine the height and width to use for scaling. +%\item +% The |\fptest| is used to compare the aspect ratios of any of the two +% equal halves with the aspect ratio of the paper. If the former +% aspect ratio is higher than the latter, the scaling factor is +% based on the heights, otherwise on the widths, so as to resize +% both half picture boxes to fit within the page. +%\item +% The |\cleartoeven| command allows to use the main macro even within +% a paragraph; in any case it possibly inserts a blanc page and restarts +% working on an even page. First is sets the left half picture box; +% that complicated series of vertical and horizontal boxes of different +% specified dimensions contains displacements and the material to output; +% That complicated alternating set is to guarantee that no overfull +% vertical or horizontal boxes are created, in spite of the fact that +% an object larger than the text block is being output; at the same +% time the box must be flush right in order to reach the spine. +%\item +% The right half is even more complicated to build, because there +% is also the caption to set on the right of the page, overwriting +% the right part of the image, but the idea is always to close +% correctly every box putting the right spacing commands at the +% beginning or at the end of each box. +%\item +% Eventually a |\clearpage| flushes out everything that is still in +% the figure stack and possibly restores the vertical or horizontal +% typesetting mode depending on the status that was in force when +% the |\DFimage| command or the |DFimage| environment started its +% expansion. +% Due to the size of the images that completely fill up all the +% margins, probably the best way to output such huge images is at +% the end of a chapter, or at the end of the whole document. +%\end{enumerate} +% \begin{macrocode} +\NewDocumentCommand\FSfigure{m o m o d() d<> d|| d!!}{% + \fptest{\CompStrings{\@currenv}{DFimage}}{}{\bgroup}% + \pagestyle{empty}% + \setbox\DFtotalimage=\hbox{\includegraphics{#1}}% + \DFwidth=\wd\DFtotalimage \DFheight=\ht\DFtotalimage + \ifdim \DFheight < \DFwidth + \DFhalfwidth=0.5\DFwidth + \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}}% + \DFwidth=\DFhalfwidth \DFheight=\ht\DFtotalimage + \else + \DFhalfheight=0.5\DFheight + \setbox\DFimageII\hbox{\bgroup + \edef\x{\egroup\noexpand\includegraphics*[% + trim = 0 0 0 \the\DFhalfheight\space]}\x{#1}}% bottom half + \setbox\DFimageI\hbox{\bgroup + \edef\x{\egroup\noexpand\includegraphics*[% + trim = 0 \the\DFhalfheight\space 0 0]}\x{#1}}% tophalf + \setbox\DFimageI=\hbox{\rotatebox[origin=cc]{90}{\box\DFimageI}} + \setbox\DFimageII=\hbox{\rotatebox[origin=cc]{90}{\box\DFimageII}} + \DFwidth=\DFhalfheight \DFheight=\wd\DFtotalimage + \fi +\fptest{\DFheight/\DFwidth > \paperheight/\paperwidth}% + {\edef\DFscalefactor{\fpeval{\paperheight/\DFheight}}}% + {\edef\DFscalefactor{\fpeval{\paperwidth/\DFwidth}}}% + \setbox\DFimageI=\hbox{\scalebox{\DFscalefactor}{\usebox{\DFimageI}}}% + \setbox\DFimageII=\hbox{\scalebox{\DFscalefactor}{\usebox{\DFimageII}}}% +\cleartoeven{% + \begin{figure}[p]% + \vbox to\textheight{\vss\hsize=\textwidth% vbox 1 + \hbox to\hsize{\hspace*{-\externalmargin}% hbox 1 + \vbox to\paperheight{\vss% vbox 2 + \hbox to\paperwidth{\hss\box\DFimageI}% hbox 2 end hbox 2 + \vss}% end vbox 2 + \hss}% end hbox 1 + \vss}% end vbox 1 + \end{figure}\newpage +% + \begin{figure}[p]% + \vbox to\textheight{\vss\hsize=\textwidth% vbox 1 + \hbox to\hsize{\hspace*{-\internalmargin}% hbox 1 + \vbox to\paperheight{\vss% vbox 2 + \hbox to\paperwidth{% hbox 2 + \box\DFimageII\makebox(0,0)[lb]{% mbox 3 + \hspace*{-\FScaptionShift}% + \raisebox{0.5\textheight}{% raisebox + \rotatebox[origin=bc]{90}{% rotatebox + \DFcaptionP[#2]{#3}[#4]!#8!% + }% end rotatebox + }% end raisebox + }% end mbox 3 + }% end hbox 2 + \vss}% end vbox 2 + \hss}% end hbox 1 + \vss}% end vbox 1 + \end{figure}% +}\clearpage +\fptest{\CompStrings{\@currenv}{DFimage}}{}{\egroup}% +\reset@tmode} +% \end{macrocode} +%\vspace*{2\baselineskip} +%\noindent\makebox[\textwidth]{\setfontsize{10mm} +%\color{red} HAPPY \LaTeX-ing} %\endinput %\iffalse % %\fi +% +% \Finale +% +%\endinput +% %\iffalse %<*readme> %\fi @@ -913,4 +1230,6 @@ deriving from the use of this software; you use it at your own risk. % \end{macrocode} %\iffalse % -%\fi \ No newline at end of file +%\fi +% +% \ No newline at end of file -- cgit v1.2.3