phffullpagefigure (16aug16)

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

2 files changed, 1023 insertions, 0 deletions

diff --git a/Master/texmf-dist/source/latex/phffullpagefigure/phffullpagefigure.dtx b/Master/texmf-dist/source/latex/phffullpagefigure/phffullpagefigure.dtx
new file mode 100644
index 00000000000..9a88636dc0f
--- /dev/null
+++ b/Master/texmf-dist/source/latex/phffullpagefigure/phffullpagefigure.dtx
@@ -0,0 +1,968 @@
+% \iffalse meta-comment
+%
+% Copyright (C) 2016 by Philippe Faist <philippe.faist@bluewin.ch>
+% -------------------------------------------------------
+% 
+% This file may be distributed and/or modified under the
+% conditions of the LaTeX Project Public License, either version 1.3
+% of this license or (at your option) any later version.
+% The latest version of this license is in:
+%
+%    http://www.latex-project.org/lppl.txt
+%
+% and version 1.3 or later is part of all distributions of LaTeX 
+% version 2005/12/01 or later.
+%
+% \fi
+%
+% \iffalse
+%<*driver>
+\ProvidesFile{phffullpagefigure.dtx}
+%</driver>
+%<package>\NeedsTeXFormat{LaTeX2e}[2005/12/01]
+%<package>\ProvidesPackage{phffullpagefigure}
+%<*package>
+    [2016/08/15 v1.0 phffullpagefigure package]
+%</package>
+%
+%<*driver>
+\documentclass{ltxdoc}
+\usepackage{xcolor}
+\usepackage{phffullpagefigure}
+\usepackage[preset=xpkgdoc]{phfnote}
+\EnableCrossrefs         
+\CodelineIndex
+\RecordChanges
+\begin{document}
+  \DocInput{phffullpagefigure.dtx}
+\end{document}
+%</driver>
+% \fi
+%
+% \CheckSum{0}
+%
+% \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         \~}
+%
+%
+% \changes{v1.0}{2016/04/20}{Initial version}
+%
+% \GetFileInfo{phffullpagefigure.dtx}
+%
+% \DoNotIndex{\newcommand,\newenvironment,\def,\gdef,\edef,\xdef,\if,\else,\fi,\ifx}
+% 
+% \title{\phfqitltxPkgTitle{phffullpagefigure}}
+% \author{Philippe Faist\quad\email{philippe.faist@bluewin.ch}}
+% \date{\pkgfmtdate\filedate}
+% \maketitle
+%
+% \begin{abstract}
+%   \pkgname{phffullpagefigure}---Figures which fill up a full page of a document.
+% \end{abstract}
+%
+% \inlinetoc
+%
+% \section{Introduction}
+%
+% The package \pkgname{phffullpagefigure} provides an implementation for figures which are
+% to be displayed to occupy a full page.
+%
+% A typical use case: suppose you have a figure in PDF format of the size of the document
+% paper, for example, and wants to include it as a figure.
+%
+% This package takes care to display the caption of the figure on the preceeding page,
+% with a caption of the form ``Figure X (on facing page): \meta{caption}.''
+%
+% For two-sided documents, you may specify on which (odd/even) page side
+% you want the figure to appear.  If the document is not two-sided, the
+% figure may appear on any page.
+%
+% A number of options allow you to set the exact figure contents (usually a
+% PDF file, but it can be constructed from arbitrary \LaTeX{} commands),
+% the figure caption placement (top, own page, bottom), the caption and
+% label as usual, and the formatting of the caption if you want to replace
+% the default ``(on facing page)'' or ``(on next page).''
+%
+%
+% \section{The Full-Page-Figure Environment}
+%
+% \DescribeEnv{fullpagefigure} The |\begin{fullpagefigure}| |...|
+%   |\end{fullpagefigure}| environment starts a full-page-figure.  Inside
+% this environment, only the following commands may be used:
+% \begin{itemize}
+% \item one of the |\fig***| commands;
+% \item the |\caption| command, to provide a figure caption as for regular
+%   figures;
+% \item the |\label| command to set a label for text references to this
+%   figure, also as for regular figures.
+% \end{itemize}
+%
+% A simple example to get started:
+%
+% \begin{verbatim}
+% \begin{fullpagefigure}
+%   \figpdf{fig/my-figure} % my PDF file
+%   \caption{A colorful figure with letters and words.  The table
+%     design may remind you of going to the optician.}
+%   \label{fig:test}
+% \end{fullpagefigure}
+% \end{verbatim}
+%
+% \begin{fullpagefigure}%
+%   \iffalse meta-comment
+%     In this documentation code, we cheat and provide LaTeX code for the
+%     figure instead of a PDF file.  This is really just so that we don't
+%     have to ship an extra PDF file (and for no other reason).
+%     
+%     See a trick in http://tex.stackexchange.com/a/278101/32188 and
+%     http://tex.stackexchange.com/a/40503/32188 .
+%   \fi
+%   \figcontents{\newpage\thispagestyle{empty}\relax
+%     \newgeometry{margin=0.25in}\relax
+%     \sffamily\fontsize{36pt}{42pt}\fontseries{bx}\selectfont
+%     \hbox to 0.9\textwidth{\fcolorbox{red}{yellow}{\vbox to 0.99\textheight{\vfil\vfil\vfil\centering
+%         \leavevmode\noindent\hbox to 0.8\textwidth{ \color{red!50!black} T H I S }\par\vfil
+%         \vfil
+%         \leavevmode\noindent\hbox to 0.8\textwidth{ \color{green!70!red} F I G U R E }\par\vfil
+%         \vfil
+%         \leavevmode\noindent\hbox to 0.8\textwidth{ \color{black!40!blue} F I L L S }\par\vfil
+%         \vfil
+%         \leavevmode\noindent\hbox to 0.8\textwidth{ \color{green!40!blue} U P }\par\vfil
+%         \vfil
+%         \leavevmode\noindent\hbox to 0.8\textwidth{ \color{red!50!gray} T H E }\par\vfil
+%         \vfil
+%         \leavevmode\noindent\hbox to 0.8\textwidth{ \color{blue} W H O L E }\par\vfil
+%         \vfil
+%         \leavevmode\noindent\hbox to 0.8\textwidth{ \color{red!50!yellow} P A G E }\par\vfil
+%         \vfil\vfil\vfil}}}%
+%       \clearpage\aftergroup\restoregeometry}%
+%   \caption{A colorful figure with letters and words.  The table design
+%       may remind you of going to the optician.}%
+%   \label{fig:test}%
+% \end{fullpagefigure}
+%
+% The |\figpdf| command sets the PDF file to be displayed in full page (see
+% more details below).  You may contemplate the result of this code in
+% \autoref{fig:test}.
+%
+% Some wizard once told me that old wise men had determined that the
+% |fullpagefigure| environment should be placed at the beginning of a
+% paragraph, or on its own paragraph.  (TODO: I'm not too sure why this is
+% the case or if this is still relevant.)
+%
+%
+% The contents and appearance of the figure can be adjusted by the
+% following commands, which must be issued within the |fullpagefigure|
+% environment.
+%
+% \DescribeMacro{\figcontents} Specify the contents of the figure by calling
+% |\figcontents|\marg{\LaTeX{} commands}.  The contents can be any \LaTeX{}
+% commands which will generate the figure content.  These commands will be
+% called within an |afterpage| block.\footnote{See documentation for the
+% \pkgname{afterpage} package}
+%
+% If you want a figure to occupy several pages, you may use for example
+% |\figcontents{\includepdf{pdf-1}\includepdf{pdf-2}}|, and request that
+% the figure start on an even-side page with |\figpageside{even}|.
+%
+% If the \meta{\LaTeX{} commands} are not |\includepdf| instructions
+% and want to change the page geometry for the figure and you're using
+% the \pkgname{geometry} package, have a look at these \texttt{TeX.SX}
+% answers\footnote{\url{http://tex.stackexchange.com/a/278101/32188}
+% and \url{http://tex.stackexchange.com/a/40503/32188}} for getting
+% the |\newgeometry| and
+% |\restoregeometry| commands right.  You might use, for example:\\[1ex]
+% \noindent|\figcontents{\newpage\thispagestyle{empty}%|\\
+% \hspace*{2em}|\newgeometry{margin=0.25in}% or 0in for no margins|\\
+% \hspace*{2em}\meta{\ldots{} \LaTeX{} commands to draw figure contents ...}\\
+% \hspace*{2em}|\clearpage\aftergroup\restoregeometry}|.
+%
+%
+% 
+% \DescribeMacro{\figpdf} As a shorthand, you may use
+% |\figpdf|\oarg{options}\marg{pdf-file} as a shorthand for
+% |\figcontents{\includepdf|\oarg{options}\marg{pdf-file}|}|.
+% 
+% You should explore the options provided by |\includepdf| (from the
+% \pkgname{pdfpages} package\footnote{See documentation at
+% \url{https://www.ctan.org/pkg/pdfpages}}).  For example, the figure can
+% be resized to fill the page, pages may be selected individually from a
+% mult-page PDF, the image may be rotated, etc.
+%
+%
+% \DescribeMacro{\caption} \DescribeMacro{\label} The |\caption|\oarg{short
+% caption}\marg{caption} and |\label|\marg{identifier} macros may be used
+% as for a normal figure.  Be warned, though, that some dark manipulations
+% occur here, so it may be for example that the code passed as argument to
+% these commands is expanded only later.
+%
+% \DescribeMacro{\figpageside} Use the commands |\figpageside{odd}|,
+% |\figpageside{}|, or |\figpageside{even}| to specify on which side the
+% figure should appear on if the document is two-sided.  This command has
+% no effect if the document is not two-sided (|twoside| class option for
+% the |article| or |book| classes, for example).  Calling |\figpageside{}|,
+% i.e.\@ with an empty argument, instructs |fullpagefigure| to use either
+% side, whichever is more convenient.
+%
+% \DescribeMacro{\figplacement} Specify the figure caption placement with
+% |\figplacement||{b|$\mid$|t|$\mid$|p}|.  Each of |b| (bottom), |t| (top)
+% and |p| (own page) work as for usual LaTeX floats.  If you specify |p|,
+% do NOT combine it with any other option.  You may leave the argument
+% empty (|\figplacement{}|) to use defaults.
+%
+% The figure placement can also be specified as an optional argument to the
+% environment (e.g., |\begin{fullpagefigure}[p]| \ldots{} |\end{fullpagefigure}|).
+%
+% \DescribeMacro{\figcapmaxheight} Specify the maximum estimated height of
+% the caption with |\figcapmaxheight|\marg{length}.  This is used to see
+% whether the figure caption still fits on the current page.
+%
+% TODO: This is ugly, the height of the caption should be calculated
+% automatically\ldots{} for next time.
+%
+% By default (if no |\figcapmaxheight| is present), the figure will never
+% be assumed to fit in the remainder of the page.
+%
+% \DescribeMacro{\fullpagefigurecaptionfmt}
+% The figure label in the caption may be changed (e.g. ``Figure X (on facing page): \ldots'') by
+% redefining the command |\fullpagefigurecaptionfmt|.  See the default implementation for
+% more info (\autoref{sec:impl}).
+%
+% \DescribeMacro{\FlushAllFullPageFigures} If you need to make sure that
+% all full-page-figures have been placed up to a certain point, you may
+% issue the command |\FlushAllFullPageFigures|.  (You may wish to do so
+% before starting a new chapter.)  An optional argument
+% |\FlushAllFullPageFigures[\clearpage]| or
+% |\FlushAllFullPageFigures[\cleardoublepage]| specifies whether to
+% continue on any page or on an odd-side page only.
+% 
+%
+%
+% \section{Package Options}
+%
+% Only a single package option is recognized:
+%
+% \begin{verbatim} \usepackage[nopdfpages]{phffullpagefigure} \end{verbatim}
+%
+% If this package option is given, then the \pkgname{pdfpages} package
+% is not loaded, and the command |\figpdf| is not made available.  You
+% may use this package option if the \pkgname{pdfpages} package
+% conflicts with your setup.
+%
+%
+%
+%
+%
+%
+%
+%
+% \StopEventually{\PrintChangesAndIndex}
+%
+% \section{Implementation}
+% \label{sec:impl}
+%
+% Include some general useful packages first.
+%    \begin{macrocode}
+\RequirePackage{etoolbox}
+\RequirePackage{ifoddpage}
+\RequirePackage{afterpage}
+%    \end{macrocode}
+% 
+% The \pkgname{placeins} package provies the |\FloatBarrier| command,
+% which we use to ensure that no other float gets in the way.
+%    \begin{macrocode}
+\RequirePackage{placeins}
+%    \end{macrocode}
+% 
+% \begin{macro}{phffpf@internal@pending}
+%   Counter which stores how many full-page-figures still haven't been
+%   placed.  Used for |\FlushAllFullPageFigures| as well as making sure
+%   that the full-page-figures don't interfere with one another.
+%    \begin{macrocode}
+\newcounter{phffpf@internal@pending}
+\setcounter{phffpf@internal@pending}{0}
+%    \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\phffpfFloatBarrier}
+%   Redefine this if you don't want to use a |\FloatBarrier|.  Be warned of
+%   the following points:
+%
+%   \begin{itemize}
+%   \item |\FloatBarrier| introduces automatically a new paragraph.
+%     Nothing you can do about that a priori.
+%
+%   \item If you remove |\FloatBarrier|, you need to either be sure that
+%     there are no floats which can mess up placement of the
+%     fullpagefigure.  Alternatively, you need to provide your own
+%     mechanism that ensures that.
+%   \end{itemize}
+%
+%    \begin{macrocode}
+\def\phffpfFloatBarrier{\FloatBarrier}
+%    \end{macrocode}
+% \end{macro}
+% 
+%
+% \subsection{The Main Environment Definition}
+%
+% \begin{environment}{fullpagefigure}
+%   The main |fullpagefigure| environment.
+%    \begin{macrocode}
+\newenvironment{fullpagefigure}[1][b]{% 
+%    \end{macrocode}
+% 
+% Remember that we have a float pending to be placed:
+%    \begin{macrocode}
+  \addtocounter{phffpf@internal@pending}{1}%
+%    \end{macrocode}
+% 
+% Don't allow any other floats to meddle with our calculations.
+%    \begin{macrocode}
+  \phffpfFloatBarrier%
+  %[YYY]% -- debugging [where is a space being inserted?]
+%    \end{macrocode}
+% 
+% The following variables will store the relevant values of options
+% collected in the definition of the figure with e.g. |\figplacement|,
+% |\figcontents|, etc.
+% 
+% NOTE TO SELF: If you add a |\phffpf@val@...| storage variable, don't
+% forget to fix that value in |\phffpf@takecareofplacingfigure|.
+% 
+%    \begin{macrocode}
+  \xdef\phffpf@val@pageside{\phffpf@side@}%
+  \gdef\phffpf@val@captionopt{}%
+  \gdef\phffpf@val@caption{}%
+  \gdef\phffpf@val@label{}%
+  \gdef\phffpf@val@placement{#1}%
+  \gdef\phffpf@val@capmaxheight{\paperheight}%
+  \gdef\phffpf@val@figcontents{}%
+%    \end{macrocode}
+%
+% If this document is two-sided (facing odd/even pages), then by default
+% place the float on an odd page.  Otherwise, we don't care.
+% 
+%    \begin{macrocode}
+  \if@twoside%
+    \xdef\phffpf@val@pageside{\phffpf@side@odd}%
+  \else\fi%
+%    \end{macrocode}
+%
+% Provide a set of commands within this figure block which allow to specify
+% the figure contents and appearance:
+%    \begin{macrocode}
+  \begingroup%
+  \let\figcontents\phffpf@impl@figcontents%
+  \let\figpageside\phffpf@impl@figpageside%
+  \let\caption\phffpf@impl@caption%
+  \let\label\phffpf@impl@label%
+  \let\figplacement\phffpf@impl@placement%
+  \let\figcapmaxheight\phffpf@impl@capmaxheight%
+%    \end{macrocode}
+% 
+% Provide |\figpdf| as a shorthand, but only if applicable (i.e., the
+% |nopdfpages| package option was not specified and the
+% \pkgname{pdfpages} package was loaded):
+%    \begin{macrocode}
+  \phffpf@provide@figpdf%
+%    \end{macrocode}
+%
+% Finally, ignore any spaces following this command, as well as after the
+% |\endenvironment| command.
+%    \begin{macrocode}
+  \ignorespacesafterend%
+  \ignorespaces%
+}
+%    \end{macrocode}
+% 
+% Now, the definitions for the end of the environment:
+%    \begin{macrocode}
+{%
+%    \end{macrocode}
+%
+% Remove any spaces which might have been inserted.
+%    \begin{macrocode}
+  \ifhmode\unskip\fi%
+%    \end{macrocode}
+%
+% Restore |\caption|, |\label|, etc.\@ to their original meaning:
+%    \begin{macrocode}
+  \endgroup%
+%    \end{macrocode}
+% 
+% Finally we should actually take care of placing the figure.
+%    \begin{macrocode}
+  \phffpf@takecareofplacingfigure%
+%    \end{macrocode}
+% 
+% Finally finally, ignore any spaces following this command.  Note that
+% because the expansion of |\endfullpagefigure| is inside the definition of
+% \LaTeX' ``|\end|'' and has internal commands after that, we can't just
+% simply issue a |\ignorespaces|.
+%
+%    \begin{macrocode}
+  \phfpf@useignorespacesandallpars%
+}
+%    \end{macrocode}
+% \end{environment}
+%
+% \begin{macro}{\phffpf@useignorespacesandallpars}
+%   Utility to ignore spaces and paragraphs after the
+%   |\end{fullpagefigure}| command.\footnote{This solution was adapted from
+% \url{http://tex.stackexchange.com/a/179034/32188} and
+% \url{http://tex.stackexchange.com/a/23101/32188}.}
+%    \begin{macrocode}
+\def\phfpf@useignorespacesandallpars#1\ignorespaces\fi{%
+  #1\fi\phffpf@ignorespacesandallpars}
+\def\phffpf@ignorespacesandallpars{%
+  \begingroup%
+  \catcode`\^^M=10\relax%
+  \catcode`\^^J=10\relax%
+  \@ifnextchar\par%
+    {\endgroup\expandafter\phffpf@ignorespacesandallpars\@gobble}%
+    {\endgroup}%
+}
+%    \end{macrocode}
+% \end{macro}
+% 
+%
+%
+% \begin{macro}{\fullpagefigurecaptionfmt}
+% \begin{macro}{\fullpagefigurecaptionfmt@paren@O}
+% \begin{macro}{\fullpagefigurecaptionfmt@paren@E}
+% \begin{macro}{\fullpagefigurecaptionfmt@paren@x}
+%   The macro |\fullpagefigurecaptionfmt| is called to generate the text
+%   which is prepended to the figure caption.  It should essentially say
+%   ``Figure X (on next page): ''.
+%
+%   The argument to |\fullpagefigurecaptionfmt| is |#1| = |O|, |E| or |x|
+%   for if the figure is on an odd page, an even page, or an unspecified
+%   page.
+%    \begin{macrocode}
+\def\fullpagefigurecaptionfmt#1{%
+  \figurename\nobreakspace\thefigure\nobreakspace%
+  (\csname fullpagefigurecaptionfmt@paren@#1\endcsname)%
+}
+\def\fullpagefigurecaptionfmt@paren@O{on facing page} % for odd page figures
+\def\fullpagefigurecaptionfmt@paren@E{on next page}   % for even page figures
+\def\fullpagefigurecaptionfmt@paren@x{on next page}   % for next-page figures
+%    \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+%
+%
+% \subsection{Implementation of \phfverb{\fig}\phfverb{****} Commands}
+%
+% These macros really just store their values for later use.
+%
+% \begin{macro}{\figcontents}
+%   This macro will become |\figcontents| inside the |fullpagefigure|
+%   environment.
+%    \begin{macrocode}
+\newtoks\phffpf@tmp@toks
+\long\def\phffpf@impl@figcontents#1{%
+  \phffpf@tmp@toks={#1}%
+  \xdef\phffpf@val@figcontents{\the\phffpf@tmp@toks}%
+  \ignorespaces%
+}
+%    \end{macrocode}
+% \end{macro}
+% 
+% \begin{macro}{\phffpf@side@odd}
+% \begin{macro}{\phffpf@side@even}
+% \begin{macro}{\phffpf@side@}
+%   These hold one-character codes to signify ``odd side,'' ``even side,''
+%   or ``no specification.''
+%
+%    \begin{macrocode}
+\def\phffpf@side@odd{O}
+\def\phffpf@side@even{E}
+\def\phffpf@side@{x}
+%    \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% 
+% \begin{macro}{\figpageside}
+%   This will become |\figpageside| inside the |fullpagefigure|
+%   environment.
+%    \begin{macrocode}
+\def\phffpf@impl@figpageside#1{%
+  \ifcsname phffpf@side@#1\endcsname%
+    \xdef\phffpf@val@pageside{\csname phffpf@side@#1\endcsname}%
+  \else%
+    \PacakgeError{phffullpagefigure}{Unknown page side designation:
+      '#1'. Please use 'odd', 'even', or '' for no preference.}%
+  \fi%
+  \ignorespaces%
+}
+%    \end{macrocode}
+% \end{macro}
+% 
+% \begin{macro}{\caption}
+%   This will become |\caption| inside the |fullpagefigure| environment.
+%    \begin{macrocode}
+\def\phffpf@NOARG{}
+\def\phffpf@test@NOARG{\phffpf@NOARG}
+\newcommand\phffpf@impl@caption[2][\phffpf@NOARG]{%
+  \gdef\phffpf@val@captionopt{#1}%
+  \gdef\phffpf@val@caption{#2}%
+  \ignorespaces%
+}
+%    \end{macrocode}
+% \end{macro}
+% 
+% \begin{macro}{\label}
+%   This will become |\label| inside the |fullpagefigure| environment.
+%    \begin{macrocode}
+\def\phffpf@impl@label#1{%
+  \gdef\phffpf@val@label{#1}%
+  \ignorespaces%
+}
+%    \end{macrocode}
+% \end{macro}
+% 
+% \begin{macro}{\figplacement}
+%   This will become |\figplacement| inside the |fullpagefigure| environment.
+%    \begin{macrocode}
+\def\phffpf@impl@placement#1{%
+  \gdef\phffpf@val@placement{#1}%
+  \ignorespaces%
+}
+%    \end{macrocode}
+% \end{macro}
+% 
+% \begin{macro}{\figcapmaxheight}
+%   This will become |\figcapmaxheight| inside the |fullpagefigure|
+%   environment.
+%    \begin{macrocode}
+\def\phffpf@impl@capmaxheight#1{%
+  \gdef\phffpf@val@capmaxheight{#1}%
+  \ignorespaces%
+}
+%    \end{macrocode}
+% \end{macro}
+% 
+%
+%
+% \subsection{Placing the figures}
+%
+% Here's the gory details of how the figures are placed.
+%
+%
+% \begin{macro}{\phffpf@place@pending@figs@code}
+%   This macro will store code to be executed after the next figure has
+%   been placed.  This can be used to queue other figures to be placed
+%   later.
+%    \begin{macrocode}
+\def\phffpf@place@pending@figs@code{\phffpf@place@pending@figs@code@start}
+%    \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\phffpf@place@pending@figs@code@start}
+%   When another figure is placed, and the
+%   |\phffpf@place@pending@figs@code| is updated, then the macro
+%   |\phffpf@place@pending@figs@code@start| contains the code which
+%   reinitializes |\phffpf@place@pending@figs@code|.
+%
+%   This reinitialization code consists in precisely making sure that a
+%   future execution of |\phffpf@place@pending@igs@code@start| will start
+%   by reinitializing that macro.
+%    \begin{macrocode}
+\def\phffpf@place@pending@figs@code@start{%
+  \gdef\phffpf@place@pending@figs@code{\phffpf@place@pending@figs@code@start}}
+%    \end{macrocode}
+% \end{macro}
+%
+%
+% \begin{macro}{\phffpf@impl@figcode}
+%   The code to be inserted to generate the figure.
+%
+%   The argument |#1| is the prefix for macro names where to look up the
+%   contents of the figure and values of the figure settings.  The macro
+%   names are determined as |\csname #1@|\meta{field-name}|\endcsname|.
+%    \begin{macrocode}
+\gdef\phffpf@impl@figcode#1{%
+%    \end{macrocode}
+% 
+% Do we have a figure placement position request (|p|, |t|, |b|)?  If yes,
+% then define a macro which we will expand in front of the |\begin{figure}|
+%   command for the caption.  If no, then that macro should be left blank
+%   (first case below):
+%    \begin{macrocode}
+  \expandafter\ifblank\expandafter{\csname #1@placement\endcsname}{%
+    \edef\phffpf@tmp@figplacementarg{}%
+  }{%
+    \edef\phffpf@tmp@figplacementarg{[\csname #1@placement\endcsname]}%
+  }
+%    \end{macrocode}
+% 
+% Invoke the |figure| environment, which we use to typeset the caption.
+% Use specified placement if applicable.  Set up some basic stuff in the
+% figure: the contents, caption and label.
+%    \begin{macrocode}
+  \expandafter\figure\phffpf@tmp@figplacementarg%
+  \centering%
+  \begingroup%
+  \def\fnum@figure{\fullpagefigurecaptionfmt{\csname #1@pageside\endcsname}}%
+  \expandafter\afterpage\expandafter{\csname #1@figcontents\endcsname}%
+  \expandafter\ifx\csname #1@captionopt\endcsname\phffpf@test@NOARG%
+    \expandafter\caption\expandafter{\csname #1@caption\endcsname}%
+  \else%
+    \def\phffpf@tmp@captioncmdopt{%
+      \expandafter\caption\expandafter[\csname #1@captionopt\endcsname]}%
+    \expandafter\phffpf@tmp@captioncmdopt\expandafter{\csname #1@caption\endcsname}%
+  \fi%
+  \expandafter\notblank\expandafter{\csname #1@label\endcsname}{%
+    \expandafter\label\expandafter{\csname #1@label\endcsname}%
+  }{%
+  }
+  \endgroup%
+  \endfigure%
+%    \end{macrocode}
+%
+% Now we have placed the |figure|, so decrease our ``pending-to-be-placed''
+% counter.
+%    \begin{macrocode}
+  \addtocounter{phffpf@internal@pending}{-1}%
+%    \end{macrocode}
+%
+% \ldots{} and execute the code to place any other pending figures.  (We
+% set |\ifphffpf@flag@forcenextmaybequeuetoplacefigure| to TRUE to force
+% the next figure in queue to be placed now.)
+%    \begin{macrocode}
+  \afterpage{%
+    \phffpf@flag@forcenextmaybequeuetoplacefiguretrue%
+    \phffpf@place@pending@figs@code%
+  }%
+}
+%    \end{macrocode}
+% \end{macro}
+%
+%
+% Now, all options have been set etc., the fullpagefigure environment has finished, so
+% calculate the commands to place the figure appropriately.
+%
+%
+% \begin{macro}{\phffpf@takecareofplacingfigure}
+%   First, fix the values of the contents and settings (in case another
+%   full-page-figure comes along and messes up the |\phffpf@val@...|
+%   commands).
+%
+%   After the values have been fixed (in fact they are stored in the form
+%   of ``restore code''), then we delegate to
+%   |\phffpf@maybequeuefigurecode|, which checks whether we can place a
+%   figure or if we should queue.
+%    \begin{macrocode}
+\def\phffpf@takecareofplacingfigure{%
+%    \end{macrocode}
+%
+% A tricky part: make sure we save the values of |phffpf@val@|\meta{field}
+% in a fixed way so that several figures won't overwrite each other's
+% values.
+%
+% We build a bunch of tokens which are in fact restore code for the given
+% variables, i.e., which is a list of commands of the form
+% |\gdef\phffpf@val@|\meta{field}|{|\meta{first-level-expanded-value-of-this-field}|}|.
+% This set of tokens have the values of these variables expanded to the
+% first level, so that it is OK if the variables |\phffpf@val@|\meta{field}
+% are overwritten.
+%    \begin{macrocode}
+  \edef\phffpf@tmp@fixallfieldvalues{%
+    \noexpand\gdef\noexpand\phffpf@val@pageside{\expandonce\phffpf@val@pageside}%
+    \noexpand\gdef\noexpand\phffpf@val@captionopt{\expandonce\phffpf@val@captionopt}%
+    \noexpand\gdef\noexpand\phffpf@val@caption{\expandonce\phffpf@val@caption}%
+    \noexpand\gdef\noexpand\phffpf@val@label{\expandonce\phffpf@val@label}%
+    \noexpand\gdef\noexpand\phffpf@val@placement{\expandonce\phffpf@val@placement}%
+    \noexpand\gdef\noexpand\phffpf@val@capmaxheight{\expandonce\phffpf@val@capmaxheight}%
+    \noexpand\gdef\noexpand\phffpf@val@figcontents{\expandonce\phffpf@val@figcontents}%
+  }%
+%    \end{macrocode}
+% 
+% Finally, relay the call to
+% |\phffpf@maybequeuefigurecode|\marg{restore-code-for-figure-settings}\hspace{0pt}\marg{full-figure-code}.
+%    \begin{macrocode}
+  \edef\phffpf@tmp@figcodetwoargs{%
+    {\expandonce\phffpf@tmp@fixallfieldvalues}%
+    {\noexpand\phffpf@impl@figcode{phffpf@val}}%
+  }%
+  \expandafter\phffpf@maybequeuefigurecode\phffpf@tmp@figcodetwoargs%
+}
+%    \end{macrocode}
+% \end{macro}
+% 
+% \begin{macro}{\phffpf@maybequeuefigurecode}
+%   USAGE: |\phffpf@maybequeuefigurecode|\marg{restore-code-for-figure-settings}\hspace{0pt}\marg{full-figure-code}.
+%
+%   Checks if we can place the figure; if yes then place it on the right
+%   page, if no, then add it to the queue.
+%
+%   The arguments are: |#1| = code to restore correct |\phffpf@val@XYZ|
+%   values; |#2| = figure code.  Make sure it's expanded.
+%    \begin{macrocode}
+\long\def\phffpf@maybequeuefigurecode#1#2{%
+%    \end{macrocode}
+% 
+% Possibly we have been told to place the next figure now via the flag
+% |\ifphffpf@flag@forcenextmaybequeuetoplacefigure|.  In this case, reset
+% the flag and place the figure now (relay to |\phffpf@doplacefigure|).
+%    \begin{macrocode}
+  \ifphffpf@flag@forcenextmaybequeuetoplacefigure%
+    \phffpf@flag@forcenextmaybequeuetoplacefigurefalse
+    \phffpf@doplacefigure{#1}{#2}%
+    %
+  \else
+%    \end{macrocode}
+%
+% See if there are other figures waiting to be placed first.  If so, add
+% ours to the queue.
+%    \begin{macrocode}
+    \ifnum\value{phffpf@internal@pending}>1\relax%
+      \xdef\phffpf@place@pending@figs@code{%
+          \expandonce\phffpf@place@pending@figs@code%
+          \unexpanded{\phffpf@maybequeuefigurecode{#1}{#2}}%
+        }%
+        %\show\phffpf@place@pending@figs@code
+        %[figure queued:  \texttt{\detokenize{#1}}]%  -- DEBUGGING
+    \else%
+%    \end{macrocode}
+%
+% If not, deal with placing the figure now:
+%    \begin{macrocode}
+      \phffpf@doplacefigure{#1}{#2}%
+      %[figure placed: \texttt{\detokenize{#1}}]  -- DEBUGGING
+    \fi%
+  \fi%
+}
+%    \end{macrocode}
+% 
+% Define also the flag which will force a next call to
+% |\phffpf@maybequeuefigurecode| to place the next figure in the queue.
+%    \begin{macrocode}
+\newif\ifphffpf@flag@forcenextmaybequeuetoplacefigure
+\phffpf@flag@forcenextmaybequeuetoplacefigurefalse
+%    \end{macrocode}
+% \end{macro}
+% 
+%
+% \begin{macro}{\phffpf@doplacefigure}
+%   Place the figure now.  Determine the correct number of |\afterpage|'s
+%   to use so that the figure caption ends up on the correct page side.
+%
+%   The arguments to this macro are: |#1| = code to restore correct
+%   |phffpf@val@XYZ| values, |#2| = the figure code. Make sure it's
+%   expanded.
+%    \begin{macrocode}
+\long\def\phffpf@doplacefigure#1#2{%
+%    \end{macrocode}
+%
+% Make sure the correct values of |phffpf@val@XYZ| are restored, because we
+% need e.g. |\phffpf@val@pageside|.  They may be wrong because this might
+% be called after a figure has been queued.
+%    \begin{macrocode}
+  #1%
+%    \end{macrocode}
+%
+% Now, determine where exactly to place the figure code.  There are no other pending
+% figures.  If there is no side preference, just place the figure pretty much now.
+%    \begin{macrocode}
+  \ifx\phffpf@val@pageside\phffpf@side@%
+    \let\phffpf@tmp@doplace\@firstofone%
+  \else%
+%    \end{macrocode}
+%
+% If, however, we have a side preference, then check everything more
+% carefully.  Use the helper macros
+% |\phffpf@placecode@on|\meta{\phfverb{same}$\mid$\phfverb{other}}|parity|.
+% (The latter essentially expand to the correct number of |\afterpage|'s.)
+%    \begin{macrocode}
+    \ifx\phffpf@val@pageside\phffpf@side@odd%
+      %[CHECK DONE HERE/WANT ODD] % -- for debugging
+      \checkoddpage\ifoddpage%
+      %[IS ODD] % -- for debugging
+        \let\phffpf@tmp@doplace\phffpf@placecode@onotherparity%
+      \else%
+        %[IS NOT ODD] % -- for debugging
+        \let\phffpf@tmp@doplace\phffpf@placecode@onsameparity%
+      \fi%
+    \else%
+      %[CHECK DONE HERE/WANT EVEN] % -- for debugging
+      \checkoddpage\ifoddpage%
+        %[IS ODD] % -- for debugging
+        \let\phffpf@tmp@doplace\phffpf@placecode@onsameparity%
+      \else%
+        %[IS NOT ODD] % -- for debugging
+        \let\phffpf@tmp@doplace\phffpf@placecode@onotherparity%
+      \fi%
+    \fi%
+  \fi%
+%    \end{macrocode}
+% 
+% I think an |\hbox{}| might help to place the anchor which determines
+% which page side we are currently on.  Note that this starts a new
+% paragraph and enters horizontal mode.
+%    \begin{macrocode}
+  \leavevmode\hbox{}%
+%    \end{macrocode}
+%
+% Now, do place the figure somewhere.
+%    \begin{macrocode}
+  \phffpf@tmp@doplace{#1#2}%
+}
+%    \end{macrocode}
+% \end{macro}
+%
+%
+% \begin{macro}{\phffpf@placecode@onsameparity}
+%   Place the figure code on the same parity (page side) as we are
+%   currently.  If enough space remains on the current page, place the
+%   figure immediately.  Otherwise, use two |\afterpage|'s so as the figure
+%   caption to appear in two pages.
+%
+%    \begin{macrocode}
+\newdimen\phffpf@tmp@spaceleft
+\newdimen\phffpf@tmp@compareto
+\long\def\phffpf@placecode@onsameparity#1{%
+%    \end{macrocode}
+%
+% First, see if the caption itself requires to be on its own page (and thus
+% no height calculations are necessary, and an additional |\clearpage| is
+% required)
+% 
+%    \begin{macrocode}
+  \def\@tmpa{p}%
+  \ifx\phffpf@val@placement\@tmpa%
+    \afterpage{\vspace*{0pt}\afterpage{#1\clearpage}}%
+  \else%
+%    \end{macrocode}
+%
+% Otherwise, the figure caption is there along with some text on the page.
+% 
+% See if there is enough place left on this page to place the figure
+% caption; otherwise use two |\afterpage|'s.
+%    \begin{macrocode}
+    %[PLACING FIG CODE ON SAME PARITY]% -- debugging
+    \phffpf@tmp@spaceleft=\textheight\relax%
+    \phffpf@tmp@compareto=\phffpf@val@capmaxheight\relax%
+    \advance\phffpf@tmp@spaceleft by -\pagetotal%
+    %[DIM LEFT: \the\phffpf@tmp@spaceleft]%
+    \ifdim\phffpf@tmp@spaceleft>\phffpf@tmp@compareto%
+      %[ENOUGH DIM LEFT.] % -- debugging
+      #1%\phffpf@tmp@figcode%
+    \else%
+      %[*NOT ENOUGH* DIM LEFT.] % -- debugging
+      \afterpage{\vspace*{0pt}\afterpage{#1}}%
+    \fi%
+  \fi%
+}
+%    \end{macrocode}
+% \end{macro}
+% 
+% \begin{macro}{\phffpf@placecode@onotherparity}
+%   Place the figure caption on the opposite parity as the current page.
+%   This just requires one |\afterpage| so as the figure code to appear on
+%   the following page.
+%
+%    \begin{macrocode}
+\def\phffpf@placecode@onotherparity#1{%
+  %[PLACING FIG CODE ON OTHER PARITY]% -- debugging
+%    \end{macrocode}
+% 
+% First, see if the caption requires to be on its own page (and thus no
+% height calculations are necessary, and an additional |\clearpage| is
+% required).
+%    \begin{macrocode}
+  \def\@tmpa{p}%
+  \ifx\phffpf@val@placement\@tmpa%
+    \afterpage{#1\clearpage}%
+  \else%
+%    \end{macrocode}
+%
+% The figure caption is not on its own page.  Just use a simple |\afterpage|.
+%    \begin{macrocode}
+    \afterpage{#1}%
+  \fi%
+}
+%    \end{macrocode}
+% \end{macro}
+% 
+%
+% \subsection{Commands to Flush All Full-Page-Figures}
+%
+%
+% Here are a set of commands which can be used to ensure that all full-page
+% figure floats have been placed.
+%
+% \begin{macro}{\FlushAllFullPageFigures}
+%   The name is pretty self-explanatory.  The command is documented in the user doc above.
+%    \begin{macrocode}
+\newcommand\FlushAllFullPageFigures[1][\phffpf@clearpage]{%
+%    \end{macrocode}
+% 
+% As long as there are full-page-figures pending, clear pages until those
+% figures have been placed.
+%    \begin{macrocode}
+  \ifnumcomp{\value{phffpf@internal@pending}}{>}{0}{%
+    \clearpage%
+    %[page cleared.]% DEBUG
+    \FlushAllFullPageFigures[#1]% recurse again.
+  }{%
+%    \end{macrocode}
+%
+% All figures placed, all fine.  We still need to flush one last time
+% because at this point the figure code (ie. caption) has been placed only,
+% and we want the text that follows to come after the figure itself.  Here
+% finally we use the clear command in |#1| to continue on any page or on an
+% odd-side page only.
+%    \begin{macrocode}
+    #1%
+  }%
+}
+\def\phffpf@clearpage{\if@twoside\cleardoublepage\else\clearpage\fi}
+%    \end{macrocode}
+% \end{macro}
+% 
+%
+%
+% \subsection{Package Option Parsing}
+%
+% Note the singular form of the word ``option.''
+% 
+%    \begin{macrocode}
+\def\phffpf@provide@figpdf{}
+\newcommand\phffpf@impl@figpdf[2][]{%
+  \figcontents{\includepdf[#1]{#2}}%
+}
+\def\phffpf@do@pdfpages{%
+  \RequirePackage{pdfpages}%
+  \def\phffpf@provide@figpdf{\let\figpdf\phffpf@impl@figpdf}%
+}
+%
+\DeclareOption{nopdfpages}{\def\phffpf@do@pdfpages{}}
+\DeclareOption*{%
+  \@unknownoptionerror%
+}
+\ProcessOptions\relax
+%
+\phffpf@do@pdfpages
+%    \end{macrocode}
+%
+%\Finale
+\endinput
diff --git a/Master/texmf-dist/source/latex/phffullpagefigure/phffullpagefigure.ins b/Master/texmf-dist/source/latex/phffullpagefigure/phffullpagefigure.ins
new file mode 100644
index 00000000000..5c5cda08b44
--- /dev/null
+++ b/Master/texmf-dist/source/latex/phffullpagefigure/phffullpagefigure.ins
@@ -0,0 +1,55 @@
+%%
+%% Copyright (C) 2016 by Philippe Faist <philippe.faist@bluewin.ch>
+%%
+%% This file may be distributed and/or modified under the conditions of
+%% the LaTeX Project Public License, either version 1.3 of this license
+%% or (at your option) any later version.  The latest version of this
+%% license is in:
+%% 
+%%    http://www.latex-project.org/lppl.txt
+%% 
+%% and version 1.3 or later is part of all distributions of LaTeX version
+%% 2005/12/01 or later.
+%%
+
+\input docstrip.tex
+\keepsilent
+
+\usedir{tex/latex/phfqitltx}
+
+\preamble
+
+This is a generated file.
+
+Copyright (C) 2016 by Philippe Faist <philippe.faist@bluewin.ch>
+
+This file may be distributed and/or modified under the conditions of
+the LaTeX Project Public License, either version 1.3 of this license
+or (at your option) any later version.  The latest version of this
+license is in:
+
+   http://www.latex-project.org/lppl.txt
+
+and version 1.3 or later is part of all distributions of LaTeX version
+2005/12/01 or later.
+
+\endpreamble
+
+\generate{\file{phffullpagefigure.sty}{\from{phffullpagefigure.dtx}{package}}}
+
+\obeyspaces
+\Msg{*************************************************************}
+\Msg{*                                                           *}
+\Msg{* To finish the installation you have to move the following *}
+\Msg{* file into a directory searched by TeX:                    *}
+\Msg{*                                                           *}
+\Msg{*     phffullpagefigure.sty                                 *}
+\Msg{*                                                           *}
+\Msg{* To produce the documentation run the .dtx file through    *}
+\Msg{* (PdF-)LaTeX.                                              *}
+\Msg{*                                                           *}
+\Msg{* Happy TeXing!                                             *}
+\Msg{*                                                           *}
+\Msg{*************************************************************}
+
+\endbatchfile