summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/pgfplots/pgfplots.importexport.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/latex/pgfplots/pgfplots.importexport.tex')
-rw-r--r--Master/texmf-dist/doc/latex/pgfplots/pgfplots.importexport.tex145
1 files changed, 134 insertions, 11 deletions
diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.importexport.tex b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.importexport.tex
index e5a2a81b047..048dc50e721 100644
--- a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.importexport.tex
+++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.importexport.tex
@@ -1,20 +1,143 @@
\section{Import/Export from other formats}
-There are two (experimental) scripts which may be used to generate \LaTeX-code with plot coordinates or to simplify format conversion. They are not necessary to run \PGFPlots.
+\label{sec:pgfplots:importexport}
+This section contains information of how to single pictures into separate \pdf\ graphics files (or \eps\ graphics files). Furthermore, it explains a matlab (tm) script which allows to convert from matlab to \PGFPlots.
-\subsection{pgf2pdf.sh}
-This is a unix \texttt{bash}--script which attempts to simplify the workflow of creating PDF-Dokuments for single plots.
+\subsection{Export to \pdf/\eps}
+It is possible to export images to single \pdf-documents using routines of \pgfname\ and/or \Tikz.
-\PGF\ provides a method to externalize graphics, meaning to write specific portions of the \LaTeX-file to separate PDF/EPS-files. The script pgf2pdf.sh assumes that portions which need externalization are in files `\texttt{.pgf}' and should be converted to PDF/EPS. Two ways are supported:
+\subsubsection{Using the Externalization framework of \pgfname\ ``by hand''}
+The first way to export \TeX-pictures to single graphics files is to use the externalization framework of \pgfname.
+The basic idea is to encapsulate the desired parts with
+
+|\beginpgfgraphicnamed|\marg{output file name}
+
+\meta{picture contents}
+
+|\endpgfgraphicnamed|.
+
+\noindent Furthermore, one needs to tell \pgfname\ the name of the main document using
+
+|\pgfrealjobname|\marg{the real job's name}
+
+\noindent in the preamble. This enables two different modes:
\begin{enumerate}
- \item Run \LaTeX\ on the complete document and write only the portion of interest,
- \item Run \LaTeX\ \emph{only} on the `\texttt{.pgf}'-file. This mode requires a \TeX-file which defines all required commands and includes all required packages (a header).
+ \item The first is the normal typesetting mode. \LaTeX\ checks whether a file named \marg{output file name} with one of the accepted file extensions exists -- if that is the case, the graphics file is included with |\pgfimage| and the \meta{picture contents} is skipped. If no such file exists, the \meta{picture contents} is typeset normally. This mode is applied if |\jobname| equals \marg{the real job's name}.
+ \item The second mode applies if |\jobname| equals \marg{output file name}, it initiates the ``conversion mode'' which is used to write the graphics file \marg{output file name}. In this case, \emph{only} \meta{picture contents} is written to |\jobname|, the complete rest of the \LaTeX\ is processed as normal, but it is silently discarded.
+
+ This mode needs to be started manually with |pdflatex --jobname |\meta{output file name} for every externalized graphics file.
\end{enumerate}
+A complete example may look as follows.
+\begin{codeexample}[code only]
+\documentclass{article}
-If you are interested in externalized graphics, you should read\cite[Section~54]{tikz}. You may also type
-\begin{lstlisting}
- pgf2pdf.sh --help.
-\end{lstlisting}
-This script is experimental.
+\usepackage{pgfplots}
+
+\pgfrealjobname{test}
+
+\begin{document}
+ \begin{figure}
+ \beginpgfgraphicnamed{testfigure}
+ \begin{tikzpicture}
+ \begin{axis}
+ \addplot (\x,\x^2);
+ \end{axis}
+ \end{tikzpicture}
+ \endpgfgraphicnamed
+ \caption{Our first external graphics example}
+ \end{figure}
+
+ \begin{figure}
+ \beginpgfgraphicnamed{testfigure2}
+ \begin{tikzpicture}
+ \begin{axis}
+ \addplot (\x,\x^3);
+ \end{axis}
+ \end{tikzpicture}
+ \endpgfgraphicnamed
+ \caption{A second graphics}
+ \end{figure}
+\end{document}
+\end{codeexample}
+\noindent The file is named |test.tex|, and it is processed (for example) with
+\begin{codeexample}[code only]
+pdflatex test
+\end{codeexample}
+\noindent Now, we type
+\begin{codeexample}[code only]
+pdflatex --jobname testfigure test
+pdflatex --jobname testfigure2 test
+\end{codeexample}
+\noindent to enter conversion mode. These last calls will \emph{only} write the contents of our named graphics environments, one for \marg{testfigure} and one for \marg{testfigure2} into the respective output files |testfigure.pdf| and |testfigure2.pdf|.
+
+In summary, one needs |\pgfrealjobname| and calls |pdflatex --jobname |\marg{graphics file} for every externalized graphics environment. Please note that it is absolutely necessary to use the syntax above, \emph{not} |\begin{pgfgraphicnamed}|.
+
+These steps are explained in much more detail in Section``Externalizing Graphics'' of~\cite{tikz}. This reference also contains information about how to typeset such a document without \pgfname\ installed.
+
+I once attempted to write a unix \texttt{bash}--script |pgf2pdf.sh| which simplifies these steps in case that every externalized graphics environment is placed into a separate file |.pgf|. Interested readers find it in the installation tree.
+
+\paragraph{Attention:} Do not forget a correct |\pgfrealjobname| statement! If it is missing, externalization simply won't work. If it is wrong, any call to \LaTeX\ will produce empty output files.
+
+\subsubsection{Using the automatic Externalization framework of \Tikz}
+It is also possible to externalize graphics with the high-level library
+
+|\usetikzlibrary{external}|
+
+\noindent which comes with (recent versions of) \Tikz\footnote{At the time of this writing, it is only available in the CVS~$2.0$ version of \pgfname, sorry.}. It is a front-end for |\beginpgfgraphicnamed| which automatically encapsulates every picture in your document with the required externalization commands and performs commands to generate all required graphics files.
+\begin{enumerate}
+ \item Every |\begin{tikzpicture}| $\dotsc$ |\end{tikzpicture}| gets a file name. The file name can be assigned manually with |\tikzsetnextfilename|\marg{output file name} or automatically, in which case \meta{tex file name}|-figure|\meta{number} is used with an increasing \meta{number}.
+
+ \item The library issues the required calls to |pdflatex --jobname |\marg{output file name} automatically, using the write18 system call of \TeX. It is the same framework which can be used to call |gnuplot|.
+\end{enumerate}
+The only steps which are necessary is to use
+
+|\tikzexternalize|\marg{the job's real file name}
+
+\noindent as above. No further modification to the document is necessary. Now, the example file |test.tex| of the last subsection reads as follows:
+\begin{codeexample}[code only]
+\documentclass{article}
+
+\usepackage{pgfplots}
+
+\usetikzlibrary{external}
+\tikzexternalize{test}
+
+\begin{document}
+ \begin{figure}
+ \begin{tikzpicture}
+ \begin{axis}
+ \addplot (\x,\x^2);
+ \end{axis}
+ \end{tikzpicture}
+ \caption{Our first external graphics example}
+ \end{figure}
+
+ \begin{figure}
+ \begin{tikzpicture}
+ \begin{axis}
+ \addplot (\x,\x^3);
+ \end{axis}
+ \end{tikzpicture}
+ \caption{A second graphics}
+ \end{figure}
+\end{document}
+\end{codeexample}
+\noindent To enable the system calls, we type
+\begin{codeexample}[code only]
+pdflatex --shell-escape test
+\end{codeexample}
+\noindent and \LaTeX\ will now generate the required graphics files |test-figure0.pdf| and |test-figure1.pdf| automatically.
+
+The command |\tikzset{external/force remake}| somewhere in the document can be used to remake every following picture automatically. Of course, it is also possible to simply delete every graphics file.
+
+The library can also be configured to produce a list of figures in case system calls are undesired (or unavailable). In that case, |pdflatex --jobname |\marg{output file name} needs to be invoked for every file name listed in \meta{real file name}|.figlist|. This step can be done within a script.
+
+The command |\tikzsetexternalprefix|\marg{file prefix} can be used to prepend a directory name to every figure, for example with
+\begin{codeexample}[code only]
+\tikzsetexternalprefix{figures/}
+\end{codeexample}
+\noindent to produce |figures/test-figure0.pdf| and |figures/test-figure1.pdf| in our example.
+
+The complete reference documentation and remaining options are documented in the documentation for the ``PDF externalization library'' of~\cite{tikz}. This reference also contains information about how to typeset such a document without \pgfname\ installed.
\subsection{matlab2pgfplots.m}
This is a matlab (tm) script which attempts to convert a matlab figure to \PGFPlots.