diff options
author | Karl Berry <karl@freefriends.org> | 2020-12-23 22:13:25 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2020-12-23 22:13:25 +0000 |
commit | e7d80cd91220015119cc3d6ff3f3594bdb7b3753 (patch) | |
tree | ae1cb1800e854a328c8df17f276437ddd6994fa1 /Master/texmf-dist | |
parent | 0c74445512fcee63b6eac2575a08f36b47178e19 (diff) |
swfigure (23dec20)
git-svn-id: svn://tug.org/texlive/trunk@57211 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist')
12 files changed, 742 insertions, 250 deletions
diff --git a/Master/texmf-dist/doc/latex/swfigure/DFscreenshotA3.png b/Master/texmf-dist/doc/latex/swfigure/DFscreenshotA3.png Binary files differdeleted file mode 100644 index 93055532638..00000000000 --- a/Master/texmf-dist/doc/latex/swfigure/DFscreenshotA3.png +++ /dev/null diff --git a/Master/texmf-dist/doc/latex/swfigure/FSFakeA3.pdf b/Master/texmf-dist/doc/latex/swfigure/FSFakeA3.pdf Binary files differnew file mode 100644 index 00000000000..f8c6924f162 --- /dev/null +++ b/Master/texmf-dist/doc/latex/swfigure/FSFakeA3.pdf diff --git a/Master/texmf-dist/doc/latex/swfigure/FSfakeA3margins.pdf b/Master/texmf-dist/doc/latex/swfigure/FSFakeA3horiz.pdf Binary files differindex 7bfa9bf4487..844fad72785 100644 --- a/Master/texmf-dist/doc/latex/swfigure/FSfakeA3margins.pdf +++ b/Master/texmf-dist/doc/latex/swfigure/FSFakeA3horiz.pdf diff --git a/Master/texmf-dist/doc/latex/swfigure/FSFakeA3margins.pdf b/Master/texmf-dist/doc/latex/swfigure/FSFakeA3margins.pdf Binary files differnew file mode 100644 index 00000000000..5dd064a06b5 --- /dev/null +++ b/Master/texmf-dist/doc/latex/swfigure/FSFakeA3margins.pdf diff --git a/Master/texmf-dist/doc/latex/swfigure/FSfakeA3.pdf b/Master/texmf-dist/doc/latex/swfigure/FSfakeA3.pdf Binary files differdeleted file mode 100644 index b83e89a846f..00000000000 --- a/Master/texmf-dist/doc/latex/swfigure/FSfakeA3.pdf +++ /dev/null diff --git a/Master/texmf-dist/doc/latex/swfigure/README.txt b/Master/texmf-dist/doc/latex/swfigure/README.txt index 4d89e39e9d8..921fe427eb3 100644 --- a/Master/texmf-dist/doc/latex/swfigure/README.txt +++ b/Master/texmf-dist/doc/latex/swfigure/README.txt @@ -6,25 +6,24 @@ %% File README.txt for package swfigure - [2020-11-10 v.0.9.14 Managing large and spread wide figures] + [2020-12-23 v.0.9.18 Managing large and spread wide figures] This bundle contains the swfigure.dtx, swfigure-examples.tex, -and README.txt files plus some fake figures with extension .jpg -or .pdf and a couple of scrrenshots with extension .pdf. +and README.txt files plus eight fake figures with extension .jpg +or .pdf and a screenshot with extension .pdf. This file README.txt contains the licence, the status, and some general information. Save the README.txt and swfigure.dtx file -in a .../source/latex/swfigure/ folder either in the main TeX +in a .../source/latex/swfigure folder either in the main TeX system tree or in your personal tree. - Save the swfigure-examples.tex, the derived swfigures-examples.pdf, -and the various .jpg and .pdf files in folder .../doc/latex/swfigure/. +and the various .jpg and .pdf files in folder .../doc/latex/swfigure. Process the self extracting swfigure.dtx file with pdfLaTeX; repeat at least twice in order to get all references correct; 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 to the bin +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 to the bin all files except the .dtx and the .txt ones. The author disclaims any liability from every possible inconvenience @@ -38,9 +37,10 @@ deriving from the use of this software; you use it at your own risk. %% This work is "maintained" %% %% This work consists of files swfigure.dtx, swfigure-examples.tex -%% and README.txt, and the derived files swfigure.sty and swfigure.pdf. +%% and README.txt, and the derived files swfigure.sty, swfigure.pdf +%% subfigure-exaples.pdf. %% %% The other .jpg and .pdf files contained in this bundle are just -%% fake figures and screenshots that anybody can replicate, copy +%% fake figures and a screenshot that anybody can replicate, copy %% or modify at will. %% diff --git a/Master/texmf-dist/doc/latex/swfigure/THFake.pdf b/Master/texmf-dist/doc/latex/swfigure/THFake.pdf Binary files differnew file mode 100644 index 00000000000..949abb22997 --- /dev/null +++ b/Master/texmf-dist/doc/latex/swfigure/THFake.pdf diff --git a/Master/texmf-dist/doc/latex/swfigure/swfigure-examples.pdf b/Master/texmf-dist/doc/latex/swfigure/swfigure-examples.pdf Binary files differindex 35a9f91f0d3..be47bf44e93 100644 --- a/Master/texmf-dist/doc/latex/swfigure/swfigure-examples.pdf +++ b/Master/texmf-dist/doc/latex/swfigure/swfigure-examples.pdf diff --git a/Master/texmf-dist/doc/latex/swfigure/swfigure-examples.tex b/Master/texmf-dist/doc/latex/swfigure/swfigure-examples.tex index 66cba4ca73f..ebc8d3fd7fd 100644 --- a/Master/texmf-dist/doc/latex/swfigure/swfigure-examples.tex +++ b/Master/texmf-dist/doc/latex/swfigure/swfigure-examples.tex @@ -1,7 +1,7 @@ % !TEX encoding = UTF-8 Unicode % !TEX TS-program = pdflatex \documentclass[a4paper]{book}\errorcontextlines=100 -\usepackage[utf8]{inputenc} +\usepackage[utf8]{inputenc}\usepackage[T1]{fontenc} \usepackage{lmodern,textcomp,multicol,enumitem,mflogo,xcolor,fancyvrb} \usepackage{swfigure} \usepackage{hyperref}\hypersetup{pdfpagelayout=TwoColumnRight} @@ -33,6 +33,12 @@ \renewcommand\eTeX{\lower0.5ex\hbox{$\varepsilon\!$}\TeX} \providecommand\file{} \renewcommand\file[1]{{\normalfont\sffamily\slshape#1}} +\providecommand\amb{} + \renewcommand\amb[1]{\texttt{#1}} +\providecommand\Bambiente{} + \renewcommand\Bambiente[1]{\cs{begin}\Marg{#1}} +\providecommand\Eambiente{} + \renewcommand\Eambiente[1]{\cs{end}\Marg{#1}} \newbox\SWsynt @@ -89,19 +95,17 @@ This package works pretty well with two side printed documents with a symmetrica %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% Please, before going on reading, set your PDF viewer so that it displays two pages at time, and with the even numbered pages on the left. Only with these settings you can see the spread wide images. Some viewers display the facing pages with a little gap between them; if you don't have available a viewer that avoids this gap, simply imagine that the gap did not exist. -As far as we can say, we know that Preview.app on Macs does not use any gap. Okular on Linux does not use any gap, but traces a thin black line were the facing pages join. Adobe Reader for Windows and other platforms, has several settings for displaying two pages at a time, but only one eliminates the gap while displaying the even numbered page on the left. +As far as we can say, we know that Preview.app on Macs does not use any gap. Okular on Linux does not use any gap, but traces a thin black line were the facing pages join. Adobe Reader for Windows and other platforms, have several settings for displaying two pages at a time, but only one eliminates the gap while displaying the even numbered page on the left. -If the \pack{hyperref} package is used the option \texttt{pdfpagelayout=TwoColumnRight} may be specified; some PDF viewers understand this setting, but not necessarily the spread view lacks the gap between the facing pages. +If the \pack{hyperref} package is used, the option \texttt{pdfpagelayout=TwoColumnRight} may be specified; some PDF viewers understand this setting, but not necessarily the spread view lacks the gap between the facing pages. -It is possible to see a spread wide figure in the next two pages; a fake figure is displayed and you see that the crossing of the diagonal and medial lines takes \DFimage[SW]{SWfakeimage}{A spread wide fake image}[fig:SWfake] -place exactly on the spine. It was composed with the following command: + +It is possible to see a spread wide figure in the next two pages; a fake figure is displayed and you see that the crossing of the diagonal and medial lines takes place exactly on the spine. It was composed with the following command: \begin{ttsyntax}\setfontsize{9.85}% -... takes -\cs{DFimage}\Oarg{SW}\Marg{SWfakeimage}\Marg{A Spread Wide fake image}\Oarg{fig:SWfake}\% -place ... +\cs{DFimage}\Oarg{SW}\Marg{SWfakeimage}\Marg{A Spread Wide fake image}\Oarg{fig:SWfake} \end{ttsyntax} - +inserted between two paragraphs; it can be used also within a single paragraph, but at the end it is necessary to insert a comment character. Alternatively the environment \amb{DFimage} may be used with the closing statement just at the end of the paragraph. Other examples are shown in the following pages; the filling text is a generic text, not actually a non sense fake Latin wording such as that provided by the \pack{lipsum} package, but it is taken form package \pack{kantlipsum} where sentences appear as plain English; those sentences appear as translations of Immanuel Kant's philosophic theories, although we doubt that he wrote those very texts. @@ -109,11 +113,17 @@ Other examples are shown in the following pages; the filling text is a generic t \section{The user macro} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -The only user macro defined by this package has the following syntax: +The only user macro or user environment defined by this package has the following syntax: \begin{ttsyntax}\setfontsize{9.5}% \cs{DFimage}\oarg{display mode}\marg{image file name}\oarg{lof entry}\% -\qquad\marg{caption}\oarg{label}\parg{height correction}\aarg{line correction}|\meta{width test}|!\meta{color}! +\qquad\marg{caption}\oarg{label}\parg{height correction}\aarg{line correction}|\meta{width test}|!\meta{color}!\\[1ex] +or\\[1ex] +\Bambiente{DFimage}\oarg{display mode}\marg{image file name}\% +\qquad\oarg{lof entry}\marg{caption}\oarg{label}\parg{height correction}\aarg{line correction}|\meta{width test}|!\meta{color}! +\Eambiente{DFimage} \end{ttsyntax} +An environment, named the same as the command, may be used instead of the command; it is suggested that the end document instruction is placed after a paragraph end. + The arguments are described in detail in the twin document \file{swfigure.pdf}. We shortly repeat their meanings. \begin{description}[noitemsep] % @@ -121,29 +131,33 @@ The arguments are described in detail in the twin document \file{swfigure.pdf}. % \item[\meta{image file name}] is the name, optionally without extension, of the graphics file that contains the image; remember that the \LaTeX\ dependent typesetting engines accept graphics files in the formats described by the extensions \texttt{.pdf}, \texttt{.eps}, \texttt{.jpg}, \texttt{.png}, and few other less known formats. % -\item[\meta{lof entry}] is a short phrase that shortens the figure caption. In practice it is the optional argument of the \cs{caption} command. +\item[\meta{lof entry}] is a short phrase that contains the figure caption shortened version. In practice it is the optional argument of the \cs{caption} command. % \item[\meta{caption}] is the caption text, in practice the mandatory argument of the \cs{caption} command. % \item[\meta{label}] is the argument of the \cs{label} command; it is evident that if this optional argument is not specified, the figure cannot be referenced with the usual commands \cs{ref}, \cs{pageref}, and other similar ones. % -\item[\meta{height correction}] is an optional argument with a preset value of 0.8, it reduces the image height by that value, in order to assure that the figure has enough space for the image and its caption; if captions are not “narrative” (too many sentences) the value of 0.8 should be suited in most cases; the user, while revising the document drafts might decide to use a different value, of course always not greater than~1. This correction may be used with some display modes that concern only one page, not a full spread. +\item[\meta{height correction}] is an optional argument with a preset value of 0.8; with some display modes it reduces the image height by that value, in order to assure that the figure has enough space for the image and its caption; if captions are not “narrative” (too many sentences) the value of 0.8 should be suited in most cases; the user, while revising the document drafts might decide to use a different value, of course always not greater than~1. In the Total Height display mode, where the caption is typeset without any rotation at the right of the image, this parameter can be used to finely tune the caption width. This correction may be used with some display modes that concern only one page, not a full spread. % \item[\meta{line correction}] This optional integer number may correct the number of lines of the indentation of the wrapping text around a tall and slim figure. % -\item[\meta{width test}] is an optional fractional number smaller than~0.5 (default \texttt{0.25}) used to check that in Vertical Slim mode the width of the scaled image does not get too small so as to leave sufficient space for e decently typeset caption; the zero value implies no test. See in page~\pageref{fig:VSSmessage} the message that is output if this width becomes too small. +\item[\meta{width test}] is an optional fractional number smaller than~0.5 (default \texttt{0.25}) used to check that in Vertical Slim mode the width of the scaled image does not get too small so as to leave enough space for a decently typeset caption; the zero value implies no test. See in page~\pageref{fig:VSSmessage} the message that is output if this width becomes too small. % -\item[\meta{color}] is an optional color specification delimited by exclamation points. It is used by the \texttt{FS} full spread display mode when the included image completely fills up the spread pages; the color (default: black) may be chosen in order to contrast the image background, since it overprints the image near to its right border. +\item[\meta{color}] is an optional color specification delimited by exclamation points. It is used by the Full Spread display mode when the included image completely fills up the spread pages; the color (default: black) may be chosen in order to contrast the image background, since the caption is typeset over the image near to its right border. \end{description} -We stress the first optional argument meaning, whose default value is \texttt{SW}. It specifies the \meta{display mode}. +We stress the first optional argument meaning: it chooses a \meta{display mode} different from the default \texttt{SW} one. \begin{description}[noitemsep] % -\item[\texttt{SW}] is the acronym that specifies the \meta{display mode} for a Spread Wide figure; it consists into a full spread, without any text, and with its caption typeset in the external margin of the odd numbered page typeset in vertical mode. Since this display mode needs to start on an even page, the user should carefully find the proper place where to insert the user macro \cs{DFimage} (named as “steering” macro, since it decides which large figure style to use), because it starts a new page and possibly inserts a blank page if the new one is odd numbered. The steering macro can be also inserted within a paragraph, and after its complete expansion restores the vertical mode; nevertheless, even so, it may insert a blank page if the next page is odd numbered. Its caption is vertically typeset in the right margin at 1em distance from the image right border; it is possible to change this default value by means of the \cs{SWcaptionShift} declaration; it suffices the redefine with \cs{renewcommand} such declaration, possibly grouping it otherwise it applies to all such spread-wide figures. +\item[\texttt{SW}] is the acronym that specifies the \meta{display mode} for a Spread Wide figure; it consists into a full spread, without any text, and with its 90° rotated caption typeset in the external margin of the odd numbered page. The page margins arounf the image are preserved; only the internal margine is used by the image. Since this display mode needs to start on an even page, the user should carefully find the proper place in the source \texttt{.tex} file where to insert the user macro \cs{DFimage} (named as “steering” macro, since it decides which large figure style to use), because it starts a new page and possibly inserts a blank page if the new one is odd numbered. The steering macro can be also inserted within a paragraph, and after its complete expansion restores the vertical mode; nevertheless, even so, it may insert a blank page if the next page is odd numbered. Its caption is vertically typeset in the right margin at 1em distance from the image right border; it is possible to change this default value by means of the \cs{SWcaptionShift} declaration; it suffices to redefine with \cs{renewcommand} such declaration, possibly grouping it otherwise it applies to all such spread-wide figures. +% +\item[\texttt{HS}] refers to a Horizontal Slim image, that requires a spread wide display mode, such that the first of the facing pages is an even numbered one, and with some text beneath both half images; since the caption is below the right half, the space occupied by this part of the image would be higher than that in the facing page, and it is necessary to equalise these vertical spaces; specific code takes care of this constraint. Also in this case the user should carefully chose the place where to insert the steering macro. +% +\item[\texttt{VS}] This case refers to a Vertical Slim image. This situation requires a really slim image, so that if its “height over width” ratio (its aspect ratio) is smaller than~2, the macro does not insert anything, except a message in its place, that informs the user about the cause of this refusal and suggests other display modes. The procedure is based on the use of the \pack{wrapfig} functionalities; this package has several limitations that the user should check in its documentation. Nevertheless, if there is enough “normal” text available to wrap the figure, the result is quite good. There are two parameters to fine tune the wrapped image with its caption: the \meta{height correction} and the \meta{line correction}. % -\item[\texttt{HS}] refers to a Horizontal Slim image, that requires a spread wide display mode, such that the first of the facing pages is an even numbered one, and with some text beneath both half images; since the caption is below the right half, the space occupied by this part of the image would be higher than that in the facing page, it is necessary to equalise these vertical spaces, and the specific code takes care of this constraint. Also in this case the user should carefully chose the place where to insert the steering macro. +\item[\texttt{TH}] This display mode is useful to display a not so slim vertical image that need more space that that allowed by the Vertical Slim mode. It is printed as a large image that occupies the whole internal margine and overlaps both top and bottom margins; its caption is on the right of the image and uses also part of the external page margin . Therefore it aspect ration should be grater than one; if the aspect ratio is very large, the space occupied by the scaled image may be too slim and the remanning space on the page definitely too wide; the result is very poor, but no warning is issued. On the opposite, if the aspect ration is not large enough, the scaled image covers most of the page and to little space is available to typeset the caption in a decent way; in this case only a warning message is typeset in the \texttt{.log} file, but compilation goes on and displays the bad looking caption; possibly e fatal error takes place if the computed caption measure! turns out to be negative % -\item[\texttt{VS}] This case refers to a Vertical Slim image. This situation requires a really slim image, so that if its “height over width” ratio (its aspect ratio) is smaller than~2, the macro does not insert anything, except a message in its place, that informs the user about the cause of this refusal and suggests other display modes. The procedure is based on the use of the \pack{wrapfig} functionalities; this package has several limitations that the user should check in its documentation. Nevertheless, if there is enough “normal” text available to wrap the figure, the result is quite good. There are two parameters to fine tune the wrapped image with its caption: the \meta{height correction} and the \meta{line correction}. +\item[\texttt{TW}] In a sense this Total Width display mode is similar to the \texttt{TH} one. The difference, as already described in the previous item is that the latter sometimes scales files that are not so slim so that they become too wide and don't leave enough space for the side caption. The former, on the opposite, scales the figures so as to leave a fixed width for the side caption, but if the original figure is too slim, the scaled image becomes too large to fit into the paper height. With this display mode there is the possibility to fine tune the actual caption measure so as to get a better typesetting; the user taste may help to chose the best correction according also on the caption contents. % \item[\texttt{NF}] This display mode is the Normal Figure \LaTeX\ kernel mode; the floating figure is floated to a “floats only” page; since it contains a large image this is a reasonable solution; if the caption is pretty lengthy, the \meta{height correction} comes handy to fine tune the space necessary to the caption. % @@ -152,11 +166,10 @@ We stress the first optional argument meaning, whose default value is \texttt{SW \item[\texttt{FS}] This display mode refers to the Full Spread image covering the whole surface of two facing pages; ideally it would contain a full A3 image over two A4 facing pages without the need to shrink or expand the image; without any margin the caption is vertically typeset over the image at a certain distance from its right border. If the image has textual or colored details close to such border, a caption color may be chosen so as to contrast the image background. The distance from the right border by default is 2em, but it can be modified by redefining with \cs{renewcommand} the \cs{FScaptionShift} declaration; pay attention to group this redefinition, otherwise it applies to all such full spread figures. \end{description} + %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \section{Examples} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -On page~\pageref{fig:HSfake} and the preceding one there is an example of a horizontal slim image. - As any dedicated reader can clearly see, the Ideal of practical reason is a representation of, as far as I know, the things in themselves; as I have shown elsewhere, the phenomena should only be @@ -226,6 +239,7 @@ Ideal, the Antinomies; so, the transcendental aesthetic is just as necessary as our experience. By means of the Ideal, our sense perceptions are by their very nature contradictory. +\begin{DFimage}[VS]{VSfakeimage}{A Vertical Slim fake image}[fig:VSfake](0.75)<2> As is shown in the writings of Aristotle, the things in themselves (and it remains a mystery why this is the case) are a representation of time. Our concepts have lying before them the @@ -265,8 +279,8 @@ supposed that our faculties have lying before them, in the case of the Ideal, the Antinomies; so, the transcendental aesthetic is just as necessary as our experience. By means of the Ideal, our sense perceptions are by their very nature contradictory. +\end{DFimage} -\begin{DFimage}[VS]{VSfakeimage}{A Vertical Slim fake image}[fig:VSfake](0.75)<3> As we have already seen, what we have alone been able to show is that the objects in space and time would be falsified; what we have alone been able to show is that, our judgements are what first @@ -315,15 +329,18 @@ time (and I assert, however, that this is the case) have lying before them the objects in space and time. Because of our necessary ignorance of the conditions, it must not be supposed that, then, formal logic (and what we have alone been able to show is that this is true) is a -representation of the never-ending regress in the series of empirical +representation of the never-ending regress in the +\begin{DFimage}[HS]{HSfakeimage}{A Horizontal Slim fake image}[fig:HSfake] + series of empirical conditions, but the discipline of pure reason, in so far as this expounds the contradictory rules of metaphysics, depends on the Antinomies. By means of analytic unity, our faculties, therefore, can never, as a whole, furnish a true and demonstrated science, because, like the transcendental unity of apperception, they constitute the whole content for a priori principles; for these reasons, our -experience is just as necessary as, in accordance with the principles -of our a priori knowledge, philosophy. The objects in space and time +experience is just as necessary as, in accordance with the + principles of our a priori knowledge, philosophy. The objects +in space and time abstract from all content of knowledge. Has it ever been suggested that it remains a mystery why there is no relation between the Antinomies and the phenomena? It must not be supposed that the @@ -334,7 +351,6 @@ misapprehension, it is necessary to explain that our understanding (and it must not be supposed that this is true) is what first gives rise to the architectonic of pure reason, as is evident upon close examination. -\end{DFimage} The things in themselves are what first give rise to reason, as is proven in the ontological manuals. By virtue of natural @@ -360,9 +376,7 @@ themselves prove the validity of, on the contrary, the Categories. It remains a mystery why, indeed, the never-ending regress in the series of empirical conditions exists in philosophy, but the employment of the Antinomies, in respect of the intelligible character, can never -furnish a true and demonstrated -\begin{DFimage}[HS]{HSfakeimage}{A Horizontal Slim fake image}[fig:HSfake] -science, because, like the +furnish a true and demonstrated science, because, like the architectonic of pure reason, it is just as necessary as problematic principles. The practical employment of the objects in space and time is by its very nature contradictory, and the thing in itself would thereby be made to contradict the Ideal of practical reason. On the @@ -403,6 +417,7 @@ supposed that our faculties have lying before them, in the case of the Ideal, the Antinomies; so, the transcendental aesthetic is just as necessary as our experience. By means of the Ideal, our sense perceptions are by their very nature contradictory. +\end{DFimage} As is shown in the writings of Aristotle, the things in themselves (and it remains a mystery why this is the case) are a @@ -420,6 +435,8 @@ for our sense perceptions, and time occupies part of the sphere of the Ideal concerning the existence of the objects in space and time in general. +\DFimage[Vs]{VSfakeimage}{Wrong display mode}\label{mess:Vs} + As we have already seen, what we have alone been able to show is that the objects in space and time would be falsified; what we have alone been able to show is that, our judgements are what first @@ -437,8 +454,6 @@ this is the case) constitute the whole content for the paralogisms. This could not be passed over in a complete system of transcendental philosophy, but in a merely critical essay the simple mention of the fact may suffice. -\end{DFimage} - \DFimage[VS]{VSSfake}{A tall very slim image}[fig:VSSfake](0.65)<2>\label{fig:VSSmessage} @@ -446,7 +461,13 @@ Therefore, we can deduce that the objects in space and time (and I assert, however, that this is the case) have lying before them the objects in space and time. Because of our necessary ignorance of the conditions, it must not be supposed that, then, formal logic -(and what we have alone been able to show is that this is true) is a +(and what we have alone been able to show is +\DFimage[TH]{THFake}[Total Height fake image with +side caption]{Total Height image with side caption. The caption +looks much better if it is several lines long; therefore this +caption is deliberately filled up with a lot of words that do +not add anything to its meaning.}[fig:TH-fake](0.9) +that this is true) is a representation of the never-ending regress in the series of empirical conditions, but the discipline of pure reason, in so far as this expounds the contradictory rules of metaphysics, depends on the @@ -467,8 +488,6 @@ misapprehension, it is necessary to explain that our understanding rise to the architectonic of pure reason, as is evident upon close examination. -\DFimage[Vs]{VSfakeimage}{Wrong display mode} - The things in themselves are what first give rise to reason, as is proven in the ontological manuals. By virtue of natural reason, let us suppose that the transcendental unity of apperception @@ -494,9 +513,8 @@ remains a mystery why, indeed, the never-ending regress in the series of empirical conditions exists in philosophy, but the employment of the Antinomies, in respect of the intelligible character, can never furnish a true and demonstrated science, because, like the -architectonic of pure reason, it is just as necessary as problematic -principles. The practical employment of the objects in space and time -is by its very nature contradictory, and the thing in itself would +architectonic of pure reason, it is just as necessary as problematic principles. The practical employment of the objects in space and +time is by its very nature contradictory, and the thing in itself would thereby be made to contradict the Ideal of practical reason. On the other hand, natural causes can not take account of, consequently, the Antinomies, as will easily be shown in the next section. @@ -512,11 +530,8 @@ absolved. \DFimage[RF]{RFfakeimage}{A large Rotated Figure fake image}[fig:RFfake] -As is evident upon close examination, to avoid all -misapprehension, it is necessary to explain that, on the contrary, the -never-ending regress in the series of empirical conditions is a -representation of our inductive judgements, yet the things in -themselves prove the validity of, on the contrary, the Categories. +\DFimage[TW]{NFfakeimage}[A Total Width image with side caption]{A Total Width image with side caption. The caption is filled up with a lot of words because in such side captions besides large figures, a wordy caption looks much better. Of course for the list of figures it is much more convenient to use a shorter single phrase.}[fig:TWfake](0.8) + %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \section{Used commands} @@ -524,52 +539,88 @@ themselves prove the validity of, on the contrary, the Categories. The various large fake images have been inserted with the following commands: \begin{itemize}[noitemsep] % -\item figure~\ref{fig:SWfake} +\item figure~\ref{fig:SWfake} on page~\pageref{fig:SWfake}f: % figure 1 \begin{Verbatim}[fontsize=\setfontsize{9.7}] \DFimage[SW]{SWfakeimage}{A Spread Wide fake image}[fig:SWfake] \end{Verbatim} % -\item figure~\ref{fig:HSfake} -\begin{Verbatim}[fontsize=\setfontsize{9}] -\DFimage[HS]{HSfakeimage}{A Horizontal Slim fake image}[fig:HSfake] +\item figure~\ref{fig:VSfake} on page~\pageref{fig:VSfake}: % figure 2 +\begin{Verbatim}[fontsize=\setfontsize{7.5}] +\begin{DFimage}[VS]{VSfakeimage}{A Vertical Slim fake image}[fig:VSfake](0.75)<2> +As is shown in ... +\end{DFimage} \end{Verbatim} % -\item figure~\ref{fig:VSfake} -\begin{Verbatim}[fontsize=\setfontsize{8}] -\DFimage[VS]{VSfakeimage}{A Vertical Slim fake image}[fig:VSfake](0.525)<1> +\item figure~\ref{fig:HSfake} on page~\pageref{fig:HSfake}: % figure 3 +\begin{Verbatim}[fontsize=\setfontsize{8.2}] +... accordance with the +\begin{DFimage}[HS]{HSfakeimage}{A Horizontal Slim fake image}[fig:HSfake] + principles +of our a priori knowledge... +\end{DFimage} \end{Verbatim} % -\item figure~\ref{fig:NFfake} +\item figure \ref{fig:TH-fake} on page~\pageref{fig:TH-fake}: +\begin{Verbatim}[fontsize=\setfontsize{9.5}] +...abstract from +\begin{DFimage}[TH]{THFake}[Total Height fake image with +side caption]{Total Height image with side caption. The caption +looks much better if it is several lines long; therefore this +caption is deliberately filled up with a lot of words that do +not add anything to its meaning.}[fig:TH-fake](0.9) +all content of... +\end{Verbatim} +\newpage +% +\item figure~\ref{fig:NFfake} on page~\pageref{fig:NFfake}: % figure 5 \begin{Verbatim} \DFimage[NF]{NFfakeimage}{A large Normal Figure fake image}% [fig:NFfake] \end{Verbatim} % -\item figure~\ref{fig:RFfake} +\item figure~\ref{fig:RFfake} on page~\pageref{fig:RFfake}: % figure 6 \begin{Verbatim} \DFimage[RF]{RFfakeimage}{A large Rotated Figure fake image}% [fig:RFfake] \end{Verbatim} % -\item figure~\ref{fig:FSfakeA3} +\item figure~\ref{fig:TWfake} on page~\pageref{fig:TWfake}: % figura 7 \begin{Verbatim} -\DFimage[FS]{FSfakeA3}{Full Spread image}[fig:FSfakeA3]!red! +... the Categories. +\DFimage[TW]{NFfakeimage}[A Total Width image with side + caption]{A Total Width image with side caption. The + caption is filled up with a lot of words because in + such side captions besides large figures, a wordy + caption looks much better. Of course for the list of + figures it is much more convenient to use a shorter + single phrase.}[fig:TWfake] +\end{Verbatim} +% +\item figure~\ref{fig:FSfakeA3} on page~\pageref{fig:FSfakeA3}: % figure 8 +\begin{Verbatim}[fontsize=\setfontsize{9}] +\DFimage[FS]{FSfakeA3}{Full Spread image}[fig:FSfakeA3]!\color{red}! \end{Verbatim} % -\item figure~\ref{fig:FSfakeA3margins} +\item figure~\ref{fig:FSfakeA3margins} on page~\pageref{fig:FSfakeA3margins}: % figura 9 \begin{Verbatim} -\DFimage[FS]{FSfakeA3margins}{Full Spread uncropped image}% +\DFimage[FS]{FSfakeA3margins}[Full Spread image with margins]{...}% [fig:FSfakeA3margins] \end{Verbatim} % +\item The message on page~\pageref{mess:Vs} derives from the following input that contains a misspelt display mode option: +\begin{Verbatim} +\DFimage[Vs]{VSfakeimage}{Wrong display mode}\label{mess:Vs} +\end{Verbatim} + \end{itemize} % -%{\pagestyle{empty} +\clearpage{}\ifodd\value{page}\null\newpage\fi + \begin{DFimage}[FS]{FSfakeA3}{Full Spread image}[fig:FSfakeA3]!\color{red}! \end{DFimage} -\DFimage[FS]{FSfakeA3margins}{Full Spread of an image with margins. the margins may be larger or smaller, therefore the caption is set with a one-line gap from the page border and if this caption amounts to more than a single line, this gap remains constant, but the first caption line moves away from the page border.}[fig:FSfakeA3margins]!\large\sffamily! -%} +\DFimage[FS]{FSfakeA3margins}[Full Spread image with margins]{Full Spread of an image with margins. The margins may be larger or smaller, therefore the caption is set with a one-line gap from the page border and if this caption amounts to more than a single line, this gap remains constant, but the first caption line moves away from the page border.}[fig:FSfakeA3margins]!\large\sffamily! + \end{document} diff --git a/Master/texmf-dist/doc/latex/swfigure/swfigure.pdf b/Master/texmf-dist/doc/latex/swfigure/swfigure.pdf Binary files differindex 19dd19dd9a9..d5195dea5e2 100644 --- a/Master/texmf-dist/doc/latex/swfigure/swfigure.pdf +++ b/Master/texmf-dist/doc/latex/swfigure/swfigure.pdf diff --git a/Master/texmf-dist/source/latex/swfigure/swfigure.dtx b/Master/texmf-dist/source/latex/swfigure/swfigure.dtx index 671502d36d5..54fc18ba647 100644 --- a/Master/texmf-dist/source/latex/swfigure/swfigure.dtx +++ b/Master/texmf-dist/source/latex/swfigure/swfigure.dtx @@ -43,7 +43,7 @@ files swfigure.sty and swfigure.pdf %</driver> %<+package>\ProvidesPackage{swfigure}% %<*package> - [2020-11-10 v.0.9.14 Managing large and spread wide figures] + [2020-12-23 v.0.9.18 Managing large and spread wide figures] %</package> %<*driver> \documentclass[a4paper]{ltxdoc}\errorcontextlines=9 @@ -69,8 +69,10 @@ files swfigure.sty and swfigure.pdf \renewcommand\parg[1]{\texttt{(\meta{#1})}} \providecommand\Parg{} \renewcommand\Parg[1]{\texttt{(#1)}} -\providecommand\eTeX{} +\providecommand\barg{} +\renewcommand\barg[1]{\texttt{\char`|\meta{#1}\char`|}} \newbox\SWsynt +\providecommand\eTeX{} \renewcommand\eTeX{\lower0.5ex\hbox{$\varepsilon\!$}\TeX} \newcommand\Benv[1]{\cs{begin}\Marg{#1}} \newcommand\Eenv[1]{\cs{end}\Marg{#1}} @@ -105,12 +107,12 @@ Managing large and spread wide figures} %</driver> % \fi % -% \CheckSum{10} +% \CheckSum{1040} % % \begin{abstract} % This package defines a single command that with different options can % insert large images into the document; those that occupy an entire -% spread s get split into two halves that are inserted on +% spread get split into two halves that are inserted on % two facing pages in such a way that they merge when the document is read % on the screen (set to double page view) or is printed in a well sewn % book so that facing pages join correctly at the spine. @@ -140,26 +142,24 @@ Managing large and spread wide figures} % % In the other case it is possible to manage such large figures in % different ways; we define a single command that, according to -% different settings, can insert such figures in six different display +% different settings, can insert such figures in eight different display % modes. %\begin{enumerate}[noitemsep] % \item -% The normal \LaTeX\ kernel full page display mode, but using -% the |figure| environment with the |[p]| placing option. Apparently +% The normal \LaTeX\ kernel full page display mode, but setting the placement option to |[p]| to the figure environment. Apparently % there is no need to define a new command for this display mode, except % the advantage of using the same command as the other modes and a few -% small further functionalities that the new command has available. +% small further functionalities provided by this the new command. %\item -% The landscape display mode available with the |lscape| package +% The landscape display mode is available with the |lscape| package % and other similar ones. Again this display mode appears superfluous, -% but the advantage is to use the same command as with the other -% display modes +% but the advantage is to use the same command as the other display modes. %\item % The screen-wide display mode, where two facing pages display a large % figure divided in two halves, each one set in its page shifted to the % spine so as to occupy on each page the text width plus the internal -% margin width; with suitable aspect ratio, both facing pages are -% practically full. No other text appears in this display mode, except +% margin; with suitable aspect ratio, both facing pages are practically +% full. No other text appears on the page with this display mode, except % the caption in the right page external margin. %\item % The slim screen-wide image is similar to the previous mode, but since @@ -168,29 +168,45 @@ Managing large and spread wide figures} % page, and the left text block height is set so that that the first % lines of both text blocks are aligned. %\item -% The slim tall image is set to the side of the text block that wraps -% it. Recurse is made to the |wrapfig| package, therefore the software -% might sometimes hick-up a little bit, because of the idiosyncrasies of -% |wrapfig| that performs very well in most but not all circumstances; -% see that package documentation for such |wrapfig| limitations. With -% this |wsfigure| package we limit the use of this display mode to -% images that have a “height over width” ratio not lower than~2; we -% provide also some option arguments so as to correct small imperfections -% in the sizing of the text indention +% The slim tall image is set to the side of the text block with text +% wrapping it. Recurse is made to the |wrapfig| package, therefore the +% software might sometimes hick-up a little bit, because of the +% idiosyncrasies of |wrapfig| that performs very well in most but not +% all circumstances; see that package documentation for such |wrapfig| +% limitations. With this |wsfigure| package we limit the use of this +% display mode to images that have a “height over width” aspect ratio +% not lower than~2; we provide also some option arguments so as to correct +% small imperfections in the sizing of the text indention %\item -% A very large image, typically A3 sized, that occupies a full spread +% A very large image, typically A3 sized, occupies a full spread % including the lateral margins; it is a solution to inputting, for % example, a line drawing of a technical device, that otherwise % should be attached as a separate document; a very large table -% that does not fit the usual A4 paper and that cannot be reduced -% by means of |longtable| or scaled down to unreadable font sizes. +% that does not fit the usual A4 paper and that cannot be split in chunks +% by means of |longtable|, and cannot be scaled down to unreadable font +% sizes. +%\item +% A rather tall not so slim image can be typeset in the total height +% mode; this height is the paper (trimmed page) height; the image +% appears in a textless page, shifted to the spine, taking into +% account if the page is an odd or even numbered one. The image +% is scaled so that leaves on it side the external margin plus a part +% of the text width, generally sufficient for a side caption; it reaches the +% top and the bottom limits of the trimmed page. Should this space +% be to narrow for a decently typeset caption, a warning +% message is issued but the compilation is not stopped. It is up +% to the user to control how bad is the caption typesetting and +% possibly to provide a different display mode in order to get a +% better result. +% \item +% Anothe display mode, that we call Total Width %\end{enumerate} % % In any case, depending on the page geometry and the image aspect % ratio, it is very handy to have available a single command that % changes the display mode by just changing a single input optional -% argument. In facts the user might start with one of the six -% described display modes; after examining the document daft the +% argument. In facts the user might start with one of the eight +% described display modes; after examining the document draft the % user might chose another display mode, and it suffices to change % the optional argument, without changing the whole code. % @@ -215,7 +231,7 @@ Managing large and spread wide figures} % Should the user have available a basic or a partial \TeX\ system % installation, the simplest way to install this package is to download % the |swfigure.zip| file from the Comprehensive \TeX\ Archive Network -% (CTAN), and decompress it either in the very folder where there is +% (CTAN), to decompress it either in the very folder where there is % the document main or single document file or, for a general use, in % the user |texmf| personal tree; it might be necessary that the user % should directly create this personal tree; how to do it is described @@ -244,56 +260,65 @@ Managing large and spread wide figures} %\begin{ttsyntax} %\cs{DFimage}\oarg{display mode}\marg{image file name}\% %\qquad \oarg{lof entry}\marg{caption}\oarg{label}\% -%\qquad\parg{height correction}\aarg{line correction}|\meta{width test}|!\meta{precaption}! +%\qquad\parg{height correction}\aarg{line correction}\barg{width test}!\meta{precaption}! %\vspace{0.5\baselineskip} %or %\vspace{0.5\baselineskip} % \Benv{DFimage}\oarg{display mode}\marg{image file name}\% %\qquad \oarg{lof entry}\marg{caption}\oarg{label}\% -%\qquad\parg{height correction}\aarg{line correction}|\meta{width test}|!\meta{precaption}! +%\qquad\parg{height correction}\aarg{line correction}\barg{width test}!\meta{precaption}! %\meta{environment textual contents} %\Eenv{DFimage} %\end{ttsyntax} % \noindent where: %\begin{description}[noitemsep] +% %\item[\meta{display mode}] % is one of the following uppercase acronyms: % \texttt{NF} (Normal Figure), \texttt{RF} (Rotated Figure), % \texttt{SW} (Spread Wide image), \texttt{HS} (Horizontal Spread-wide -% image), \texttt{VS} (Vertical Slim image), and \texttt{FS} -% (Full Spread image). +% image), \texttt{VS} (Vertical Slim image), \texttt{FS} +% (Full Spread image), \texttt{TH} (Total Height image), and \texttt{TW} (Total Width image). +% %\item[\meta{image file name}] % is the name of the image graphic file; remember that the \LaTeX based % \TeX\ system typesetting programs accept graphic files in the formats % with extensions \texttt{.pdf}, \texttt{.eps}, \texttt{.jpg}, % \texttt{.png}, and few other less common ones. It is not necessary to % specify the extension, but it is not forbidden. +% %\item[\meta{lof entry}] % is the optional entry to the List Of Figures; it defaults to the % \meta{caption} text, but if the latter is sort of lengthy, it is % better to enter a shorter text in that list. +% %\item[\meta{caption}] % is the caption text. +% %\item[\meta{label}] % this optional argument is the string that forms the \cs{label} command % argument; of course, if this argument is not specified, the figure % number and its page cannot be referenced with \cs{ref}, \cs{pageref} % and other similar commands. +% %\item[\meta{height correction or color}] % is a round parenthesis delimited optional argument; as a % \emph{height correction} it is a fractional number lower than~1 % (default 0.8) with which to further scale the scaled image height % to be included; it is used by some display modes, and it is ignored -% by others. +% by others. In the total height mode, it can be used to scale the +% captions width. +% %\item[\meta{line correction}] is an angle bracket delimited optional % argument preset to zero. It is relevant only with the slim % vertical image display mode. Sometimes the |wrapfig| package % indents the wrapping text in such a way as to leave to much or too % little vertical space around the image and its caption; by examining -% the document drafts it is possible to correct the predetermined -% number of lines by increasing or decreasing the vertical space by -% any (integer) number of lines. -%\item[\meta{width test}] this further vertical bars-delimited argument +% the document draft it is possible to correct the predetermined +% number of indented lines by increasing or decreasing the vertical +% space by any (integer) number of lines. +% +%\item[\meta{width test}] this further vertical bar-delimited argument % is used only when dealing with vertical slim images; when they are % scaled down in order to fit in the available space, their width may % become too small to allow a decently typeset caption below the @@ -303,12 +328,14 @@ Managing large and spread wide figures} % \meta{width test} fraction is \texttt{0.25}, but the user can specify % a different value, even zero; with the zero value this width test is % skipped. -%\item[\meta{precaption}] is an optional color declaratio delimited by +% +%\item[\meta{precaption}] is an optional color declaration delimited by % exclamation points; the default value is ‘empty’; it is used only % by the \texttt{FS} display mode in order to typeset a caption, for % example, with a contrasting color over the background image average % color, and/or with a displacement of the first or only caption line, % and/or with a different font. +% %\end{description} % %^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% @@ -326,9 +353,9 @@ Managing large and spread wide figures} % does not know in advance the vertical space occupied by the caption, % therefore the optional \meta{height correction} comes handy for % small adjustments; this display mode is fully and freely floating, -% although its positioning option is fixed to~|[p]|, an only-float page. -% Therefore don't use it it the image is not really such as to occupy -% most of text block area. +% although its positioning option is fixed to~|[p]|, a float-only page. +% Therefore don't use it if the image is not really such as to occupy +% most of the text block area. % %\item[\texttt{RF}] % This display mode is convenient when the image @@ -354,7 +381,7 @@ Managing large and spread wide figures} % If the aspect ratio of the image to include is lower than~2, the % following message is printed in the document where the image % should appear (of course with |#1| replaced by the actual image -% file name):\\ +% file name):\\[2ex] %\begin{minipage}{0.7\textwidth} %\begin{verbatim} % =========================================== @@ -382,13 +409,16 @@ Managing large and spread wide figures} % then should help the automatic positioning by choosing very carefully % where to insert the \cs{DFfigure} command in the source text; possibly % the user should chose an end of paragraph close to the end of a page. +% The command or the environment may be used even within a source file +% paragraph; with a little attention: there should be no space between +% the end document command and the first character of the following text. % %\item[\texttt{HS}] % This display mode is convenient when the initial image aspect % ratio is very small; if it is smaller than~0.3 its insertion % leaves enough space beneath the two image halves (plus caption) % so that normal text can fill the space under such spread wide -% slim figure. The constrains described for display mode \texttt{SW} +% slim figure. The constraints described for display mode \texttt{SW} % apply also to this mode. % % \item[\texttt{FS}] @@ -399,24 +429,64 @@ Managing large and spread wide figures} % without scaling down its contents. With this full occupation of both % facing pages, there is no room for any caption; therefore the actual % image, besides occupying an A3 page, should have a minimum white -% margin around, so that a caption can be superimposed to the white +% margin around, so that a caption can be superimposed to the image white % part if its original bottom margin that, upon rotation, becomes the -% right one. If the original image has no margins, the caption may be -% typeset with contrasting different color from the default black one. -% +% right one, is large nough. If the original image has no margins, the +% caption is typeset ove the image, but it may be colored with contrasting +% color compared to the average background one. +% +% \item[\texttt{TH}] +% This mode is suited for tall figures that do not show well when their +% height is scaled to the text height; the upper and lower margins are +% available for a larger scale factor; even the internal margin is +% helpful to gain some space. In this case, though, the page header and +% footer should be avoided and the figure caption should be set at the +% image side, without any rotation; the little problem that arises in +% this case is that the caption, always close to the external margin, +% should not be rotated and its measure should be adapted in order to +% properly use the horizontal space left on the page. If this space is +% too narrow the figure, in spite if being taller then wide, is too +% wide: it has an aspect ratio higher than one but not enough. This +% display mode requires that the image has an aspect ratio greater +% than, say, $\sqrt2$, otherwise the caption measure becomes too short. +% A warning message is issued if the total space left on the page is +% smaller than the external margin, where the caption would have the +% same measure as a marginal note. In spite if this fact, compilation +% goes on, and the attentive user not only evaluates the result, +% and examines the \texttt{.log} file where he finds the explanation +% of the possibly too bad result. +% \item[\texttt{TW}] +% A another Total Width mode is is defined such that the scaled +% image and its (side) caption occupy the upper part of the page/paper. +% The given image is scaled to occupy the internal margin plus 80\% +% of the text block width; the remaining horizontal space is provided +% for a side caption and its lateral spaces, If the aspect ratio +% of the original image is not smaller than text block and internal +% margin widths divided by the paper height, the scaling might produce +% a scaled image too tall to fit into the paper. No tests are made +% in this sense, but it is up to the user the best choice for +% displaying a given image. On an A4 paper, depending on the page +% design, the aspect ratio available should be approximately 1.8, +% therefore this design accommodates a large number of different +% aspect ratio images, from a not so slim tall portrait image to +% a landscape image. A square image, scaled as described above, +% may occupy approximately the upper half of the page. +% The caption is always well typedset in the adjacent free space, +% and it is possible to slightly modify its measure by using an +% optional argument. %\end{description} % %^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % \section{Acknowlegements} %^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % -% This package would not exist if Heinrich Flech did not need -% to insert several types of large images in his documents; he asked +% This package would not exist if Heinrich Fleck did not need +% to insert several large images in his documents; he asked % me to create suitable commands and/or environments and he tested % all the series of progressive developments of this package; believing % that this package might be useful to other \TeX\ users, he invited % me to submit the result to the \TeX\ community, and here it is. -% Heinrich did not want his name as an author, because he insists +% Heinrich did not want his name as a co-author, because he insists % that he was “just” a tester. He was precious and I warmly thank him. % % Thanks also to Benedict Wilde who spotted some errors and suggested @@ -429,6 +499,12 @@ Managing large and spread wide figures} % different formats and page designs; but this was not my aim: I wanted % something possibly independent from the document class and not % requiring any particular printer. +% The seventh display mode came to our minds when we found tall figures +% that did not show well scaled to the \emph{text block} height, but could +% show better if scaled to \emph{paper} height, with the caption at their +% side; actually we found that it was better to scale the image to a +% width of the internal margin plus 80\% of the text width, and placing +% the image flush to the upper paper border and to the spine. The eighth display mode is a varinat of the preceding one and allows to place some text beneath the image and caption block. % %^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %\newpage @@ -456,7 +532,7 @@ Managing large and spread wide figures} %\iffalse %<*package> %\fi -% The required \TeX\ format and is date, and the identification of this +% The required \TeX\ format with is date, and the identification of this % package have already ben inserted by the initial commands of this % documented file. % @@ -468,7 +544,7 @@ Managing large and spread wide figures} % variables, are also numerical expressions connected with relation % operators; for further details it suffices to examine the % |interface3.pdf| file, that is integral part of any recent \TeX\ -% system distribution. We neede also some commands to compare strings +% system distribution. We needed also some commands to compare strings % or to check if a given string was included into an L3 sequence % (list) of strings. % @@ -480,14 +556,15 @@ Managing large and spread wide figures} % are \verb+||+ (\texttt{OR}), \verb+&&+ (\texttt{and}), and \verb+!+ % (\texttt{NOT}), plus other less common ones; the \verb+!+ negates the % status of boolean variables, but also the numerical relation operators; -% these, on turn, may be paired so that, for example |>=| is the same +% these, on turn, may be paired so that, for example |>=| behaves as % as~|!<|. +% % The comparisons of strings with the following syntax %\begin{ttsyntax} %\cs{CompStrings}\marg{string\ped{1}}\marg{string\ped{2}} %\end{ttsyntax} -%Produces a boolean result that may be used as a \meta{test} argument -% to |\fptest| +% Produces a boolean result that may be used as a \meta{test} argument +% to |\fptest|. % The |\SetList| macro defines a named L3 sequence variable containing % the reference list of valid display modes, while the |\TestList| is % an L3 function that tests if a given string is listed in a named @@ -496,16 +573,14 @@ Managing large and spread wide figures} %\cs{SetList}\marg{list name}\marg{comma separated string list} % \cs{TestList}\meta{string}\marg{list name}\marg{true}\marg{false} %\end{ttsyntax} -% The fields \meta{true} and \meta{false}, as usual, are the action +% The fields \meta{true} and \meta{false}, as usual, are the actions % to be executed if the test is true or false; the test is true if % \meta{string} is listed into the \meta{named list}. % -% The |trace| package is still present in this beta version of the -% package; it will not be present any more in the future stable versions. % Packages |graphicx|, |afterpage|, and |wrapfig| are functional -% for this package. In order to avoid “Option Clash” messages, such -% packages are loaded without any option; should the user load some -% or all of them with options, the user should load them +% for this package. In order to avoid “Option Clash” error messages, +% such packages are loaded without any option; should the user load +% some or all of them with options, the user should load them % \emph{before} loading this package. This particular documentation % does not require the |graphicx| package, because it is already % loaded by |swfigure|. @@ -529,8 +604,6 @@ Managing large and spread wide figures} \ExplSyntaxOff -\RequirePackage{trace} - \RequirePackage{graphicx} \RequirePackage{afterpage} \RequirePackage{wrapfig} @@ -540,13 +613,15 @@ Managing large and spread wide figures} % we assign parameters relating to the page design. We also compute % the dimensions of the available spread space so as to have available % the elements to compare the aspect ratios of the images and of the -% available spaces. The |\if@SWtmode| switch is used only by the |SW| -% display mode in order to save the typesetting mode that was active -% when the |\DFimage| command was used in the source file; if it was -% in text mode, the switch is set to |true| and no spaces should be -% present after the last argument of that macro; the result is that -% the |\SWfigure| service macro shifts to vertical mode, but as soon -% as it is completed the switch test restores the text mode. +% available spaces. The |\if@SWtmode| switch is used by all text modes +% in order to save the typesetting mode that was active when the +% |\DFimage| command or the homonymous environment was used in the source +% file; if it was in text mode, the switch is set to |true| and no spaces +% should be present after the last argument of that macro or after the +% closing environment statement; the result is that every service macro +% shifts to vertical mode, but as soon as it is completed the switch test +% restores the text mode. A blank line, though, after the command or the +% environment starts a new paragraph. % % \begin{macrocode} \newdimen\internalmargin @@ -562,6 +637,7 @@ Managing large and spread wide figures} \newdimen\DFheight \newdimen\DFhalfheight \newdimen\FigSpace +\newdimen\TScaptionwidth \def\SWcaptionShift{1em}% \def\FScaptionShift{2em}% \newsavebox\DFtotalimage @@ -577,12 +653,13 @@ Managing large and spread wide figures} % a zero height vertical box and deal with the mandatory and optional % arguments according to the following syntax: %\begin{ttsyntax} -%\cs{DFcaption}\oarg{lof entry}\marg{caption}\oarg{label} +%\cs{DFcaption}\oarg{lof entry}\marg{caption}\oarg{label}\\[1ex] +%\cs{DFcaptionP}\oarg{lof entry}\marg{caption}\oarg{label} %\end{ttsyntax} % Notice that the \meta{lof entry} defaults to the full caption text if % a different text is not explicitly entered. -% This commands are specific to those display modes that compose -% the caption in vertical mode, therefore the caption measure is the +% These commands are specific to those display modes that compose +% the caption in vertical direction, therefore the caption measure is the % |\textheight|. % \begin{macrocode} \NewDocumentCommand\DFcaption{O{#2} m o}{\refstepcounter{figure}% @@ -591,7 +668,7 @@ Managing large and spread wide figures} \addcontentsline{lof}{figure}{\protect\numberline{\thefigure}#1} \IfValueT{#3}{\label{#3}}\relax% } -\NewDocumentCommand\DFcaptionP{O{#2} m o D!!{black}}% +\NewDocumentCommand\DFcaptionP{O{#2} m o D!!{\color{black}}}% {\refstepcounter{figure}% \vbox to 0pt{\vss\hsize=\textheight\parindent=0pt\leavevmode #4\relax Figure \thefigure\quad #2}% @@ -609,6 +686,9 @@ Managing large and spread wide figures} % after complete expansion. This is useful, especially for spread wide % display modes, to chose the most suitable place in the source file to % place the |\DFimage| command with its arguments. +% The |\cleartoeven| possibly inserts an empty page if the new page +% is odd numbered; the |\cleartopage| simply clears the current page, +% but it does not insert any empty page. % % \begin{macrocode} @@ -617,7 +697,7 @@ Managing large and spread wide figures} \@SWtmodefalse \else \unskip\@SWtmodetrue\linebreak - \vadjust{\vspace{0pt plus1fill}\newpage}% + \vadjust{\vspace{0pt plus1fill}\par}% \fi} \newcommand\reset@tmode{\if@SWtmode\expandafter\noindent\ignorespaces\fi} @@ -627,31 +707,36 @@ Managing large and spread wide figures} \ifodd\c@page\afterpage{#1}\else#1\fi% } +\newcommand\cleartopage{\set@tmode@newpage\clearpage} + % \end{macrocode} % Now we define the “real” user macro necessary to chose the % \meta{display mode} and the various parameters necessary for the % desired one. See section~\ref{sec:Usage} on page\pageref{sec:Usage} % for its syntax and the other necessary arguments. Notice that only % two arguments are mandatory: the \meta{image file name} and the -% \meta{caption} text. All the other five optional parameters are +% \meta{caption} text. All the other eight optional parameters are % delimited by various delimiters; the first one, \meta{display mode} % has as default setting the acronym \texttt{SW} for a “Spread-Wide” % display mode; this mode was the one this package was initially % conceived for, and its initials recall this priority. All other -% modes came afterwards. the other optional parameters may have a -% default value, but they are ignored by certain modes that don use -% those parameters. As for the previous macro |\DFimage|, here +% modes came afterwards. The other optional parameters may have a +% default value, but they are ignored by certain modes that don't use +% those parameters. As for the previous macro, for |\DFimage| % the \meta{lof entry} defaults to the full \meta{caption} text. % % Actually \cs{DFimage} just examines the \meta{display mode}, and % accordingly passes the necessary parameters to the actual macros % that implement the various mode displays. It outputs an error % message if the \meta{display mode} acronym was misspelt. +% The |\DFimage| command (and environment) needs the full list +% of arguments, whileand the |DFwarning| macros requires just +% the two arguments it is going to actually use. % \begin{macrocode} \NewDocumentEnvironment{DFimage}% - {O{SW} m O{#4} m o D(){0.8} D<>{0} D||{0.25} D!!{}}% + { O{SW} m O{#4} m o D(){0.8} D<>{0} D||{0.25} D!!{} }% {% - \SetList{\DisplayModeList}{SW,HS,VS,FS,NF,RF}% + \SetList{\DisplayModeList}{SW,HS,VS,FS,NF,RF,TH,TW}% \TestList{\DisplayModeList}{#1}% {\csuse{#1figure}{#2}[#3]{#4}[#5](#6)<#7>|#8|!#9!% \fptest{\CompStrings{\@currenv}{DFimage}}{}{\reset@tmode}% @@ -664,19 +749,18 @@ Managing large and spread wide figures} \aftergroup\reset@tmode }% -\NewDocumentCommand\DFwarning{ o m o m o d() d<> d|| d!!}% -{\PackageWarning{swfigure}% +\NewDocumentCommand\DFwarning{ o m o m }{% +\PackageWarning{swfigure}% {********************************************\MessageBreak Option #1\space is not valid. Nothing done \MessageBreak \MessageBreak Image #2 was not processed \MessageBreak - *******************************************\MessageBreak + ********************************************\MessageBreak }% } - % \end{macrocode} -% In the following subsections the six specific display mode macros +% In the following subsections the eight specific display mode macros % are examined and commented. %^^A===================================== % \subsection{The \cs{SWfigure} macro for Spread Wide images} @@ -688,10 +772,10 @@ Managing large and spread wide figures} %\end{ttsyntax} % The various arguments have already been described; as you see the % \meta{display mode} argument is not there anymore, as well as the -% last two optional arguments of |\DFfigure|.Notice that the +% last two optional arguments of |\DFfigure|. Notice that the % \meta{caption} text, the third argument of this macro, is used also -% to initialise the \meta{lof entry}, so that if the user doe not -% specify such short caption entry, the default is identica to the +% to initialise the \meta{lof entry}, so that if the user does not +% specify such short caption entry, the default is identical to the % full caption. Notice the the last arguments are not actually used; % they are needed in the definition due to the way |DFimage| transfers % its arguments to the called macros. @@ -713,8 +797,8 @@ Managing large and spread wide figures} % macro contains only keywords and numbers and may be executed % without errors. % -% Let $W$ be the total spread width and $w$ be the initial image -% width; let $H$ be the text height and $h$ the initial image height; +% Let $W$ be the total spread width and $w$ be the original image +% width; let $H$ be the text height and $h$ the original image height; % compute the $A_\mathrm{W}$ to be the aspect ratio of the spread % available space $H/W$. Similarly let $A_\mathrm{fig}$ be the initial % image aspect ratio; we have to scale the image with a @@ -743,8 +827,8 @@ Managing large and spread wide figures} % line over the |\fptest| macro emphasises this correspondence. Once the % scaling factors are found the boxes containing the half figures % are scaled and further on are inserted in floating figure -% environments; we use une of the dirty tricks: the matrioska dolls; this -% metaphor describes nested |\makeboxe|s used to mask their actual +% environments; we use one of the dirty tricks: the matrioska dolls; this +% metaphor describes nested |\makebox|es used to mask their actual % widths, but capable to push the images towards the spread spine. % Eventually the caption is set in the right margin of the right % spread page, rotated $90^\circ$ counterclockwise. @@ -783,7 +867,7 @@ trim = \the\DFhalfwidth\space 0 0 0]}\x{#1}}% \begin{figure}[p]% \vbox to\textheight{\vss\hsize=\textwidth \makebox[\hsize][r]{\makebox[\FigSpace][l]{\box\DFimageII}% -% Rotated caption in the right page +% Rotated caption in the right odd-numbered page \makebox(0,0)[lb]{\hspace*{\SWcaptionShift}\raisebox{0.5\textheight}{% \rotatebox[origin=tc]{90}{\DFcaption[#2]{#3}[#4]% % @@ -797,10 +881,10 @@ trim = \the\DFhalfwidth\space 0 0 0]}\x{#1}}% % page figures} %^^A======================================== % This code is without surprises, except that it receives from the -% |DFimage| steering macro five usable arguments (plus three more +% |DFimage| selector macro five usable arguments (plus three more % ones that are not actually used); the fifth (optional) one % being delimited by round parentheses; by default, it contains the -% value 0.8, but the user can pass to the steering macro a different +% value 0.8, but the user can pass to the selector macro a different % value in order to reduce the actual image size so as to leave % enough space beneath it for the caption; the user, in facts, does % not know in advance how many lines would occupy a structured @@ -823,11 +907,11 @@ trim = \the\DFhalfwidth\space 0 0 0]}\x{#1}}% % way of displaying a large figure, except, perhaps, the fact % the instead of invoking the |lscape| package, the whole figure % is rotated by means of rotating the very box that was used -% to contain the scaled image; the steering macro does not pass +% to contain the scaled image; the selector macro does not pass % any \meta{height correction} argument to this macro, because % it automatically scales the box containing the image and % the caption so as to fill up the height or the width of the -% text block. Of course the macro signature includes also +% text block. Of course the macro L3 signature includes also % the descriptors of unused arguments. % \begin{macrocode} \NewDocumentCommand\RFfigure{m o m o d() d<> d|| d!!}{% @@ -858,20 +942,20 @@ trim = \the\DFhalfwidth\space 0 0 0]}\x{#1}}% % textual contents of the text block the result may be very good. % % The user is recommended to attentively read the |wrapfig| -% documentation because it has several limitations. here we suggest +% documentation because it has several limitations. Here we suggest % the user to open the environment just before a paragraph and % close it after several paragraphs; remember that since the opening % and the closing statements are far away from one another, it is -% possible to forget this situation and insert another such environment -% within the former one ,or a |\DFimage| command, and this will -% produce undesirable effects; never ever nest two |Dfimage| -% environments and never ever insert a |\DFimage| command within -% an environment. +% possible to forget this situation and insert another such +% environment, or a |\DFimage| command, within the former one +% and this will produce undesirable effects; never ever nest two +% |Dfimage| environments and never ever insert a |\DFimage| command +% within an environment. % % The user should help a little bit the correct performance of % this macro; for this reason, besides the \meta{height correction} -% factor, the steering macro may pass to it also the \meta{line -% correction} in order to correct the amount of lines the surrounding +% factor, the selector macro may pass to it also the \meta{line +% correction} in order to correct the amount of lines the wrapping % text should be indented; by playing with both corrections % good results may be obtained. % @@ -890,7 +974,7 @@ trim = \the\DFhalfwidth\space 0 0 0]}\x{#1}}% % its delimiting tokens are two vertical bars, \verb+| |+, and its % default value is \texttt{0.25}. This means that if the scaled % image becomes narrower than this coefficient times the text width, -% an other message is typeset in place of the figure. Depending of the +% an other message is typeset in place of the figure. Depending on the % various elements that influence these tests, the user can try % different values for this coefficient, even reaching the value zero, % that eliminates such test on the scaled image width. @@ -902,22 +986,22 @@ trim = \the\DFhalfwidth\space 0 0 0]}\x{#1}}% \DFwidth=\wd\DFtotalimage \DFheight=\ht\DFtotalimage \edef\VS@aspectratio{\fpeval{\DFheight/\DFwidth}} \fptest{ \VS@aspectratio < 2 }% - {\begin{center}\ttfamily + {\begin{center}\ttfamily\relax ===========================================\\ - Image \textit{#1} is not tall enough.\\ - Consider using a display mode different\\ + Image #1 is not tall enough. \\ + Consider using a display mode different \\ from VS; may be NF or RF are better suited.\\ ===========================================\\ - Nothing done!\\ + Nothing done! \\ =========================================== \end{center} }% {\edef\VS@factor{\fpeval{#5\textheight/\DFheight}}% \fptest{\VS@factor>1 || \VS@factor\DFwidth < #7\textwidth}% {% - \begin{center}\ttfamily + \begin{center}\ttfamily\relax =================================================\\ - The scaled image \textit{#1} is too slim. \\ + The scaled image #1 is too slim. \\ Maybe directly using the wrapfig package might \\ solve this problem. \\ =================================================\\ @@ -944,14 +1028,13 @@ trim = \the\DFhalfwidth\space 0 0 0]}\x{#1}}% % \end{macrocode} % %^^A===================================== -% \subsection{The \cs{HSfigure} macro for spread wide slim -% figures} +% \subsection{The \cs{HSfigure} macro for spread wide slim figures} %^^A===================================== % % The beginning of the macro is not so different from that used % for the |SWfigure| macro. But this time there is no alternative -% to scale the image taking into account only its width and the -% spread width. The new little problem, now, is to match the total +% to scale the image because only its width and the spread width are +% significant. The new little problem, now, is to match the total % height of the two halves of the original wide and slim image, % so that the texts of the two facing pages have their respective % first lines perfectly aligned. @@ -1001,7 +1084,9 @@ trim = \the\DFhalfwidth\space 0 0 0]}\x{#1}}% }% }% } + % \end{macrocode} +% %^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %\subsection{The \cs{FSfigure}~macro for Full Spread figures} %^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% @@ -1010,9 +1095,9 @@ trim = \the\DFhalfwidth\space 0 0 0]}\x{#1}}% % advanced printers that use different sized papers, this package aims % to be independent form any class and any printer; it is limited to % the ordinary default paper size A4, as it is usual in Europe, but -% letter paper is also valid); ideally it would typeset an A3 sized -% image on a full spread, i.e. by using also the space of all the -% margins. +% letter paper is also valid; ideally it would typeset an A3 sized +% image on a full spread, i.e. by filling also the space of all the +% lateral margins. % % Actually with American paper sizes there is not a series of sizes % that behaves as the ISO A series, but this macro tries to adjust the @@ -1024,12 +1109,12 @@ trim = \the\DFhalfwidth\space 0 0 0]}\x{#1}}% % two identically sized halves, and sets them on two facing pages joining % them at the spine but covering the greatest part of both pages, so % as to avoid exceeding either the paper height or twice the paper width. -% If the image has an aspect ratio close to $\sqrt{1/2}$, it does the -% same, except rotating the image. +% If the image has an landscape aspect ratio close to $\sqrt{1/2}$, it +% does the same, except rotating the image. % % In any case the user creates a separate PDF file to be imported into % the document that is supposed to contain it; it is better if this PDF -% is of vectorial type, i.e. any drawing and all fonts should should be +% is of vectorial type, i.e. any drawing and all fonts should be % vectorial; this PDF might contain photos or similar images of % rasterised type, but the pixel density should be suitably high in % order to preserve the image quality. @@ -1041,9 +1126,9 @@ trim = \the\DFhalfwidth\space 0 0 0]}\x{#1}}% % therefore if a caption is needed, it is overprinted on the image; % in case $(a)$ there are no problems because the caption goes over % the white right margin (rotated 90° counterclockwise); while in -% case $(b)$ the caption is over printed un the right side of the +% case $(b)$ the caption is over printed on the right side of the % image; depending on the image “background” a different color -% might be more suited compared to black (the default color). +% might be more suited compared to the the default color (black). % The last macro argument takes care of inserting before the caption % any declaration that may involve color, displacement, font encoding % (seldom necessary), family, series, shape and size; @@ -1053,7 +1138,7 @@ trim = \the\DFhalfwidth\space 0 0 0]}\x{#1}}% % optional arguments in a different way: %\begin{ttsyntax}\setfontsize{9.25}% %\cs{FSimage}\marg{image file name}\oarg{lof entry}\marg{caption text}\oarg{label string} -%\qquad\parg{height correction}\aarg{line correction}|\meta{width text|!\meta{precaption}! +%\qquad\parg{height correction}\aarg{line correction}\barg{width text}!\meta{precaption}! %\end{ttsyntax} % The above is the full definition, but the fifth, sixth and seventh % arguments are not used; they are necessary for the special @@ -1062,33 +1147,33 @@ trim = \the\DFhalfwidth\space 0 0 0]}\x{#1}}% % % Moreover, since the included image overlaps the top and bottom % margins, if these contain the header and footer such elements -% would show if the image is not opaque enough; in any case the +% would show if the image is not sufficiently opaque; in any case the % footer would show because it overlaps the image. Since most -% images are not opaque at all it is better to locally use the +% images are not really opaque it is better to locally use the % \texttt{empty} page style, but without using the |\thispagestyle| -% command, because it hold for just one page, while the spread -% occupies two pages. The macro provides this setting but it has +% command, because it holds for just one page, while the spread +% occupies two pages. The macro provides this setting but it has % to create a group in case the |\DFimage| command is used, while % it is not necessary when using the |DFimage| environment, % therefore the current environment is tested and the opening -% |\bgroup| and closing |\egroup| commands are used onlY if the +% |\bgroup| and closing |\egroup| commands are used only if the % code is used without the environment. % % Therefore the code steps are the following: %\begin{enumerate}[noitemsep] %\item % The initial figure is loaded into a box from which the necessary -% measures are taken; in particular the its width and its height in +% measures are taken; in particular its width and its height in % order to check the aspect ratio, or better, which dimension is greater % than the other. If the height is smaller than the width the image is -% sort of panoramic and we proceed splitting the total image box into +% sort of landscape and we proceed splitting the total image box into % two equal halves, with a vertical cut in the middle. %\item % Otherwise the image is as a portrait, and we split the total image % block into two halves with an horizontal cut in the middle; such two % boxes need a rotation of 90° anticlockwise due to the horizontal cut of -% an original higher than wide image. With this operation we simulate a -% rotation of the original image, because it is not allowed to +% an original that was higher than wide image. With this operation we +% simulate a rotation of the original image, because it is not allowed to % simultaneously rotate and trim the original image; the trimming % action apparently cannot be executed together with any other one % among the many other that the |\includegraphics| command can @@ -1101,7 +1186,7 @@ trim = \the\DFhalfwidth\space 0 0 0]}\x{#1}}% % equal halves with the aspect ratio of the paper. If the former % aspect ratio is higher than the latter, the scaling factor is % based on the heights, otherwise on the widths, so as to resize -% both half picture boxes to fit within the page. +% both half picture boxes to fit within the paper. %\item % The |\cleartoeven| command allows to use the main macro even within % a paragraph; in any case it possibly inserts a blanc page and restarts @@ -1122,7 +1207,7 @@ trim = \the\DFhalfwidth\space 0 0 0]}\x{#1}}% % Eventually a |\clearpage| flushes out everything that is still in % the figure stack and possibly restores the vertical or horizontal % typesetting mode depending on the status that was in force when -% the |\DFimage| command or the |DFimage| environment started its +% the |\DFimage| command or the |DFimage| environment started their % expansion. % Due to the size of the images that completely fill up all the % margins, probably the best way to output such huge images is at @@ -1192,11 +1277,276 @@ trim = \the\DFhalfwidth\space 0 0 0]}\x{#1}}% }\clearpage \fptest{\CompStrings{\@currenv}{DFimage}}{}{\egroup}% \reset@tmode} + +% \end{macrocode} +% +%^^A======================================== +%\subsection{The \cs{THfigure} macro for the Total Height figure} +%^^A======================================== +% This Total Height display mode exploit the total paper height to +% scale a figure and sets the image close to the spine independently +% from the fact that the spine ins on the right of even numbered +% pages, and on the left on odd numbered ones; a test is made on the +% page parity, that in any case is going to contain only the figure +% with its caption and nothing else. For this reason the macro provides +% a \cs{cleartopage} at the beginning and another similar command on the +% end. As usual this macro is not supposed to be used by the user, +% who should use the command \cs{DFimage}; using the environment +% is recommended if it is used within a paragraph, but it should not +% include any text. +% +% The full syntax is the following: +%\begin{ttsyntax}\setfontsize{9.25}% +%\cs{FSimage}\marg{image file name}\oarg{lof entry}\marg{caption text}\oarg{label string} +%\qquad\parg{caption width percent}\aarg{line correction}\barg{width text}!\meta{precaption}! +%\end{ttsyntax} +% although the last three arguments are not used. +% +% All the code before the first \cs{cleartopage} command is used to +% examine the dimensions of the original image, and to perform the +% necessary assignments to the various dimensions and boxes. The +% test on the relationship between the \cs{DFwidth} image width and +% the sum of the text and internal margin widths is to compute the +% caption measure and assign the result to the dimension +% register \cs{TScaptionwidth}; this width is tested to control if it +% is too small; in case a warning message is issued. +% +% The following question is natural: When is this display mode +% convenient? After all, also the \texttt{VS} display mode applies +% to tall and slim images, so this \texttt{TH} mode and the other +% \texttt{VS} mode are in competition. In a way they are, but their +% results are very different; The latter mode produces images non +% larger than half the test block and not taller than the text block. +% The former mode produces images that are taller than the text block +% and possibly larger than the text block. Therefore this is one of +% the possible criteria to chose which display mode is more suitable +% for a given image. another other criterion deals with the image aspect +% ratio and the available space aspect ratio; since the height of the +% \texttt{TH} scaled image is fixed, the user should pay attention to +% its width; the scaled image width, in facts, should not exceed the +% sum of the internal margin width and the test block one, otherwise +% the space for the caption becomes too small and a warning message +% is issued. At the same time if the scaled image width is smaller +% than approximately one half of the text width plus the internal +% margin one, the space remaining for the caption becomes too large. +% +% After that the |figure| environment is coded starting with +% the control on the page parity; depending on this parity different +% dirty tricks with several kinds of boxes are performed so as to +% set into the page a huge block that fills all the available vertical +% space on the paper; the parity influences the order in which the various +% embedded boxes interact with one another, but the main point is +% that the box containing the caption must be on the external side +% of the box containing the image; its measure may be fine tuned +% (increased or reduced) with respect to available white space; the +% argument \meta{caption width percent} delimited by round parentheses +% by default equals 0.8, but the user can specify a different value +% to the selector macro, so that the caption measure is that specified +% percentage of the computed caption width. +% +% After closing the |figure| environment a final \cs{clearpage} is +% issued so that the figures stack remains completely empty; in +% particular the current figure is output, but the initial typesetting +% mode is restored, so that if the environment was specified in the +% middle of a paragraph the paragraph continues to be typeset without +% problems; of course if the environment is followed by a blanc line, +% such settings become ineffective because a new paragraph is started. +% The end of the \cs{DFimage} command provides to close the group, +% therefore all the assignments to the various registers are restored. +% \begin{macrocode} +\NewDocumentCommand\THfigure{m o m o d() d<> d|| d!!}{% + \setbox\DFtotalimage=\hbox{\includegraphics{#1}}% + \DFheight=\ht\DFtotalimage \DFwidth=\wd\DFtotalimage + \edef\DFscalefactor{\fpeval{\paperheight/\DFheight}} + \setbox\DFimageI\hbox{% + \scalebox{\DFscalefactor}{\usebox{\DFtotalimage}}}% + \DFwidth=\wd\DFimageI + \ifdim\dimexpr\paperwidth-\DFwidth < 2\externalmargin\relax + \PackageWarning{swfigure}{% + *******************************************\MessageBreak + Figure #1 is too wide to be set in a \MessageBreak + Total Height display mode. \MessageBreak + There is not enough space for its caption. \MessageBreak + Expect questionable results. \MessageBreak + *******************************************\MessageBreak}% + \fi + \FigSpace=\DFwidth + \dimen10=\dimexpr\topmargin+1in-(\paperheight-\headsep-\headheight + -\textheight-\footskip)/2\relax + \TScaptionwidth=\dimexpr\paperwidth-\FigSpace-3\columnsep\relax + \cleartopage + \thispagestyle{empty}% + \begin{figure} + \ifodd\c@page\relax% odd page + \begin{minipage}[c][\textheight][t]{\textwidth}% minibox1 + \vspace*{\dimen10}% + \makebox[\textwidth][l]{\hspace*{-\internalmargin}% hbox2 + \vbox to\textheight{\vss% vbox3 + \hbox to\paperwidth{% hbox4 + \parbox{\FigSpace}{\box\DFimageI}% + \hspace{\columnsep}% + \makebox[\TScaptionwidth]{% + \parbox{#5\TScaptionwidth}{% + \caption[#2]{#3}\IfValueT{#4}{\label{#4}}\relax}% + }% + }% end hbox4 + \vss}% end vbox3 + }% end hbox2 + \end{minipage}% end minibox1 + \else % even page + \begin{minipage}[c][\textheight][t]{\textwidth} + \vspace*{\dimen10}% + \makebox[\textwidth][l]{\kern-\externalmargin + \vbox to\textheight{\vss + \hbox to\paperwidth{\hss + \hbox to\TScaptionwidth{\hss + \parbox{#5\TScaptionwidth}{% + \caption[#2]{#3}\IfValueT{#4}{\label{#4}}\relax}% + }\hspace{\columnsep}% + \parbox{\FigSpace}{\box\DFimageI}% + }\vss + }% + }% + \end{minipage}% + \fi + \end{figure}% + \clearpage\reset@tmode +} % \end{macrocode} +% +%^^A======================================== +%\subsection{The \texttt{TW} for the Total Width +% image plus its side caption} +%^^A======================================== +% This particular mode is a variant of the \texttt{FH} full height mode, +% where scaling of a not sufficiently narrow image, may produce a figure +% that does not exceed the page dimesions, but that might leave such a +% small narrow strip of white space to typeset the caption that it comes +% out as a very poorly typeset object. This other \texttt{TW} does not +% have this drawback, but it might produce figures that exceed the paper +% height in order to remain within the preset limits foreseen for a nicely +% typeset side caption. +% +% Some details are pretty delicate, but let us start from the beginning. +% The seven code lines afterthe first one, are the usual lines similar +% to those at the beginning of the other macros; The original image is +% stored in a box, from which all possible metric informations are derived +% and the scaling factor is computed; afterward the boc is scaled +% according to the computed scaling factor, and re-stored into the +% same box. +% +% Command |\cleartopage| behaves as usual and sets the |\if@SWtmode| +% so as to be able to restore the typesetting modo (horizontal or +% vertical) at the end of this macro expansion. This means, also, +% that for this display mode both the command and the homonymous +% environment |DFimage| may be used. +% +% The page style is set to |empty|, so that the full width block may +% be set flush to the top of the paper, without overwriting any page +% decoration; even the possible folio in the bottom margin is not +% overwritten onto the image. +% +% The test for the parity of the folio number is taken; the true and +% the false branches are very similar, bat the actions that differ +% because depend on the folio parity are interspersed between the +% other code lines. This is why two |figure|environments are defined, +% even if their contents is pretty similar. +% +% We comment the true branch for odd numbered figures, and with slight +% changes they equal those for the even numbered page; Therefore we +% omit the latter. +% +% We box the figure and the caption into an |\hbox| named |\DFimageII|; +% the image box |\DFimageI| si typeset inside a |\parbox| were the measure +% is specified as the boxed image width. The |\parbox| as well as the +% following |minipage| environment are but vertically centred, so that +% we are sure that the caption median will coincide with that of the +% boxed image. As you see the caption is at the right of the boxed +% image, and in an odd numbered page the caption is close and partially +% over the external margin; the opposite takes place for the even +% numbered pages, and again the caption is close or over such page +% external margin. +% +% We can now measure the various geometric properties of the image-caption +% block; notice that his block is large as the internal margin plus +% spaces plus the caption for a total of |\paperwidth|. We should +% keep this in mind in order to re-box the block into a |\textwidth| +% wide box with the necessary stretch and shrink horizontal glue +% in oder to let it fit the paper width wich is larger that the +% text width + +% Moreover we measure the upper white margin, that is white, because +% of the |empty| page style, but the header box, its separator from +% the text, the |\topmargin| with its 1~inch offset, in order to raise +% the image-caption box to be flush to the upper paper border. +% Now we can fill up a vertical box of the computed height; this box +% is inside the text block, but it must overlap the upper vertical +% space so the real height of this box is smaller than its contents +% and a vertical stretch and shrink glue is necessary. +% Eventually with these nestes vertical and horizontal boxes we can +% output the whole contents and the result is as we expected. +% \begin{macrocode} +\NewDocumentCommand\TWfigure{m o m o d() d<> d|| d!!}{% + \setbox\DFtotalimage=\hbox{\includegraphics{#1}}% + \DFheight=\ht\DFtotalimage \DFwidth=\wd\DFtotalimage + \FigSpace=\dimexpr\internalmargin+0.80\textwidth\relax + \TScaptionwidth=\dimexpr\paperwidth-\FigSpace-2\columnsep\relax + \edef\DFscalefactor{\fpeval{\FigSpace/\DFwidth}} + \setbox\DFimageI=\hbox{\scalebox{\DFscalefactor}{\box\DFtotalimage}} + \DFwidth=\wd\DFimageI \DFheight\ht\DFimageI + \cleartopage + \thispagestyle{empty}% + \ifodd\value{page}% odd numbered page + \begin{figure} + \setbox\DFimageII=\hbox{% + \parbox{\FigSpace}{\box\DFimageI}\hspace{\columnsep}% + \begin{minipage}{\TScaptionwidth}\centering + \parbox{#5\hsize}{\caption[#2]{#3}% + \IfValueT{#4}{\label{#4}}\relax}% + \end{minipage} + }% + \DFheight=\ht\DFimageII \dimen8=\dp\DFimageII + \advance\DFheight by\dp\DFimageII + \dp\DFimageII=\z@ \ht\DFimageII=\DFheight + \dimen10=\fpeval{\topskip+1in+\headheight+\headsep}\p@ + \advance\dimen8 by\baselineskip + \advance\DFheight by-\dimen10\relax + \vbox to\DFheight{\vss + \hbox{\raise \dimen8\hbox to\textwidth{% + \hspace{-\internalmargin}\box\DFimageII\hss}}% + }% + \end{figure} + \else% even numbered page + \begin{figure} + \setbox\DFimageII=\hbox{% + \begin{minipage}{\TScaptionwidth}\centering + \parbox{#5\hsize}{\caption[#2]{#3}% + \IfValueT{#4}{\label{#4}}\relax}% + \end{minipage} + \hspace{\columnsep}% + \parbox{\FigSpace}{\box\DFimageI} + }% + \DFheight=\ht\DFimageII \dimen8=\dp\DFimageII + \advance\DFheight by\dp\DFimageII + \dp\DFimageII=\z@ \ht\DFimageII=\DFheight + \dimen10=\fpeval{\topskip+1in+\headheight+\headsep}\p@ + \advance\dimen8 by\baselineskip + \advance\DFheight by-\dimen10\relax + \vbox to\DFheight{\vss + \hbox{\raise \dimen8\hbox to\textwidth{\hss% + \box\DFimageII\hspace{-\internalmargin}}}% + }% + \hbox to\textwidth{\hspace{-\internalmargin}\box\DFimageII\hss} + \end{figure}% + \fi + \reset@tmode +} + +% \end{macrocode} +% %\vspace*{2\baselineskip} %\noindent\makebox[\textwidth]{\setfontsize{10mm} %\color{red} HAPPY \LaTeX-ing} -%\endinput %\iffalse %</package> %\fi @@ -1205,31 +1555,4 @@ trim = \the\DFhalfwidth\space 0 0 0]}\x{#1}}% % %\endinput % -%\iffalse -%<*readme> -%\fi -% \begin{macrocode} -This bundle contains file the swfigure.dtx and README.txt files. -This file README.txt contains the licence, the status, and some -general information. Save both in a .../source/latex/swfigure -folder either in the main TeX system tree or in your personal -tree. - -This swfigure.dtx file is a self extracting documented one. -Run pdfLaTeX at least twice on this file in order to get all -references correct, and you obtain the swfigure.pdf and the -swfigure.sty files. After extraction move the .sty file to -the .../tex/latex/swfigure folder, and move the .pdf file to -the .../doc/latex/swfigure folder. From the original folder -.../source/latex/swfigure move all files, except the .dtx and -the .txt files, to the bin. - -The author disclaims any liability from every possible inconvenience -deriving from the use of this software; you use it at your own risk. - -% \end{macrocode} -%\iffalse -%</readme> -%\fi % -%
\ No newline at end of file diff --git a/Master/texmf-dist/tex/latex/swfigure/swfigure.sty b/Master/texmf-dist/tex/latex/swfigure/swfigure.sty index dcadb523c24..f63332322e5 100644 --- a/Master/texmf-dist/tex/latex/swfigure/swfigure.sty +++ b/Master/texmf-dist/tex/latex/swfigure/swfigure.sty @@ -11,7 +11,7 @@ %% \NeedsTeXFormat{LaTeX2e}[2020/01/01] \ProvidesPackage{swfigure}% - [2020-11-10 v.0.9.14 Managing large and spread wide figures] + [2020-12-23 v.0.9.18 Managing large and spread wide figures] \RequirePackage{etoolbox} \RequirePackage{xfp} @@ -31,8 +31,6 @@ \ExplSyntaxOff -\RequirePackage{trace} - \RequirePackage{graphicx} \RequirePackage{afterpage} \RequirePackage{wrapfig} @@ -49,6 +47,7 @@ \newdimen\DFheight \newdimen\DFhalfheight \newdimen\FigSpace +\newdimen\TScaptionwidth \def\SWcaptionShift{1em}% \def\FScaptionShift{2em}% \newsavebox\DFtotalimage @@ -65,7 +64,7 @@ \addcontentsline{lof}{figure}{\protect\numberline{\thefigure}#1} \IfValueT{#3}{\label{#3}}\relax% } -\NewDocumentCommand\DFcaptionP{O{#2} m o D!!{black}}% +\NewDocumentCommand\DFcaptionP{O{#2} m o D!!{\color{black}}}% {\refstepcounter{figure}% \vbox to 0pt{\vss\hsize=\textheight\parindent=0pt\leavevmode #4\relax Figure \thefigure\quad #2}% @@ -79,7 +78,7 @@ \@SWtmodefalse \else \unskip\@SWtmodetrue\linebreak - \vadjust{\vspace{0pt plus1fill}\newpage}% + \vadjust{\vspace{0pt plus1fill}\par}% \fi} \newcommand\reset@tmode{\if@SWtmode\expandafter\noindent\ignorespaces\fi} @@ -89,10 +88,12 @@ \ifodd\c@page\afterpage{#1}\else#1\fi% } +\newcommand\cleartopage{\set@tmode@newpage\clearpage} + \NewDocumentEnvironment{DFimage}% - {O{SW} m O{#4} m o D(){0.8} D<>{0} D||{0.25} D!!{}}% + { O{SW} m O{#4} m o D(){0.8} D<>{0} D||{0.25} D!!{} }% {% - \SetList{\DisplayModeList}{SW,HS,VS,FS,NF,RF}% + \SetList{\DisplayModeList}{SW,HS,VS,FS,NF,RF,TH,TW}% \TestList{\DisplayModeList}{#1}% {\csuse{#1figure}{#2}[#3]{#4}[#5](#6)<#7>|#8|!#9!% \fptest{\CompStrings{\@currenv}{DFimage}}{}{\reset@tmode}% @@ -105,13 +106,13 @@ \aftergroup\reset@tmode }% -\NewDocumentCommand\DFwarning{ o m o m o d() d<> d|| d!!}% -{\PackageWarning{swfigure}% +\NewDocumentCommand\DFwarning{ o m o m }{% +\PackageWarning{swfigure}% {********************************************\MessageBreak Option #1\space is not valid. Nothing done \MessageBreak \MessageBreak Image #2 was not processed \MessageBreak - *******************************************\MessageBreak + ********************************************\MessageBreak }% } @@ -176,22 +177,22 @@ trim = \the\DFhalfwidth\space 0 0 0]}\x{#1}}% \DFwidth=\wd\DFtotalimage \DFheight=\ht\DFtotalimage \edef\VS@aspectratio{\fpeval{\DFheight/\DFwidth}} \fptest{ \VS@aspectratio < 2 }% - {\begin{center}\ttfamily + {\begin{center}\ttfamily\relax ===========================================\\ - Image \textit{#1} is not tall enough.\\ - Consider using a display mode different\\ + Image #1 is not tall enough. \\ + Consider using a display mode different \\ from VS; may be NF or RF are better suited.\\ ===========================================\\ - Nothing done!\\ + Nothing done! \\ =========================================== \end{center} }% {\edef\VS@factor{\fpeval{#5\textheight/\DFheight}}% \fptest{\VS@factor>1 || \VS@factor\DFwidth < #7\textwidth}% {% - \begin{center}\ttfamily + \begin{center}\ttfamily\relax =================================================\\ - The scaled image \textit{#1} is too slim. \\ + The scaled image #1 is too slim. \\ Maybe directly using the wrapfig package might \\ solve this problem. \\ =================================================\\ @@ -250,6 +251,7 @@ trim = \the\DFhalfwidth\space 0 0 0]}\x{#1}}% }% }% } + \NewDocumentCommand\FSfigure{m o m o d() d<> d|| d!!}{% \fptest{\CompStrings{\@currenv}{DFimage}}{}{\bgroup}% \pagestyle{empty}% @@ -312,6 +314,122 @@ trim = \the\DFhalfwidth\space 0 0 0]}\x{#1}}% }\clearpage \fptest{\CompStrings{\@currenv}{DFimage}}{}{\egroup}% \reset@tmode} + +\NewDocumentCommand\THfigure{m o m o d() d<> d|| d!!}{% + \setbox\DFtotalimage=\hbox{\includegraphics{#1}}% + \DFheight=\ht\DFtotalimage \DFwidth=\wd\DFtotalimage + \edef\DFscalefactor{\fpeval{\paperheight/\DFheight}} + \setbox\DFimageI\hbox{% + \scalebox{\DFscalefactor}{\usebox{\DFtotalimage}}}% + \DFwidth=\wd\DFimageI + \ifdim\dimexpr\paperwidth-\DFwidth < 2\externalmargin\relax + \PackageWarning{swfigure}{% + *******************************************\MessageBreak + Figure #1 is too wide to be set in a \MessageBreak + Total Height display mode. \MessageBreak + There is not enough space for its caption. \MessageBreak + Expect questionable results. \MessageBreak + *******************************************\MessageBreak}% + \fi + \FigSpace=\DFwidth + \dimen10=\dimexpr\topmargin+1in-(\paperheight-\headsep-\headheight + -\textheight-\footskip)/2\relax + \TScaptionwidth=\dimexpr\paperwidth-\FigSpace-3\columnsep\relax + \cleartopage + \thispagestyle{empty}% + \begin{figure} + \ifodd\c@page\relax% odd page + \begin{minipage}[c][\textheight][t]{\textwidth}% minibox1 + \vspace*{\dimen10}% + \makebox[\textwidth][l]{\hspace*{-\internalmargin}% hbox2 + \vbox to\textheight{\vss% vbox3 + \hbox to\paperwidth{% hbox4 + \parbox{\FigSpace}{\box\DFimageI}% + \hspace{\columnsep}% + \makebox[\TScaptionwidth]{% + \parbox{#5\TScaptionwidth}{% + \caption[#2]{#3}\IfValueT{#4}{\label{#4}}\relax}% + }% + }% end hbox4 + \vss}% end vbox3 + }% end hbox2 + \end{minipage}% end minibox1 + \else % even page + \begin{minipage}[c][\textheight][t]{\textwidth} + \vspace*{\dimen10}% + \makebox[\textwidth][l]{\kern-\externalmargin + \vbox to\textheight{\vss + \hbox to\paperwidth{\hss + \hbox to\TScaptionwidth{\hss + \parbox{#5\TScaptionwidth}{% + \caption[#2]{#3}\IfValueT{#4}{\label{#4}}\relax}% + }\hspace{\columnsep}% + \parbox{\FigSpace}{\box\DFimageI}% + }\vss + }% + }% + \end{minipage}% + \fi + \end{figure}% + \clearpage\reset@tmode +} + +\NewDocumentCommand\TWfigure{m o m o d() d<> d|| d!!}{% + \setbox\DFtotalimage=\hbox{\includegraphics{#1}}% + \DFheight=\ht\DFtotalimage \DFwidth=\wd\DFtotalimage + \FigSpace=\dimexpr\internalmargin+0.80\textwidth\relax + \TScaptionwidth=\dimexpr\paperwidth-\FigSpace-2\columnsep\relax + \edef\DFscalefactor{\fpeval{\FigSpace/\DFwidth}} + \setbox\DFimageI=\hbox{\scalebox{\DFscalefactor}{\box\DFtotalimage}} + \DFwidth=\wd\DFimageI \DFheight\ht\DFimageI + \cleartopage + \thispagestyle{empty}% + \ifodd\value{page}% odd numbered page + \begin{figure} + \setbox\DFimageII=\hbox{% + \parbox{\FigSpace}{\box\DFimageI}\hspace{\columnsep}% + \begin{minipage}{\TScaptionwidth}\centering + \parbox{#5\hsize}{\caption[#2]{#3}% + \IfValueT{#4}{\label{#4}}\relax}% + \end{minipage} + }% + \DFheight=\ht\DFimageII \dimen8=\dp\DFimageII + \advance\DFheight by\dp\DFimageII + \dp\DFimageII=\z@ \ht\DFimageII=\DFheight + \dimen10=\fpeval{\topskip+1in+\headheight+\headsep}\p@ + \advance\dimen8 by\baselineskip + \advance\DFheight by-\dimen10\relax + \vbox to\DFheight{\vss + \hbox{\raise \dimen8\hbox to\textwidth{% + \hspace{-\internalmargin}\box\DFimageII\hss}}% + }% + \end{figure} + \else% even numbered page + \begin{figure} + \setbox\DFimageII=\hbox{% + \begin{minipage}{\TScaptionwidth}\centering + \parbox{#5\hsize}{\caption[#2]{#3}% + \IfValueT{#4}{\label{#4}}\relax}% + \end{minipage} + \hspace{\columnsep}% + \parbox{\FigSpace}{\box\DFimageI} + }% + \DFheight=\ht\DFimageII \dimen8=\dp\DFimageII + \advance\DFheight by\dp\DFimageII + \dp\DFimageII=\z@ \ht\DFimageII=\DFheight + \dimen10=\fpeval{\topskip+1in+\headheight+\headsep}\p@ + \advance\dimen8 by\baselineskip + \advance\DFheight by-\dimen10\relax + \vbox to\DFheight{\vss + \hbox{\raise \dimen8\hbox to\textwidth{\hss% + \box\DFimageII\hspace{-\internalmargin}}}% + }% + \hbox to\textwidth{\hspace{-\internalmargin}\box\DFimageII\hss} + \end{figure}% + \fi + \reset@tmode +} + %% %% Distributable under the LaTeX Project Public License, %% version 1.3c or higher (your choice). The latest version of |