faq-graphics.tex

% $Id: faq-graphics.tex,v 1.27 2014/01/22 17:29:03 rf10 Exp $

\section{Graphics}

\Question[Q-impgraph]{Importing graphics into \AllTeX{} documents}

Knuth, when designing the current version of \TeX{} back in the early
1980s, could discern no ``standard'' way of expressing graphics in
documents.  He reasoned that this state could not persist for ever,
but that it would be foolish for him to define \TeX{} primitives that
allowed the import of graphical image definitions.  He therefore
deferred the specification of the use of graphics to the writers of
\acro{DVI} drivers; \TeX{} documents would control the drivers by
means of \nothtml{\csx{special} commands (}% beware line breaks
\Qref{\csx{special} commands}{Q-specials}\nothtml{)}.

There is therefore a straightforward way for anyone to import graphics
into their document: read the specification of the \csx{special}
commands your driver uses, and `just' code them.  This is the
hair-shirt approach: it definitely works, but it's not for everyone.

Over the years, therefore, ``graphics inclusion'' packages have sprung
up; most were designed for inclusion of
\nothtml{Encapsulated \PS{} graphics (}% beware line break
\Qref{Encapsulated \PS{} graphics}{Q-eps}\nothtml{)}\nobreakspace---
which has become the \emph{lingua franca} of graphics inclusion over
the last decade or so.

Notable examples are the \Package{epsf} package (distributed with
\ProgName{dvips}) and the \Package{psfig} package.  (Both of these
packages were designed to work well with both \plaintex{} and
\LaTeXo{}; they are both still available.)  All such packages were
tied to a particular \acro{DVI} driver (\ProgName{dvips}, in
the above two cases), but their code could be configured for others.

The obvious next step was to make the code configurable dynamically.
The \LaTeX{} standard \Package{graphics} package and its derivatives
made this step: it is strongly preferred for all current work.

Users of \plaintex{} have two options allowing them to use
\Package{graphicx}: the \Package{miniltx} ``\LaTeX{} emulator'' and
the \Package{graphicx.tex} front-end allow you to load
\Package{graphicx}, and \Qref*{\Eplain}{Q-eplain} allows you to load
it (using the full \LaTeX{} syntax) direct.

The \Package{graphics} package takes a variety of ``driver
options''~--- package options that select code to generate the
commands appropriate to the \acro{DVI} driver in use.  In most cases,
your \AllTeX{} distribution will provide a \File{graphics.cfg} file
that will select the correct driver for what you're doing (for
example, a distribution that provides both \LaTeX{} and \PDFLaTeX{}
will usually provide a configuration file that determines whether
\PDFLaTeX{} is running, and selects the definitions for it if so).

The \Package{graphics} package provides a toolkit of commands (insert
graphics, scale a box, rotate a box), which may be composed to provide
most facilities you need; the basic command, \csx{includegraphics},
takes one optional argument, which specifies  the bounding box of the
graphics to be included.

The \Package{graphicx} package uses the facilities of of
\Package{graphics} behind a rather more sophisticated command syntax
to provide a very powerful version of the \csx{includegraphics}
command.  \Package{graphicx}'s version can combine scaling and
rotation, viewporting and clipping, and many other things.  While this
is all a convenience (at some cost of syntax), it is also capable of
producing noticeably more efficient \PS{}, and some of its
combinations are simply not possible with the \Package{graphics}
package version.

The \Package{epsfig} package provides the same facilities as
\Package{graphicx}, but via a \csx{psfig} command (also known as
\csx{epsfig}), capable of emulating
the behaviour (if not the bugs) the old \Package{psfig} package.
\Package{Epsfig} also supplies homely support for former users of the
\Package{epsf} package.  However, there's a support issue: if you
declare you're using \Package{epsfig}, any potential mailing list or
usenet helper has to clear out of the equation the possibility that
you're using ``old'' \Package{epsfig}, so that support is slower
coming than it would otherwise be.

There is no rational reason to stick with the old packages, which have
never been entirely satisfactory in the \LaTeX{} context. (One
irrational reason to leave them behind is that their replacement's
name tends not to imply that it's exclusively related to \PS{}
graphics.  The reasoning also excludes \Package{epsfig}, of course.)

A wide variety of detailed techniques and tricks have been developed
over the years, and Keith Reckdahl's \Package{epslatex} outlines them
in compendious detail: this highly recommendable document is available
from \acro{CTAN}.  An invaluable review of the practicalities of
exchanging graphics between sites,
% beware multiple line break problems
\begin{wideversion} % hyperversion
``\href{http://silas.psfc.mit.edu/elec_fig/elec_figures.pdf}{Graphics for Inclusion in Electronic Documents}''
\end{wideversion}
\begin{narrowversion} % non-hyper
\href{http://silas.psfc.mit.edu/elec_fig/elec_figures.pdf}%
     {``Graphics for Inclusion in Electronic Documents''}
\end{narrowversion}
has been written by Ian Hutchinson; the document isn't on \acro{CTAN},
but may also be
% beware line breaks
\href{http://silas.psfc.mit.edu/elec_fig/}{browsed on the Web}.
\begin{ctanrefs}
\item[epsf.tex]\CTANref{epsf}
\item[epsfig.sty]Part of the \CTANref{graphics} bundle
\item[epslatex.pdf]\CTANref{epslatex}
\item[graphics.sty]\CTANref{graphics}
\item[graphicx.sty]Part of the \CTANref{graphics} bundle
\item[miniltx.tex]\CTANref{graphics-plain}
\item[psfig.sty]\CTANref{psfig}
\end{ctanrefs}

\Question[Q-dvipsgraphics]{Imported graphics in \ProgName{dvips}}

\ProgName{Dvips}, as originally conceived, can only import a single
graphics format: \nothtml{encapsulated \PS{} (\extension{eps} files, }%
\Qref{encapsulated \PS{}}{Q-eps}\htmlonly{ (\extension{eps} files}).
\ProgName{Dvips} also deals with the slightly eccentric \acro{EPS} that is
created by \Qref*{\MP{}}{Q-MP}.

Apart from the fact that a depressing proportion of drawing
applications produce corrupt \acro{EPS} when asked for such output,
this is pretty satisfactory for vector graphics work.

To include bitmap graphics, you need some means of converting them to
\PS{}; in fact many standard image manipulators (such as
\ProgName{ImageMagick}'s \ProgName{convert}) make a good job of
creating \acro{EPS} files (but be sure to ask for output at \PS{}
level~2 or higher).  (\ProgName{Unix} users should beware of
\ProgName{xv}'s claims: it has a tendency to downsample your bitmap to
your screen resolution.)

Special purpose applications \ProgName{jpeg2ps} (which converts
\acro{JPEG} files using \PS{} level 2 functionality),
\ProgName{bmeps} (which converts both \acro{JPEG} and \acro{PNG}
files) and \ProgName{a2ping}/\ProgName{sam2p} (which convert a
bewildering array of bitmap formats to \acro{EPS} or \acro{PDF} files;
\ProgName{sam2p} is one of the engines that \ProgName{a2ping} uses)
are also considered ``good bets''.

\ProgName{Bmeps} comes with patches to produce your own version of
\ProgName{dvips} that can cope with \acro{JPEG} and \acro{PNG} direct,
using \ProgName{bmeps}'s conversion library.  \ProgName{Dvips}, as
distributed by \miktex{}, comes with those patches built-in, but
assuming that capability destroys portability, and is only
recommendable if you are sure you will never want to share your
document.
\begin{ctanrefs}
\item[a2ping]\CTANref{a2ping}
\item[bmeps]Distributed as part of \CTANref{dktools}[bmeps]
\item[jpeg2ps]\CTANref{jpeg2ps}
\item[sam2p]\CTANref{sam2p}
\end{ctanrefs}

\Question[Q-pdftexgraphics]{Imported graphics in \PDFLaTeX{}}

\PDFTeX{} itself has a rather wide range of formats that it can
``natively'' incorporate into its output \acro{PDF} stream:
\acro{JPEG} (\extension{jpg} files) for photographs and similar images,
\acro{PNG} files for artificial bitmap images, and \acro{PDF} for
vector drawings.  Old versions of \PDFTeX{} (prior to version~1.10a)
supported \acro{TIFF} (\extension{tif} files) format as an alternative
to \acro{PNG} files; don't rely on this facility, even if you
\emph{are} running an old enough version of \PDFTeX{}\dots{}

In addition to the `native' formats, the standard \PDFLaTeX{}
\Package{graphics} package setup causes Hans Hagen's \File{supp-pdf}
macros to be loaded: these macros are capable of translating the
output of \MP{} to \acro{PDF} ``on the fly''; thus \MP{} output
(\extension{mps} files) may also be included in \PDFLaTeX{} documents.

