From 98d97883f83dd86032b6b058692d87b9fa83926b Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Fri, 28 Jun 2013 22:26:18 +0000 Subject: FAQ-en (7jun13) git-svn-id: svn://tug.org/texlive/trunk@31019 c570f23f-e606-0410-a88d-b1316a301751 --- .../FAQ-en/archive-version/faq-graphics.tex | 1011 -------------------- 1 file changed, 1011 deletions(-) delete mode 100644 Master/texmf-dist/doc/generic/FAQ-en/archive-version/faq-graphics.tex (limited to 'Master/texmf-dist/doc/generic/FAQ-en/archive-version/faq-graphics.tex') diff --git a/Master/texmf-dist/doc/generic/FAQ-en/archive-version/faq-graphics.tex b/Master/texmf-dist/doc/generic/FAQ-en/archive-version/faq-graphics.tex deleted file mode 100644 index 1c242162815..00000000000 --- a/Master/texmf-dist/doc/generic/FAQ-en/archive-version/faq-graphics.tex +++ /dev/null @@ -1,1011 +0,0 @@ -% $Id: faq-graphics.tex,v 1.26 2012/11/24 10:56: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 -\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 -\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}[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=.:: -\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[]{graphicx} -\end{verbatim} -\end{quote} -you will write: -\begin{quote} -\begin{verbatim} -\usepackage[]{graphicx-psmin} -\end{verbatim} -\end{quote} -and at the start of your document, you write: -\begin{quote} -\begin{verbatim} -\loadgraphics[]{} -\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]Distributed as part of the \MP{} distribution \CTANref{metapost} -\item[mptopdf]Part of \CTANref{pdftex-graphics} -\end{ctanrefs} -\LastEdit{2010-03-16} - -\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 V\TeX{} (both in its - commercial and in its free versions) understands them, and 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. - -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{}. 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, % ! line break -\Qref*{V\TeX{}'s GeX processor}{Q-commercial} 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. - -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 \ProgName{ghostscript} as well as -customised viewers such as \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[ghostscript]\CTANref{ghostscript} -\item[gsview]\CTANref{gsview} -\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[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{2012-03-16} -- cgit v1.2.3