Debian Codegraph @

texmf-dist/doc/generic/pgf/pgfmanual-en-base-external.tex

raw
1 % Copyright 2019 by Till Tantau
2 %
3 % This file may be distributed and/or modified
4 %
5 % 1. under the LaTeX Project Public License and/or
6 % 2. under the GNU Free Documentation License.
7 %
8 % See the file doc/generic/pgf/licenses/LICENSE for more details.
9
10
11 \section{Externalizing Graphics}
12 \label{section-external}
13
14 \subsection{Overview}
15
16 There are two fundamentally different ways of inserting graphics into a
17 \TeX-document. First, you can create a graphic using some external program like
18 |xfig| or |InDesign| and then include this graphic in your text. This is done
19 using commands like |\includegraphics| or |\pgfimage|. In this case, the
20 graphic file contains all the low-level graphic commands that describe the
21 picture. When such a file is included, all \TeX\ has to worry about is the size
22 of the picture; the internals of the picture are unknown to \TeX\ and it does
23 not care about them.
24
25 The second method of creating graphics is to use a special package that
26 transforms \TeX-commands like |\draw| or |\psline| into appropriate low-level
27 graphic commands. In this case, \TeX\ has to do all the hard work of
28 ``typesetting'' the picture and if a picture has a complicated internal
29 structure this may take a lot of time.
30
31 While \pgfname\ was created to facilitate the second method of creating
32 pictures, there are two main reasons why you may need to employ the first
33 method of image-inclusion, nevertheless:
34 %
35 \begin{enumerate}
36 \item Typesetting a picture using \TeX\ can be a very time-consuming
37 process. If \TeX\ needs a minute to typeset a picture, you do not want
38 to wait this minute when you re\TeX\ your document after having changed
39 a single comma.
40 \item Some users, especially journal editors, may not be able to process
41 files that contain \pgfname\ commands -- for the simple reason that the
42 systems of many publishing houses do not have \pgfname\ installed.
43 \end{enumerate}
44
45 In both cases, the solution is to ``extract'' or ``externalize'' pictures that
46 would normally be typeset every time a document is \TeX ed. Once the pictures
47 have been extracted into separate graphics files, these graphic files can be
48 reinserted into the text using the first method.
49
50 Extracting a graphic from a file is not as easy as it may sound at first since
51 \TeX\ cannot write parts of its output into different files and a bit of
52 trickery is needed. The following macros simplify the workflow:
53 %
54 \begin{enumerate}
55 \item You have to tell \pgfname\ which files will be used for which
56 pictures. To do so, you enclose each picture that you wish to be
57 ``externalized'' in a pair of |\beginpgfgraphicnamed| and
58 |\endpgfgraphicnamed| macros.
59 \item The next step is to generate the extracted graphics. For this you run
60 \TeX\ with the |\jobname| set to the graphic file's name. This will
61 cause |\pgfname| to behave in a very special way: All of your document
62 will simply be thrown away, \emph{except} for the single graphic having
63 the same name as the current jobname.
64 \item After you have run \TeX\ once for each graphic that your wish to
65 externalize, you can rerun \TeX\ on your document normally. This will
66 have the following effect: Each time a |\beginpgfgraphicnamed| is
67 encountered, \pgfname\ checks whether a graphic file of the given name
68 exists (if you did step 2, it will). If this graphic file exists, it
69 will be input and the text till the corresponding |\endpgfgraphicnamed|
70 will be ignored.
71 \end{enumerate}
72
73 In the rest of this section, the above workflow is explained in more detail.
74
75
76 \subsection{Workflow Step 1: Naming Graphics}
77
78 In order to put each graphic in an external file, you first need to tell
79 \pgfname\ the names of these files.
80
81 \begin{command}{\beginpgfgraphicnamed\marg{file name prefix}}
82 This command indicates that everything up to the next call of
83 |\endpgfgraphicnamed| is part of a graphic that should be placed in a file
84 named \meta{file name prefix}|.|\meta{suffix}, where the \meta{suffix}
85 depends on your backend driver. Typically, \meta{suffix} will be |dvi| or
86 |pdf|.
87
88 Here is a typical example of how this command is used:
89 %
90 \begin{codeexample}[code only]
91 % In file main.tex:
92 ...
93 As we see in Figure~\ref{fig1}, the world is flat.
94 \begin{figure}
95 \beginpgfgraphicnamed{graphic-of-flat-world}
96 \begin{tikzpicture}
97 \fill (0,0) circle (1cm);
98 \end{tikzpicture}
99 \endpgfgraphicnamed
100 \caption{The flat world.}
101 \label{fig1}
102 \end{figure}
103 \end{codeexample}
104
105 Each graphic to be externalized should have a unique name. Note that this
106 name will be used as the name of a file in the file system, so it should
107 not contain any funny characters.
108
109 This command can have three different effects:
110 %
111 \begin{enumerate}
112 \item The easiest situation arises if there does not yet exist a
113 graphic file called \meta{file name prefix}|.|\meta{suffix}, where
114 the \meta{suffix} is one of the suffixes understood by your current
115 backend driver (so |pdf| or |jpg| if you use |pdftex|, |eps| if you
116 use |dvips|, and so on). In this case, both this command and the
117 |\endpgfgraphicnamed| command simply have no effect.
118 \item A more complex situation arises when a graphic file named
119 \meta{file name prefix}|.|\meta{suffix} \emph{does} exist. In this
120 case, this graphic file is included using the |\includegraphics|
121 command%
122 %
123 \footnote{Actually, the command key \texttt{/pgf/images/include
124 external} is invoked which calls an appropriate
125 \texttt{\textbackslash includegraphics} command.}.
126 %
127 Furthermore, the text between |\beginpgfgraphicnamed| and
128 |\endpgfgraphicnamed| is ignored.
129
130 When the text is ``ignored'', what actually happens is that all
131 text up to the next occurrence of |\endpgfgraphicnamed| is thrown
132 away without any macro expansion. This means, in particular, that
133 (a) you cannot put |\endpgfgraphicnamed| inside a macro and (b) the
134 macros used in the graphics need not be defined at all when the
135 graphic file is included. \item The most complex behavior arises
136 when current the |\jobname| equals the \meta{file name prefix} and,
137 furthermore, the \emph{real job name} has been declared. The
138 behavior for this case is explained later.
139 \end{enumerate}
140
141 Note that the |\beginpgfgraphicnamed| does not really have any effect until
142 you have generated the graphic files named. Till then, this command is
143 simply ignored. Also, if you delete the graphics file later on, the
144 graphics are typeset normally once more.
145 \end{command}
146
147 \begin{command}{\endpgfgraphicnamed}
148 This command just marks the end of the graphic that should be externalized.
149 \end{command}
150
151
152 \subsection{Workflow Step 2: Generating the External Graphics}
153
154 We have now indicated all the graphics for which we would like graphic files to
155 be generated. In order to generate the files, you now need to modify the
156 |\jobname| appropriately. This is done in two steps:
157 %
158 \begin{enumerate}
159 \item You use the following command to tell \pgfname\ the real name of your
160 |.tex| file:
161 %
162 \begin{command}{\pgfrealjobname\marg{name}}
163 Tells \pgfname\ the real name of your job. For instance, if you
164 have a file called |survey.tex| that contains two graphics that you
165 wish to be called |survey-graphic1| and |survey-graphic2|, then you
166 should write the following.
167 %
168 \begin{codeexample}[code only]
169 % This is file survey.tex
170 \documentclass{article}
171 ...
172 \usepackage{tikz}
173 \pgfrealjobname{survey}
174 \end{codeexample}
175 \end{command}
176 \item You run \TeX\ with the |\jobname| set to the name of the graphic for
177 which you need an external graphic to be generated. To set the
178 |\jobname|, you use the |--jobname=| option of \TeX:
179 %
180 \begin{codeexample}[code only, tikz syntax=false]
181 bash> latex --jobname=survey-graphic1 survey.tex
182 \end{codeexample}
183 %
184 \end{enumerate}
185
186 The following things will now happen:
187 %
188 \begin{enumerate}
189 \item |\pgfrealjobname| notices that the |\jobname| is not the ``real''
190 jobname and, thus, must be the name of a graphic that is to be put in
191 an external file.
192 \item At the beginning of the document, \pgfname\ changes the definition of
193 \TeX's internal |\shipout| macro. The new shipout macro simply throws
194 away the output. This means that the document is typeset normally, but
195 no output is produced.
196 \item When the |\beginpgfgraphicnamed{|\meta{name}|}| command is
197 encountered where the \meta{name} is the same as the current
198 |\jobname|, then a \TeX-box is started and \meta{everything} up to the
199 following |\endpgfgraphicnamed| command is stored inside this box.
200
201 Note that, typically, \meta{everything} will contain just a single
202 |{tikzpicture}| or |{pgfpicture}| environment. However, this need not
203 be the case, you can use, say, a |{pspicture}| environment as
204 \meta{everything} or even just some normal \TeX-text.
205 \item At the |\endpgfgraphicnamed|, the box \emph{is} shipped out using the
206 original |\shipout| command. Thus, unlike everything else, the contents
207 of the graphic is made part of the output.
208 \item When the box containing the graphic is shipped out, the paper size is
209 modified such that it is exactly equal to the height and width of the
210 box.
211 \end{enumerate}
212
213 The net effect of everything described above is that the two commands
214 %
215 \begin{codeexample}[code only, tikz syntax=false]
216 bash> latex --jobname=survey-graphic1 survey.tex
217 bash> dvips survey-graphic1
218 \end{codeexample}
219 %
220 \noindent produce a file called |survey-graphic1.ps| that consists of a single
221 page that contains exactly the graphic produced by the code between
222 |\beginpgfgraphicnamed{survey-graphic1}| and |\endpgfgraphicnamed|.
223 Furthermore, the size of this single page is exactly the size of the graphic.
224
225 If you use pdf\TeX, producing the graphic is even simpler:
226 %
227 \begin{codeexample}[code only, tikz syntax=false]
228 bash> pdflatex --jobname=survey-graphic1 survey.tex
229 \end{codeexample}
230 %
231 \noindent produces the single-page |pdf|-file |survey-graphic1.pdf|.
232
233
234 \subsection{Workflow Step 3: Including the External Graphics}
235
236 Once you have produced all the pictures in the text, including them into the
237 main document is easy: Simply run \TeX\ again without any modification of the
238 |\jobname|. In this case the |\pgfrealjobname| command will notice that the
239 main file is, indeed, the main file. The main file will then be typeset
240 normally and the |\beginpgfgraphicnamed| commands also behave normally, which
241 means that they will try to include the generated graphic files -- which is
242 exactly what you want.
243
244 Suppose that you wish to send your survey to a journal that does not have
245 \pgfname\ installed. In this case, you now have all the necessary external
246 graphics, but you still need \pgfname\ to automatically include them instead of
247 the executing the picture code! One way to solve this problem is to simply
248 delete all of the \pgfname\ or \tikzname\ code from your |survey.tex| and
249 instead insert appropriate |\includegraphics| commands ``by hand''. However,
250 there is a better way: You input the file |pgfexternal.tex|.
251
252 \begin{filedescription}{pgfexternal.tex}
253 This file defines the command |\beginpgfgraphicnamed| and causes it to have
254 the following effect: It includes the graphic file given as a parameter to
255 it and then gobbles everything up to |\endpgfgraphicnamed|.
256
257 Since |\beginpgfgraphicnamed| does not do macro expansion as it searches
258 for |\endpgfgraphicnamed|, it is not necessary to actually include the
259 packages necessary for \emph{creating} the graphics. So the idea is that
260 you comment out things like |\usepackage{tikz}| and instead say
261 |\input pgfexternal.tex|.
262
263 Indeed, the contents of this file is simply the following line:
264 %
265 \begin{codeexample}[code only]
266 \long\def\beginpgfgraphicnamed#1#2\endpgfgraphicnamed{\includegraphics{#1}}
267 \end{codeexample}
268
269 Instead of |\input pgfexternal.tex| you could also include this line in
270 your main file.
271 \end{filedescription}
272
273 As a final remark, note that the |baseline| option does not work directly with
274 pictures written to an external graphic file. The simple reason is that there
275 is no way to store this baseline information in an external graphic file. To
276 allow the |baseline| option (or any \TeX\ construction with non-zero depth),
277 the baseline information is stored into a separate file. This file is named
278 \marg{image file}|.dpth| and contains something like |5pt|.
279
280 So, if you need baseline information, you will have to keep the external
281 graphic file together with its~|.dpth| file. Furthermore, the short command in
282 |\input pgfexternal.tex| is no longer enough because it ignores any baseline
283 information. You will need to use |\input pgfexternalwithdepth.tex| instead (it
284 is shown below). It is slightly longer, but it can be used in the same way as
285 |pgfexternal.tex|.
286
287 \begin{key}{/pgf/images/include external (initially \textbackslash pgfimage\{\#1\})}
288 \label{pgf:includeexternalkey}
289 \index{External Graphics!Bounding Box Issues}
290 This key constitutes the public interface to exchange the
291 |\includegraphics| command used for the image inclusion.
292
293 Redefining this key allows to provide bounding box or viewport options:
294 %
295 \begin{codeexample}[code only]
296 \pgfkeys{/pgf/images/include external/.code={\includegraphics[viewport=0 0 211.28 175.686]{#1}}}
297 \end{codeexample}
298 %
299 Do not forget the |.code| here which redefines the command.
300
301 One application could be image externalization and bounding box
302 restrictions: As far as I know, a |.pdf| graphics with restricted bounding
303 box is always cropped (which is not always desired). One solution could be
304 to use |latex| and |dvips| which doesn't have this restriction. Another is
305 to manually provide the |viewport| option as shown above.
306
307 A possible value for |viewport| can be found in the |.pdf| image, search
308 for |/MediaBox = [ ... ]|.
309 \end{key}
310
311
312 \subsection{A Complete Example}
313
314 Let us now have a look at a simple, but complete example. We start out with a
315 normal file called |survey.tex| that has the following contents:
316 %
317 \begin{codeexample}[code only]
318 % This is the file survey.tex
319 \documentclass{article}
320
321 \usepackage{graphics}
322 \usepackage{tikz}
323
324 \begin{document}
325 In the following figure, we see a circle:
326 \begin{tikzpicture}
327 \fill (0,0) circle (10pt);
328 \end{tikzpicture}
329
330 By comparison, in this figure we see a rectangle:
331 \begin{tikzpicture}
332 \fill (0,0) rectangle (10pt,10pt);
333 \end{tikzpicture}
334 \end{document}
335 \end{codeexample}
336
337 Now our editor tells us that the publisher will need all figures to be provided
338 in separate PostScript or |.pdf|-files. For this, we enclose all figures in
339 |...graphicnamed|-pairs and we add a call to the |\pgfrealjobname| macro:
340 %
341 \begin{codeexample}[code only]
342 % This is the file survey.tex
343 \documentclass{article}
344
345 \usepackage{graphics}
346 \usepackage{tikz}
347 \pgfrealjobname{survey}
348
349 \begin{document}
350 In the following figure, we see a circle:
351 \beginpgfgraphicnamed{survey-f1}
352 \begin{tikzpicture}
353 \fill (0,0) circle (10pt);
354 \end{tikzpicture}
355 \endpgfgraphicnamed
356
357 By comparison, in this figure we see a rectangle:
358 \beginpgfgraphicnamed{survey-f2}
359 \begin{tikzpicture}
360 \fill (0,0) rectangle (10pt,10pt);
361 \end{tikzpicture}
362 \endpgfgraphicnamed
363 \end{document}
364 \end{codeexample}
365
366 After these changes, typesetting the file will still yield the same output as
367 it did before -- after all, we have not yet created any external graphics.
368
369 To create the external graphics, we run |pdflatex| twice, once for each
370 graphic:
371 %
372 \begin{codeexample}[code only, tikz syntax=false]
373 bash> pdflatex --jobname=survey-f1 survey.tex
374 This is pdfTeX, Version 3.141592-1.40.3 (Web2C 7.5.6)
375 entering extended mode
376 (./survey.tex
377 LaTeX2e <2005/12/01>
378 ...
379 ) [1] (./survey-f1.aux) )
380 Output written on survey-f1.pdf (1 page, 1016 bytes).
381 Transcript written on survey-f1.log.
382 \end{codeexample}
383
384 \begin{codeexample}[code only, tikz syntax=false]
385 bash> pdflatex --jobname=survey-f2 survey.tex
386 This is pdfTeX, Version 3.141592-1.40.3 (Web2C 7.5.6)
387 entering extended mode
388 (./survey.tex
389 LaTeX2e <2005/12/01>
390 ...
391 (./survey-f2.aux) )
392 Output written on survey-f2.pdf (1 page, 1002 bytes).
393 Transcript written on survey-f2.log.
394 \end{codeexample}
395
396 We can now send the two generated graphics (|survey-f1.pdf| and
397 |survey-f2.pdf|) to the editor. However, the publisher cannot use our
398 |survey.tex| file, yet. The reason is that it contains the command
399 |\usepackage{tikz}| and they do not have \pgfname\ installed.
400
401 Thus, we modify the main file |survey.tex| as follows:
402 %
403 \begin{codeexample}[code only]
404 % This is the file survey.tex
405 \documentclass{article}
406
407 \usepackage{graphics}
408 \input pgfexternal.tex
409 % \usepackage{tikz}
410 % \pgfrealjobname{survey}
411
412 \begin{document}
413 In the following figure, we see a circle:
414 \beginpgfgraphicnamed{survey-f1}
415 \begin{tikzpicture}
416 \fill (0,0) circle (10pt);
417 \end{tikzpicture}
418 \endpgfgraphicnamed
419
420 By comparison, in this figure we see a rectangle:
421 \beginpgfgraphicnamed{survey-f2}
422 \begin{tikzpicture}
423 \fill (0,0) rectangle (10pt,10pt);
424 \end{tikzpicture}
425 \endpgfgraphicnamed
426 \end{document}
427 \end{codeexample}
428 %
429 If we now run pdf\LaTeX, then, indeed, \pgfname\ is no longer needed:
430 % In the following, we switch off typesetting of listings because the
431 % parentheses confuse the pretty printer
432 %
433 \begin{codeexample}[code only,typeset listing/.code=#1]
434 bash> pdflatex survey.tex
435 This is pdfTeX, Version 3.141592-1.40.3 (Web2C 7.5.6)
436 entering extended mode
437 (./survey.tex
438 LaTeX2e <2005/12/01>
439 Babel <v3.8h> and hyphenation patterns for english, ..., loaded.
440 (/usr/local/gwTeX/texmf.texlive/tex/latex/base/article.cls
441 Document Class: article 2005/09/16 v1.4f Standard LaTeX document class
442 (/usr/local/gwTeX/texmf.texlive/tex/latex/base/size10.clo))
443 (/usr/local/gwTeX/texmf.texlive/tex/latex/graphics/graphics.sty
444 (/usr/local/gwTeX/texmf.texlive/tex/latex/graphics/trig.sty)
445 (/usr/local/gwTeX/texmf.texlive/tex/latex/config/graphics.cfg)
446 (/usr/local/gwTeX/texmf.texlive/tex/latex/pdftex-def/pdftex.def))
447 (/Users/tantau/Library/texmf/tex/generic/pgf/generic/pgf/utilities/pgfexternal.
448 tex) (./survey.aux)
449 (/usr/local/gwTeX/texmf.texlive/tex/context/base/supp-pdf.tex
450 [Loading MPS to PDF converter (version 2006.09.02).]
451 ) <survey-f1.pdf, id=1, 23.33318pt x 19.99973pt> <use survey-f1.pdf>
452 <survey-f2.pdf, id=2, 13.33382pt x 10.00037pt> <use survey-f2.pdf> [1{/Users/ta
453 ntau/Library/texmf/fonts/map/pdftex/updmap/pdftex.map} <./survey-f1.pdf> <./sur
454 vey-f2.pdf>] (./survey.aux) )</usr/local/gwTeX/texmf.texlive/fonts/type1/bluesk
455 y/cm/cmr10.pfb>
456 Output written on survey.pdf (1 page, 10006 bytes).
457 Transcript written on survey.log.
458 \end{codeexample}
459
460 To our editor, we send the following files:
461 %
462 \begin{itemize}
463 \item The last |survey.tex| shown above.
464 \item The graphic file |survey-f1.pdf|.
465 \item The graphic file |survey-f2.pdf|.
466 \item The file |pgfexternal.tex|, whose contents is simply
467 %
468 \begin{codeexample}[code only]
469 \long\def\beginpgfgraphicnamed#1#2\endpgfgraphicnamed{\includegraphics{#1}}
470 \end{codeexample}
471 %
472 (Alternatively, we can also directly add this line to our |survey.tex|
473 file).
474 \end{itemize}
475 %
476 In case we have used the |baseline| option, we also need to include any |.dpth|
477 files and we need to use the file |pgfexternalwithdepth.tex| instead of
478 |pgfexternal.tex|. This file also checks for the existence of |.dpth| files
479 containing baseline information, its contents is
480 %
481 \begin{codeexample}[code only]
482 \long\def\beginpgfgraphicnamed#1#2\endpgfgraphicnamed{%
483 \begingroup
484 \setbox1=\hbox{\includegraphics{#1}}%
485 \openin1=#1.dpth
486 \ifeof1 \box1
487 \else
488 \read1 to\pgfincludeexternalgraphicsdp\closein1
489 \dimen0=\pgfincludeexternalgraphicsdp\relax
490 \hbox{\lower\dimen0 \box1 }%
491 \fi
492 \endgroup
493 }
494 \end{codeexample}
495 %
496 Again, we could simply copy these lines to our |survey.tex| file.
497
498
499 %%% Local Variables:
500 %%% mode: latex
501 %%% TeX-master: "pgfmanual"
502 %%% End: