% \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