diff options
Diffstat (limited to 'graphics/pgf/base/doc/pgfmanual-en-base-external.tex')
-rw-r--r-- | graphics/pgf/base/doc/pgfmanual-en-base-external.tex | 502 |
1 files changed, 502 insertions, 0 deletions
diff --git a/graphics/pgf/base/doc/pgfmanual-en-base-external.tex b/graphics/pgf/base/doc/pgfmanual-en-base-external.tex new file mode 100644 index 0000000000..c6df6dc442 --- /dev/null +++ b/graphics/pgf/base/doc/pgfmanual-en-base-external.tex @@ -0,0 +1,502 @@ +% Copyright 2019 by Till Tantau +% +% This file may be distributed and/or modified +% +% 1. under the LaTeX Project Public License and/or +% 2. under the GNU Free Documentation License. +% +% See the file doc/generic/pgf/licenses/LICENSE for more details. + + +\section{Externalizing Graphics} +\label{section-external} + +\subsection{Overview} + +There are two fundamentally different ways of inserting graphics into a +\TeX-document. First, you can create a graphic using some external program like +|xfig| or |InDesign| and then include this graphic in your text. This is done +using commands like |\includegraphics| or |\pgfimage|. In this case, the +graphic file contains all the low-level graphic commands that describe the +picture. When such a file is included, all \TeX\ has to worry about is the size +of the picture; the internals of the picture are unknown to \TeX\ and it does +not care about them. + +The second method of creating graphics is to use a special package that +transforms \TeX-commands like |\draw| or |\psline| into appropriate low-level +graphic commands. In this case, \TeX\ has to do all the hard work of +``typesetting'' the picture and if a picture has a complicated internal +structure this may take a lot of time. + +While \pgfname\ was created to facilitate the second method of creating +pictures, there are two main reasons why you may need to employ the first +method of image-inclusion, nevertheless: +% +\begin{enumerate} + \item Typesetting a picture using \TeX\ can be a very time-consuming + process. If \TeX\ needs a minute to typeset a picture, you do not want + to wait this minute when you re\TeX\ your document after having changed + a single comma. + \item Some users, especially journal editors, may not be able to process + files that contain \pgfname\ commands -- for the simple reason that the + systems of many publishing houses do not have \pgfname\ installed. +\end{enumerate} + +In both cases, the solution is to ``extract'' or ``externalize'' pictures that +would normally be typeset every time a document is \TeX ed. Once the pictures +have been extracted into separate graphics files, these graphic files can be +reinserted into the text using the first method. + +Extracting a graphic from a file is not as easy as it may sound at first since +\TeX\ cannot write parts of its output into different files and a bit of +trickery is needed. The following macros simplify the workflow: +% +\begin{enumerate} + \item You have to tell \pgfname\ which files will be used for which + pictures. To do so, you enclose each picture that you wish to be + ``externalized'' in a pair of |\beginpgfgraphicnamed| and + |\endpgfgraphicnamed| macros. + \item The next step is to generate the extracted graphics. For this you run + \TeX\ with the |\jobname| set to the graphic file's name. This will + cause |\pgfname| to behave in a very special way: All of your document + will simply be thrown away, \emph{except} for the single graphic having + the same name as the current jobname. + \item After you have run \TeX\ once for each graphic that your wish to + externalize, you can rerun \TeX\ on your document normally. This will + have the following effect: Each time a |\beginpgfgraphicnamed| is + encountered, \pgfname\ checks whether a graphic file of the given name + exists (if you did step 2, it will). If this graphic file exists, it + will be input and the text till the corresponding |\endpgfgraphicnamed| + will be ignored. +\end{enumerate} + +In the rest of this section, the above workflow is explained in more detail. + + +\subsection{Workflow Step 1: Naming Graphics} + +In order to put each graphic in an external file, you first need to tell +\pgfname\ the names of these files. + +\begin{command}{\beginpgfgraphicnamed\marg{file name prefix}} + This command indicates that everything up to the next call of + |\endpgfgraphicnamed| is part of a graphic that should be placed in a file + named \meta{file name prefix}|.|\meta{suffix}, where the \meta{suffix} + depends on your backend driver. Typically, \meta{suffix} will be |dvi| or + |pdf|. + + Here is a typical example of how this command is used: + % +\begin{codeexample}[code only] +% In file main.tex: +... +As we see in Figure~\ref{fig1}, the world is flat. +\begin{figure} + \beginpgfgraphicnamed{graphic-of-flat-world} + \begin{tikzpicture} + \fill (0,0) circle (1cm); + \end{tikzpicture} + \endpgfgraphicnamed + \caption{The flat world.} + \label{fig1} +\end{figure} +\end{codeexample} + + Each graphic to be externalized should have a unique name. Note that this + name will be used as the name of a file in the file system, so it should + not contain any funny characters. + + This command can have three different effects: + % + \begin{enumerate} + \item The easiest situation arises if there does not yet exist a + graphic file called \meta{file name prefix}|.|\meta{suffix}, where + the \meta{suffix} is one of the suffixes understood by your current + backend driver (so |pdf| or |jpg| if you use |pdftex|, |eps| if you + use |dvips|, and so on). In this case, both this command and the + |\endpgfgraphicnamed| command simply have no effect. + \item A more complex situation arises when a graphic file named + \meta{file name prefix}|.|\meta{suffix} \emph{does} exist. In this + case, this graphic file is included using the |\includegraphics| + command% + % + \footnote{Actually, the command key \texttt{/pgf/images/include + external} is invoked which calls an appropriate + \texttt{\textbackslash includegraphics} command.}. + % + Furthermore, the text between |\beginpgfgraphicnamed| and + |\endpgfgraphicnamed| is ignored. + + When the text is ``ignored'', what actually happens is that all + text up to the next occurrence of |\endpgfgraphicnamed| is thrown + away without any macro expansion. This means, in particular, that + (a) you cannot put |\endpgfgraphicnamed| inside a macro and (b) the + macros used in the graphics need not be defined at all when the + graphic file is included. \item The most complex behavior arises + when current the |\jobname| equals the \meta{file name prefix} and, + furthermore, the \emph{real job name} has been declared. The + behavior for this case is explained later. + \end{enumerate} + + Note that the |\beginpgfgraphicnamed| does not really have any effect until + you have generated the graphic files named. Till then, this command is + simply ignored. Also, if you delete the graphics file later on, the + graphics are typeset normally once more. +\end{command} + +\begin{command}{\endpgfgraphicnamed} + This command just marks the end of the graphic that should be externalized. +\end{command} + + +\subsection{Workflow Step 2: Generating the External Graphics} + +We have now indicated all the graphics for which we would like graphic files to +be generated. In order to generate the files, you now need to modify the +|\jobname| appropriately. This is done in two steps: +% +\begin{enumerate} + \item You use the following command to tell \pgfname\ the real name of your + |.tex| file: + % + \begin{command}{\pgfrealjobname\marg{name}} + Tells \pgfname\ the real name of your job. For instance, if you + have a file called |survey.tex| that contains two graphics that you + wish to be called |survey-graphic1| and |survey-graphic2|, then you + should write the following. + % +\begin{codeexample}[code only] +% This is file survey.tex +\documentclass{article} +... +\usepackage{tikz} +\pgfrealjobname{survey} +\end{codeexample} + \end{command} + \item You run \TeX\ with the |\jobname| set to the name of the graphic for + which you need an external graphic to be generated. To set the + |\jobname|, you use the |--jobname=| option of \TeX: + % +\begin{codeexample}[code only, tikz syntax=false] +bash> latex --jobname=survey-graphic1 survey.tex +\end{codeexample} + % +\end{enumerate} + +The following things will now happen: +% +\begin{enumerate} + \item |\pgfrealjobname| notices that the |\jobname| is not the ``real'' + jobname and, thus, must be the name of a graphic that is to be put in + an external file. + \item At the beginning of the document, \pgfname\ changes the definition of + \TeX's internal |\shipout| macro. The new shipout macro simply throws + away the output. This means that the document is typeset normally, but + no output is produced. + \item When the |\beginpgfgraphicnamed{|\meta{name}|}| command is + encountered where the \meta{name} is the same as the current + |\jobname|, then a \TeX-box is started and \meta{everything} up to the + following |\endpgfgraphicnamed| command is stored inside this box. + + Note that, typically, \meta{everything} will contain just a single + |{tikzpicture}| or |{pgfpicture}| environment. However, this need not + be the case, you can use, say, a |{pspicture}| environment as + \meta{everything} or even just some normal \TeX-text. + \item At the |\endpgfgraphicnamed|, the box \emph{is} shipped out using the + original |\shipout| command. Thus, unlike everything else, the contents + of the graphic is made part of the output. + \item When the box containing the graphic is shipped out, the paper size is + modified such that it is exactly equal to the height and width of the + box. +\end{enumerate} + +The net effect of everything described above is that the two commands +% +\begin{codeexample}[code only, tikz syntax=false] +bash> latex --jobname=survey-graphic1 survey.tex +bash> dvips survey-graphic1 +\end{codeexample} +% +\noindent produce a file called |survey-graphic1.ps| that consists of a single +page that contains exactly the graphic produced by the code between +|\beginpgfgraphicnamed{survey-graphic1}| and |\endpgfgraphicnamed|. +Furthermore, the size of this single page is exactly the size of the graphic. + +If you use pdf\TeX, producing the graphic is even simpler: +% +\begin{codeexample}[code only, tikz syntax=false] +bash> pdflatex --jobname=survey-graphic1 survey.tex +\end{codeexample} +% +\noindent produces the single-page |pdf|-file |survey-graphic1.pdf|. + + +\subsection{Workflow Step 3: Including the External Graphics} + +Once you have produced all the pictures in the text, including them into the +main document is easy: Simply run \TeX\ again without any modification of the +|\jobname|. In this case the |\pgfrealjobname| command will notice that the +main file is, indeed, the main file. The main file will then be typeset +normally and the |\beginpgfgraphicnamed| commands also behave normally, which +means that they will try to include the generated graphic files -- which is +exactly what you want. + +Suppose that you wish to send your survey to a journal that does not have +\pgfname\ installed. In this case, you now have all the necessary external +graphics, but you still need \pgfname\ to automatically include them instead of +the executing the picture code! One way to solve this problem is to simply +delete all of the \pgfname\ or \tikzname\ code from your |survey.tex| and +instead insert appropriate |\includegraphics| commands ``by hand''. However, +there is a better way: You input the file |pgfexternal.tex|. + +\begin{filedescription}{pgfexternal.tex} + This file defines the command |\beginpgfgraphicnamed| and causes it to have + the following effect: It includes the graphic file given as a parameter to + it and then gobbles everything up to |\endpgfgraphicnamed|. + + Since |\beginpgfgraphicnamed| does not do macro expansion as it searches + for |\endpgfgraphicnamed|, it is not necessary to actually include the + packages necessary for \emph{creating} the graphics. So the idea is that + you comment out things like |\usepackage{tikz}| and instead say + |\input pgfexternal.tex|. + + Indeed, the contents of this file is simply the following line: + % +\begin{codeexample}[code only] +\long\def\beginpgfgraphicnamed#1#2\endpgfgraphicnamed{\includegraphics{#1}} +\end{codeexample} + + Instead of |\input pgfexternal.tex| you could also include this line in + your main file. +\end{filedescription} + +As a final remark, note that the |baseline| option does not work directly with +pictures written to an external graphic file. The simple reason is that there +is no way to store this baseline information in an external graphic file. To +allow the |baseline| option (or any \TeX\ construction with non-zero depth), +the baseline information is stored into a separate file. This file is named +\marg{image file}|.dpth| and contains something like |5pt|. + +So, if you need baseline information, you will have to keep the external +graphic file together with its~|.dpth| file. Furthermore, the short command in +|\input pgfexternal.tex| is no longer enough because it ignores any baseline +information. You will need to use |\input pgfexternalwithdepth.tex| instead (it +is shown below). It is slightly longer, but it can be used in the same way as +|pgfexternal.tex|. + +\begin{key}{/pgf/images/include external (initially \textbackslash pgfimage\{\#1\})} +\label{pgf:includeexternalkey} +\index{External Graphics!Bounding Box Issues} + This key constitutes the public interface to exchange the + |\includegraphics| command used for the image inclusion. + + Redefining this key allows to provide bounding box or viewport options: + % +\begin{codeexample}[code only] +\pgfkeys{/pgf/images/include external/.code={\includegraphics[viewport=0 0 211.28 175.686]{#1}}} +\end{codeexample} + % + Do not forget the |.code| here which redefines the command. + + One application could be image externalization and bounding box + restrictions: As far as I know, a |.pdf| graphics with restricted bounding + box is always cropped (which is not always desired). One solution could be + to use |latex| and |dvips| which doesn't have this restriction. Another is + to manually provide the |viewport| option as shown above. + + A possible value for |viewport| can be found in the |.pdf| image, search + for |/MediaBox = [ ... ]|. +\end{key} + + +\subsection{A Complete Example} + +Let us now have a look at a simple, but complete example. We start out with a +normal file called |survey.tex| that has the following contents: +% +\begin{codeexample}[code only] +% This is the file survey.tex +\documentclass{article} + +\usepackage{graphics} +\usepackage{tikz} + +\begin{document} +In the following figure, we see a circle: +\begin{tikzpicture} + \fill (0,0) circle (10pt); +\end{tikzpicture} + +By comparison, in this figure we see a rectangle: +\begin{tikzpicture} + \fill (0,0) rectangle (10pt,10pt); +\end{tikzpicture} +\end{document} +\end{codeexample} + +Now our editor tells us that the publisher will need all figures to be provided +in separate PostScript or |.pdf|-files. For this, we enclose all figures in +|...graphicnamed|-pairs and we add a call to the |\pgfrealjobname| macro: +% +\begin{codeexample}[code only] +% This is the file survey.tex +\documentclass{article} + +\usepackage{graphics} +\usepackage{tikz} +\pgfrealjobname{survey} + +\begin{document} +In the following figure, we see a circle: +\beginpgfgraphicnamed{survey-f1} +\begin{tikzpicture} + \fill (0,0) circle (10pt); +\end{tikzpicture} +\endpgfgraphicnamed + +By comparison, in this figure we see a rectangle: +\beginpgfgraphicnamed{survey-f2} +\begin{tikzpicture} + \fill (0,0) rectangle (10pt,10pt); +\end{tikzpicture} +\endpgfgraphicnamed +\end{document} +\end{codeexample} + +After these changes, typesetting the file will still yield the same output as +it did before -- after all, we have not yet created any external graphics. + +To create the external graphics, we run |pdflatex| twice, once for each +graphic: +% +\begin{codeexample}[code only, tikz syntax=false] +bash> pdflatex --jobname=survey-f1 survey.tex +This is pdfTeX, Version 3.141592-1.40.3 (Web2C 7.5.6) +entering extended mode +(./survey.tex +LaTeX2e <2005/12/01> +... +) [1] (./survey-f1.aux) ) +Output written on survey-f1.pdf (1 page, 1016 bytes). +Transcript written on survey-f1.log. +\end{codeexample} + +\begin{codeexample}[code only, tikz syntax=false] +bash> pdflatex --jobname=survey-f2 survey.tex +This is pdfTeX, Version 3.141592-1.40.3 (Web2C 7.5.6) +entering extended mode +(./survey.tex +LaTeX2e <2005/12/01> +... +(./survey-f2.aux) ) +Output written on survey-f2.pdf (1 page, 1002 bytes). +Transcript written on survey-f2.log. +\end{codeexample} + +We can now send the two generated graphics (|survey-f1.pdf| and +|survey-f2.pdf|) to the editor. However, the publisher cannot use our +|survey.tex| file, yet. The reason is that it contains the command +|\usepackage{tikz}| and they do not have \pgfname\ installed. + +Thus, we modify the main file |survey.tex| as follows: +% +\begin{codeexample}[code only] +% This is the file survey.tex +\documentclass{article} + +\usepackage{graphics} +\input pgfexternal.tex +% \usepackage{tikz} +% \pgfrealjobname{survey} + +\begin{document} +In the following figure, we see a circle: +\beginpgfgraphicnamed{survey-f1} +\begin{tikzpicture} + \fill (0,0) circle (10pt); +\end{tikzpicture} +\endpgfgraphicnamed + +By comparison, in this figure we see a rectangle: +\beginpgfgraphicnamed{survey-f2} +\begin{tikzpicture} + \fill (0,0) rectangle (10pt,10pt); +\end{tikzpicture} +\endpgfgraphicnamed +\end{document} +\end{codeexample} +% +If we now run pdf\LaTeX, then, indeed, \pgfname\ is no longer needed: +% In the following, we switch off typesetting of listings because the +% parentheses confuse the pretty printer +% +\begin{codeexample}[code only,typeset listing/.code=#1] +bash> pdflatex survey.tex +This is pdfTeX, Version 3.141592-1.40.3 (Web2C 7.5.6) +entering extended mode +(./survey.tex +LaTeX2e <2005/12/01> +Babel <v3.8h> and hyphenation patterns for english, ..., loaded. +(/usr/local/gwTeX/texmf.texlive/tex/latex/base/article.cls +Document Class: article 2005/09/16 v1.4f Standard LaTeX document class +(/usr/local/gwTeX/texmf.texlive/tex/latex/base/size10.clo)) +(/usr/local/gwTeX/texmf.texlive/tex/latex/graphics/graphics.sty +(/usr/local/gwTeX/texmf.texlive/tex/latex/graphics/trig.sty) +(/usr/local/gwTeX/texmf.texlive/tex/latex/config/graphics.cfg) +(/usr/local/gwTeX/texmf.texlive/tex/latex/pdftex-def/pdftex.def)) +(/Users/tantau/Library/texmf/tex/generic/pgf/generic/pgf/utilities/pgfexternal. +tex) (./survey.aux) +(/usr/local/gwTeX/texmf.texlive/tex/context/base/supp-pdf.tex +[Loading MPS to PDF converter (version 2006.09.02).] +) <survey-f1.pdf, id=1, 23.33318pt x 19.99973pt> <use survey-f1.pdf> +<survey-f2.pdf, id=2, 13.33382pt x 10.00037pt> <use survey-f2.pdf> [1{/Users/ta +ntau/Library/texmf/fonts/map/pdftex/updmap/pdftex.map} <./survey-f1.pdf> <./sur +vey-f2.pdf>] (./survey.aux) )</usr/local/gwTeX/texmf.texlive/fonts/type1/bluesk +y/cm/cmr10.pfb> +Output written on survey.pdf (1 page, 10006 bytes). +Transcript written on survey.log. +\end{codeexample} + +To our editor, we send the following files: +% +\begin{itemize} + \item The last |survey.tex| shown above. + \item The graphic file |survey-f1.pdf|. + \item The graphic file |survey-f2.pdf|. + \item The file |pgfexternal.tex|, whose contents is simply + % +\begin{codeexample}[code only] +\long\def\beginpgfgraphicnamed#1#2\endpgfgraphicnamed{\includegraphics{#1}} +\end{codeexample} + % + (Alternatively, we can also directly add this line to our |survey.tex| + file). +\end{itemize} +% +In case we have used the |baseline| option, we also need to include any |.dpth| +files and we need to use the file |pgfexternalwithdepth.tex| instead of +|pgfexternal.tex|. This file also checks for the existence of |.dpth| files +containing baseline information, its contents is +% +\begin{codeexample}[code only] +\long\def\beginpgfgraphicnamed#1#2\endpgfgraphicnamed{% + \begingroup + \setbox1=\hbox{\includegraphics{#1}}% + \openin1=#1.dpth + \ifeof1 \box1 + \else + \read1 to\pgfincludeexternalgraphicsdp\closein1 + \dimen0=\pgfincludeexternalgraphicsdp\relax + \hbox{\lower\dimen0 \box1 }% + \fi + \endgroup +} +\end{codeexample} +% +Again, we could simply copy these lines to our |survey.tex| file. + + +%%% Local Variables: +%%% mode: latex +%%% TeX-master: "pgfmanual" +%%% End: |