summaryrefslogtreecommitdiff
path: root/macros/latex
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex')
-rw-r--r--macros/latex/contrib/apa7/apa7.dtx21
-rw-r--r--macros/latex/contrib/apa7/apa7.pdfbin527794 -> 528179 bytes
-rw-r--r--macros/latex/contrib/apa7/samples/longsample.pdfbin196742 -> 196742 bytes
-rw-r--r--macros/latex/contrib/apa7/samples/shortsample.pdfbin64106 -> 65283 bytes
-rw-r--r--macros/latex/contrib/ccool/ccool.dtx95
-rw-r--r--macros/latex/contrib/ccool/ccool.pdfbin815868 -> 815782 bytes
-rw-r--r--macros/latex/contrib/everypage/README37
-rw-r--r--macros/latex/contrib/everypage/README.md64
-rw-r--r--macros/latex/contrib/everypage/everypage.dtx451
-rw-r--r--macros/latex/contrib/everypage/everypage.ins51
-rw-r--r--macros/latex/contrib/everypage/everypage.pdfbin17714 -> 0 bytes
-rw-r--r--macros/latex/contrib/swfigure/HSfakeimage.jpgbin0 -> 21156 bytes
-rw-r--r--macros/latex/contrib/swfigure/NFfakeimage.jpgbin0 -> 17036 bytes
-rw-r--r--macros/latex/contrib/swfigure/README.txt45
-rw-r--r--macros/latex/contrib/swfigure/RFfakeimage.jpgbin0 -> 24216 bytes
-rw-r--r--macros/latex/contrib/swfigure/SWfakeImage.jpgbin0 -> 31599 bytes
-rw-r--r--macros/latex/contrib/swfigure/VSfakeimage.jpgbin0 -> 26148 bytes
-rw-r--r--macros/latex/contrib/swfigure/swfigure-examples.pdfbin0 -> 531258 bytes
-rw-r--r--macros/latex/contrib/swfigure/swfigure-examples.tex434
-rw-r--r--macros/latex/contrib/swfigure/swfigure.dtx855
-rw-r--r--macros/latex/contrib/swfigure/swfigure.pdfbin0 -> 452825 bytes
21 files changed, 1857 insertions, 196 deletions
diff --git a/macros/latex/contrib/apa7/apa7.dtx b/macros/latex/contrib/apa7/apa7.dtx
index b81d61d094..31ec9cb98b 100644
--- a/macros/latex/contrib/apa7/apa7.dtx
+++ b/macros/latex/contrib/apa7/apa7.dtx
@@ -4,11 +4,11 @@
% %
% CHANGE THESE VALUES WITH EACH NEW RELEASE: %
% %
-%<class>\ProvidesClass{apa7}[2020/08/12 v2.03 APA formatting (7th edition)]
+%<class>\ProvidesClass{apa7}[2020/10/11 v2.04 APA formatting (7th edition)]
% %
%<*internal> %
-\def\apaSevenVersionDate{2020/08/12}
-\def\apaSevenVersionNumber{2.03}
+\def\apaSevenVersionDate{2020/10/11}
+\def\apaSevenVersionNumber{2.04}
% %
% %
% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@@ -255,6 +255,8 @@ and the derived files apa7.ins,
%
% \changes{v2.03}{2020/08/12}{Added French localization. }
%
+% \changes{v2.04}{2020/10/11}{Updated ORCID link style for jou mode. }
+%
% \begin{abstract}
% The \textit{Publication Manual} of the American Psychological
% Association is widely used in the social sciences. The most
@@ -2743,6 +2745,11 @@ and the derived files apa7.ins,
\@ifundefined{def@jou}{}{%
+\renewcommand{\addORCIDlink}[2]{\href{https://orcid.org/#2}{{\mbox{\scalerel*{
+\begin{tikzpicture}[yscale=-1,transform shape]
+\pic{orcidlogo};
+\end{tikzpicture}
+}{|}}} #1}}
%========== balance last-page columns =================
@@ -3387,7 +3394,7 @@ and the derived files apa7.ins,
\title{Sample APA-Style Document Using the \textsf{apa7} Package}
\authorsnames{Daniel A. Weiss}
-\authorsaffiliations{A University Somewhere}
+\authorsaffiliations{Departement of Psychology, A University Somewhere}
\leftheader{Weiss}
@@ -3398,6 +3405,10 @@ and the derived files apa7.ins,
\keywords{APA style, demonstration}
+\authornote{\addORCIDlink{Daniel A. Weiss}{0000-0000-0000-0000}, Department of Psychology, A University Somewhere
+
+Changes of Affiliations and other info here to describe what needs to be said}
+
\begin{document}
\maketitle
We begin with \textcite{Shotton1989}. We can also cite this work in
@@ -3410,7 +3421,7 @@ Method section.
\subsection{Participants}
We had a lot of people in this study, show in Figure \ref{fig:Figure1}.
-\begin{figure}[htbp]
+\begin{figure}[!htp]
\caption{This is my figure caption.}
\includegraphics[bb=0in 0in 2.5in 2.5in, height=1.4in, width=1.4in]{Figure1.pdf}
\figurenote{This is an awesome figure.}
diff --git a/macros/latex/contrib/apa7/apa7.pdf b/macros/latex/contrib/apa7/apa7.pdf
index d38e5802c1..48cbdad488 100644
--- a/macros/latex/contrib/apa7/apa7.pdf
+++ b/macros/latex/contrib/apa7/apa7.pdf
Binary files differ
diff --git a/macros/latex/contrib/apa7/samples/longsample.pdf b/macros/latex/contrib/apa7/samples/longsample.pdf
index 841fc1b02f..a306e58e99 100644
--- a/macros/latex/contrib/apa7/samples/longsample.pdf
+++ b/macros/latex/contrib/apa7/samples/longsample.pdf
Binary files differ
diff --git a/macros/latex/contrib/apa7/samples/shortsample.pdf b/macros/latex/contrib/apa7/samples/shortsample.pdf
index 57c1868a5b..12717d7dde 100644
--- a/macros/latex/contrib/apa7/samples/shortsample.pdf
+++ b/macros/latex/contrib/apa7/samples/shortsample.pdf
Binary files differ
diff --git a/macros/latex/contrib/ccool/ccool.dtx b/macros/latex/contrib/ccool/ccool.dtx
index a58f11a00c..933183883d 100644
--- a/macros/latex/contrib/ccool/ccool.dtx
+++ b/macros/latex/contrib/ccool/ccool.dtx
@@ -75,16 +75,48 @@ ccool.sty, and ccool.pdf.
%<package> \RequirePackage{xparse}[2020/03/06]
%<package> \ProvidesExplPackage
%<package> {ccool} % Package name
-%<package> {2020/06/04} % Release date
-%<package> {3.0} % Release version
+%<package> {2020/10/10} % Release date
+%<package> {3.1} % Release version
%<package> {cool --- A key-value document command parser} % Description
%
%<*driver>
-\RequirePackage{fvextra}%^^A\NB{done}{Warning:csquotes should be loaded after fvextra->nope}
+\RequirePackage{fvextra, xparse}%^^A\NB{done}{Warning:csquotes should be loaded after fvextra->nope}
\documentclass[full, show-notes]{l3doc}
\listfiles
-\usepackage{amsmath, amssymb}
-\usepackage[
+%^^A\usepackage{xparse, longtable, array, booktabs}
+\ExplSyntaxOn
+\clist_new:N \g__ccooldoc_usepackage_clist
+\cs_new_protected:Nn \__ccooldoc_usepackage:n
+{
+ \clist_put_right:Nn \g__ccooldoc_usepackage_clist
+ {
+ \textbackslash{}usepackage\char`{ #1 \char`}
+ }
+ \usepackage{#1}
+}
+\cs_new_protected:Nn \__ccooldoc_usepackage:nn
+{
+ \clist_put_right:Nn \g__ccooldoc_usepackage_clist
+ {
+ {
+ \textbackslash{}
+ usepackage
+ \char`[ #1 \char`]
+ \char`{ #2 \char`}
+ }
+ }
+ \usepackage[#1]{#2}
+}
+\cs_new:Nn \__ccooldoc_usepackage:
+{
+ \texttt
+ {
+ \noindent
+ \clist_use:Nnnn \g__ccooldoc_usepackage_clist { \\ } { \\ } { \\ }
+ }
+}
+\__ccooldoc_usepackage:n{amsmath, amssymb}
+\__ccooldoc_usepackage:nn{
%^^A afrikaans,
%^^A basque,
%^^A catalan,
@@ -119,13 +151,11 @@ spanish.noquoting,
%^^A turkmen,
%^^A welsh,
english
-]{babel}
-\usepackage{bookmark}
-\usepackage{ccool}
-\usepackage[T1]{fontenc}% \char`[
-\usepackage{microtype}
-\usepackage{tabto}
-\usepackage{tcolorbox}
+}
+{babel}
+\__ccooldoc_usepackage:n{bookmark, ccool, microtype, tabto, tcolorbox}
+\__ccooldoc_usepackage:nn{T1}{fontenc}% \char`[
+ \ExplSyntaxOff
\tcbuselibrary{listings, breakable}
\makeatletter
\newcommand*{\docsetnameref}{\def\@currentlabelname}%https://tex.stackexchange.com/questions/537751
@@ -214,7 +244,8 @@ english
\providecommand\pkgoptex{\docarg{Expans}}
\providecommand\pkgoptfi{\docarg{File}}
\providecommand\pkgoptin{\docarg{Inner}}
-\providecommand\pkgoptions{kvl0}
+%^^A\providecommand\pkgoptions{kvl0}
+\providecommand\pkgoptions{\doccceptkvl$_0$}
\providecommand\pkgoptou{\docarg{Outer}}
\providecommand\pkgoptpad{\docarg{Default}}%default
\providecommand\pkgoptpa{\docarg{Param}}
@@ -224,8 +255,8 @@ english
\providecommand\pkgparex{\texttt{*}}%expand
\providecommand\pkgparhe{tl$_{1}$}%head
\providecommand\pkgparin{code$_{1}$}%inner
-\providecommand\pkgparkvlnxt{kvl$_{2}$}
-\providecommand\pkgparkvl{kvl$_{1}$}
+\providecommand\pkgparkvl{\doccceptkvl$_1$}
+\providecommand\pkgparkvlnxt{\doccceptkvl$_2$}
\providecommand\pkgparou{code$_{2}$}%outer
\providecommand\pkgparpa{tl$_{2}$}%param
\providecommand\pkgparsiii{tl$_{5}$}
@@ -273,8 +304,7 @@ english
% \selectlanguage{french}
% \begin{docabstract}{Résumé}
% L'extension~\pkg{ccool} pour \LaTeX~met à disposition une interface de type \textit{clé-valeur}, \nameref{usage:cs:ccool},
-% destinée à faciliter la géneration de commandes. Les
-% paramètres globaux contrôlant le traitement de ces \textit{clé-valeur} sont fixés
+% destinée à faciliter la géneration de commandes. Les paramètres globaux contrôlant le traitement de ces \textit{clé-valeur} sont fixés
% par défaut pour répondre aux besoins courants, suivant le contexte (langage, mode textuel ou mathématique).
% Un exemple d'application, est la command-isation des conventions de notation (\docexpand{\cs{Reel}}{} |\mathbb{R}|),
% au point dans le \env{document} où elles sont introduites (``Soit~$\mathbb{R}$~les nombres réels.'').
@@ -295,8 +325,8 @@ english
% \addcontentsline{toc}{section}{\protect\numberline{\thesection}Convention}
% \section*{Convention}
% \begin{enumerate}[label={\emph{\alph*)}}]
-% \item \label{conv:expl3} Loosely, those of \cite{interface3}, for example as to the meaning of \meta{\docccepttl}.
-% \item \label{conv:xparse} Those of \cite{xparse}, for example \docparo{arg} is a \docccept{\docxparseo}.
+% \item \label{conv:expl3} Loosely, those of \cite{interface3}, for example as to the meaning of \docccept{\docccepttl}, which may be abbreviated \docccept{tl}.
+% \item \label{conv:xparse} Those of \cite{xparse}, for example \docparo{arg} is an \docccept{\docxparseo}.
% \item \docassign{\meta{X}}{\docarg{Y}}: set \meta{X} to |Y|
% \item \docexpand{\cs{X}}{\docarg{Y}}: \cs{X} expands to |Y|
% \item If unspecified, the environment in which a macro is to be used is \docenvdoc.
@@ -439,7 +469,7 @@ english
% \nameref{usage:opt:se},
% and \nameref{usage:opt:wr}.
% \begin{description}
-% \item[Semantics] Modify the behavior of \nameref{usage:cs:ccool}
+% \item[Semantics] Modify the default behavior of \nameref{usage:cs:ccool}
% \end{description}
% \end{function}
%
@@ -458,7 +488,7 @@ english
% \item[Syntax] \texttt{eo\docpipe{}ee\docpipe{}ex\docpipe{}xo\docpipe{}xe\docpipe{}xx}
% \end{description}
%
-% \DocPhantomSection{subsection}{\pkgoptfi}{usage:opt:fi}
+% \DocPhantomSection*{subsection}{\pkgoptfi}{usage:opt:fi}
% \DescribeOption{\pkgoptfi}
% \begin{description}
% \item[Also see] \autoref{part:usage}~\nameref{ccool:wr} and \autoref{part:impl}~\nameref{impl:opt:fi}
@@ -606,6 +636,21 @@ english
%</guardlisting>
% \fi
%
+% \phantomsection\addcontentsline{toc}{section}
+% {\ref{listing:thisdeps}. This doc's dependencies}
+% \iffalse
+%<*guardlisting>
+% \fi
+\begin{listing}[This doc's dependencies]
+ {label=listing:thisdeps}
+ \ExplSyntaxOn
+ \__ccooldoc_usepackage:
+ \ExplSyntaxOff
+\end{listing}
+% \iffalse
+%</guardlisting>
+% \fi
+%
% \phantomsection\addcontentsline{toc}{section}
% {\ref{listing:numbrsys:base}. \texorpdfstring{Let~$\mathbb{N}$ and $\mathbb{R}$ denote\dots} (start of the tutorial)}
% \iffalse
@@ -813,7 +858,7 @@ english
% \fi
\begin{listing}[Language and mode]
{label=listing:lang}
- %^^A--->
+ % ^^A--->
\textbf{\languagename}{:}~\Ccool{ X = x, Y = y }*
\begin{otherlanguage}{spanish}
\CcoolOption[ Separ ]\\
@@ -893,7 +938,7 @@ english
% \fi
%
% \phantomsection\addcontentsline{toc}{section}
-% {\ref{listing:hw:i}. Hello, world! (testing)}
+% {\ref{listing:hw:i}. Hello, world! (for testing's sake)}
% \iffalse
%<*guardlisting>
% \fi
@@ -1594,6 +1639,10 @@ english
% {2020/06/04}
% {Miscellaneous }
%
+% \changes{\docvers{3}{1}}
+% {2020/10/10}
+% {Replaced: \doclist{thisdeps}'s content, from exhaustive dependencies to those explicit with \cs{usepackage}}
+%
% \PrintChanges
% \PrintIndex
% \clearpage
diff --git a/macros/latex/contrib/ccool/ccool.pdf b/macros/latex/contrib/ccool/ccool.pdf
index e39ed031af..b5263ecc37 100644
--- a/macros/latex/contrib/ccool/ccool.pdf
+++ b/macros/latex/contrib/ccool/ccool.pdf
Binary files differ
diff --git a/macros/latex/contrib/everypage/README b/macros/latex/contrib/everypage/README
deleted file mode 100644
index d0a70b4b6c..0000000000
--- a/macros/latex/contrib/everypage/README
+++ /dev/null
@@ -1,37 +0,0 @@
-The everypage package extends LaTeX providing hooks to do actions on every page
-or on the current page. Specifically, actions are performed before the page is
-shipped, so they can be used to put watermarks in the background of a page, or
-to set the page layout. The package reminds in some sense bobhook by Karsten
-Tinnefeld, but it differs in the way in which the hooks are implemented, as
-detailed in the following. In some sense it may also be related to the package
-everyshi by Martin Schroeder, but again the implementation is different.
-
-The "everypage" package is copyright 2006-2007
-by Sergio Callegari <sergio.callegari@gmail.com>
-
-It comprises this README file, as well as files
-everypage.dtx
-everypage.ins
-
-To install the package, run LaTeX on the installation script everypage.ins and
-follow the instructions provided by the script itself.
-
-NOTE:
---------------
-This is version 1.1 of the everypage package.
-Version 1.0 had a bug that caused LaTeX to exceed its capacity or to hang.
-Such behaviour was particularly evident in conjunction with the draftwatermark
-package.
-
-UPGRADE IS RECOMMENDED
-
-
---------------
-
-"everypage" may be distributed and/or modified under the conditions of the
-LaTeX Project Public License, either version 1.3 of this licence, or
-any later version. The latest version of this license is at
-http://www.latex-project.org/lppl.txt and version 1.3 is part
-of all distributions of LaTeX version 2003/06/01 or later.
-
-This work has the LPPL maintenance status "author-maintained".
diff --git a/macros/latex/contrib/everypage/README.md b/macros/latex/contrib/everypage/README.md
new file mode 100644
index 0000000000..6863d49865
--- /dev/null
+++ b/macros/latex/contrib/everypage/README.md
@@ -0,0 +1,64 @@
+# The `everypage` package
+
+## Warning
+
+This package is now in *legacy status*. Functionality similar to that provided
+by this package is directly implemented in LaTeX since its 2020 Fall
+release. Do not use everypage in new documents and do not rely on it in new
+packages or classes of yours.
+
+When running on a pre-2020-10-01 version of LaTeX, `everypage` will now fall
+back to `everypage-1x`, its own past code base.
+
+When running on a modern LaTeX, `everypage` will strive to provide its legacy
+interfaces by using the newer LaTeX facilities. However, full equivalence is
+not possible and breakage may occur. Load `everypage-1x` in place of
+`everypage` if you really want to force usage of the old code base (that might
+keep working for a few more LaTeX release cycles).
+
+
+## Historic behavior
+
+The `everypage` package extends LaTeX providing hooks to do actions on every
+page or on the current page. Specifically, actions are performed before the page
+is shipped, so they can be used to put watermarks in the background of a page,
+or to set the page layout. The package reminds in some sense `bobhook` by
+Karsten Tinnefeld, but it differs in the way in which the hooks are
+implemented, as detailed in the package documentation. In some sense it may
+also be related to the package `everyshi` by Martin Schroeder, but again the
+implementation is different.
+
+The `everypage` package is copyright 2006, 2007, 2020.
+by Sergio Callegari <sergio.callegari@gmail.com>
+
+It comprises this `README.md` file, as well as files
+- `everypage.dtx`
+- `everypage.ins`
+
+To install the package, run LaTeX on the installation script `everypage.ins`
+and follow the instructions provided by the script itself.
+
+
+## Notes
+
+This is version 2.0 of the `everypage` package, suitable for LaTeX releases
+post Fall 2020.
+
+Version 1.2 might keep working for a few more LaTeX release cycles. It is now
+available as `everypage-1x`. It fixed a minor issue with the ordering of
+operations, in version 1.1.
+
+Version 1.1 fixed a bug in version 1.0 that caused LaTeX to exceed its capacity
+or to hang. Such behaviour was particularly evident in conjunction with the
+draftwatermark package.
+
+UPGRADE IS RECOMMENDED
+
+## License
+
+Package `everypage` may be distributed and/or modified under the conditions of
+the LaTeX Project Public License, version 1.3. This license is available at
+http://www.latex-project.org/lppl.txt and is part of all distributions of LaTeX
+version 2003/06/01 or later.
+
+This work has the LPPL maintenance status "author-maintained".
diff --git a/macros/latex/contrib/everypage/everypage.dtx b/macros/latex/contrib/everypage/everypage.dtx
index 02cf2149a3..e390b6b980 100644
--- a/macros/latex/contrib/everypage/everypage.dtx
+++ b/macros/latex/contrib/everypage/everypage.dtx
@@ -1,6 +1,6 @@
% \iffalse meta-comment
%
-% Copyright 2006-2007
+% Copyright 2006-2007, 2020
% Sergio Callegari <sergio.callegari@gmail.com>
%
% ---------------------------------------------
@@ -21,10 +21,12 @@
%
%<*driver>
\documentclass{ltxdoc}
-\usepackage{mathptmx, helvet, courier}
+\usepackage{mathptmx}
+\usepackage[T1]{fontenc}
+\usepackage[scaled=0.92]{helvet}
+% \usepackage{courier}
+\usepackage{hologo}
\EnableCrossrefs
-\DoNotIndex{\def,\gdef,\let,\NeedsTeXFormat,\newcommand}
-\DoNotIndex{\ProvidesPackage,\endinput}
\CodelineIndex
\RecordChanges
\begin{document}
@@ -34,12 +36,19 @@
%
% \fi
%
-% \CheckSum{44}
+% \DoNotIndex{\@ifundefined, \g@addto@macro}
+% \DoNotIndex{\def, \gdef, \let, \newcommand}
+% \DoNotIndex{\MessageBreak, \PackageWarningNoLine, \NeedsTeXFormat}
+% \DoNotIndex{\ProvidesPackage, \RequirePackage}
+% \DoNotIndex{\put}
+% \DoNotIndex{\endinput}
+%
+% \CheckSum{71}
%
% \def\filename{everypage.dtx}
-% \def\fileversion{1.1}
-% \def\filedate{2007/06/20}
-% \def\docdate{2007/06/20}
+% \def\fileversion{2.0}
+% \def\filedate{2020/10/11}
+% \def\docdate{2020/10/11}
%
% \newcommand*{\Lpack}[1]{\textsf {#1}} ^^A typeset a package
% \newcommand*{\Lopt}[1]{\textsf {#1}} ^^A typeset an option
@@ -60,99 +69,322 @@
%
% \maketitle
%
+% \section*{WARNING}
+% \changes{R2.0}{2020/10/11}{Package is now in a `legacy' status.}
+%
+% This package is now in \emph{legacy status}. Functionality similar to
+% that provided by this package has been directly implemented in \LaTeX\
+% since its 2020 Fall release. Do not use \Lpack{everypage} in new
+% documents and do not rely on it in new packages or classes of
+% yours.
+%
+% \smallskip
+% When running on a pre-2020-10-01 version of \LaTeX, \Lpack{everypage}
+% will now fall back to \Lpack{everypage-1x}, its own past
+% code base.\smallskip
+%
+% When running on a modern \LaTeX, \Lpack{everypage} will strive to
+% provide its legacy interfaces by using the newer \LaTeX\ facilities.
+% However, full equivalence is not possible and breakage may occur. When
+% truly needed, try loading \Lpack{everypage-1x} in place of
+% \Lpack{everypage} to force usage of the old code base. This is expected
+% to keep working for a few more \LaTeX\ release cycles after Fall 2020.
+%
+% \bigskip\bigskip
+%
% \begin{abstract}
-% The \Lpack{everypage} package extends \LaTeX\ providing hooks to do
-% actions on every page or on the current page. Specifically, actions
-% are performed \emph{before} the page is shipped, so they can be
-% used to put watermarks \emph{in the background} of a page, or to
-% set the page layout. The package reminds in some sense
-% \Lpack{bobhook} by Karsten Tinnefeld, but it differs in the way in
-% which the hooks are implemented, as detailed in the following.
-% In some sense it may also be related to the package
-% \Lpack{everyshi} by Martin Schroeder, but again the implementation
-% is different.
+% The \Lpack{everypage} package was meant to extend \LaTeX\ providing
+% hooks to do actions on every page or on the current page. Currently,
+% similar functionality is directly provided by \LaTeX. Specifically,
+% \Lpack{everypage} supports actions performed \emph{before} the page is
+% shipped, so they can be used to put watermarks \emph{in the
+% background} of a page, or to set the page layout. The package is in
+% many ways similar to \Lpack{bobhook} by Karsten Tinnefeld, but it
+% differs in the way in which the hooks are implemented. In some sense,
+% it may also be related to package \Lpack{everyshi} by Martin
+% Schroeder, but again the implementation is different.
% \end{abstract}
%
% \section{Introduction}
-%
-% This program adds two \LaTeX\ hooks that get run when document
-% pages are finalized and output to the dvi or pdf
+%
+% Until a recent past, \LaTeX\ provided no explicit hooks to be run as
+% documents pages were finalized and output to the dvi or pdf
+% file. Consequently, many solutions were developed to work around this
+% limitation and to offer features (e.g., watermarks) that would otherwise
+% be impossible. These solution included packages such as
+% \Lpack{everyshi}, \Lpack{bobhook} and \Lpack{watermark}. Package
+% \Lpack{everypage} was a solution providing plumbing that could be used
+% in higher level packages such as \Lpack{draftwatermark} (watermarking)
+% and \Lpack{flippdf} (print preprocessing) to mention a couple of them.
+%
+% All of these extensions relied on applying modifications to some \LaTeX\
+% internals and as such were prone to subtle interactions with other
+% packages and breakage. The situation has been cleared by the 2020 Fall
+% \LaTeX\ release where an official and generic support for hooks has been
+% introduced.
+%
+% As of today, \Lpack{everypage} can be considered obsolete. It needs to
+% remain around because older releases of \LaTeX\ are still in use and
+% legacy code exist that is based on the interfaces it exposes. However,
+% no new document, class or package should be based on it. Furthermore, it
+% can be expected that existing packages that use \Lpack{everypage} will
+% progressively learn to rely directly on the new \LaTeX\ hook mechanism.
+%
+% This manual is meant to aid the transition by showing how
+% \Lpack{everypage} is now being updated to cater both for older and newer
+% \LaTeX\ kernels. Specifically, it illustrates:
+% \begin{enumerate}
+% \item how \Lpack{everypage} is now actually split in two packages:
+% \Lpack{everypage-1x}, providing the old code base; and
+% \Lpack{everypage} itself, that strives to implement the legacy
+% interface on top of the new mechanisms offered by \LaTeX;
+% \item how \Lpack{everypage} can automatically import the old code base
+% as needed, how loading of the latter can be forced (if absolutely
+% needed or for comparison) and for how long the old code can be
+% expected to keep working with newer releases of \LaTeX;
+% \item how the legacy interface of \Lpack{everypage}, once
+% implemented/emulated on top of the new \LaTeX\ facilities actually
+% differs from its nominal behavior.
+% \end{enumerate}
+%
+% \section{The original code base}
+% \label{sec:original}
+% \changes{R1.0}{2006/06/30}{%
+% Initial release.}
+%
+% The original implementation of \Lpack{everypage}, now available as
+% \Lpack{everypage-1x}, adds two \LaTeX\ hooks that get
+% run when document pages are finalized and output to the dvi or pdf
% file. Specifically, one hook gets executed on every page, while the
% other is executed for the current page. Hook actions are are performed
-% \emph{before} the page is output on the medium, and this is
-% important to be able to play with the page layout or to put things
-% \emph{behind} the page contents (e.g., watermarks such as an image,
-% framing, the ``DRAFT'' word, and the like).
-%
-% The package reminds in some sense \Lpack{bobhook} by Karsten
-% Tinnefeld, but it differs in the way in which the hooks are
-% implemented:
+% \emph{before} the page is output on the medium, and this is important to
+% be able to play with the page layout or to put things \emph{behind} the
+% page contents (e.g., watermarks).
+%
+% \subsection{User interface}
+% \label{ssec:ui}
%
+% \DescribeMacro{\AddEverypageHook} The |\AddEverypageHook| command
+% accepts one argument and adds it to the list of hooks that are run
+% before every page is output. Similarly, the
+% \DescribeMacro{\AddThispageHook}|\AddThispageHook| command accepts one
+% argument, however it adds it to the list of hooks that are run before
+% the \emph{current} page is output.
+%
+% The following rules apply:
+%
% \begin{enumerate}
-% \item there is no formatting inherent in the hooks. If one wants to
-% put some watermark on a page, it is his own duty to put in the
-% hook the code to place the watermark in the right position. Also
-% note that the hooks code should \emph{eat up no space} in the
-% page. Again, if the hooks are meant to place some material on the
-% page, it is the duty of the hook programmer to put code in the
-% hooks to pretend that the material has zero width and zero height.
-% The implementation is \emph{lighter} than the \Lpack{bobhook} one,
-% and possibly more flexible, since one is not limited by any
-% pre-coded formatting for the hooks. On the other hand it is
-% possibly more difficult to use. Nonetheless, it is easy to think
-% of other packages relying on \Lpack{everypage} to deliver more
-% user-friendly and \emph{task specific} interfaces. Already there
-% are a couple of them: the package \Lpack{flippdf} produces
-% mirrored pages in a PDF document and \Lpack{draftwatermark}
-% watermarks document pages.
-% \item similarly to \Lpack{bobhook} and \Lpack{watermark}, the
-% package relies on the manipolatoin of the internal \LaTeX\ macro
-% |\@begindvi| to do the job. However, the redefinition of
-% |\@begindvi| is here postponed as much as possible, striving to
-% avoid interference with other packages using |\AtBeginDvi| or
-% anyway manipulating |\@begindvi|. Specifically \Lpack{everypage}
-% makes no special assumption on the initial code that |\@begindvi|
-% might contain.
+% \item once hooks are introduced and stacked in a series, there is no way
+% to unstack them, nor to clear them;
+% \item in order to have hooks that get run only when specific conditions
+% are met, conditionals must be included in the hooks;
+% \item \label{itm:formatting}%
+% there is no formatting inherent in the hooks. If one wants to put some
+% watermark on a page, it is his own duty to put in the hook the code to
+% place the watermark in the right position and with the appropriate
+% appearance and style. When the hooks are run, the page is still empty,
+% so that one begins filling it at point (1\,inch, 1\,inch) from the top
+% left corner;
+% \item \label{itm:nospace}%
+% the hook code should \emph{eat up no space}. This means that hooks
+% meant to place some material on the page, need to have the material
+% placed in a box with zero width and height beforehand.
+% \item no particular assumption is made on the \LaTeX\ output
+% driver, so \Lpack{everypage} should work equally well with \LaTeX,
+% \hologo{pdfLaTeX}, \hologo{LuaLaTeX}, or \hologo{XeLaTeX}. Similarly,
+% the package should work equally well with dvi, dvips, etc.\@ output
+% drivers. Obviously, the final compatibility with the different output
+% drivers depends on the actual code that is placed in the hooks.
% \end{enumerate}
%
-% Also in some sense \Lpack{everypage} can be related to package
-% \Lpack{everyshi} by Martin Schroeder, but it differs radically from
-% it in the implementation. In fact,\Lpack{everypage} operates by
-% manipulation of the |\@begindvi| macro, rather than at the
-% lower level |\shipout| macro.
-%
-% \section{User interface}
-% \DescribeMacro{\AddEverypageHook}\DescribeMacro{\AddThispageHook}
-% The |\AddEverypageHook| accepts one argument and adds it to the list
-% of hooks that are run before every page is output. The
-% |\AddThispageHook| accepts one argument and adds it to the list of
-% hooks that are run before the current page is output.
-%
-% Note that once hooks are stacked, there is no way to unstack them,
-% nor to clear them. In order to have hooks that get run only when
-% specific conditions are met, conditionals must be included in the
-% hooks.
-%
-% Also note that no particular assumption is made on the \LaTeX\
-% output driver, so \Lpack{everypage} should work equally well with
-% \LaTeX\ and pdf\LaTeX. Furthermore, the package should work equally
-% well with dvi, dvips, etc.\@ output drivers. Obviously, the final
-% compatibility with the different output drivers depends on the
-% actual code that is placed in the hooks.
-%
-% For usage examples, please see the \Lpack{flippdf} and
-% \Lpack{draftwatermark} packages.
+% \subsection{Comparison with other packages}
%
+% The purpose of the original code base is better understood by comparing
+% it to other packages that were meant to solve related problems at the
+% time when \LaTeX\ had no hook mechanism of its own:
+%
+% \begin{itemize}
+% \item In comparison with \Lpack{bobhook} by Karsten Tinnefeld,
+% Lpack{everypage} (in its legacy incarnation) used to differ in purpose
+% and in the hook implementation. Package \Lpack{everypage} was meant to
+% make no assumption on what one could want to do on every page, whether
+% to add text, images, or some low-level instruction for the output
+% driver, or even to perform some accounting task. This made the package
+% lighter and more flexible at the cost of being more difficult to
+% use. In other words, \Lpack{everypage} was meant to be more of a
+% plumbing to be employed in higher level packages;
+% \item in comparison with \Lpack{watermark} by Alexander I.~Rozhenko,
+% similar considerations could me made. Specifically, \Lpack{watermark}
+% is explicitly targeted at making it easy to put watermarks on document
+% pages, while \Lpack{everypage} is lower level.
+% \item in comparison to both \Lpack{bobhook} and \Lpack{watermark},
+% \Lpack{everypage} used to employ a similar low level mechanism, by
+% manipulation of the internal \LaTeX\ macro |\@begindvi| to do the
+% job. However, the redefinition of |\@begindvi| in \Lpack{everypage}
+% was postponed as much as possible, striving to avoid interference with
+% other packages using |\AtBeginDvi| or anyway manipulating
+% |\@begindvi|. Furthermore, \Lpack{everypage} made no special
+% assumption on the initial code that |\@begindvi| might contain.
+% \item in comparison with \Lpack{everyshi} by Martin Schroeder,
+% \Lpack{everypage} used to be similarly low level, but relied on
+% changing the |\@begindvi| macro, rather than the even lower-level
+% |\shipout| macro.
+% \end{itemize}
+%
+% \subsection{Known applications of the \Lpack{everypage} code}
+%
+% Package \Lpack{everypage} has historically found application in at least
+% two higher level packages, namely:
+% \begin{itemize}
+% \item \Lpack{draftwatermark}, meant at providing extended facilities for
+% page watermarking on all \LaTeX\ engines and output drivers; and
+% \item \Lpack{flippdf}, meant at catering for a frequent preprint
+% requirement, where publisher may require a document with
+% \emph{mirrored} pages to get the best results out of a photographic
+% printout process.
+% \end{itemize}
+%
+% \section{The new code base}
+% \changes{R2.0}{2020/10/11}{%
+% Complete package rewrite to take advantage of the new
+% LaTeX hook mechanisms introduced in the Fall 2020 release.}
+%
+% The new code base differs from the old one because it does not touch
+% any \LaTeX\ internals. Conversely it relies on the hook mechanism that
+% is officially provided by \LaTeX\ since its 2020 fall release.
+% Obviously, this has no other purpose than to provide back
+% compatibility for older \LaTeX\ code written before such \LaTeX\
+% release and relying on the original \Lpack{everypage} interfaces.
+%
+% To this aim, the new code base does the following:
+% \begin{enumerate}
+% \item complains out loud, reminding that new code should not be based on
+% \Lpack{everypage}, but rather make direct usage of the new \LaTeX\
+% interfaces;
+% \item checks whether the new \LaTeX\ interfaces are actually
+% available. If this is not the case, it resorts to loading
+% \Lpack{everypage-1x} that provides the old code base;
+% \item \label{itm:addtohook}%
+% implements/emulates the |\AddEverypageHook| and |\AddThispageHook|
+% commands on top of the new |\AddToHook| and |\AddToHookNext| \LaTeX\
+% commands.
+% \end{enumerate}
+%
+% With specific reference to point \ref{itm:addtohook} above, note that
+% the new hook mechanism provided by \LaTeX\ is extensively documented in
+% issue 32 of \emph{\LaTeX\ News} and in file
+% |lthooks-doc.pdf|. Furthermore, consider that \Lpack{everypage} employs
+% hooks in the \emph{shipout} class, which are documented in file
+% |ltshipout-doc.pdf|.
+%
+% \subsection{Compatibility of the new code with the original \Lpack{everypage}
+% interface}
+%
+% Because the implementation is different and due to choices (in fact,
+% quite reasonable ones) by the \LaTeX\ developers, the new implementation
+% of \Lpack{everypage} cannot be exactly equivalent to the original one
+% (hence, please, do not open bugs for this!).
+%
+% The main difference is the hook code provided by the user now gets
+% wrapped in a |\put| command, inside a |picture| environment with
+% |\unitlength| at 1\,pt. This is because \Lpack{everypage} relies on a
+% |shipout/background| type hook. The |\put| command typesets material at
+% (1\,in, -1\,in) to emulate the original coordinate system of
+% \Lpack{everypage}. This means that some of the points about the
+% interface in section~\ref{ssec:ui} do not apply anymore (or at least do
+% not apply in the same way). Specifically, point \ref{itm:formatting}
+% about lack of any pre-canned formatting is not completely true anymore,
+% because of the implicit picture environment. Furthermore, point
+% \ref{itm:nospace} about the need not to eat up space can now be
+% completely ignored.
+%
+% While the changes described above seem to go in the direction of less
+% rules and less concern, this might not be always true and subtle
+% breakage of legacy code may happen in corner cases.
+%
+% \section{Forcing usage of the older code base}
+%
+% The usage of the older code base of \Lpack{everypage} can be forced by
+% simply substituting |\usepackage{everypage-1x}| for
+% |\usepackage{everypage}|. In this case, no warning about the package
+% obsolescence is emitted, because it is assumed that the user knows what
+% he/she is doing. However, explicitly requiring \Lpack{everypage-1x}
+% is obviously discouraged.
+%
+% The old code base actually works just fine with the Fall 2020 \LaTeX\
+% release and it will probably keep to do so for a few more \LaTeX\
+% release cycles. This is mostly up to the \LaTeX\ developers and their
+% will to maintain untouched some internal deprecated interfaces. In any case,
+% |\usepackage{everypage-1x}| will eventually stop working and is now
+% declared in an \emph{unmaintained state}.
+%
+%
% \StopEventually {}
-%
% \section{Implementation}
-%
+% \subsection{Implementation of \Lpack{everypage}}
+% \iffalse
+%<*everypage>
+% \fi
% Announce the name and version of the package, which requires
% \LaTeXe.
% \begin{macrocode}
\NeedsTeXFormat{LaTeX2e}
\ProvidesPackage{everypage}%
- [2007/06/20 1.1 Hooks to run on every page]
+ [2020/10/11 R2.0 Hooks to run on every page]
+% \end{macrocode}
+% Complain out loud about the package being obsolete.
+% \begin{macrocode}
+\PackageWarningNoLine{everypage}{%
+ Functionality similar to this package has recently\MessageBreak
+ been implemented in LaTeX. This package is now in\MessageBreak
+ legacy status.\MessageBreak
+ Please, don't use it in new documents and packages}
+% \end{macrocode}
+% Depending on the actual functionalities provided by \LaTeX\ consider
+% loading \Lpack{everypage-1x}. If so doing, warn about this too and
+% stop. Otherwise give some more warnings.
+% \begin{macrocode}
+\@ifundefined{AddToHook}{%
+ \PackageWarningNoLine{everypage}{%
+ You appear to be running a version of LaTeX\MessageBreak
+ too old to provide the new functionality.\MessageBreak
+ Forcing fallback to `everypage-1x` that\MessageBreak
+ uses an older code base}
+ \RequirePackage{everypage-1x}
+ \endinput}{%
+ \PackageWarningNoLine{everypage}{%
+ You appear to be running a version of LaTeX\MessageBreak
+ providing the new functionality.\MessageBreak
+ Doing the best to deliver the original `everypage`\MessageBreak
+ interface on top of it. Strict equivalence is\MessageBreak
+ not possible, breakage may occur.\MessageBreak
+ If truly needed, Use `everypage-1x` to force the\MessageBreak
+ loading of an older code base}}
+% \end{macrocode}
+% \begin{macro}{\AddEverypageHook}\begin{macro}{\AddThispageHook}%
+% Finally, implement the \Lpack{everypage} interface on top of the \LaTeX\
+% |shipout/background| hooks.
+% \begin{macrocode}
+\newcommand*{\AddEverypageHook}[1]{%
+ \AddToHook{shipout/background}{\put(1in,-1in){#1}}}
+\newcommand*{\AddThispageHook}[1]{%
+ \AddToHookNext{shipout/background}{\put(1in,-1in){#1}}}
+% \end{macrocode}
+% \end{macro}\end{macro}
+% \iffalse
+%</everypage>
+% \fi
+%
+% \subsection{Implementation of \Lpack{everypage-1x}}
+% \iffalse
+%<*everypage-1x>
+% \fi
+% Announce the name and version of the package, which requires
+% \LaTeXe.
+% \begin{macrocode}
+\NeedsTeXFormat{LaTeX2e}
+\ProvidesPackage{everypage-1x}%
+ [2020/10/10 1.2 Hooks to run on every page]
% \end{macrocode}
%
% \begin{macro}{\sc@everypage@hook}\begin{macro}{\sc@everypage@hook}
@@ -191,6 +423,11 @@
% \end{macro}
%
% \begin{macro}{\sc@op@preamble}
+% \changes{R1.1}{2007/06/20}{%
+% Fix an out of memory condition.}
+% \changes{R1.2}{2020/10/10}{%
+% Reorder operations to take care of code to execute at the beginning of
+% the output before the `everypage' hooks.}
% The outputpage preamble contains instructions to redefine the
% |\@begindvi| macro that is called at every page output by the
% original |\@outputpage| code.
@@ -201,10 +438,10 @@
\newcommand*{\sc@op@preamble}{%
\let\sc@begindvi\@begindvi
\def\@begindvi{%
+ \sc@begindvi
\sc@everypage@hook
\sc@thispage@hook
- \gdef\sc@thispage@hook{}
- \sc@begindvi}}
+ \gdef\sc@thispage@hook{}}}
% \end{macrocode}
% \end{macro}
%
@@ -230,31 +467,33 @@
% other packages are loaded.
% \begin{macrocode}
\AtBeginDocument{\sc@ep@init}
-\endinput
% \end{macrocode}
+% \iffalse
+%</everypage-1x>
+% \fi
%
% \Finale
+% \PrintChanges
% \PrintIndex
%
-%% \CharacterTable
-%% {Upper-case \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
-%% Lower-case \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
-%% Digits \0\1\2\3\4\5\6\7\8\9
-%% Exclamation \! Double quote \" Hash (number) \#
-%% Dollar \$ Percent \% Ampersand \&
-%% Acute accent \' Left paren \( Right paren \)
-%% Asterisk \* Plus \+ Comma \,
-%% Minus \- Point \. Solidus \/
-%% Colon \: Semicolon \; Less than \<
-%% Equals \= Greater than \> Question mark \?
-%% Commercial at \@ Left bracket \[ Backslash \\
-%% Right bracket \] Circumflex \^ Underscore \_
-%% Grave accent \` Left brace \{ Vertical bar \|
-%% Right brace \} Tilde \~}
+% \CharacterTable
+% {Upper-case \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
+% Lower-case \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
+% Digits \0\1\2\3\4\5\6\7\8\9
+% Exclamation \! Double quote \" Hash (number) \#
+% Dollar \$ Percent \% Ampersand \&
+% Acute accent \' Left paren \( Right paren \)
+% Asterisk \* Plus \+ Comma \,
+% Minus \- Point \. Solidus \/
+% Colon \: Semicolon \; Less than \<
+% Equals \= Greater than \> Question mark \?
+% Commercial at \@ Left bracket \[ Backslash \\
+% Right bracket \] Circumflex \^ Underscore \_
+% Grave accent \` Left brace \{ Vertical bar \|
+% Right brace \} Tilde \~}
\endinput
-%%% Local Variables:
-%%% mode: doctex
-%%% TeX-master: t
-%%% End:
-
+% %% Local Variables:
+% %% mode: doctex
+% %% TeX-master: t
+% %% End: \ No newline at end of file
diff --git a/macros/latex/contrib/everypage/everypage.ins b/macros/latex/contrib/everypage/everypage.ins
index 9131ac4269..2da7b69a6e 100644
--- a/macros/latex/contrib/everypage/everypage.ins
+++ b/macros/latex/contrib/everypage/everypage.ins
@@ -1,5 +1,5 @@
%% everypage.ins
-%% Copyright 2006
+%% Copyright 2006-2007, 2020
%% Sergio Callegari <sergio.callegari@gmail.com>
%%
%% ---------------------------------------------
@@ -25,17 +25,14 @@
%% --------------- start of docstrip commands ------------------
%%
\input docstrip.tex
-\preamble
-This is file `everypage.sty',
-generated with the docstrip utility.
-The original source files were:
+\usedir{tex/latex/everypage}
-everypage.dtx
+\preamble
- IMPORTANT NOTICE:
+IMPORTANT NOTICE:
-Copyright 2006
+Copyright 2006-2007, 2020
Sergio Callegari <sergio.callegari@gmail.com>
---------------------------------------------
@@ -43,25 +40,27 @@ This file is part of the everypage package,
a contribution to the LaTeX2e system.
---------------------------------------------
-This program consists of the files listed in the README file included
-in the package.
+This program consists of the files listed in the README.md file included in
+the package.
Any modified versions of this file must be renamed with new filenames
-distinct from everypage.sty.
+distinct from \outFileName.
-For distribution of the original source see the terms
-for copying and modification in the file everypage.dtx.
+For distribution of the original source see the terms for copying and
+modification in the file \inFileName.
-This generated file may be distributed as long as the
-original source files, as listed above, are part of the
-same distribution. (The sources need not necessarily be
-in the same archive or directory.)
+This generated file may be distributed as long as the original source files,
+as listed above, are part of the same distribution. (The sources need not
+necessarily be in the same archive or directory.)
\endpreamble
\keepsilent
\Msg{*** Generating the LaTeX2e package files ***}
-\generate{\file{everypage.sty}{\from{everypage.dtx}{}}}
+
+\generate{\file{everypage.sty}{\from{everypage.dtx}{everypage}}}
+\generate{\file{everypage-1x.sty}{\from{everypage.dtx}{everypage-1x}}}
+
\ReportTotals
\Msg{***********************************************************}
@@ -70,15 +69,17 @@ in the same archive or directory.)
\Msg{* file(s) into a directory searched by TeX:}
\Msg{*}
\Msg{* \space\space everypage.sty}
+\Msg{* \space\space everypage-070620.sty}
\Msg{*}
\Msg{*}
-\Msg{* To produce the documentation run the files ending with}
-\Msg{* `.dtx' through LaTeX (or maybe pdfLaTeX).}
-\Msg{* Process any name.idx file by:}
-\Msg{* \space\space\space\space makeindex -s gind.ist name}
-\Msg{* Process any name.glo file by:}
-\Msg{* \space\space\space\space makeindex -s gglo.ist -o name.gls name.glo}
-\Msg{* Re run through LaTeX the .dtx files as necessary}
+\Msg{* To produce the documentation:}
+\Msg{* - run everypage.dtx through LaTeX}
+\Msg{* - Process everypage.idx by:}
+\Msg{* \space\space\space\space makeindex -s gind.ist everypage}
+\Msg{* - Process any everypage.glo by:}
+\Msg{* \space\space\space\space
+ makeindex -s gglo.ist -o everypage.gls everypage.glo}
+\Msg{* Re run through LaTeX everypage.dtx as necessary}
\Msg{*}
\Msg{***********************************************************}
diff --git a/macros/latex/contrib/everypage/everypage.pdf b/macros/latex/contrib/everypage/everypage.pdf
deleted file mode 100644
index 29882b0c01..0000000000
--- a/macros/latex/contrib/everypage/everypage.pdf
+++ /dev/null
Binary files differ
diff --git a/macros/latex/contrib/swfigure/HSfakeimage.jpg b/macros/latex/contrib/swfigure/HSfakeimage.jpg
new file mode 100644
index 0000000000..47d8bb8d94
--- /dev/null
+++ b/macros/latex/contrib/swfigure/HSfakeimage.jpg
Binary files differ
diff --git a/macros/latex/contrib/swfigure/NFfakeimage.jpg b/macros/latex/contrib/swfigure/NFfakeimage.jpg
new file mode 100644
index 0000000000..098557cd2f
--- /dev/null
+++ b/macros/latex/contrib/swfigure/NFfakeimage.jpg
Binary files differ
diff --git a/macros/latex/contrib/swfigure/README.txt b/macros/latex/contrib/swfigure/README.txt
new file mode 100644
index 0000000000..702eefb35d
--- /dev/null
+++ b/macros/latex/contrib/swfigure/README.txt
@@ -0,0 +1,45 @@
+%%
+%% This is file `README.txt',
+%% generated with the docstrip utility.
+%%
+%% The original source files were:
+%%
+%% swfigure.dtx (with options: `readme')
+%%
+%% Copyright (C) 2020 Claudio Beccari all rights reserved.
+%% License information appended
+%%
+
+File README.txt for package swfigure
+ [2020-10-11 v.0.9.07 Managing large and spread wide figures]
+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.
+
+%%
+%% Distributable under the LaTeX Project Public License,
+%% version 1.3c or higher (your choice). The latest version of
+%% this license is at: http://www.latex-project.org/lppl.txt
+%%
+%% This work is "maintained"
+%%
+%% This work consists of files swfigure.dtx and READEME.txt, and the derived
+%% files swfigure.sty and swfigure.pdf
+%%
+%%
+%% End of file `README.txt'.
diff --git a/macros/latex/contrib/swfigure/RFfakeimage.jpg b/macros/latex/contrib/swfigure/RFfakeimage.jpg
new file mode 100644
index 0000000000..be547643e9
--- /dev/null
+++ b/macros/latex/contrib/swfigure/RFfakeimage.jpg
Binary files differ
diff --git a/macros/latex/contrib/swfigure/SWfakeImage.jpg b/macros/latex/contrib/swfigure/SWfakeImage.jpg
new file mode 100644
index 0000000000..bd247babeb
--- /dev/null
+++ b/macros/latex/contrib/swfigure/SWfakeImage.jpg
Binary files differ
diff --git a/macros/latex/contrib/swfigure/VSfakeimage.jpg b/macros/latex/contrib/swfigure/VSfakeimage.jpg
new file mode 100644
index 0000000000..71e5ee0473
--- /dev/null
+++ b/macros/latex/contrib/swfigure/VSfakeimage.jpg
Binary files differ
diff --git a/macros/latex/contrib/swfigure/swfigure-examples.pdf b/macros/latex/contrib/swfigure/swfigure-examples.pdf
new file mode 100644
index 0000000000..5ef68cb2ce
--- /dev/null
+++ b/macros/latex/contrib/swfigure/swfigure-examples.pdf
Binary files differ
diff --git a/macros/latex/contrib/swfigure/swfigure-examples.tex b/macros/latex/contrib/swfigure/swfigure-examples.tex
new file mode 100644
index 0000000000..17513fdd2f
--- /dev/null
+++ b/macros/latex/contrib/swfigure/swfigure-examples.tex
@@ -0,0 +1,434 @@
+% !TEX encoding = UTF-8 Unicode
+% !TEX TS-program = pdflatex
+\documentclass[twoside,notitlepage]{report}\errorcontextlines=100
+\usepackage[utf8]{inputenc}
+\usepackage{lmodern,textcomp,multicol,enumitem,mflogo,xcolor,fancyvrb}
+\usepackage{swfigure}
+
+\providecommand*\diff{\mathop{}\!\mathrm{d}}
+\providecommand\cs{}
+ \renewcommand\cs[1]{\normalfont{\texttt{\char92#1}}}
+\providecommand\meta{}
+ \renewcommand\meta[1]{{\normalfont\textlangle\textit{#1}\textrangle}}
+\providecommand\marg{}
+ \renewcommand\marg[1]{\texttt{\{\meta{#1}\}}}
+\providecommand\Marg{}
+ \renewcommand\Marg[1]{\texttt{\{#1\}}}
+\providecommand\oarg{}
+ \renewcommand\oarg[1]{\texttt{[\meta{#1}]}}
+\providecommand\Oarg{}
+ \renewcommand\Oarg[1]{\texttt{[#1]}}
+\providecommand\aarg{}
+ \renewcommand\aarg[1]{\texttt{<\meta{#1}>}}
+\providecommand\Aarg{}
+ \renewcommand\Aarg[1]{\texttt{<#1>}}
+\providecommand\parg{}
+ \renewcommand\parg[1]{\texttt{(\meta{#1})}}
+\providecommand\Parg{}
+ \renewcommand\Parg[1]{\texttt{(#1)}}
+\providecommand\pack{}
+ \renewcommand\pack[1]{\textsf{#1}}
+\providecommand\eTeX{}
+ \renewcommand\eTeX{\lower0.5ex\hbox{$\varepsilon\!$}\TeX}
+\providecommand\file{}
+ \renewcommand\file[1]{{\normalfont\sffamily\slshape#1}}
+
+\newbox\SWsynt
+
+\newenvironment{medaglione}%
+{\par\medskip\fboxrule=0.8pt\fboxsep6pt\relax
+\begin{lrbox}{\SWsynt}\minipage{\dimexpr\linewidth-2\fboxsep-2\fboxrule}}%
+{\endminipage\end{lrbox}\noindent\fbox{\box\SWsynt}\par\medskip}
+
+\newenvironment{ttsyntax}{\medaglione\raggedright\ttfamily\obeylines}{\endmedaglione}
+
+\providecommand\setfontsize{}
+\DeclareRobustCommand\setfontsize[2][1.2]{%
+\linespread{#1}\fontsize{#2}{#2}\selectfont}
+
+
+\makeatletter
+\providecommand\GetFileInfo[1]{%
+ \def\filename{#1}%
+ \def\@tempb##1 v.##2 ##3\relax##4\relax{%
+ \def\filedate{##1}%
+ \def\fileversion{##2}%
+ \def\fileinfo{##3}}%
+ \edef\@tempa{\csname ver@#1\endcsname}%
+ \expandafter\@tempb\@tempa\relax? ? \relax\relax}
+
+\counterwithout{section}{chapter}
+
+\begin{document}
+\GetFileInfo{swfigure.sty}
+\title{The \pack{swfigure} package --- Usage examples}
+\author{Claudio Beccari\thanks{Email: \texttt{claudio dot beccari at gmail dot com}}}
+\date{Version \fileversion~---~ Last revised \filedate}
+\maketitle
+
+\begin{abstract}
+Managing large images is not that straightforward to do. Package \pack{swfigure} was initially created to handle such large figures that required a whole spread to display them; the package initial letters SW are the acronym of Spread Wide. While developing this package, other display modes were introduced, so that with a single user command it is possible to display a large image in five different modes, that are to be chosen according to the figure aspect ratio, and the page design of the document.
+This package works pretty well with two side printed documents with a symmetrical page design, i.e. with the same dimension for the inner margins and, respectively, the outer margins. The documented \TeX\ file that describes the software does not have a symmetrical design, therefore this second file is necessary in order to show some examples.
+\end{abstract}
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\section{Introduction}
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+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.
+
+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{flushleft}\ttfamily\obeylines
+\cs{DFimage}Oarg{SW}\Marg{SWfakeimage}\Marg{A Spread Wide fake image}\Oarg{fig:SWfake}
+\end{flushleft}
+
+\DFimage[SW]{SWfakeimage}{A spread wide fake image}[fig:SWfake]
+
+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, although we doubt that Emmanuel Kant wrote those very texts.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\section{The user macro}
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+The only user macro defined by this pckge has the following syntax:
+\begin{ttsyntax}
+\cs{DFimage}\oarg{display mode}\marg{image file name}\oarg{lof entry}\%
+\qquad\marg{caption}\oarg{label}\parg{height correction}\aarg{line correction}
+\end{ttsyntax}
+The arguments are described in detail in the twin document \file{swfigure.pdf}. We shortly repeat their meanings.
+\begin{description}[noitemsep]
+%
+\item[\meta{display mode}] See below the various display modes.
+%
+\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{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{line correction}] This optional integer number may correct the number of lines of the indention of the wrapping text around a tall and slim figure.
+%
+\end{description}
+
+We stress the first optional argument meaning, whose default value is \texttt{SW}. It specifies the \meta{display mode}.
+\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 in a vertical fashion. 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{DGimage} (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.
+%
+\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 under the right half, the space occupied by this part of the image is 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{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) si 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{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.
+%
+\item[\texttt{RF}] This fifth display mode refers to the Rotated Figure obtainable by means of the \pack{lscape} package; here the package is not used, but a direct rotation is performed by the macro. Again the \meta{height correction} optional value may be useful in order to leave more or less space to the caption; if the latter is pretty wordy, a smaller value of the preset 0.8 value mai be chosen, while for a single line caption a slightly higher value may be convenient.
+%
+\end{description}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\section{A \texttt{HS} example}
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+On pages~\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
+used as a canon for our understanding. The paralogisms of practical
+reason are what first give rise to the architectonic of practical
+reason. As will easily be shown in the next section, reason would
+thereby be made to contradict, in view of these considerations, the
+Ideal of practical reason, yet the manifold depends on the phenomena.
+Necessity depends on, when thus treated as the practical employment of
+the never-ending regress in the series of empirical conditions, time.
+Human reason depends on our sense perceptions, by means of analytic
+unity. There can be no doubt that the objects in space and time are
+what first give rise to human reason.
+
+\DFimage[HS]{HSfakeimage}{A Horizontal Slim fake image}[fig:HSfake]
+
+Let us suppose that the noumena have nothing to do
+with necessity, since knowledge of the Categories is a
+posteriori. Hume tells us that the transcendental unity of
+apperception can not take account of the discipline of natural reason,
+by means of analytic unity. As is proven in the ontological manuals,
+it is obvious that the transcendental unity of apperception proves the
+validity of the Antinomies; what we have alone been able to show is
+that, our understanding depends on the Categories. It remains a
+mystery why the Ideal stands in need of reason. It must not be
+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.
+
+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
+paralogisms of natural reason, but our a posteriori concepts have
+lying before them the practical employment of our experience. Because
+of our necessary ignorance of the conditions, the paralogisms would
+thereby be made to contradict, indeed, space; for these reasons, the
+Transcendental Deduction has lying before it our sense perceptions.
+(Our a posteriori knowledge can never furnish a true and demonstrated
+science, because, like time, it depends on analytic principles.) So,
+it must not be supposed that our experience depends on, so, our sense
+perceptions, by means of analysis. Space constitutes the whole content
+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.
+
+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
+give rise to metaphysics. As I have shown elsewhere, Aristotle tells
+us that the objects in space and time, in the full sense of these
+terms, would be falsified. Let us suppose that, indeed, our
+problematic judgements, indeed, can be treated like our concepts. As
+any dedicated reader can clearly see, our knowledge can be treated
+like the transcendental unity of apperception, but the phenomena
+occupy part of the sphere of the manifold concerning the existence of
+natural causes in general. Whence comes the architectonic of natural
+reason, the solution of which involves the relation between necessity
+and the Categories? Natural causes (and it is not at all certain that
+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.
+
+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
+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
+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
+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
+Antinomies (and it is not at all certain that this is the case) are
+the clue to the discovery of philosophy, because of our necessary
+ignorance of the conditions. As I have shown elsewhere, to avoid all
+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.
+
+\DFimage[VS]{VSfakeimage}{A Vertical Slim fake image}[fig:VSfake](0.7)<2>
+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
+abstracts from all content of knowledge; in view of these
+considerations, the Ideal of human reason, on the contrary, is the key
+to understanding pure logic. Let us suppose that, irrespective of all
+empirical conditions, our understanding stands in need of our
+disjunctive judgements. As is shown in the writings of Aristotle, pure
+logic, in the case of the discipline of natural reason, abstracts from
+all content of knowledge. Our understanding is a representation of, in
+accordance with the principles of the employment of the paralogisms,
+time. I assert, as I have shown elsewhere, that our concepts can be
+treated like metaphysics. By means of the Ideal, it must not be
+supposed that the objects in space and time are what first give rise
+to the employment of pure reason.
+
+\DFimage[NF]{NFfakeimage}{A large Normal Figure fake image}[fig:NFfake]
+
+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. 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 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
+other hand, natural causes can not take account of, consequently, the
+Antinomies, as will easily be shown in the next section.
+Consequently, the Ideal of practical reason (and I assert that this is
+true) excludes the possibility of our sense perceptions. Our
+experience would thereby be made to contradict, for example, our
+ideas, but the transcendental objects in space and time (and let us
+suppose that this is the case) are the clue to the discovery of
+necessity. But the proof of this is a task from which we can here be
+absolved.
+
+\DFimage[RF]{RFfakeimage}{A large Rotated Figure fake image}[fig:RFfake]
+
+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
+used as a canon for our understanding. The paralogisms of practical
+reason are what first give rise to the architectonic of practical
+reason. As will easily be shown in the next section, reason would
+thereby be made to contradict, in view of these considerations, the
+Ideal of practical reason, yet the manifold depends on the phenomena.
+Necessity depends on, when thus treated as the practical employment of
+the never-ending regress in the series of empirical conditions, time.
+Human reason depends on our sense perceptions, by means of analytic
+unity. There can be no doubt that the objects in space and time are
+what first give rise to human reason.
+
+Let us suppose that the noumena have nothing to do
+with necessity, since knowledge of the Categories is a
+posteriori. Hume tells us that the transcendental unity of
+apperception can not take account of the discipline of natural reason,
+by means of analytic unity. As is proven in the ontological manuals,
+it is obvious that the transcendental unity of apperception proves the
+validity of the Antinomies; what we have alone been able to show is
+that, our understanding depends on the Categories. It remains a
+mystery why the Ideal stands in need of reason. It must not be
+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.
+
+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
+paralogisms of natural reason, but our a posteriori concepts have
+lying before them the practical employment of our experience. Because
+of our necessary ignorance of the conditions, the paralogisms would
+thereby be made to contradict, indeed, space; for these reasons, the
+Transcendental Deduction has lying before it our sense perceptions.
+(Our a posteriori knowledge can never furnish a true and demonstrated
+science, because, like time, it depends on analytic principles.) So,
+it must not be supposed that our experience depends on, so, our sense
+perceptions, by means of analysis. Space constitutes the whole content
+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.
+
+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
+give rise to metaphysics. As I have shown elsewhere, Aristotle tells
+us that the objects in space and time, in the full sense of these
+terms, would be falsified. Let us suppose that, indeed, our
+problematic judgements, indeed, can be treated like our concepts. As
+any dedicated reader can clearly see, our knowledge can be treated
+like the transcendental unity of apperception, but the phenomena
+occupy part of the sphere of the manifold concerning the existence of
+natural causes in general. Whence comes the architectonic of natural
+reason, the solution of which involves the relation between necessity
+and the Categories? Natural causes (and it is not at all certain that
+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.
+
+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
+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
+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
+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
+Antinomies (and it is not at all certain that this is the case) are
+the clue to the discovery of philosophy, because of our necessary
+ignorance of the conditions. As I have shown elsewhere, to avoid all
+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.
+
+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
+abstracts from all content of knowledge; in view of these
+considerations, the Ideal of human reason, on the contrary, is the key
+to understanding pure logic. Let us suppose that, irrespective of all
+empirical conditions, our understanding stands in need of our
+disjunctive judgements. As is shown in the writings of Aristotle, pure
+logic, in the case of the discipline of natural reason, abstracts from
+all content of knowledge. Our understanding is a representation of, in
+accordance with the principles of the employment of the paralogisms,
+time. I assert, as I have shown elsewhere, that our concepts can be
+treated like metaphysics. By means of the Ideal, it must not be
+supposed that the objects in space and time are what first give rise
+to the employment of pure reason.
+
+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. 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 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
+other hand, natural causes can not take account of, consequently, the
+Antinomies, as will easily be shown in the next section.
+Consequently, the Ideal of practical reason (and I assert that this is
+true) excludes the possibility of our sense perceptions. Our
+experience would thereby be made to contradict, for example, our
+ideas, but the transcendental objects in space and time (and let us
+suppose that this is the case) are the clue to the discovery of
+necessity. But the proof of this is a task from which we can here be
+absolved.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\section{Used commands}
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+The various large fake images have been inserted with the following commands:
+\begin{itemize}[noitemsep]
+%
+\item figure~\ref{fig:SWfake}
+\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 Horizonta Slim fake image}[fig:HSfake]
+\end{Verbatim}
+%
+\item figure~\ref{fig:VSfake}
+\begin{Verbatim}[fontsize=\setfontsize{8}]
+\DFimage[VS]{VSfakeimage}{A Vertical Slim fake image}[fig:VSfake](0.7)<2>
+\end{Verbatim}
+%
+\item figure~\ref{fig:NFfake}
+\begin{Verbatim}
+\DFimage[NF]{NFfakeimage}{A large Normal Figure fake image}%
+ [fig:NFfake]
+\end{Verbatim}
+%
+\item figure~\ref{fig:RFfake}
+\begin{Verbatim}
+\DFimage[RF]{RFfakeimage}{A large Rotated Figure fake image}%
+ [fig:RFfake]
+\end{Verbatim}
+\end{itemize}
+%
+\listoffigures
+\end{document}
+
diff --git a/macros/latex/contrib/swfigure/swfigure.dtx b/macros/latex/contrib/swfigure/swfigure.dtx
new file mode 100644
index 0000000000..d848cae2fa
--- /dev/null
+++ b/macros/latex/contrib/swfigure/swfigure.dtx
@@ -0,0 +1,855 @@
+% \iffalse
+% !TEX encoding = UTF-8 Unicode
+% !TEX TS-program = pdflatex
+%<*internal>
+\begingroup
+\input docstrip.tex
+\keepsilent
+\preamble
+
+ Copyright (C) 2020 Claudio Beccari all rights reserved.
+ License information appended
+
+\endpreamble
+
+\postamble
+
+Distributable under the LaTeX Project Public License,
+version 1.3c or higher (your choice). The latest version of
+this license is at: http://www.latex-project.org/lppl.txt
+
+This work is "maintained"
+
+This work consists of files swfigure.dtx and READEME.txt, and the derived
+files swfigure.sty and swfigure.pdf
+
+\endpostamble
+\askforoverwritefalse
+
+\generate{\file{swfigure.sty}{\from{swfigure.dtx}{package}}}
+%\generate{\file{README.txt}{\from{swfigure.dtx}{readme}}}
+
+\def\tmpa{plain}
+\ifx\tmpa\fmtname\endgroup\expandafter\bye\fi
+\endgroup
+%</internal>
+% \fi
+%
+% \iffalse
+%<*package>
+%<package>\NeedsTeXFormat{LaTeX2e}[2020/01/01]
+%</package>
+%<*driver>
+\ProvidesFile{swfigure.dtx}%
+%</driver>
+%<+package>\ProvidesPackage{swfigure}%
+%<+readme>File README.txt for package swfigure
+%<*package|readme>
+ [2020-10-11 v.0.9.07 Managing large and spread wide figures]
+%</package|readme>
+%<*driver>
+\documentclass[a4paper]{ltxdoc}\errorcontextlines=9
+\hfuzz 10pt
+\usepackage[utf8]{inputenc}
+\usepackage{lmodern,textcomp,multicol,enumitem,mflogo,xcolor}
+\usepackage{swfigure}
+
+\providecommand*\diff{\mathop{}\!\mathrm{d}}
+\renewcommand\meta[1]{{\normalfont\textlangle\textit{#1}\textrangle}}
+\renewcommand\marg[1]{\texttt{\{\meta{#1}\}}}
+\providecommand\Marg{}
+\renewcommand\Marg[1]{\texttt{\{#1\}}}
+\providecommand\oarg{}
+\renewcommand\oarg[1]{\texttt{[\meta{#1}]}}
+\providecommand\Oarg{}
+\renewcommand\Oarg[1]{\texttt{[#1]}}
+\providecommand\aarg{}
+\renewcommand*\aarg[1]{\texttt{<\meta{#1}>}}
+\providecommand\Aarg{}
+\renewcommand\Aarg[1]{\texttt{<#1>}}
+\providecommand\parg{}
+\renewcommand\parg[1]{\texttt{(\meta{#1})}}
+\providecommand\Parg{}
+\renewcommand\Parg[1]{\texttt{(#1)}}
+\providecommand\eTeX{}
+\newbox\SWsynt
+\renewcommand\eTeX{\lower0.5ex\hbox{$\varepsilon\!$}\TeX}
+
+\newenvironment{medaglione}%
+{\par\medskip\fboxrule=0.8pt\fboxsep6pt\relax
+\begin{lrbox}{\SWsynt}\minipage{\dimexpr\linewidth-2\fboxsep-2\fboxrule}}%
+{\endminipage\end{lrbox}\noindent\fbox{\box\SWsynt}\par\medskip}
+
+\newenvironment{ttsyntax}{\medaglione\raggedright\ttfamily\obeylines}{\endmedaglione}
+
+\providecommand\setfontsize{}
+\DeclareRobustCommand\setfontsize[2][1.2]{%
+\linespread{#1}\fontsize{#2}{#2}\selectfont}
+
+\GetFileInfo{swfigure.dtx}
+\title{The \texttt{swfigure} package\\
+Managing large and spread wide figures}
+\author{Claudio Beccari\thanks{E-mail: \texttt{claudio dot beccari at gmail dot com}}}
+\date{Version \fileversion~---~ Last revised \filedate}
+
+\begin{document}\errorcontextlines=100
+\maketitle
+\columnseprule=0.4pt
+\begin{multicols}{2}
+ \tableofcontents
+ \end{multicols}
+ \DocInput{swfigure.dtx}
+\end{document}
+%</driver>
+% \fi
+%^^A \CheckSum{10}^^A Doesn't this work any more?
+%
+% \begin{abstract}
+% This package defines a single command that with different options can
+% insert large images into the document; those that occupy an entire
+% spread s get split into two halves that are inserted on
+% two facing pages in such a way that they merge when the document is read
+% on the screen (set to double page view) or is printed in a well sewn
+% book so that facing pages join correctly at the spine.
+% This documentation is accompanied by another file
+% |swfigure-examples.pdf| containing examples of this package several
+% uses.
+% \end{abstract}
+%
+%^^A \DFimage[SW]{SWfakeimage}{A large fake image}[fig:SWfake]
+%^^A It does not work with the page design of this document.
+%
+%^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%\section{Introduction}
+%^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+% Sometimes it is necessary to insert in a given document very large
+% images; either they are larger than a spread, or they do not exceed
+% the width of a spread. In the first case it is necessary to use
+% to large sheets of paper folded in the proper way and inserted in the
+% printed document as special inserts; or for documents to be read on
+% the screen such large sheets have to be attached to the document as
+% separate files to be viewed in windows different from that where the
+% document is being read.
+%
+% In the other case it is possible to manage such large figures in
+% different ways; we define a single command that, according to
+% different settings, can insert such figures in five different display
+% modes.
+%\begin{enumerate}[noitemsep]
+% \item
+% The normal \LaTeX\ kernel full page display mode, but using
+% the |figure| environment with the |[p]| placing option. Apparently
+% there is no need to define a new command for this display mode, except
+% the advantage of using the same command as the other modes and a few
+% small further functionalities that the new command has available.
+%\item
+% The landscape display mode available with the |lscape| package
+% and other similar ones. Again this display mode appears superfluous,
+% but the advantage is to use the same command as with the other
+% display modes
+%\item
+% The screen-wide display mode, where two facing pages display a large
+% figure divided in two halves, each one set in its page shifted to the
+% spine so as to occupy on each page the text width plus the internal
+% margin width; with suitable aspect ratio, both facing pages are
+% practically full. No other text appears in this display mode, except
+% the caption in the right page external margin.
+%\item
+% The slim screen-wide image is similar to the previous mode, but since
+% the figure is slim, it is set at the top of two facing pages, with text
+% underneath; the caption is under the right figure half in the right
+% page, and the left text block height is set so that that the first
+% lines of both text blocks are aligned.
+%\item
+% The slim tall image is set to the side of the text block that wraps
+% it. Recurse is made to the |wrapfig| package, therefore the software
+% might sometimes hick-up a little bit, because of the idiosyncrasies of
+% |wrapfig| that performs very well in most but not all circumstances;
+% see that package documentation for such |wrapfig| limitations. With
+% this |wsfigure| package we limit the use of this display mode to
+% images that have a “height over width” ratio not lower than~2; we
+% provide also some option arguments so as to correct small imperfections
+% in the sizing of the text indention
+%\end{enumerate}
+%
+% In any case, depending on the page geometry and the image aspect
+% ratio, it is very handy to have available a single command that
+% changes the display mode by just changing a single input optional
+% argument. In facts the user might start with one of the five
+% described display modes; after examining the document daft the
+% user might chose another display mode, and it suffices to change
+% the optional argument, without changing the whole code.
+%
+% \bigskip
+%
+% \noindent\fbox{\textcolor{red}{WARNING}}\quad This package performs
+% well with documents typeset in \texttt{twoside} mode, and with a page
+% design where the internal margins of both the odd and even pages
+% are equal (symmetrical page design). For example, it does not work
+% with this document designed to work in \texttt{oneside} mode and
+% where the the left page margin is always larger than the right one
+% of each page; this page design is functional to the documentation
+% of the \TeX\ system software.
+%
+%^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%\section{Installation}
+%^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%
+% This package is already installed with any complete and up to date
+% \TeX\ system distribution, \TeX\ Live or MiK\TeX.
+%
+% Should the user have available a basic or a partial \TeX\ system
+% installation, the simplest way to install this package is to download
+% the |swfigure.zip| file from the Comprehensive \TeX\ Archive Network
+% (CTAN), and decompress it either in the very folder where there is
+% the document main or single document file or, for a general use, in
+% the user personal |texmf| tree; it is possible that the user should
+% directly create this personal tree; how to do it is described in the
+% documentation of the user \TeX\ system distribution.
+%
+% The same holds true if the user employs a vintage \TeX\ system
+% distribution; this package requires the \LaTeX3 modern language
+% functionalities, therefore a \LaTeX\ kernel with a date after
+% 2019-01-01. Lacking this modern kernel, the package is strongly
+% limited, because packages |xparse| and |xfp| are used for its
+% internal workings.
+%
+%
+%^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%\section{Usage}\label{sec:Usage}
+%^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+% This package defines a single user command, |DFimage| to be used
+% with the following syntax:
+%\begin{ttsyntax}
+%\cs{DFimage}\oarg{display mode}\marg{image file name}\oarg{lof entry}\marg{caption}\oarg{label}\%
+%\qquad\parg{heigth correction}\aarg{line correction}
+%\end{ttsyntax}
+% where:
+%\begin{description}[noitemsep]
+%\item[\meta{display mode}]
+% is one of the following uppercase acronyms:
+% \texttt{NF} (Normal Figure), \texttt{RF} (Rotated Figure),
+% \texttt{SW} (Spread Wide image), \texttt{HS} (Horizontal Spread-wide
+% image), and \texttt{VS} (Vertical Slim image).
+%\item[\meta{image fie name}]
+% Is the name of the image graphic file; remember that the \LaTeX based
+% \TeX\ system typesetting programs accept graphic files in the formats
+% with extensions \texttt{.pdf}, \texttt{.eps}, \texttt{.jpg},
+% \texttt{.png}, and few other less common ones. It is not necessary to
+% specify the extension, but it is not forbidden.
+%\item[\meta{lof entry}]
+% is the optional entry to the List Of Figures; it defaults to the
+% \meta{caption} text, but if the latter is sort of lengthy, it is
+% better to enter a shorter text in that list.
+%\item[\meta{caption}]
+% is the caption text.
+%\item[\meta{label}]
+% this optional argument is the string that forms the argument of the
+% \cs{label} command; of course, if this argument is not specified,
+% the figure number and its page cannot be referenced with \cs{ref},
+% \cs{pageref} and other similar commands.
+%\item[\meta{height correction}]
+% This normal parenthesis delimited optional argument is a fractional
+% number lower than~1 (default 0.8) with which to further scale the
+% scaled image height to be included; it is used by some display modes,
+% and it is ignored by others.
+%\item[\meta{line correction}] is an angle bracket delimited optional
+% argument preset to zero. It is relevant only with the slim
+% vertical image display mode. Sometimes the |wrapfig| package
+% indents the wrapping text in such a way as to leave to much or too
+% little vertical space around the image and its caption; by examining
+% the document drafts it is possible to increase or decrease the
+% vertical space by any (integer) number of lines.
+%\end{description}
+%
+%^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+% \section{Display mode peculiarities}
+%^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+% Each of the listed display modes has its own pros and cons.
+% In the following the phrase “aspect ratio” refers to the “height
+% over width” ratio either of the image or of the available space
+% where to put the image and possibly its caption.
+%\begin{description}[noitemsep]
+%
+%\item[\texttt{NF}]
+% This display mode is convenient when the image
+% aspect ratio is close to the text block one. Of course the user
+% does not know in advance the vertical space occupied by the caption,
+% therefore the optional \meta{height correction} comes handy for
+% small adjustments; this display mode is fully and freely floating,
+% although its positioning is fixed to~|[p]|.
+%
+%\item[\texttt{RF}]
+% This display mode is convenient when the image
+% aspect ratio is close to the reciprocal of the text block one. This
+% mode accepts the \meta{height correction} in order to leave space
+% to the caption. It is a fully and freely floating object with the
+% same pros and cons as the \texttt{NF} display mode.
+%
+%\item[\texttt{SW}]
+% This display mode is convenient when a really large
+% image requires two pages to display all its details; its aspect ratio
+% should be close to the two page aspect ratio of the total space
+% available for the two page spread; depending on the page design this
+% total space approximate value probably is close to~0.5.
+% The object to be included in the document should start on an even
+% page, therefore it moves to the first even page available; this
+% implies that the last document page before the spread wide image
+% may be blank or may be shorter than the other text pages; the user
+% then should help the automatic positioning by choosing very carefully
+% where to insert the \cs{DFfigure} command in the source text; it can
+% even set it within a paragraph and the command provides a new page
+% just after the line that contains the \cs{DFfigure} command;
+% therefore if the paragraph is close to the end of an odd page and
+% the position of \cs{DFfigure} command is properly positioned within this
+% paragraph, the spread wide insertion would not disturb the quality
+% of the typeset document.
+%
+%\item[\texttt{HS}]
+% This display mode is convenient when the initial image aspect
+% ratio is very small; if it is smaller than~0.3 its insertion
+% leaves enough space beneath the two image halves (plus caption)
+% so that normal text can fill the space under such spread wide
+% slim figure. The constrains described for display mode \texttt{SW}
+% apply also to this mode.
+%
+%\item[\texttt{VS}]
+% This mode is convenient for tall and slim figures with aspect ratio
+% not lower than~2; but for obvious reasons, it should not be too
+% large, let's say not higher than about~3. As always this depends on
+% the page design and the caption size. The limitations of the
+% underlying of the |wrapfig| package forbids its usage too close to
+% section headings, explicit lists and texts typeset in special modes
+% with different measure than normal text. Again it is up to the user
+% to chose where to insert the \cs{DFfigure} command. If the aspect
+% ratio of the image to include is lower than~2, this message is printed
+% in the document where the image should appear (of course with |#2| replaced by the actual image file name):
+%\begin{verbatim}
+% ===========================================
+% Figure #2 is not tall enough.
+% Consider using a display mode different
+% from VS; may be NF or RF are better suited.
+% ===========================================
+% Nothing done!
+% ===========================================
+%\end{verbatim}
+%^^A
+%\end{description}
+%
+%^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+% \section{Acknowlegements}
+%^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%
+% This package would not exist if Heinrich Flech did not need
+% to insert several types of large images in his documents; he asked
+% me to create suitable commands and/or environments and he tested
+% all the series of progressive developments of this package; believing
+% that this package might be useful to other \TeX\ users, he invited
+% me to submit the result to the \TeX\ community, and here it is.
+% Heinrich did not want his name as an author, because he insists
+% that he was “just” a tester. He was precious and I warmly thank him.
+%
+%^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%\begin{thebibliography}{9}
+%\bibitem{bib:xparse} The \LaTeX3 Project, \emph{The \texttt{xparse} package} --- Document command parser. Release date 2020-05-15. PDF document readable with \texttt{texdoc xparse}.
+%\bibitem{bib:xfp} The \LaTeX3 Project, \emph{The \texttt{xfp} package} --- Floating Point Unit. Release date 2020-05-15. PDF document readable with \texttt{texdoc xfp}.
+%\bibitem{bib:Int3} The \LaTeX3 Project, \emph{The \LaTeX3 interfaces}. Release date 2020-09-24. PDF Document readable with \texttt{texdoc interface3}.
+%\bibitem{bib:graphics} D.P.~Carlisle and The \LaTeX3 Project, \emph{Packages in the `graphics' bundle}. Release date 2020-08-21. PDF document readable with \texttt{texdoc grfguide}.
+%\bibitem{bib:etoolbox} P. Lehman and J Wright, \emph{the \texttt{etoolbox} Package} --- An e-TeX Toolbox for Class and Package Authors. version 2.5j, released on 2020-08-24. PDF document readable with \texttt{texdoc etoolbox}.
+%\bibitem{bib:lscape} D.P. Carlisle, \emph{The \texttt{lscape} package}. Version 3.02 released on 2020-05-28. PDF document readable with \texttt{texdoc lscape}.
+%\bibitem{bib:afterpage} D.P. Carlisle, \emph{The \texttt{afterpage} package}. Version 1.08 released on 2014-10-28. PDF document readable with \texttt{texdoc afterpage}.
+%\bibitem{bib:wrapfig} D. Arseneau, \emph{The \texttt{wrapfig} package}. Version 3.6 released on 2003-01-31.
+%\bibitem{bib:memman} P. Wilson, \emph{The Memoir Class for Configurable Typesetting} ---User guide. Version 3.7m released 2020-09-10. PDF document readable with \texttt{texdoc memman}.
+%\end{thebibliography}
+%
+% \StopEventually{}
+%
+%^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+% \section{The code}
+%^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+% The required \TeX\ format and is date, and the identification of this
+% package have already ben inserted by the initial commands of this
+% documented file.
+%
+% Here we call the initial required packages and, since the necessary
+% software to define some \LaTeX3 (L3) language “functions” are already
+% part of the \LaTeX\ kernel, we just use them in order to define a
+% robust \LaTeXe/L3 interface to create a testing macro that accepts
+% many logical operators that act on items that, besides being boolean
+% variables, are also numerical expressions connected with relation
+% operators; for further details it suffices to examine the
+% |interface3.pdf| file, that is integral part of any recent \TeX\
+% system distribution.
+%
+% The syntax of the new testing macro is the following:
+%\begin{ttsyntax}
+%\cs{fptest}\marg{test}\marg{true}\marg{false}
+%\end{ttsyntax}
+% The logical operators that are usable in the \meta{text} phrase
+% are \verb+||+ (\texttt{OR}), \verb+&&+ (\texttt{and}), and \verb+!+
+% (\texttt{NOT}), plus other less common ones; the \verb+!+ negates the
+% status of boolean variables, but also the numerical relation operators;
+% these, on turn, may be paired so that, for example |>=| is the same
+% as~|!<|.
+%
+% The |trace| package is still present in this beta version of the
+% package; it will not be present in the next stable versions.
+% Packages |graphicx|, |afterpage|, and |wrapfig| are functional
+% for this package. In order to avoid “Option Clash” messages, such
+% packages are loaded without any option; should the user load some
+% or all of them with options, this operation must be done
+% \emph{before} loading this package.
+%\iffalse
+%<*package>
+%\fi
+% \begin{macrocode}
+\RequirePackage{etoolbox}
+\RequirePackage{xparse}
+\RequirePackage{xfp}
+
+\ExplSyntaxOn
+\AtBeginDocument{%
+\ProvideExpandableDocumentCommand\fptest{m m m}{%
+ \fp_compare:nTF{#1}{#2}{#3}}
+}
+\ExplSyntaxOff
+
+\RequirePackage{trace}
+
+\RequirePackage{graphicx}
+\RequirePackage{afterpage}
+\RequirePackage{wrapfig}
+
+% \end{macrocode}
+% We define some dimension and some counter registers; to some dimensions
+% we assign parameters relating to the page design. We also compute
+% the dimensions of the available spread space so as to have available
+% the elements to compare the aspect ratios of the images and of the
+% available spaces.
+% \begin{macrocode}
+\newdimen\internalmargin
+\internalmargin=\dimexpr\oddsidemargin+1in+1bp\relax
+\newdimen\spreadwidth
+\spreadwidth=\dimexpr 2\textwidth+2\internalmargin\relax
+%
+\newdimen\DFwidth
+\newdimen\DFheight
+\newdimen\DFhalfwidth
+\newdimen\DFheight
+\newdimen\FigSpace
+\newsavebox\DFtotalimage
+\newsavebox\DFimageI
+\newsavebox\DFimageII
+\newsavebox\RFbox
+\newdimen\VS@textwidth
+\newcount\VS@lines
+
+% \end{macrocode}
+% The following caption-like command recompiles the captions within
+% a zero height vertical box and deals with the mandatory and optional
+% arguments according to the following syntax:
+%\begin{ttsyntax}
+%\cs{DFcaption}\oarg{lof entry}\marg{caption}\oarg{label}
+%\end{ttsyntax}
+% Notice that the ]lof entry defaults to the full caption text if
+% a different text is not explicitly entered.
+% This command is specific those those display modes that compose
+% the caption in vertical mode, therefore the measure is the
+% |\textheight|.
+% \begin{macrocode}
+\NewDocumentCommand\DFcaption{O{#2} m o}{\refstepcounter{figure}%
+ \vtop to 0pt{\hsize=\textheight\parindent=0pt\leavevmode
+ Figure \thefigure\quad #2\vss}%
+ \addcontentsline{lof}{figure}{\protect\numberline{\thefigure}#1}
+ \IfValueT{#3}{\label{#3}}\relax%
+}
+
+% \end{macrocode}
+% The |\cleartoevenpage| command may already exist in the document class.
+% We prefer to make an absolute redefinition so as to be sure that it
+% performs as we need in this package. We tested with the |memoir|
+% class that already has such a command, and no problems were found
+%
+% \begin{macrocode}
+\DeclareRobustCommand\cleartoevenpage{%
+ \clearpage\ifodd\value{page}\null\clearpage\fi}
+% \end{macrocode}
+%
+% Now we define the “real” user macro necessary to chose the
+% \meta{display mode} and the various parameters necessary for the
+% desired one. See section~\ref{sec:Usage} on page\pageref{sec:Usage}
+% for its syntax and the other necessary arguments. Notice that only
+% two arguments are mandatory: the \meta{image file name} and the
+% \meta{caption} text. All the other five optional parameters are
+% delimited by various delimiters; the first one, \meta{display mode}
+% has as default setting the acronym \texttt{SW} for a “Spread-Wide”
+% display mode; this mode was the one this package was initially
+% conceived for, and its initials recall this priority. All other
+% modes came afterwards. the other optional parameters may have a
+% default value, but they are ignored by certain modes that don use
+% those parameters. As for the previous macro |\DFimage|, here the \meta{lof entry} defaults to the full \meta{caption} text.
+%
+% Actually \cs{DFimage} just examines the \meta{display mode}, and
+% accordingly passes the necessary parameters to the actual macros
+% that implement the various mode displays. It outputs an error
+% message if the \meta{display mode} acronym was misspelt.
+% \begin{macrocode}
+\NewDocumentEnvironment{DFimage}{O{SW} m O{#4} m o D(){0.8} D<>{0}}{%
+\ifstrequal{#1}{SW}%
+ {%
+ \SWfigure{#2}[#3]{#4}[#5]%
+ }%
+ {\ifstrequal{#1}{NF}%
+ {%
+ \NFfigure{#2}[#3]{#4}[#5](#6)%
+ }%
+ {\ifstrequal{#1}{RF}% OK
+ {%
+ \RFfigure{#2}[#3]{#4}[#5]%
+ }%
+ {\ifstrequal{#1}{VS}%
+ {%
+ \VSfigure{#2}[#3]{#4}[#5](#6)<#7>%
+ }%
+ {\ifstrequal{#1}{HS}
+ {%
+ \HSfigure{#2}[#3]{#4}[#5](#6)%
+ }%
+ {\PackageWarning{swfigure}%
+ {%
+ **************************************\MessageBreak
+ Option #1\space is not valid \MessageBreak
+ Nothing done \MessageBreak
+ Image #2\space was not processed \MessageBreak
+ **************************************\MessageBreak}%
+ }%
+ }%
+ }%
+ }%
+ }%
+}%
+
+% \end{macrocode}
+% In the following subsection the five specific display mode macros
+% are examined and commented.
+%^^A=====================================
+% \subsection{The specific \cs{SWfigure} macro for Spread Wide images}
+%^^A=====================================
+%The specific macro for spread-wide images has the following syntax:
+%\begin{ttsyntax}
+%\cs{SWfigure}\marg{image file name}\oarg{lof entry}\marg{caption}\oarg{label}
+%\end{ttsyntax}
+% The various arguments have already been described; as you see the
+% \meta{display mode} argument is not there anymore, as well as the
+% last two optional arguments of |\DFfigure|.
+%
+% The working strategy is the following: first the typesetting mode is
+% tested and, in case, a filling of the current line is
+% performed and, by means of a |\vadjust| \TeX\ native macro, a
+% |\newpage| command is executed; in any case a |\cleartoevenpapge|
+% is executed so as to be sure to start any action while an even page
+% is being processed. Then the initial image to be divided in two
+% halves is stored in a box; this box is examined in order
+% to find its total width and heigh, so as to be able to compute the
+% aspect ratio. All other dimensions are examined to have available
+% all the necessary data to display the image halves in the requested
+% way.
+%
+% Notice that the |trim| option to |\includegraphics|, used to
+% divide the initial image in two exact halves, (apparently) must
+% be used without specifying other options; but, most important,
+% it requires real numbers, not macros; therefore we have to make
+% use of the usual dirty trick of defining an expanded macro
+% |\x| within a group that the macro itself closes upon its
+% expansion; in this way the principal part of the |\includegraphics|
+% macro contains only keywords and numbers and may be executed
+% without errors.
+%
+% Let $W$ be the total spread width and $w$ be the initial image
+% width; let $H$ be the text height and $h$ the initial image height;
+% compute the $A_\mathrm{W}$ to be the aspect ratio of the spread
+% available space $H/W$. Similarly let $A_\mathrm{fig}$ aspect
+% ratio of the initial image; we have to scale the image with a
+% scaling factor such that the image keeps its aspect ratio, but
+% its scaled height does not exceed the text block height, and
+% its scaled width does not exceed the spread width; of course the
+% aim is to maintain the scaled image as large as possible therefore
+% we have to chose the most suited of the two scaling factors that
+% can be computed from the given data and the inequalities
+% described above.
+% In mathematical terms we have to chose the initial image scaling
+% factor $S$ such that:
+%\begin{equation}
+%S= \left\{
+% \begin{array}{lll}
+% w/W &\mathrm{if}& A_\mathrm{fig} \leq A_\mathrm{W}\\
+% h/H &\mathrm{if}& A_\mathrm{fig} > A_\mathrm{W}
+% \end{array}
+%\right.
+%\label{equ:ScalingFactor}
+%\end{equation}
+% This choice is made by testing the various ratios by means of
+% the L3 |\fptest| macro, that computes such ratios and compares them.
+% The commented line below shows exactly which lengths are used to
+% compute the ratios, and which comparison is executed. Once the
+% scaling factors are found the boxes containing the half figures
+% are scaled and further on are inserted in floating figure
+% environments; we use another dirty trick of matrioska dolls; this
+% metaphor describes nested |\makeboxe|s used to mask their actual
+% widths, but capable to push the images towards the spread
+% spine.
+% Eventually the caption is set in the right margin of the right
+% spread page, rotated $90^\circ$ counterclockwise.
+% \begin{macrocode}
+\NewDocumentCommand\SWfigure{m O{#3} m o}{%
+\unless\ifvmode
+ \csuse{@bsphack}%
+ \vadjust{\vspace{0pt plus1fill}\csuse{@esphack}\newpage}%
+\fi
+\cleartoevenpage
+\setbox\DFtotalimage=\hbox{\includegraphics{#1}}%
+\DFwidth=\wd\DFtotalimage \DFhalfwidth=0.5\DFwidth
+\DFheight=\ht\DFtotalimage
+\FigSpace=\dimexpr\textwidth+\internalmargin\relax
+%
+\setbox\DFimageI\hbox{\bgroup
+\edef\x{\egroup\noexpand\includegraphics*[%
+trim = 0 0 \the\DFhalfwidth\space 0]}\x{#1}}%
+%
+\setbox\DFimageII\hbox{\bgroup
+\edef\x{\egroup\noexpand\includegraphics*[%
+trim = \the\DFhalfwidth\space 0 0 0]}\x{#1}}%
+%
+% h/w > H/W
+\fptest{\DFheight/\DFhalfwidth > \textheight/\FigSpace}%
+ {\edef\DFscalefactor{\fpeval{\textheight/\DFheight}}}%
+ {\edef\DFscalefactor{\fpeval{\FigSpace/\DFhalfwidth}}}%
+%
+\setbox\DFimageI=\hbox{\scalebox{\DFscalefactor}{\usebox{\DFimageI}}}%
+\setbox\DFimageII=\hbox{\scalebox{\DFscalefactor}{\usebox{\DFimageII}}}%
+%
+\begin{figure}[p]%
+\vbox to\textheight{\vss\hsize=\textwidth%\
+\makebox[\hsize][l]{\makebox[\FigSpace][r]{\box\DFimageI}}\vss}%
+\end{figure}\clearpage
+%
+\begin{figure}[p]%
+\vbox to\textheight{\vss\hsize=\textwidth
+\makebox[\hsize][r]{\makebox[\FigSpace][l]{\box\DFimageII}%
+% Rotated caption in the right page
+\makebox(0,0)[lb]{\hspace*{1em}\raisebox{0.5\textheight}{%
+\rotatebox[origin=tc]{90}{\DFcaption[#2]{#3}[#4]%
+%
+}}}}\vss}%
+\end{figure}\clearpage}
+
+% \end{macrocode}
+%^^A========================================
+%\subsection{The specific \cs{NFfigure} macro for normal full
+% page figures}
+%^^A========================================
+% This code is without surprises, except that it receives from the
+% |DFimage| steering macro five arguments, the last (optional) one
+% being delimited by round parentheses; by default, it contains the
+% value 0.8, but the user can pass to the steering macro a different
+% value in order to reduce the actual image size so as to leave
+% enough space beneath it for the caption; the user, in facts, does
+% not know in advance how many lines would occupy a structured
+% complex caption.
+% \begin{macrocode}
+\NewDocumentCommand\NFfigure{m O{#3} m o d()}{%
+ \begin{figure}[p]
+ \includegraphics[width=\linewidth,height=#5\textheight,
+ keepaspectratio]{#1}%
+ \caption[#2]{#3}%
+ \IfValueT{#4}{\label{#4}}\relax
+ \end{figure}
+}
+
+% \end{macrocode}
+%^^A========================================
+% \subsection{The specific \cs{RFfigure} macro for rotated figures}
+%^^A========================================
+% There are no new comments to make about this almost standard
+% way of displaying a large figure, except, perhaps, the fact
+% the instead of invoking the |lscape| package, the whole figure
+% is rotated by means of rotating the very box that was used
+% to contain the scaled image; the steering macro does not pass
+% any \meta{height correction} argument to this macro, because
+% it automatically scales the box containing the image and
+% the caption so as to fill up the height or the width of the
+% text block.
+% \begin{macrocode}
+%\NewDocumentCommand\RFfigure{m o m o}{%
+\NewDocumentCommand\RFfigure{m O{#3} m o}{%
+ \dimen8=\textwidth\dimen10=\textheight
+ \figure[p]\setbox\RFbox=\hbox{%
+ \rotatebox[origin=cc]{90}{\parbox[b][\dimen8][c]{\dimen10}%
+ {\centering\includegraphics[width=\dimen10, height=\dimen8,
+ keepaspectratio]{#1}%
+ \caption[#2]{#3}%
+ \IfValueT{#4}{\label{#4}}\relax%
+ }}}%
+ \edef\RFx{\fpeval{\ht\RFbox/\textheight}}%
+ \edef\RFy{\fpeval{\wd\RFbox/\textwidth}}%
+ \fptest{\RFx > \RFy}%
+ {\scalebox{\RFx}{\box\RFbox}}%
+ {\scalebox{\RFy}{\box\RFbox}}%
+ \endfigure}
+
+% \end{macrocode}
+%^^A========================================
+% \subsection{The specific \cs{VSfigure} macro for tall and slim figures}
+%^^A========================================
+% This is the most troublesome macro, because it needs to depend
+% on the |wrapfig| package, in order to set the image with its
+% caption on the external side of the text block, with the text flowing
+% around it. Package |wrapfig| has several limitations concerning
+% the text that flows around the image. Nevertheless with a “normal”
+% textual contents of the text block the result may be very good.
+%
+% The user should help a little bit the correct performance of
+% this macro; for this reason, besides the \meta{height correction}
+% factor, the steering macro may pass to it also the \meta{line
+% correction} in order to correct the amount of lines the surrounding
+% text should be indented; by playing with both corrections
+% good results may be obtained.
+%
+% Notice that only with this macro a test on the initial image
+% aspect ratio is performed; should this image have an aspect ratio
+% smaller than~2, the process is aborted and a message is printed
+% in the output document that informs the user and recommends to
+% use another \meta{display mode} acronym.
+%
+% \begin{macrocode}
+\NewDocumentCommand\VSfigure{m O{#3} m o d() D<>{0}}{%
+ \setbox\DFtotalimage=\hbox{\includegraphics{#1}}
+ \DFwidth=\wd\DFtotalimage \DFheight=\ht\DFtotalimage
+ \edef\VS@aspectratio{\fpeval{\DFheight/\DFwidth}}
+ \fptest{ \VS@aspectratio < 2 }%
+ {\begin{center}\ttfamily
+ ===========================================\\
+ Figure #2 is not tall enough.\\
+ Consider using a display mode different\\
+ from VS; may be NF or RF are better suited.\\
+ ===========================================\\
+ Nothing done!\\
+ ===========================================
+ \end{center}
+ }%
+ {\edef\VS@factor{\fpeval{#5\textheight/\DFheight}}%
+ \setbox\DFtotalimage=
+ \hbox{\scalebox{\VS@factor}{\box\DFtotalimage}}%
+ \edef\VS@width{\fpeval{\VS@factor*\DFwidth}\p@}%
+ \setbox\DFtotalimage=\vbox{\hsize=\VS@width%
+ \def\@captype{figure}\box\DFtotalimage
+ \caption[#2]{#3}%
+ \IfValueT{#4}{\label{#4}}\relax}
+ \VS@lines=
+ \fpeval{round(\ht\DFtotalimage/\baselineskip,0)+#6}%
+ \begin{wrapfigure}[\VS@lines]{O}[0pt]{\VS@width}%
+ \box\DFtotalimage
+ \end{wrapfigure}}%
+}
+
+% \end{macrocode}
+%
+%^^A=====================================
+% \subsection{The specific \cs{HSfigure} macro for spread wide slim
+% figures}
+%^^A=====================================
+%
+% The beginning of the macro is not so different from that used
+% for the |SWfigure| macro. But this time there is no alternative
+% to scale the image taking into account only its width and the
+% spread width. The new little problem, now, is to match the total
+% height of the two halves of the original wide and slim image,
+% so that the texts of the two facing pages have their respective
+% first lines perfectly aligned.
+%
+% Since the right half of the figure contains also the caption
+% it is necessary to box again the left page box so as to have
+% the same hight and depth as the right page one.
+% \begin{macrocode}
+\NewDocumentCommand\HSfigure{m o m o d()}{%
+ \unless\ifvmode
+ \csuse{@bsphack}%
+ \vadjust{\vspace{0pt plus1fill}\csuse{@esphack}\newpage}%
+ \fi
+ \cleartoevenpage
+ \setbox\DFtotalimage=\hbox{\includegraphics{#1}}
+ \DFwidth=\wd\DFtotalimage \DFhalfwidth=0.5\DFwidth
+ \FigSpace=0.5\spreadwidth% W
+%
+ \setbox\DFimageI\hbox{\bgroup
+ \edef\x{\egroup\noexpand\includegraphics*[%
+ trim = 0 0 \the\DFhalfwidth\space 0]}\x{#1}}%
+%
+ \setbox\DFimageII\hbox{\bgroup
+ \edef\x{\egroup\noexpand\includegraphics*[%
+ trim = \the\DFhalfwidth\space 0 0 0]}\x{#1}}%
+%
+ \edef\DFscalefactor{\fpeval{\FigSpace/\DFhalfwidth}}%
+%
+ \setbox\DFimageI=\hbox{%
+ \scalebox{\DFscalefactor}{\usebox{\DFimageI}}}%
+ \setbox\DFimageII=\hbox{%
+ \scalebox{\DFscalefactor}{\usebox{\DFimageII}}}%
+ \setbox\DFimageII=
+ \hbox{\dimen10=\linewidth\dimen8\internalmargin
+ \vbox{\hsize\DFhalfwidth\parindent\z@
+ \box\DFimageII\par
+ \leavevmode\hspace*{\dimen8}%
+ \vtop{\hsize\dimen10\parindent\z@
+ \textwidth=\hsize
+ \DFcaption[#2]{#3}[#4]%
+ }%
+ }%
+ }%
+ \setbox\DFimageI=\vbox to\ht\DFimageII{\box\DFimageI\vss}%
+%
+ \begin{figure}[t]
+ \makebox[\textwidth][l]{%
+ \makebox[\DFhalfwidth][l]{\box\DFimageI}}%
+ \end{figure}
+ \afterpage{%
+ \begin{figure}[t]
+ \makebox[\textwidth][r]{%
+ \makebox[\DFhalfwidth][r]{\box\DFimageII}}%
+ \end{figure}%
+ }
+}
+% \end{macrocode}
+%\begin{center}\setfontsize{15mm}
+%\color{red} HAPPY \LaTeX-ING
+%\end{center}
+%\endinput
+%\iffalse
+%</package>
+%\fi
+%\iffalse
+%<*readme>
+%\fi
+% \begin{macrocode}
+This bundle contains file the swfigure.dtx and README.txt files.
+This file README.txt contains the licence, the status, and some
+general information. Save both in a .../source/latex/swfigure
+folder either in the main TeX system tree or in your personal
+tree.
+
+This swfigure.dtx file is a self extracting documented one.
+Run pdfLaTeX at least twice on this file in order to get all
+references correct, and you obtain the swfigure.pdf and the
+swfigure.sty files. After extraction move the .sty file to
+the .../tex/latex/swfigure folder, and move the .pdf file to
+the .../doc/latex/swfigure folder. From the original folder
+.../source/latex/swfigure move all files, except the .dtx and
+the .txt files, to the bin.
+
+The author disclaims any liability from every possible inconvenience
+deriving from the use of this software; you use it at your own risk.
+
+% \end{macrocode}
+%\iffalse
+%</readme>
+%\fi \ No newline at end of file
diff --git a/macros/latex/contrib/swfigure/swfigure.pdf b/macros/latex/contrib/swfigure/swfigure.pdf
new file mode 100644
index 0000000000..5e3fad2b04
--- /dev/null
+++ b/macros/latex/contrib/swfigure/swfigure.pdf
Binary files differ