summaryrefslogtreecommitdiff
path: root/graphics/pgf/base/doc/pgfmanual-en-base-external.tex
diff options
context:
space:
mode:
Diffstat (limited to 'graphics/pgf/base/doc/pgfmanual-en-base-external.tex')
-rw-r--r--graphics/pgf/base/doc/pgfmanual-en-base-external.tex502
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: