Initial commit

4 files changed, 1107 insertions, 0 deletions

diff --git a/macros/latex/contrib/graphbox/README.txt b/macros/latex/contrib/graphbox/README.txt
new file mode 100644
index 0000000000..777a6974d5
--- /dev/null
+++ b/macros/latex/contrib/graphbox/README.txt
@@ -0,0 +1,40 @@
+graphbox v1.1
+Copyright 2013-2018 Niklas Beisert
+
+graphbox is an extension for the LaTeX2e package
+graphicx to facilitate the placement of graphics
+relative to the current position
+using additional optional arguments [...]
+of \includegraphics.
+For example, changing the vertical alignment is convenient
+for using graphics as elements of (mathematical) formulae.
+Options for shifting, smashing and hiding the graphics
+are mainly intended for designing presentations using,
+e.g., the beamer framework.
+
+The package consists of the files
+
+    README.txt    readme file
+    graphbox.ins  installation file
+    graphbox.dtx  source file
+    graphbox.sty  package file
+    gboxsamp.tex  sample latex file
+    gboxsamp.mps  sample graphics file
+    graphbox.pdf  manual
+
+The distribution consists of the files
+README.txt, graphbox.ins and graphbox.dtx.
+
+Run "(pdf)latex graphbox.dtx" to compile the manual graphbox.pdf.
+
+Run "tex graphbox.ins" to create the package graphbox.sty and the sample gboxsamp.tex.
+Copy the file graphbox.sty to an appropriate directory of your LaTeX
+distribution, e.g. texmf-root/tex/latex/graphbox.
+
+This work 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.
diff --git a/macros/latex/contrib/graphbox/graphbox.dtx b/macros/latex/contrib/graphbox/graphbox.dtx
new file mode 100644
index 0000000000..bff7c33956
--- /dev/null
+++ b/macros/latex/contrib/graphbox/graphbox.dtx
@@ -0,0 +1,1026 @@
+% \iffalse
+%
+% graphbox.dtx Copyright (C) 2013-2018 Niklas Beisert
+%
+% This work 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.
+%
+% This work has the LPPL maintenance status `maintained'.
+%
+% The Current Maintainer of this work is Niklas Beisert.
+%
+% This work consists of the files graphbox.dtx and graphbox.ins
+% and the derived files graphbox.sty, gboxsamp.tex and gboxsamp.mps
+%
+%<package|sample>\NeedsTeXFormat{LaTeX2e}[1996/12/01]
+%<package>\ProvidesPackage{graphbox}[2018/01/17 v1.1 extension for graphicx to adjust containing box]
+%<sample>\ProvidesFile{gboxsamp.tex}[2018/01/17 v1.1 sample for graphbox]
+%<figure>%!PS-Adobe-3.0 EPSF-3.0
+%<*driver>
+%\ProvidesFile{graphbox.drv}[2018/01/17 v1.1 graphbox Reference Manual file]
+\PassOptionsToClass{10pt,a4paper}{article}
+\documentclass{ltxdoc}
+
+\usepackage[margin=35mm]{geometry}
+\usepackage{hyperref}
+\usepackage{hyperxmp}
+\usepackage[usenames]{color}
+
+\hypersetup{colorlinks=true}
+\hypersetup{pdfstartview=FitH}
+\hypersetup{pdfpagemode=UseNone}
+\hypersetup{pdfsource={}}
+\hypersetup{pdflang={en-UK}}
+\hypersetup{pdfcopyright={Copyright 2013-2018 Niklas Beisert.
+  This work 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.}}
+\hypersetup{pdflicenseurl={http://www.latex-project.org/lppl.txt}}
+\hypersetup{pdfcontactaddress={ETH Zurich, ITP, HIT K, Wolfgang-Pauli-Strasse 27}}
+\hypersetup{pdfcontactpostcode={8093}}
+\hypersetup{pdfcontactcity={Zurich}}
+\hypersetup{pdfcontactcountry={Switzerland}}
+\hypersetup{pdfcontactemail={nbeisert@itp.phys.ethz.ch}}
+\hypersetup{pdfcontacturl={http://people.phys.ethz.ch/\xmptilde nbeisert/}}
+
+\begin{document}
+
+\title{The \textsf{graphbox} Package}
+\hypersetup{pdftitle={The graphbox Package}}
+\author{Niklas Beisert\\[2ex]
+        Institut f\"ur Theoretische Physik\\
+        Eidgen\"ossische Technische Hochschule Z\"urich\\
+        Wolfgang-Pauli-Strasse 27, 8093 Z\"urich, Switzerland\\[1ex]
+        \href{mailto:nbeisert@itp.phys.ethz.ch}{\texttt{nbeisert@itp.phys.ethz.ch}}}
+\hypersetup{pdfauthor={Niklas Beisert}}
+\hypersetup{pdfsubject={Manual for the LaTeX2e Package graphbox}}
+\date{17 January 2018, \textsf{v1.1}}
+\maketitle
+
+\begin{abstract}\noindent
+\textsf{graphbox} is an extension for the \LaTeXe{} package
+\textsf{graphicx} to facilitate the placement of graphics
+relative to the current position
+using additional optional arguments |[...]|
+of |\includegraphics|.
+For example, changing the vertical alignment is convenient
+for using graphics as elements of (mathematical) formulae.
+Options for shifting, smashing and hiding the graphics
+are mainly intended for designing presentations using,
+e.g., the \textsf{beamer} framework.
+\end{abstract}
+
+\tableofcontents
+
+% we do not have the sample graphics yet, so we use LaTeX internals:
+\newcommand{\drawbox}[1]{%
+ \setlength{\unitlength}{#1}%
+ \begin{picture}(1, 1)%
+ \put(0,0){\line(1,1){1}}%
+ \put(1,0){\line(-1,1){1}}%
+ \end{picture}%
+}
+\newcommand{\hidebox}[1]{%
+ \setlength{\unitlength}{#1}%
+ \begin{picture}(1, 1)%
+ \end{picture}%
+}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\section{Introduction}
+
+Changing the placement of graphics using |\includegraphics|
+of the \textsf{graphicx} package is tedious.
+The command allows to scale and even rotate a figure
+by the optional arguments |[...]| of |\includegraphics|, namely |scale|
+(|xscale|, |yscale|) and |rotate|.
+However, it lacks options to change the vertical alignment,
+shift the graphics or modify the containing {\TeX} box.
+In order to position the graphics according to one's needs,
+one would normally use the standard boxing tools of {\LaTeX} such as
+|\makebox|,
+|\parbox|,
+|\raisebox|
+or the
+|minipage| and |picture| environments.
+%
+While practically anything can be achieved by a combination of these tools,
+it has several disadvantages:
+%
+\begin{itemize}
+\item
+use of complex commands for standard situations;
+\item
+several boxing commands need to be combined to achieve the desired effect;
+leads to several levels of nesting around the actual |\includegraphics| command;
+\item
+readability of the {\LaTeX} construction is low (what is going on?);
+\item
+adjusting the placement is tedious;
+\item
+the higher-level boxing commands of {\LaTeX} require to specify the box width;
+however, the actual dimensions of the graphics are typically not known
+(or they change as the graphics is modified);
+furthermore the same number needs to be used in several places;
+\item
+guessing the width of the required boxes may lead to extra space
+around the graphics or warning messages about an overfull box;
+\item
+\ldots
+\end{itemize}
+%
+Therefore it would be desirable to specify the placement
+along with other options in the |[...]| argument
+of |\includegraphics|.
+This may be helpful in the following situations:
+%
+\begin{itemize}
+\item
+presentations where several figure
+need to be placed across the frames
+without disturbing the flow of the text;
+similarly, in the composition of posters;
+\item
+when graphics are used as elements
+of (mathematical) formulae
+one might prefer a central vertical alignment
+over the default baseline alignment of
+|\includegraphics|.
+\end{itemize}
+
+The following discusses these situations in more detail.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Vertical Alignment}
+
+Suppose you want to show graphics files%
+\footnote{a diagonal cross will serve as the sample figure in this documentation.}
+of different height next to each other
+(potentially accompanied by some text).
+A plain inclusion via |\includegraphics| will produce
+the output:
+%
+\[\drawbox{1cm}\qquad\drawbox{2cm}\qquad\mbox{some text}\]
+%
+This is because |\includegraphics| puts the graphics into a box
+whose baseline is the lower bound of the box:
+%
+\[\underline{\qquad\fbox{\drawbox{1cm}}\qquad\fbox{\drawbox{2cm}}\qquad\fbox{\mbox{some text}}\qquad}\]
+%
+Instead, a central alignment of the graphics is desirable in many situations:
+%
+\[
+\parbox{1cm}{\drawbox{1cm}}\qquad
+\parbox{2cm}{\drawbox{2cm}}
+\qquad\mbox{some text}
+\]
+%
+This can be achieved by code such as:
+%
+\begin{verbatim}
+  \parbox{1cm}{\includegraphics[width=1cm]{...}}
+  \qquad
+  \parbox{2cm}{\includegraphics[width=2cm]{...}}
+  \qquad
+  \mbox{some text}
+\end{verbatim}
+%
+However, if the width of the graphics is not as evident
+(e.g.\ when no width is specified or the graphics is scaled),
+the resulting output may easily look like:%
+\footnote{Boxes were added to display the size of the bounding boxes.}
+%
+\[
+\fbox{\parbox{0.8cm}{\makebox[0cm][l]{\drawbox{1cm}}}}
+\qquad
+\fbox{\parbox{3cm}{\centering\drawbox{2cm}}}
+\qquad\mbox{some text}
+\]
+%
+The present extension \textsf{graphbox} adds the option |align| to
+|\includegraphics| to simplify the declaration:
+\begin{verbatim}
+  \includegraphics[align=c,width=1cm]{...}
+  \qquad
+  \includegraphics[align=c,width=2cm]{...}
+  \qquad
+  \mbox{some text}
+\end{verbatim}
+%
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Graphics Placement}
+
+A related issue is the fine-tuning of graphics placement:
+In {\LaTeX} this can be achieved by the commands
+|\raisebox| (vertically) and |\hspace| (horizontally).
+Furthermore, one might want to place
+the graphics into some free space relative to the present position.
+This is commonly needed in designing presentations or posters,
+where the flow of the text and the graphics is often fine-tuned.
+For example, one may ignore the vertical height of the graphics
+using |\smash|. Or one might place the graphics
+at the present horizontal position without allocating space by
+|\makebox[0pt]|, |\llap| or |\rlap|.
+
+Each of these elementary operations can be handled well,
+but their combination can become very involved:
+%
+\begin{verbatim}
+  \smash{\raisebox{.1cm}{\makebox[0pt][l]{\hspace{1cm}{\includegraphics{...}}}}}
+\end{verbatim}
+%
+For example, this may be used to produce the output:
+\[
+\begin{tabular}[b]{cccc}
+  & A & B & C \\\hline
+D & 1 & 2 & 3 \\
+E & 4 & 5 & 6 \\
+F & 7 & 8 & 9
+\end{tabular}
+\fbox{\smash{\raisebox{.1cm}{\makebox[0pt][l]{\hspace{1cm}\drawbox{2cm}}}}}
+\]
+%
+Here, the graphics was put next to a table.
+The small box represents the anchor of the graphics.
+It occupies no space which allows
+to centre the table irrespectively of
+the size of the graphics.
+Unfortunately, the command is not easily readable.
+The \textsf{graphbox} extension abbreviates the declaration
+and make it much more accessible:
+%
+\begin{verbatim}
+  \includegraphics[smash=tr,hshift=1cm,vshift=.1cm]{...}
+\end{verbatim}
+%
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Hiding Graphics}\label{sec:hide}
+
+Sometimes one might wish to hide a graphics while reserving the space
+it would occupy.%
+\footnote{In the \textsf{graphicx} package a
+similar effect achieved by the option |draft|.
+However, here the graphics are replaced by a box containing the file name.}
+For example, this feature is needed in
+presentations where the frames are successively uncovered.
+In this \textsf{beamer} class the uncovering of frames is
+conveniently achieved by the command |\pause|.
+Unfortunately, the effect of |\pause| on graphics
+is that they are either displayed or taken out of the text flow.
+This has the effect that the formatting
+can change drastically when graphics elements are uncovered:
+%
+\[
+\fbox{
+\mbox{\textcolor[gray]{0.5}{before}}
+\
+\mbox{\textcolor[gray]{0.5}{after}}
+}
+\quad\longrightarrow\quad
+\fbox{
+\mbox{before}\
+\drawbox{1cm}
+\mbox{after}\
+}
+\]
+%
+
+
+The \textsf{graphbox} extension adds the option |hide|
+to |\includegraphics| to hide the corresponding
+graphics while reserving the space it would otherwise occupy:
+%
+\[
+\fbox{\hidebox{1.5cm}}
+\quad\longleftrightarrow\quad
+\fbox{\drawbox{1.5cm}}
+\]
+%
+Moreover, in conjunction with the \textsf{beamer} class,
+the definition of the |\includegraphics| command
+is altered such that it uses the same amount of
+space in all visibility modes (specified through the
+|\pause| mechanism and the |<...>| extension).
+Visibility is handled by automatically setting the |hide| option:
+%
+\[
+\fbox{
+\mbox{\textcolor[gray]{0.5}{before}}\
+\hidebox{1cm}\
+\mbox{\textcolor[gray]{0.5}{after}}
+}
+\quad\longrightarrow\quad
+\fbox{
+\mbox{before}\
+\drawbox{1cm}\
+\mbox{after}
+}
+\]
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\section{Usage}
+
+To use \textsf{graphbox} simply add the command
+\begin{center}|\usepackage{graphbox}|\end{center}
+to the preamble of your {\LaTeX} document.
+If not yet present,
+the package \textsf{graphicx} will automatically be loaded.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Extensions}
+
+The package mainly extends the functionality of
+the |\includegraphics| command of the \textsf{graphicx} package
+by allowing several additional optional arguments |[...]| as follows:
+
+\begin{itemize}
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\item
+|hide|[|=|\textit{bool}]
+
+hides the graphics (unless \textit{bool}=|false|) but reserves the space
+it would have occupied.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\item
+|align|[|=|\textit{valign}]
+
+adjusts the vertical alignment of the graphics where \textit{valign} is one of the following:
+\begin{itemize}
+\item[|b|:]
+baseline aligned to bottom of graphics;\\
+default behaviour when |align| is not specified;
+\item[|c|:]
+centre of current line aligned to centre of graphics;%
+\footnote{The centre of the line appears to be (18/31)ex above the baseline
+which is at the centre of a capital letter for the default font.}\\
+default behaviour when no parameter is given;
+\item[|t|:]
+top of current line aligned to top of graphics;%
+\footnote{The top of the line is defined as (36/31)ex above the baseline
+which is the height of a capital letter for the default font.}
+\item[|l|:]
+baseline aligned to bottom of graphics; same as |b|;
+\item[|m|:]
+baseline aligned to centre of graphics;
+\item[|u|:]
+baseline aligned to top of graphics.
+\end{itemize}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\item
+|vsmash|[|=|\textit{vpos}]
+
+reduces the height of the bounding box to zero
+(equivalent to |\smash|);
+places the graphics according to
+\textit{vpos} which can take the following values:
+\begin{itemize}
+\item[|b|:]
+positions top of graphics below top of current line;
+\item[|c|:]
+positions centre of graphics at centre of current line;\\
+default behaviour when no parameter is given;
+\item[|t|:]
+positions bottom of graphics at baseline;
+\item[|l|:]
+positions top of graphics at baseline;
+\item[|m|:]
+positions centre of graphics at baseline;
+\item[|u|:]
+ positions bottom of graphics at baseline; same as |t|;
+\item[|n|:]
+no vertical smashing.
+\end{itemize}
+%
+Note that the parameter \textit{vpos}
+has the opposite effect
+of the parameter \textit{valign} of |align|.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\item
+|hsmash|[|=|\textit{hpos}]
+
+reduces the width of the bounding box to zero
+(equivalent to |\makebox[0pt]|);
+places the graphics according to
+\textit{hpos} which can take the following values
+\begin{itemize}
+\item[|r|:]
+positions graphics right of current position;
+\item[|c|:]
+positions centre of the graphics at current position;
+default behaviour when no parameter is given;
+\item[|l|:]
+positions graphics left of current position;
+\item[|n|:]
+no horizontal smashing;
+default behaviour when |hsmash| is not specified.
+\end{itemize}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\item
+|smash|[|=|\textit{vpos}\,\textit{hpos}]
+
+combination of |vsmash=|\textit{vpos} and
+|hsmash=|\textit{hpos};
+default behaviour is |cc|.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\item
+|vshift=|\textit{len}
+
+shifts the graphics up by \textit{len}.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\item
+|hshift=|\textit{len}
+
+shifts the graphics to the right by \textit{len};
+has no effect unless |hsmash| is activated.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\item
+|tmargin=|\textit{len}
+
+adds a top margin of height \textit{len};
+has no effect when |vsmash| is activated.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\item
+|bmargin=|\textit{len}
+
+adds a bottom margin of height \textit{len}
+below the baseline;
+has no effect when |vsmash| is activated.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\item
+|vmargin=|\textit{len}
+
+adds a bottom and top margin of height \textit{len};
+has no effect when |vsmash| is activated.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\item
+|lmargin=|\textit{len}
+
+adds a left margin of width \textit{len};
+has no effect when |hsmash| is activated.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\item
+|rmargin=|\textit{len}
+
+adds a right margin of width \textit{len};
+has no effect when |hsmash| is activated.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\item
+|hmargin=|\textit{len}
+
+adds a left and right margin of width \textit{len};
+has no effect when |hsmash| is activated.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\item
+|margin=|\textit{len}
+
+adds an overall margin of length \textit{len}
+around the graphics;
+has no effect when |smash| is activated.
+
+\end{itemize}
+%
+In specifying lengths in the above arguments,
+there are two additional dimensions |\gwidth| and |\gheight|
+representing the actual width and height of the included graphics.
+For example, one can add a horizontal margin of 10\%
+of the size of the graphics by specifying |hmargin=0.1\gwidth|.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Package Options}
+
+The package provides one option:
+%
+\begin{itemize}
+\item
+|nobeamer|
+
+do not override the overlay processing
+of the \textsf{beamer} class for |\includegraphics|;
+as usual, graphics will occupy no space when covered.
+\end{itemize}
+
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\section{Information}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Copyright}
+
+\begingroup
+\parskip1ex
+\parindent0pt
+
+Copyright \copyright{} 2013--2018 Niklas Beisert
+
+This work 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
+  \url{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.
+
+This work has the LPPL maintenance status `maintained'.
+
+The Current Maintainer of this work is Niklas Beisert.
+
+This work consists of the files |README.txt|, |graphbox.ins| and |graphbox.dtx|
+as well as the derived files |graphbox.sty|, |gboxsamp.tex| with |gboxsamp.mps|
+and |graphbox.pdf|.
+
+\endgroup
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Files and Installation}
+
+The package consists of the files
+%
+\begin{center}
+\begin{tabular}{ll}
+    |README.txt|   & readme file \\
+    |graphbox.ins| & installation file \\
+    |graphbox.dtx| & source file \\
+    |graphbox.sty| & package file \\
+    |gboxsamp.tex| & sample file \\
+    |gboxsamp.mps| & sample figure \\
+    |graphbox.pdf| & manual
+\end{tabular}
+\end{center}
+%
+The distribution consists of the files
+|README.txt|, |graphbox.ins| and |graphbox.dtx|.
+%
+\begin{itemize}
+\item
+Run (pdf)\LaTeX{} on |graphbox.dtx|
+to compile the manual |graphbox.pdf| (this file).
+\item
+Run \LaTeX{} on |graphbox.ins| to create the package |graphbox.sty|
+and the sample consisting of |gboxsamp.tex| and |gboxsamp.mps|.
+Copy the file |graphbox.sty| to an appropriate directory of your \LaTeX{}
+distribution, e.g.\ \textit{texmf-root}|/tex/latex/graphbox|.
+\end{itemize}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Interaction with CTAN Packages}
+
+The \textsf{graphbox} package extends the
+package \href{http://ctan.org/pkg/graphicx}{\textsf{graphicx}}.
+It also changes some functionality of the class
+\href{http://ctan.org/pkg/beamer}{\textsf{beamer}}
+if present:
+%
+\begin{itemize}
+\item
+Compatibility with the \textsf{graphicx} package
+has been tested with
+v1.0f (1999/02/16) and
+v1.0g (2014/04/25).
+
+\item
+The changes of functionality are described
+in section~\ref{sec:hide}.
+Compatibility with the
+\textsf{beamer} class
+has been tested with v3.33 (2013/12/25).
+
+\end{itemize}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%\subsection{Feature Suggestions}
+%
+%\begin{itemize}
+%\item
+%Combine hshift and vshift into one definition. how? which order?
+%\item
+%negative bmargin
+%\item
+%change \includegraphics missing file error into a warning?
+%\end{itemize}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Revision History}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\paragraph{v1.1:} 2018/01/17
+
+\begin{itemize}
+\item
+hooked deeper into |\includegraphics| chain
+\item
+manual rearranged
+\item
+minor internal changes
+\end{itemize}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\paragraph{v1.0:} 2014/08/31
+
+\begin{itemize}
+\item
+added further placement options
+\item
+manual and installation package added
+\item
+first version published on CTAN
+\end{itemize}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\paragraph{v0.8:} 2014/08/25
+
+\begin{itemize}
+\item
+basic functionality
+\end{itemize}
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\appendix
+
+\settowidth\MacroIndent{\rmfamily\scriptsize 000\ }
+\parskip1ex
+\parindent0pt
+
+ \DocInput{graphbox.dtx}
+
+\end{document}
+%</driver>
+% \fi
+%
+% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+% \section{Sample File}
+%\iffalse
+%<*sample>
+%\fi
+%
+% In this section we provide a {\LaTeX} example how to use
+% some of the \textsf{graphbox} extensions to \textsf{graphicx}.
+% Preamble:
+%
+%    \begin{macrocode}
+\documentclass[12pt]{article}
+
+\usepackage[margin=2cm]{geometry}
+\usepackage{graphicx}
+\usepackage{graphbox}
+%    \end{macrocode}
+
+% The macro |\sample{|\textit{options}|}| prints a block demonstrating the flow of text
+% testing the new |\includegraphics| arguments \textit{options}:
+%
+% \fbox{\parbox{0.6\textwidth}
+% {\textbf{options:} \textit{options}\par\vspace{1ex}
+% \parbox{0.6\textwidth}
+% {
+% XXXXXX\phantom{\fbox{}}XXXXXX\\
+% XXXXXX\phantom{\fbox{}}XXXXXX\\
+% XXXXXX\fbox{\drawbox{1cm}}XXXXXX\\
+% XXXXXX\phantom{\fbox{}}XXXXXX\\
+% XXXXXX\phantom{\fbox{}}XXXXXX
+% }}}\par
+%
+% The box indicates the resulting bounding box of the
+% |\includegraphics| command.
+% It is defined as follows:
+%    \begin{macrocode}
+\newcommand{\sample}[1]{
+\textbf{options:} \texttt{#1}\par\vspace{1ex}
+\parbox{0.6\textwidth}{%
+XXXXXX\phantom{\fbox{}}XXXXXX\\%
+XXXXXX\phantom{\fbox{}}XXXXXX\\%
+XXXXXX\fbox{\includegraphics[#1]{gboxsamp.mps}}XXXXXX\\%
+XXXXXX\phantom{\fbox{}}XXXXXX\\%
+XXXXXX\phantom{\fbox{}}XXXXXX%
+}\vspace{1cm}\par}
+%    \end{macrocode}
+
+% In the document body we test the various new options for |\includegraphics|:
+%    \begin{macrocode}
+\begin{document}
+\sample{}
+\sample{hide}
+\sample{hide=true}
+\sample{hide=false}
+\newpage
+\sample{align=b}
+\sample{align=c}
+\sample{align=t}
+\newpage
+\sample{align=l}
+\sample{align=m}
+\sample{align=u}
+\newpage
+\sample{vshift=10pt}
+\sample{vshift=-10pt}
+\newpage
+\sample{lmargin=10pt}
+\sample{rmargin=10pt}
+\sample{tmargin=10pt}
+\sample{bmargin=10pt}
+\newpage
+\sample{lmargin=-10pt}
+\sample{rmargin=-10pt}
+\sample{tmargin=-10pt}
+\sample{bmargin=-10pt}
+\newpage
+\sample{vsmash=b}
+\sample{vsmash=c}
+\sample{vsmash=t}
+\newpage
+\sample{vsmash=l}
+\sample{vsmash=m}
+\sample{vsmash=u}
+\newpage
+\sample{hsmash=l}
+\sample{hsmash=c}
+\sample{hsmash=r}
+\newpage
+\sample{smash=tl}
+\sample{smash=cc}
+\sample{smash=br}
+\newpage
+\sample{smash,vshift=10pt}
+\sample{smash,hshift=10pt}
+\sample{smash,hshift=-10pt,vshift=-10pt}
+\end{document}
+%    \end{macrocode}
+%\iffalse
+%</sample>
+%\fi
+%
+% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+% \paragraph{Sample Graphics.}
+%\iffalse
+%<*figure>
+%\fi
+%
+% The following is a sample Metapost graphics file (|gboxsamp.mps|)
+% for use in the sample {\LaTeX} file:
+%
+%    \begin{macrocode}
+%!PS-Adobe-3.0 EPSF-3.0
+%%BoundingBox: -21 -21 21 21
+%%EndComments
+%%Page: 1 1
+ 0 0 0 setrgbcolor 0 1.5 dtransform truncate idtransform setlinewidth pop []
+ 0 setdash 1 setlinecap 1 setlinejoin 10 setmiterlimit
+newpath -20 20 moveto 20 -20 lineto stroke
+newpath -20 -20 moveto 20 20 lineto stroke
+%%EOF
+%    \end{macrocode}
+% It contains a black cross:
+% \[\fbox{\drawbox{1.5cm}}\]
+% The frame indicates the size of the graphics but it does not belong to it.
+%
+%\iffalse
+%</figure>
+%\fi
+%
+% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+% \section{Implementation}
+%\iffalse
+%<*package>
+%\fi
+%
+% In this section we describe the package |graphbox.sty|.
+
+% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+% \paragraph{Package Options.}
+%
+% By default, the package overrides the overlay meachanism
+% for includegraphics of the class beamer.
+% The global option |nobeamer| disables the interaction.
+%    \begin{macrocode}
+\newif\ifGin@box@beamer\Gin@box@beamertrue
+\DeclareOption{nobeamer}{\Gin@box@beamerfalse}
+\ProcessOptions
+%    \end{macrocode}
+
+% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+% \paragraph{Required Packages.}
+%
+% The package loads \textsf{graphicx} if not yet present:
+%    \begin{macrocode}
+\RequirePackage{graphicx}
+%    \end{macrocode}
+
+% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+% \paragraph{Internal Definitions.}
+%
+% The package defines a box and several dimension registers:
+%
+%    \begin{macrocode}
+\newsavebox{\Gin@box@box}
+\newlength{\Gin@box@width}
+\newlength{\Gin@box@height}
+\newlength{\Gin@box@raise}
+\newlength{\Gin@box@hspace}
+\newlength{\Gin@box@bwidth}
+\newlength{\Gin@box@bheight}
+%    \end{macrocode}
+
+% The following macros store the parameters for the present graphics:
+%
+%    \begin{macrocode}
+\def\Gin@box@align{b}
+\def\Gin@box@hsmash{n}
+\def\Gin@box@hshift{0pt}
+\def\Gin@box@vshift{0pt}
+\def\Gin@box@lmargin{0pt}
+\def\Gin@box@rmargin{0pt}
+\def\Gin@box@tmargin{0pt}
+\def\Gin@box@bmargin{0pt}
+\newif\ifGin@box@hide\Gin@box@hidefalse
+\newif\ifGin@box@vsmash\Gin@box@vsmashfalse
+%    \end{macrocode}
+
+% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+% \paragraph{Additional Arguments.}
+%
+% The optional arguments of |\includegraphics| are parsed by \textsf{keyval}
+% which calls the appropriate handlers. We add handlers to introduce additional
+% optional arguments:
+%
+%    \begin{macrocode}
+\define@key{Gin}{hide}[true]{\lowercase{\Gin@boolkey{#1}}{box@hide}}
+\define@key{Gin}{align}[c]{\def\Gin@box@align{#1}}
+\define@key{Gin}{hsmash}[c]{\edef\Gin@box@hsmash{#1}}
+\define@key{Gin}{vsmash}[c]{\if#1n\Gin@box@vsmashfalse\else%
+                             \Gin@box@vsmashtrue\edef\Gin@box@align{%
+                             \if#1bt\else\if#1tb\else%
+                             \if#1lu\else\if#1ul\else#1\fi\fi\fi\fi\fi}}
+\define@key{Gin}{smash}[cc]{\expandafter\KV@Gin@vsmash\@firstoftwo#1%
+                            \expandafter\KV@Gin@hsmash\@secondoftwo#1}
+\define@key{Gin}{hshift}{\def\Gin@box@hshift{#1}}
+\define@key{Gin}{vshift}{\def\Gin@box@vshift{#1}}
+\define@key{Gin}{lmargin}{\def\Gin@box@lmargin{#1}}
+\define@key{Gin}{rmargin}{\def\Gin@box@rmargin{#1}}
+\define@key{Gin}{tmargin}{\def\Gin@box@tmargin{#1}}
+\define@key{Gin}{bmargin}{\def\Gin@box@bmargin{#1}}
+\define@key{Gin}{hmargin}{\def\Gin@box@lmargin{#1}\def\Gin@box@rmargin{#1}}
+\define@key{Gin}{vmargin}{\def\Gin@box@tmargin{#1}\def\Gin@box@bmargin{#1}}
+\define@key{Gin}{margin}{\def\Gin@box@lmargin{#1}\def\Gin@box@rmargin{#1}%
+                         \def\Gin@box@tmargin{#1}\def\Gin@box@bmargin{#1}}
+%    \end{macrocode}
+%
+% The options are stored in internal registers for later processing.
+% The arguments of |hsmash| and |vsmash| work in the opposite direction
+% for conventional alignment of {\LaTeX} boxes. Therefore the parameters
+% |t| and |b| as well as |r| and |l| are interchanged.
+
+% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+% \paragraph{Argument Processing.}
+%
+% Next, we overwrite the function |\Gin@setfile| called by |\includegraphics|
+% after the optional parameters have been processed
+% by |\setkeys{Gin}{...}|:
+%    \begin{macrocode}
+\let\old@box@Gin@setfile\Gin@setfile
+\def\Gin@setfile#1#2#3{%
+%    \end{macrocode}
+% We first save the graphics into the box |\Gin@box@box|
+% and compute its width and height:
+%    \begin{macrocode}
+ \sbox{\Gin@box@box}{\old@box@Gin@setfile{#1}{#2}{#3}}%
+ \settowidth{\Gin@box@width}{\usebox{\Gin@box@box}}%
+ \settoheight{\Gin@box@height}{\usebox{\Gin@box@box}}%
+%    \end{macrocode}
+% Temporarily define the macros |\gwidth| and |\gheight|
+% to represent the width and height of the graphics, respectively:
+%    \begin{macrocode}
+ \def\gwidth{\Gin@box@width}%
+ \def\gheight{\Gin@box@height}%
+%    \end{macrocode}
+% Ignore top and bottom margin if vsmash is active:
+%    \begin{macrocode}
+ \ifGin@box@vsmash%
+  \def\Gin@box@tmargin{0pt}\def\Gin@box@bmargin{0pt}\fi%
+%    \end{macrocode}
+% Compute the vertical box dimensions:
+%    \begin{macrocode}
+ \setlength{\Gin@box@raise}{\Gin@box@vshift}%
+ \setlength{\Gin@box@bheight}{\Gin@box@height}%
+ \addtolength{\Gin@box@bheight}{\Gin@box@tmargin}%
+ \addtolength{\Gin@box@bheight}{\Gin@box@bmargin}%
+ \if\Gin@box@align t%
+  \addtolength{\Gin@box@raise}{-\Gin@box@height}%
+  \addtolength{\Gin@box@raise}{1.161290323ex}\fi%
+ \if\Gin@box@align u%
+  \addtolength{\Gin@box@raise}{-\Gin@box@height}\fi%
+ \if\Gin@box@align c%
+  \addtolength{\Gin@box@raise}{-0.5\Gin@box@height}%
+  \addtolength{\Gin@box@raise}{0.580645161ex}\fi%
+ \if\Gin@box@align m%
+  \addtolength{\Gin@box@raise}{-0.5\Gin@box@height}\fi%
+%    \end{macrocode}
+% Compute the horizontal box dimensions:
+%    \begin{macrocode}
+ \setlength{\Gin@box@hspace}{0pt}%
+ \if\Gin@box@hsmash n%
+  \setlength{\Gin@box@bwidth}{\Gin@box@width}%
+  \addtolength{\Gin@box@bwidth}{\Gin@box@lmargin}%
+  \addtolength{\Gin@box@bwidth}{\Gin@box@rmargin}%
+  \setlength{\Gin@box@hspace}{\Gin@box@lmargin}%
+ \else%
+  \setlength{\Gin@box@bwidth}{0pt}%
+  \setlength{\Gin@box@hspace}{\Gin@box@hshift}%
+  \if\Gin@box@hsmash l%
+   \addtolength{\Gin@box@hspace}{-\Gin@box@width}\fi%
+  \if\Gin@box@hsmash c%
+   \addtolength{\Gin@box@hspace}{-0.5\Gin@box@width}\fi%
+ \fi%
+%    \end{macrocode}
+% Define the vertical box:
+%    \begin{macrocode}
+ \ifGin@box@vsmash\expandafter\smash\fi{%
+  \raisebox{\Gin@box@raise}{%
+   \parbox[b]{\Gin@box@bwidth}{%
+    \rule[-\Gin@box@bmargin]{0pt}{\Gin@box@bheight}%
+    \smash{%
+%    \end{macrocode}
+% Define the horizontal box:
+%    \begin{macrocode}
+     \makebox[0pt][l]{%
+      \hspace*{\Gin@box@hspace}%
+%    \end{macrocode}
+% Print the graphics unless hidden:
+%    \begin{macrocode}
+      \ifGin@box@hide\else\usebox{\Gin@box@box}\fi%
+     }%
+    }%
+   }%
+  }%
+ }%
+}
+%    \end{macrocode}
+
+% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%\paragraph{Interaction with class beamer.}
+%
+% For the class \textsf{beamer} we want to override the overlay mechanism
+% to always reserve the space the graphics would occupy.
+% Here we have to overwrite the command |\includegraphics|.
+%    \begin{macrocode}
+\@ifclassloaded{beamer}{\ifGin@box@beamer
+%    \end{macrocode}
+% Save the original definition of |\includegraphics| and begin the new one:
+%    \begin{macrocode}
+ \let\old@box@includegraphics\includegraphics
+ \newcommand<>{\fibox@includegraphics}[2][]{\Gin@box@hidefalse%
+%    \end{macrocode}
+% Check whether overlay parameters |<...>| are specified.
+% If none, use the counter of the |\pause| mechanism to determine visibility.
+% Call |\alt<...>| to set the |hide| argument according to visibility:
+%    \begin{macrocode}
+  \beamer@ifempty{#3}%
+   {\alt<\c@beamerpauses->{}{\Gin@box@hidetrue}}%
+   {\alt#3{}{\Gin@box@hidetrue}}%
+%    \end{macrocode}
+% Pass on to old definition:
+%    \begin{macrocode}
+  \old@box@includegraphics[#1]{#2}}
+%    \end{macrocode}
+% \textsf{beamer} overwrites |\includegraphics|
+% at the beginning of the document body.
+% We have to overwrite it again discarding
+% the changes introduced by \textsf{beamer}:
+%    \begin{macrocode}
+ \AtBeginDocument{\let\includegraphics=\fibox@includegraphics}
+\fi}{}
+%    \end{macrocode}
+
+%\iffalse
+%</package>
+%\fi
+%
+\endinput
diff --git a/macros/latex/contrib/graphbox/graphbox.ins b/macros/latex/contrib/graphbox/graphbox.ins
new file mode 100644
index 0000000000..e2ef935b91
--- /dev/null
+++ b/macros/latex/contrib/graphbox/graphbox.ins
@@ -0,0 +1,41 @@
+\def\batchfile{graphbox.ins}
+\input docstrip.tex
+
+\keepsilent
+% graphbox.ins Copyright (C) 2013-2018 Niklas Beisert
+%
+% This work 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.
+
+\preamble
+
+Copyright (C) 2013-2018 Niklas Beisert
+
+This work 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
+
+% the style and sample files 
+\generate{\askforoverwritefalse
+\file{graphbox.sty}{\from{graphbox.dtx}{package}}
+\file{gboxsamp.tex}{\from{graphbox.dtx}{sample}}
+\nopreamble\nopostamble
+\file{gboxsamp.mps}{\from{graphbox.dtx}{figure}}
+}
+
+\Msg{***********************************************************************}
+\Msg{* Done. Please copy the file graphbox.sty to an appropriate directory *}
+\Msg{* of your LaTeX distribution, e.g. texmf-root/tex/latex/graphbox.     *} 
+\Msg{***********************************************************************}
+\endinput
diff --git a/macros/latex/contrib/graphbox/graphbox.pdf b/macros/latex/contrib/graphbox/graphbox.pdf
new file mode 100644
index 0000000000..53c8be5e94
--- /dev/null
+++ b/macros/latex/contrib/graphbox/graphbox.pdf