diff options
Diffstat (limited to 'Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-external.tex')
-rw-r--r-- | Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-external.tex | 435 |
1 files changed, 435 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-external.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-external.tex new file mode 100644 index 00000000000..83fc1fe0385 --- /dev/null +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-external.tex @@ -0,0 +1,435 @@ +% Copyright 2007 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. A bit of trickery is needed and the |pgfbaseimage| package +provides macros that simplify the following 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. For this, you use a pair of +commands that are declared in the package |pgfbaseimage|. + +\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 that is 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. 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 behaviour arises when current the |\jobname| + equals the \meta{file name prefix} and, furthermore, the + a \emph{real job name} has been declared. The behaviour 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] +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 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 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] +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] +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 +together with pictures written to an external graphic file. The simple +reason is that there is no way to store this baseline information is +an external graphic file. + + +\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] +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] +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: +\begin{codeexample}[code only] +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} + +%%% Local Variables: +%%% mode: latex +%%% TeX-master: "pgfmanual" +%%% End: |