The commonest problem users encounter, when switching from \TeX{}, is
that there is no straightforward way to include \acro{EPS} files:
since \PDFTeX{} is its own ``driver'', and since it contains no means
of converting \PS{} to \acro{PDF}, there's no direct way the job can
be done.

The simple solution is to convert the \acro{EPS} to an appropriate
\acro{PDF} file.  The \ProgName{epstopdf} program will do this: it's
available either as a Windows executable or as a \ProgName{Perl}
script to run on Unix and other similar systems.  A \LaTeX{} package,
\Package{epstopdf}, can be used to generate the requisite \acro{PDF}
files ``on the fly''; this is convenient, but requires that you
suppress one of \TeX{}'s security checks: don't allow its use in files
from sources you don't entirely trust.

The package \Package{pst-pdf} permits other things than `mere'
graphics files in its argument.  \Package{Pst-pdf} operates (the
authors suggest) ``like \BibTeX{}''~--- you process your file using
\PDFLaTeX{}, then use \LaTeX{}, \ProgName{dvips} and \ProgName{ps2pdf}
in succession, to produce a secondary file to input to your next
\PDFLaTeX{} run.  (Scripts are provided to ease the production of the
secondary file.)

A further extension is \Package{auto-pst-pdf}, which generates
\acro{PDF} (essentially) transparently, by spawning a job to process
output such as \Package{pst-pdf} uses.  If your \pdflatex{}
installation doesn't automatically allow it~--- see % ! line break
\Qref*{spawning a process}{Q-spawnprog}~--- then you need to start
\pdflatex{} with:
\begin{quote}
\begin{verbatim}
pdflatex -shell-escape <file>
\end{verbatim}
\end{quote}
for complete `automation'.

An alternative solution is to use \ProgName{purifyeps}, a
\ProgName{Perl} script which uses the good offices of
\ProgName{pstoedit} and of \MP{} to convert your Encapsulated \PS{} to
``Something that looks like the encapsulated \PS{} that comes out of
\MP{}'', and can therefore be included directly.  Sadly,
\ProgName{purifyeps} doesn't work for all \extension{eps} files.

