diff options
author | Karl Berry <karl@freefriends.org> | 2009-10-09 22:55:11 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2009-10-09 22:55:11 +0000 |
commit | 4be9896a3192173699de340a9f0475654efedb3a (patch) | |
tree | da0e954012cd781f875c761c42f6a76e50e2f272 /Master/texmf-dist/doc/generic/FAQ-en/faq-graphics.tex | |
parent | bd1227ad4919d2fbe17d63213bf48542f9c36f38 (diff) |
faq 3.19a update (9oct09)
git-svn-id: svn://tug.org/texlive/trunk@15725 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/generic/FAQ-en/faq-graphics.tex')
-rw-r--r-- | Master/texmf-dist/doc/generic/FAQ-en/faq-graphics.tex | 880 |
1 files changed, 880 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/generic/FAQ-en/faq-graphics.tex b/Master/texmf-dist/doc/generic/FAQ-en/faq-graphics.tex new file mode 100644 index 00000000000..45270301eb1 --- /dev/null +++ b/Master/texmf-dist/doc/generic/FAQ-en/faq-graphics.tex @@ -0,0 +1,880 @@ +% $Id: faq-graphics.tex,v 1.2 2009/06/18 23:13:04 rf10 Exp rf10 $ + +\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_pdf}; the document is also available + in \PS{} format as \CTANref{epslatex_ps} +\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]\CTANref{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. + +A similar 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.) + +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 +``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{}' +\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}. +\begin{ctanrefs} +\item[epstopdf]Browse \CTANref{epstopdf} +\item[epstopdf.sty]Distributed with Heiko Oberdiek's packages + \CTANref{oberdiek} +\item[pdftricks.sty]\CTANref{pdftricks} +\item[pst-pdf.sty]\CTANref{pst-pdf} +\item[pstoedit]\CTANref{pstoedit} +\item[purifyeps]\CTANref{purifyeps} +\end{ctanrefs} + +\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 +\ProgName{ghostscript} or \ProgName{Acrobat} \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 \ProgName{ghostscript} ``on the fly'' so as to be +able 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} + +\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} +\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 sample, given in the +\Package{graphics} bundle documentation, is: +\begin{quote} +\begin{verbatim} +\graphicspath{{eps/}{tiff/}} +\end{verbatim} +\end{quote} +however, if the security checks on your \AllTeX{} system allow, the +path may be anything you choose (rather than strictly relative, like +those above); note that the trailing ``\texttt{/}'' \emph{is} required. + +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 disadvantage of the \csx{graphicspath} method is inefficiency. The +package will call \AllTeX{} once for each entry in the list, which is +itself slows things. More seriously, \TeX{} remembers the file name, +thus effectively losing memory, every time it's +asked to look up a file, so a document that uses a huge number of +graphical inputs could be embarrassed by lack of memory. + +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 +\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} + +\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 +\ProgName{ghostscript} (or some other \PS{} previewer). However, +the \PS{} `engine' in \ProgName{ghostscript} \emph{doesn'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 regularly confuse sophisticated minds, this can prove +troublesome. If you're suffering such problems (the symptom is that +characters disappear, or are wrongly presented) the only 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 of a jiffy of Knuth's, by +Dan Luecking. 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]\CTANref{mpsproof} +\item[mptopdf]Part of \CTANref{pdftex-graphics} +\end{ctanrefs} + +\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 \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{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-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 \Package{PSTricks}; this gives you access to all the power of + \PS{} from \TeX{} itself, by sophisticated use of + \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 V\TeX{} (both in its + commercial and in its free versions) understands them. \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, using it with \PDFLaTeX{} is an awful fidget: if you + simply want the graphical capabilities, \Package{pgf}, together with + its rather pleasing ``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 + common \LaTeX{} commands that will utilise the graphical + capabilities of both \PS{} and \acro{PDF} equally. +\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{} +\item \ProgName{Mfpic}; you liked \MF{}, but can't understand the + language? The package makes up \MF{} or \MP{} code for you + within using familiar-looking \TeX{} macros. Not \emph{quite} the + full power of \MP{}, but a friendlier interface; of course, 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 Eitan Gurari's \Package{dratex}, which is as powerful as most + other \TeX{} drawing packages, but is an entirely new + implementation, which is not as hard on memory, is much more + readable (and is fully documented). +\end{itemize} +\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[pstricks]\CTANref{pstricks} +\item[tikz.sty]Distributed with \CTANref{pgf} +\end{ctanrefs} + +\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). + +Labels on graphics produced by all those \emph{other} tools is where +the \Package{psfrag} package can help. 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{PS text}}{\emph{Repl text}}, which instructs +the system to replace the original (``\texttt{PS}'') 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{}. The % ! line break +\Qref*{\Package{pst-pdf} package}{Q-pdftexgraphics} can support such +usage. In fact, the \Package{pst-pdf} support package +\Package{auto-pst-pdf} offers a configuration setting precisely for +use with \Package{psfrag}. + +On the other hand, +\begin{narrowversion} + V\TeX{}'s GeX processor (\Qref{}{Q-commercial}) +\end{narrowversion} +\begin{wideversion} + \Qref*{V\TeX{}}{Q-commercial}'s GeX processor +\end{wideversion} +explicitly deals with \Package{psfrag}, both in its free and +commercial instances. + +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. + +\Package{Pstricks} can of course do everything that \Package{overpic} +can, with all the flexibility of \PS{} programming that it offers +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[iTe]\CTANref{ite} +\item[laprint]Distributed with \CTANref{psfragx} +\item[overpic.sty]\CTANref{overpic} +\item[psfrag.sty]\CTANref{psfrag} +\item[psfragx.sty]\CTANref{psfragx} +\item[pstricks.sty]\CTANref{pstricks} +\item[pst-pdf.sty]\CTANref{pst-pdf} +\end{ctanrefs} + |