swfigure (23dec20)

git-svn-id: svn://tug.org/texlive/trunk@57211 c570f23f-e606-0410-a88d-b1316a301751

10 files changed, 120 insertions, 69 deletions

diff --git a/Master/texmf-dist/doc/latex/swfigure/DFscreenshotA3.png b/Master/texmf-dist/doc/latex/swfigure/DFscreenshotA3.png
deleted 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
new 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
index 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
new 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
deleted 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
new 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
index 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
index 19dd19dd9a9..d5195dea5e2 100644
--- a/Master/texmf-dist/doc/latex/swfigure/swfigure.pdf
+++ b/Master/texmf-dist/doc/latex/swfigure/swfigure.pdf