Good coverage of the problem is to be found in Herbert Vo\ss {}'s
\href{http://pstricks.tug.org/main.cgi?file=pdf/pdfoutput}{\acro{PDF} support page},
which is targeted at the use of \Package{pstricks} in
\PDFLaTeX{}, and also covers the \Package{pstricks}-specific package
\Package{pdftricks}.  A recent alternative (not covered in % ! line break
Herbert Vo\ss {}'s page) is \Package{pdftricks2}, which offers similar
facilities to \Package{pdftricks}, but with some useful variations.
\begin{ctanrefs}
\item[auto-pst-pdf.sty]\CTANref{auto-pst-pdf}
\item[epstopdf]Browse \CTANref{epstopdf}
\item[epstopdf.sty]Distributed with Heiko Oberdiek's packages
  \CTANref{oberdiek}
\item[pdftricks.sty]\CTANref{pdftricks}
\item[pdftricks2.sty]\CTANref{pdftricks2}
\item[pst-pdf.sty]\CTANref{pst-pdf}
\item[pstoedit]\CTANref{pstoedit}
\item[purifyeps]\CTANref{purifyeps}
\end{ctanrefs}
\LastEdit{2012-11-20}

\Question[Q-dvipdfmgraphics]{Imported graphics in \ProgName{dvipdfm}}

\ProgName{Dvipdfm} (and \ProgName{dvipdfmx}) translates direct from
\acro{DVI} to \acro{PDF} (all other available routes produce \PS{}
output using \ProgName{dvips} and then convert that to \acro{PDF} with
\href{http://www.ghostscript.com/}{\ProgName{ghostscript}}
or \ProgName{Acrobat}'s \ProgName{Distiller}).

\ProgName{Dvipdfm}/\ProgName{Dvipdfmx} are particularly flexible
applications.  They permit the inclusion of bitmap and \acro{PDF}
graphics (as does \Qref*{\PDFTeX{}}{Q-pdftexgraphics}), but are also
capable of employing
\href{http://www.ghostscript.com/}{\ProgName{ghostscript}} ``on the
fly'' to permit the inclusion of encapsulated \PS{} (\extension{eps})
files by translating them to \acro{PDF}.  In this way, they combine the good
qualities of \ProgName{dvips} and of \PDFTeX{} as a means of
processing illustrated documents.

Unfortunately, ``ordinary'' \LaTeX{} can't deduce the bounding box of
a binary bitmap file (such as \acro{JPEG} or \acro{PNG}), so you have
to specify the bounding box.  This may be done explicitly, in the
document:
\begin{quote}
\begin{verbatim}
\usepackage[dvipdfm]{graphicx}
...
\includegraphics[bb=0 0 540 405]{photo.jpg}
\end{verbatim}
\end{quote}
It's usually not obvious what values to give the ``\texttt{bb}'' key,
but the program \ProgName{ebb} will generate a file
containing the information; the above numbers came from an
\ProgName{ebb} output file \File{photo.bb}:
\begin{quote}
\begin{verbatim}
%%Title: /home/gsm10/photo.jpg
%%Creator: ebb Version 0.5.2
%%BoundingBox: 0 0 540 405
%%CreationDate: Mon Mar  8 15:17:47 2004
\end{verbatim}
\end{quote}
If such a file is available, you may abbreviate the inclusion
code, above, to read:
\begin{quote}
\begin{verbatim}
\usepackage[dvipdfm]{graphicx}
...
\includegraphics{photo}
\end{verbatim}
\end{quote}
which makes the operation feel as simple as does including
\extension{eps} images in a \LaTeX{} file for processing with
\ProgName{dvips}; the \Package{graphicx} package knows to look for a
\extension{bb} file if no bounding box is provided in the
\csx{includegraphics} command.

The one place where usage isn't quite so simple is the need to quote
\ProgName{dvipdfm} explicitly, as an option when loading the
\Package{graphicx} package: if you are using \ProgName{dvips}, you
don't ordinarily need to specify the fact, since the default graphics
configuration file (of most distributions) ``guesses'' the
\texttt{dvips} option if you're using \TeX{}.
\begin{ctanrefs}
\item[dvipdfm]\CTANref{dvipdfm}
\item[dvipdfmx]\CTANref{dvipdfmx}
\item[ebb]Distributed as part of \CTANref{dvipdfm}
\end{ctanrefs}
\LastEdit{2013-06-03}

\Question[Q-grffilenames]{``Modern'' graphics file names}

\TeX{} was designed in a world where file names were very simple
indeed, typically strictly limited both in character set and length.
In modern systems, such restrictions have largely disappeared, which
leaves \TeX{} rather at odds with its environment.  Particular
problems arise with spaces in file names, but things like multiple
period characters can seriously confuse the \Package{graphics}
package.

The specification of \TeX{} leaves some leeway for distributions to
adopt file access appropriate to their operating system, but this
hasn't got us very far.  Many modern distributions allow you to
specify a file name as \texttt{"file name.tex"} (for example), which
helps somewhat, but while this allows us to say
\begin{quote}
\begin{verbatim}
\input "foo bar.tex"
\end{verbatim}
\end{quote}
the analogous usage
\begin{quote}
\begin{verbatim}
\includegraphics{"gappy graphics.eps"}
\end{verbatim}
\end{quote}
using ``ordinary'' \LaTeX{} causes confusion in \ProgName{xdvi} and
\ProgName{dvips}, even though it works at compilation time.  Sadly,
even within such quotes, multiple dots give \csx{includegraphics}
difficulties.  Note that
\begin{quote}
\begin{verbatim}
\includegraphics{"gappy graphics.pdf"}
\end{verbatim}
\end{quote}
works in a similar version of \PDFTeX{}.

If you're using the \Package{graphics} package, the \Package{grffile}
package will help.  The package offers several options, the simplest
of which are \pkgoption{multidot} (allowing more than one dot in a
file name) and \pkgoption{space} (allowing space in a file name).  The
\pkgoption{space} option requires that you're running on a
sufficiently recent version of \PDFTeX{}, in \acro{PDF} mode~--- and
even then it won't work for \MP{} files, which are read as \TeX{}
input, and therefore use the standard input mechanism).
\begin{ctanrefs}
\item[grffile.sty]Distributed as part of \CTANref{oberdiek}[grffile]
\end{ctanrefs}

\Question[Q-graphicspath]{Importing graphics from ``somewhere else''}

By default, graphics commands like \csx{includegraphics} look
``wherever \TeX{} files are found'' for the graphic file they're being
asked to use.  This can reduce your flexibility if you choose to hold
your graphics files in a common directory, away from your \AllTeX{}
sources.

The simplest solution is to patch \TeX{}'s path, by changing the
default path.  On most systems, the default path is taken from the
environment variable \texttt{TEXINPUTS}, if it's present; you can adapt that
to take in the path it already has, by setting the variable to
\begin{quote}
\begin{verbatim}
TEXINPUTS=.:<graphics path(s)>:
\end{verbatim}
\end{quote}
on a Unix system; on a Windows system the separator will be ``\texttt{;}''
rather than ``\texttt{:}''.  The ``\texttt{.}'' is there to ensure
that the current directory is searched first; the trailing
``\texttt{:}'' says ``patch in the value of \texttt{TEXINPUTS} from
your configuration file, here''.

This method has the merit of efficiency (\AllTeX{} does \emph{all} of
the searches, which is quick), but it's always clumsy and may prove
inconvenient to use in Windows setups (at least).

The alternative is to use the \Package{graphics} package command
\csx{graphicspath}; this command is of course also available to users
of the \Package{graphicx} and the \Package{epsfig} packages.  The
syntax of \csx{graphicspath}'s one argument is slightly odd: it's a
sequence of paths (typically relative paths), each of which is
enclosed in braces.  A slightly odd example (slightly modified from one
given in the \Package{graphics} bundle documentation) is:
\begin{quote}
\begin{verbatim}
\graphicspath{{eps/}{png/}}
\end{verbatim}
\end{quote}
which will search for graphics files in subdirectories \File{eps} and
\File{png} of the directory in which \LaTeX{} is running.  (Note that
the trailing ``\texttt{/}'' \emph{is} required.)

(Note that some \AllTeX{} systems will only allow you to use files in
the current directory and its sub-directories, for security reasons.
However, \csx{graphicspath} imposes no such restriction: as far as
\emph{it} is concerned, you can access files anywhere.)

Be aware that \csx{graphicspath} does not affect the operations of
graphics macros other than those from the graphics bundle~--- in
particular, those of the outdated \Package{epsf} and
\Package{psfig} packages are immune.

The slight disadvantage of the \csx{graphicspath} method is
inefficiency.  The package will call \AllTeX{} once for each entry in
the list to look for a file, which of course slows things.  Further,
\AllTeX{} remembers the name of any file it's asked to look up, thus
effectively losing memory, so that in the limit a document that uses a
huge number of graphical inputs could be embarrassed by lack of
memory.  (Such ``memory starvation'' is pretty unlikely with any
ordinary document in a reasonably modern \AllTeX{} system, but it
should be borne in mind.)

If your document is split into a variety of directories, and each
directory has its associated graphics, the \Package{import} package
may well be the thing for you; see the discussion % beware line break
\latexhtml{of ``bits of document in other directories'' (}{in the question ``}%
\Qref{bits of document in other directories}{Q-docotherdir}%
\latexhtml{)}{''}.
\begin{ctanrefs}
\item[graphics \nothtml{\rmfamily}bundle]\CTANref{graphics}
\item[import.sty]\CTANref{import}
\end{ctanrefs}

\Question[Q-graph-pspdf]{Portable imported graphics}

A regular need is a document to be distributed in more than
one format: commonly both \PS{} and \acro{PDF}.  The
following advice is based on a post by one with much experience of
dealing with the problem of dealing with \acro{EPS} graphics in this
case.
\begin{itemize}
\item Don't specify a driver when loading loading whichever version of
  the \Package{graphics} package you use.  The scheme relies on the
  distribution's ability to decide which driver is going to be used:
  the choice is between \ProgName{dvips} and \PDFTeX{}, in this case.
  Be sure to exclude options \pkgoption{dvips}, \pkgoption{pdftex} and
  \pkgoption{dvipdfm} (\ProgName{dvipdfm} is not used in this scheme,
  but the aspirant \acro{PDF}-maker may be using it for his output,
  before switching to the scheme).
\item Use \cmdinvoke{includegraphics}[...]{filename} without
  specifying the extension (i.e., neither \extension{eps} nor
  \extension{pdf}).
\item For every \extension{eps} file you will be including, produce a
  \extension{pdf} version, as described in % beware line break
  \Qref[question]{Graphics in \PDFLaTeX{}}{Q-pdftexgraphics}.  Having
  done this, you will have two copies of each graphic (a \extension{eps}
  and a \extension{pdf} file) in your directory.
\item Use \PDFLaTeX{} (rather than
  \LaTeX{}--\ProgName{dvips}--distillation or
  \LaTeX{}--\ProgName{dvipdfm}) to produce your \acro{PDF} output.
\end{itemize}
\ProgName{Dvipdfm}'s charms are less than attractive here: the
document itself needs to be altered from its default
(\ProgName{dvips}) state, before \ProgName{dvipdfm} will process it.

\Question[Q-repeatgrf]{Repeated graphics in a document}

A logo or ``watermark'' image, or any other image that is repeated in
your document, has the potential to make the processed version of the
document unmanageably large.  The problem is, that the default
mechanisms of graphics usage add the image at every point it's to be
used, and when processed, the image appears in the output file at each
such point.

Huge \PS{} files are embarrassing; explaining \emph{why} such a file
is huge, is more embarrassing still.

The \Qref*{\File{epslatex} graphics tutorial}{Q-tutbitslatex}
describes a technique for avoiding the problem: basically, one
converts the image that's to be repeated into a \PS{} subroutine, and
load that as a \ProgName{dvips} prologue file.  In place of the image,
you load a file (with the same bounding box as the image) containing
no more than an invocation of the subroutine defined in the prologue.

The \File{epslatex} technique is tricky, but does the job.  Trickier
still is the neat scheme of converting the figure to a one-character
Adobe Type~3 outline font.  While this technique is for the ``real
experts'' only (the author of this answer has never even tried it), it has
potential for the same sort of space saving as the \File{epslatex}
technique, with greater flexibility in actual use.

More practical is Hendri Adriaens' \Package{graphicx-psmin}; you load
this \emph{in place} of \Package{graphicx}, so rather than:
\begin{quote}
\begin{verbatim}
\usepackage[<options>]{graphicx}
\end{verbatim}
\end{quote}
you will write:
\begin{quote}
\begin{verbatim}
\usepackage[<options>]{graphicx-psmin}
\end{verbatim}
\end{quote}
and at the start of your document, you write:
\begin{quote}
\begin{verbatim}
\loadgraphics[<bb>]{<list of graphics>}
\end{verbatim}
\end{quote}
and each of the graphics in the list is converted to an ``object'' for
use within the resulting \PS{} output.  (This is, in essence, an
automated version of the \File{epslatex} technique described above.)

Having loaded the package as above, whenever you use
\csx{includegraphics}, the command checks if the file you've asked for
is one of the graphics in \csx{loadgraphics}' list.  If so, the
operation is converted into a call to the ``object'' rather than a new
copy of the file; the resulting \PS{} can of course be \emph{much} smaller.

Note that the package requires a recent \ProgName{dvips}, version
5.95b (this version isn't~--- yet~--- widely distributed).

If your \PS{} is destined for conversion to \acro{PDF}, either by a
\href{http://www.ghostscript.com/}{\ProgName{ghostscript}}-based
mechanism such as \ProgName{ps2pdf} or by
(for example) \ProgName{Acrobat} \ProgName{Distiller}, the issue isn't
so pressing, since the distillation mechanism will amalgamate graphics
objects whether or not the \PS{} has them amalgamated.  \PDFTeX{} does
the same job with graphics, automatically converting multiple uses
into references to graphics objects.
\begin{ctanrefs}
\item[graphicx-psmin.sty]\CTANref{graphicx-psmin}
\end{ctanrefs}
\LastEdit{2013-06-03}

\Question[Q-grmaxwidth]{Limit the width of imported graphics}

Suppose you have graphics which may or may not be able to fit within
the width of the page; if they will fit, you want to set them at their
natural size, but otherwise you want to scale the whole picture so
that it fits within the page width.

You do this by delving into the innards of the graphics package (which
of course needs a little \LaTeX{} internals programming):
\begin{quote}
\begin{verbatim}
\makeatletter
\def\maxwidth{%
  \ifdim\Gin@nat@width>\linewidth
    \linewidth
  \else
    \Gin@nat@width
  \fi
}
\makeatother
\end{verbatim}
\end{quote}
This defines a ``variable'' width which has the properties you want.
Replace \csx{linewidth} if you have a different constraint on the width
of the graphic.

Use the command as follows:
\begin{quote}
\begin{verbatim}
\includegraphics[width=\maxwidth]{figure}
\end{verbatim}
\end{quote}

\Question[Q-topgraph]{Top-aligning imported graphics}

When \TeX{} sets a line of anything, it ensures that the base-line of
each object in the line is at the same level as the base-line of the
final object.  (Apart, of course, from \csx{raisebox} commands\dots{})

Most imported graphics have their base-line set at the bottom of the
picture.  When using packages such as \Package{subfig}, one often
wants to align figures by their tops.  The following odd little bit of
code does this:
\begin{quote}
\begin{verbatim}
\vtop{%
  \vskip0pt
  \hbox{%
    \includegraphics{figure}%
  }%
}
\end{verbatim}
\end{quote}
The \csx{vtop} primitive sets the base-line of the resulting object to
that of the first ``line'' in it; the \csx{vskip} creates the illusion
of an empty line, so \csx{vtop} makes the very top of the box into the
base-line.

In cases where the graphics are to be aligned with text, there is a
case for making the base-line one ex-height below the top of the box,
as in:
\begin{quote}
\begin{verbatim}
\vtop{%
  \vskip-1ex
  \hbox{%
    \includegraphics{figure}%
  }%
}
\end{verbatim}
\end{quote}
A more \LaTeX{}-y way of doing the job (somewhat inefficiently) uses
the \Package{calc} package:
\begin{quote}
\begin{verbatim}
\usepackage{calc}
...
\raisebox{1ex-\height}{\includegraphics{figure}}
\end{verbatim}
\end{quote}
(this has the same effect as the text-align version, above).

The fact is, \emph{you} may choose where the base-line ends up.  This
answer merely shows you sensible choices you might make.

\Question[Q-mpprologues]{Displaying \MP{} output in \ProgName{ghostscript}}

\MP{} ordinarily expects its output to be included in some context
where the `standard' \MF{} fonts (that you've specified) are already
defined~--- for example, as a figure in \TeX{} document.  If you're
debugging your \MP{} code, you may want to view it in a
\href{http://www.ghostscript.com/}{\ProgName{ghostscript}}-based (or some
other \PS{}) previewer, but note that viewers (even
\href{http://www.ghostscript.com/}{\ProgName{ghostscript}})
\emph{don't} ordinarily have the fonts loaded, and you'll experience
an error such as
\begin{quote}
\begin{verbatim}
Error: /undefined in cmmi10
\end{verbatim}
\end{quote}
There is provision in \MP{} for avoiding this problem: issue the
command \texttt{prologues := 2;} at the start of the \extension{mp} file.

Unfortunately, the \PS{} that \MP{} inserts in its output,
following this command, is incompatible with ordinary use of the
\PS{} in inclusions into \AllTeX{} documents, so it's best to
make the \texttt{prologues} command optional.  Furthermore, \MP{} takes a
very simple-minded approach to font encoding: since \TeX{} font
encodings are anything but simple, encoding of text in diagrams are
another source of problems.  If you're suffering such problems (the
symptom is that 
characters disappear, or are wrongly presented) the solution is
to view the `original' \MP{} output after processing through
\LaTeX{} and \ProgName{dvips}.

Conditional compilation may be done either
by inputting \File{MyFigure.mp} indirectly from a simple wrapper
\File{MyFigureDisplay.mp}:
\begin{quote}
\begin{verbatim}
prologues := 2;
input MyFigure
\end{verbatim}
\end{quote}
or by issuing a shell command such as
\begin{quote}
\begin{verbatim}
mp '\prologues:=2; input MyFigure'
\end{verbatim}
\end{quote}
(which will work without the quote marks if you're not using a Unix
shell).

A suitable \LaTeX{} route would involve processing
\File{MyFigure.tex}, which contains:
\begin{quote}
\begin{verbatim}
\documentclass{article}
\usepackage{graphicx}
\begin{document}
\thispagestyle{empty}
\includegraphics{MyFigure.1}
\end{document}
\end{verbatim}
\end{quote}
Processing the resulting \acro{DVI} file with the \ProgName{dvips}
command
\begin{quote}
\begin{verbatim}
dvips -E -o MyFigure.eps MyFigure
\end{verbatim}
\end{quote}
would then give a satisfactory Encapsulated \PS{} file.  This
procedure may be automated using the \ProgName{Perl} script
\ProgName{mps2eps}, thus saving a certain amount of tedium.

The \plaintex{} user may use an adaptation, by
Dan Luecking, of a jiffy of Knuth's.  Dan's version
\Package{mpsproof.tex} will work under
\TeX{} to produce a \acro{DVI} file for use with \ProgName{dvips}, or
under \PDFTeX{} to produce a \acro{PDF} file, direct.  The output is
set up to look like a proof sheet.

A script application, \ProgName{mptopdf}, is available in recent
\AllTeX{} distributions: it seems fairly reliably to produce
\acro{PDF} from \MP{}, so may reasonably be considered an answer to
the question\dots{}
\begin{ctanrefs}
\item[mps2eps]\CTANref{mps2eps}
\item[mpsproof.tex]Distributed as part of the \MP{} distribution \CTANref{metapost}
\item[mptopdf]Part of \CTANref{pdftex-graphics}
\end{ctanrefs}
\LastEdit{2013-04-23}

\Question[Q-drawing]{Drawing with \TeX{}}

There are many packages to do pictures in \AllTeX{} itself (rather than
importing graphics created externally), ranging from simple use of
\LaTeX{} \environment{picture} environment, through enhancements like
\ProgName{eepic}, to 
sophisticated (but slow) drawing with \pictex{}. Depending on your type
of drawing, and setup, here are a few systems you may consider:
\begin{itemize}
\item The \environment{picture} environment provides rather primitive
  drawing capabilities (anything requiring more than linear
  calculations is excluded, unless a font can come to your help).  The
  environment's tedious insistence on its own \csx{unitlength}, as the
  basic measurement in a diagram, may be avoided by use of the
  \Package{picture} package, which detects whether a length is quoted
  as a number or as a length, and acts accordingly.
\item \Package{epic} was designed to make use of the \LaTeX{}
  \environment{picture} environment somewhat less agonising;
  \Package{eepic} extends it, and is capable of using \ProgName{tpic}
  \csx{special} commands to improve printing performance.  (If the
  \csx{special}s aren't available, the \Package{eepicemu} will do the
  business, far less efficiently.
\item \Package{pict2e}; this was advertised in % !line break
  \Qref*{the \LaTeX{} manual}{Q-latex-books}, but didn't appear for nearly
  ten years after publication of the book!  It removes all the petty
  restrictions that surround the use of the \environment{picture}
  environment.  It therefore suffers \emph{only} from the rather
  eccentric drawing language of the environment, and is a far more
  useful tool than the original environment has ever been.  (Note that
  \Package{pict2e} supersedes David Carlisle's stop-gap
  \Package{pspicture}.)
\item \pictex{} is a venerable, and very powerful, system, that draws
  by placing dots on the page to give the effect of a line or curve.  While
  this has the potential of great power, it is (of course) much slower
  than any of the other established packages.  What's more, there
  are problems with its \Qref*{documentation}{Q-docpictex}.
\item \Package{PSTricks} gives you access to the (considerable) power of
  \PS{} via a set of \TeX{} macros, which talk to \PS{} using 
  \Qref*{\csx{special} commands}{Q-specials}.  Since \PS{} is itself a
  pretty powerful programming language, many astounding things can in
  principle be achieved using \Package{PSTricks} (a wide range of
  contributed packages, ranging from world mapping to lens design
  diagrams, is available).
  \Package{Pstricks}' \csx{special}s are
  by default specific to \ProgName{dvips}, but there is
  a \Package{Pstricks} `driver' that allow \Package{Pstricks} to
  operate under \xetex{}.  \PDFTeX{} users may use \Package{pst-pdf},
  which (like \Package{epstopdf}~--- see % ! line break
  \Qref[question]{\PDFLaTeX{} graphics}{Q-pdftexgraphics}) generates
  \acro{PDF} files using an auxiliary program, from \Package{PSTricks}
  commands (\Package{pst-pdf} also requires a recent installation of
  the \Package{preview} package).

  There is a \Package{PSTricks} mailing list
  (\mailto{pstricks@tug.org}) which you may
  \href{http://tug.org/mailman/listinfo/pstricks}{join}, or you may
  just browse the % ! line break
  \href{http://tug.org/pipermail/pstricks/}{list archives}.
\item \Package{pgf}: while \Package{pstricks} is very powerful and
  convenient from `traditional' \TeX{}, using it with \PDFLaTeX{} is
  pretty tiresome: if you 
  simply want the graphical capabilities, \Package{pgf}, together with
  its ``user-oriented'' interface \Package{tikz}, may be a good
  bet for you.  While \acro{PDF} has (in essence) the same graphical
  capabilities as \PS{}, it isn't programmable; \Package{pgf} provides
  \LaTeX{} commands that will utilise the graphical capabilities of
  both \PS{} and \acro{PDF} equally.  \Package{Pgf} has extensive
  mathematical support, which allows it to rival \Package{PSTricks}'
  use of the computation engine within \PS{}.
  The \Package{pgf} manual is enormous, but a simple introduction which
  allows the user to get a feel for the capabilities of the system, is
  available at \url{http://cremeronline.com/LaTeX/minimaltikz.pdf}
\item \MP{}; you liked \MF{}, but never got to grips with font files?
  Try \Qref*{\MP{}}{Q-MP}~---
  all the power of \MF{}, but it generates \PS{} figures; \MP{}
  is nowadays part of most serious \AllTeX{} distributions.  Knuth
  uses it for all his work\dots{}

  Note that you can % ! line break
  \Qref*{``embed'' \MP{} source in your document}{Q-inlgrphapp} (i.e.,
  keep it in-line with your \LaTeX{} code).
\item You liked \MF{} (or \MP{}), but find the language difficult?
  \ProgName{Mfpic} makes up \MF{} or \MP{} code for you using
  familiar-looking \AllTeX{} macros.  Not \emph{quite} the full power
  of \MF{} or \MP{}, but a friendlier interface, and with \MP{} output
  the results can be used equally well in either \LaTeX{} or \PDFLaTeX{}.
\item You liked \pictex{} but don't have enough memory or time?  Look
  at the late Eitan Gurari's \Package{dratex}: it is just as powerful,
  but is an entirely new implementation which is not as hard on
  memory, is much more readable and is (admittedly sparsely) documented at
  \url{http://www.cse.ohio-state.edu/~gurari/tpf/html/README.html},
  as well as in the author's book ``TeX and LATeX: Drawing and
  Literate Programming'', which remains available from on-line
  booksellers.
\end{itemize}

In addition, there are several means of generating code for your
graphics application (\ProgName{asymptote}, \ProgName{gnuplot} and
\MP{}, at least) in-line in your document, and then have them
processed in a command spawned from your \AllTeX{} run.  For details,
see \Qref{question}{Q-inlgrphapp}.
\begin{ctanrefs}
\item[dratex.sty]\CTANref{dratex}
\item[epic.sty]\CTANref{epic}
\item[eepic.sty]\CTANref{eepic}
\item[eepicemu.sty]\CTANref{eepic}
\item[mfpic]\CTANref{mfpic}
\item[preview.sty]\CTANref{preview}
\item[pspicture.sty]\CTANref{pspicture}
\item[pst-pdf.sty]\CTANref{pst-pdf}
\item[pgf.sty]\CTANref{pgf}
\item[pict2e.sty]\CTANref{pict2e}
\item[pictex.sty]\CTANref{pictex}
\item[picture.sty]Distributed as part of \CTANref{oberdiek}[picture]
\item[pstricks]\CTANref{pstricks}
\item[tikz.sty]Distributed as part of \CTANref{pgf}
\end{ctanrefs}
\LastEdit{2012-10-19}

\Question[Q-inlgrphapp]{In-line source for graphics applications}

Some of the free-standing graphics applications may also be used
(effectively) in-line in \LaTeX{} documents; examples are
\begin{booklist}
\item[asymptote]The package \Package{asymptote} (provided in the
  \ProgName{asymptote} distribution) defines an environment
  \environment{asy} which arranges that its contents are available for
  processing, and will therefore be typeset (after ``enough'' runs, in
  the `usual' \LaTeX{} way).

  Basically, you write
  \begin{quote}
    \cmdinvoke{begin}{asy}\\
    \latexhtml{\hspace*{1em}}{~~}\texttt{\meta{asymptote code}}\\
    \cmdinvoke{end}{asy}
  \end{quote}
  and then execute
\begin{quote}
\begin{verbatim}
latex document
asy document-*.asy
latex document
\end{verbatim}
\end{quote}
\item[egplot]Allows you to incorporate \ProgName{GNUplot}
  instructions in your document, for processing outside of \LaTeX{}.
  The package provides commands that enable the user to do calculation
  in \ProgName{GNUplot}, feeding the results into the diagram
  to be drawn.
\item[gmp]Allows you to include the source of MetaPost diagrams, with
  parameters of the diagram passed from the environment call.
\item[emp]An earlier package providing facilities similar to those of
  \Package{gmp} (\Package{gmp}'s author hopes that his package will
  support the facilities \Package{emp}, which he believes is in need
  of update.)
\item[mpgraphics]Again, allows you to program parameters of \MP{}
  diagrams from your \LaTeX{} document, including the preamble details
  of the \LaTeX{} code in any recursive call from \MP{}.
\end{booklist}
In all cases (other than \Package{asymptote}), these packages require
that you can % ! line break
\Qref*{run external programs from within your document}{Q-spawnprog}.
\begin{ctanrefs}
\item[asymptote.sty]\CTANref{asymptote}
\item[egplot.sty]\CTANref{egplot}
\item[emp.sty]\CTANref{emp}
\item[gmp.sty]\CTANref{gmp}
\item[mpgraphics.sty]\CTANref{mpgraphics}
\end{ctanrefs}
\LastEdit*{2011-03-16}

\Question[Q-drawFeyn]{Drawing Feynman diagrams in \LaTeX{}}

Michael Levine's \Package{feynman} bundle for drawing the diagrams in
\LaTeXo{} is still available.

Thorsten Ohl's \Package{feynmf} is designed for use with current
\LaTeX{}, and works in
combination with \MF{} (or, in its \Package{feynmp} incarnation, with
\MP{}).  The \ProgName{feynmf} or
\ProgName{feynmp} package reads a description of the diagram written
in \TeX{}, and writes out code.  \MF{} (or \MP{}) can then produce a
font (or \PS{} file) for use in a subsequent \LaTeX{} run.  For
new users, who have access to \MP{}, the \PS{} version is
probably the better route, for document portability and other reasons.
% checked rf 2001/03/22

Jos Vermaseren's \Package{axodraw} is mentioned as an alternative in
the documentation of \Package{feynmf}, but it is written entirely in
terms of \ProgName{dvips} \csx{special} commands, and is thus rather
imperfectly portable.

An alternative approach is implemented by Norman Gray's \Package{feyn}
package.  Rather than creating complete diagrams as postscript images,
\Package{feyn} provides a font (in a variety of sizes) containing
fragments, which you can compose to produce complete diagrams.  It
offers fairly simple diagrams which look good in equations, rather
than complicated ones more suitable for display in figures.
\begin{ctanrefs}
\item[axodraw]\CTANref{axodraw}
\item[feyn \nothtml{\rmfamily}font bundle]\CTANref{feyn}
\item[feynman bundle]\CTANref{feynman}
\item[feynmf/feynmp bundle]\CTANref{feynmf}
\end{ctanrefs}

\Question[Q-labelfig]{Labelling graphics}

``Technical'' graphics (such as graphs and diagrams) are often
labelled with quite complex mathematical expressions: there are few
drawing or graphing tools that can do such things (the honourable
exception being \MP{}, which allows you to program the labels, in
\AllTeX{}, in the middle of specifying your graphic).

Placing `labels' on graphics produced by all those \emph{other} tools is
what we discuss here.  (Note that the term ``label'' should be
liberally interpreted; many of the techniques \emph{were} designed for
use when applying labels to figures, but they may be used equally well
to draw funny faces on a figure \dots{} or anything.

The time-honoured \Package{psfrag} package can help, if your image is
included as an (encapsulated) \PS{} file.  Place an unique
text in your graphic, using the normal text features of your tool, and
you can ask \Package{psfrag} to replace the text with arbitrary
\AllTeX{} material.  \Package{Psfrag}'s ``operative'' command is
\cmdinvoke{psfrag}{\emph{Orig text}}{\emph{Repl text}}, which
instructs the system to replace the original (``unique'') text with
the \TeX{}-typeset replacement text.  Optional arguments permit
adjustment of position, scale and rotation; full details may be found
in \File{pfgguide} in the distribution.

Since \Package{psfrag} works in terms of (encapsulated) \PS{} files,
it needs extra work for use with \PDFLaTeX{}.  Two techniques are
available, using \Qref*{\Package{pst-pdf} package}{Q-pdftexgraphics}
in a mode designed to do this work; and using \Package{pdfrack}.

The \Qref*{\Package{Pst-pdf} package}{Q-pdftexgraphics} can support
this ``extra work'' usage.  In fact, the \Package{pst-pdf} support
package \Package{auto-pst-pdf} offers a configuration setting
precisely for use with \Package{psfrag}.

If you have the `right' environment (see below), you could try the
\Package{pdfrack} script bundle.  The script aims to cut each figure
out of your source, using it to produce a small \LaTeX{} file with
nothing but the figure inclusion commands.  Each of these figure files
is then processed to \PS{}, compiled using the \csx{psfrag} commands,
and the resulting output converted to \acro{PDF} again.

\Package{Pdfrack} is written to use the Unix Bourne shell (or
equivalent); thus your environment needs to be a Unix-based system, or
some equivalent such as \ProgName{cygwin} under windows.  (What is
more, \Package{pdfrack}'s author is rather disparaging about his
package; the present author has never tried it.)

The \Package{psfragx} package goes one step further than
\Package{psfrag}: it provides a means whereby you can put the
\Package{psfrag} commands into the preamble of your \acro{EPS} file
itself.  \Package{Psfrag} has such a command itself, but deprecates
it; \Package{psfragx} has cleaned up the facility, and provides a
script \ProgName{laprint} for use with \ProgName{Matlab} to produce
appropriately tagged output.  (In principle, other graphics
applications could provide a similar facility, but apparently none does.)

\ProgName{Emacs} users may find the embedded editor \ProgName{iTe} a
useful tool for placing labels: it's a \AllTeX{}-oriented graphical
editor written in \ProgName{Emacs Lisp}.  You create
\environment{iteblock} environments containing graphics and text, and
may then invoke \ProgName{iTe} to arrange the elements relative to one
another.

Another useful approach is \Package{overpic}, which overlays a
\environment{picture} environment on a graphic included by use of
\csx{includegraphics}.  This treatment lends itself to ready placement
of texts and the like on top of a graphic.  The package can draw a
grid for planning your ``attack''; the distribution comes with simple
examples.

The \Package{lpic} package is somewhat similar to \Package{overpic};
it defines an environment \environment{lpic} (which places your
graphic for you): within the environment you may use the command
\csx{lbl} to position \LaTeX{} material at appropriate places over the
graphic.

\Package{Pinlabel} is another package whose author thought in the same
sort of way as that of \Package{overpic}; the documentation explains
in detail how to plan your `labelling attack'~--- in this case by
loading your figure into a viewer and taking measurements from it.
(The package discusses direct use of
\href{http://www.ghostscript.com/}{\ProgName{ghostscript}} as well as
customised viewers such as
\href{http://www.ghostgum.com.au/}{\ProgName{gsview}} or
\ProgName{gv}.)

\Package{Pstricks} can of course do everything
that \Package{overpic}, \Package{lpic} or \Package{pinlabel}
can, with all the flexibility of \PS{} programming that it offers.
This capability is exemplified by the \Package{pst-layout} package,
which seems to be a superset of both \Package{overpic} and
\Package{lpic}.

Similarly, \Package{pgf/TikZ} has all the power needed, but no
explicit package has been released.

The \Package{pstricks} web site has a page with several % ! line break
\href{http://pstricks.tug.org/main.cgi?file=Examples/overlay}{examples of labelling}
which will get you started; if \Package{pstricks} is % ! line break
\Qref*{an option for you}{Q-drawing}, this route is worth a try.

The confident user may, of course, do the whole job in a picture
environment which itself includes the graphic.  I would recommend
\Package{overpic} or the \Package{pstricks} approach, but such things
are plainly little more than a convenience over what is achievable
with the do-it-yourself approach.
\begin{ctanrefs}
\item[auto-pst-pdf.sty]\CTANref{auto-pst-pdf}
\item[gv]\CTANref{gv}
\item[iTe]\CTANref{ite}
\item[laprint]Distributed with \CTANref{psfragx}
\item[lpic.sty]\CTANref{lpic}
\item[overpic.sty]\CTANref{overpic}
\item[pdfrack]\CTANref{pdfrack}
\item[pinlabel.sty]\CTANref{pinlabel}
\item[pgf.sty]\CTANref{pgf}
\item[psfrag.sty]\CTANref{psfrag}
\item[psfragx.sty]\CTANref{psfragx}
\item[pstricks.sty]\CTANref{pstricks}
\item[pst-layout.sty]\CTANref{pst-layout}
\item[pst-pdf.sty]\CTANref{pst-pdf}
\end{ctanrefs}
\LastEdit{2013-06-03}