1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
|
% main=manual.tex
\subsection{Installation and Prerequisites}
\subsubsection{Licensing}
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
A copy of the GNU General Public License can be found in the package file
\begin{verbatim}
doc/latex/pgfplots/gpl-3.0.txt
\end{verbatim}
You may also visit~\url{http://www.gnu.org/licenses}.
\subsubsection{Prerequisites}
\PGFPlots\ requires \PGF\ with \textbf{at least version~$2.0$}. It is used with
\begin{verbatim}
\usepackage{pgfplots}
\end{verbatim}
in your preamble (see section~\ref{sec:tex:dialects} for information about how to use it with Con{\TeX}t and plain \TeX).
%\subsubsection{Installation}
There are several ways how to teach \TeX\ where to find the files. Choose the option which fits your needs best.
\subsubsection{Installation in Windows}
Windows users often use Mik\TeX\ which downloads the latest stable package versions automatically. As far as I know, you do not need to install anything manually here. However, Mik\TeX\ provides a feature to install packages locally in its own \TeX-Directory-Structure (TDS). This is the preferred way if you like to install newer version than those of Mik\TeX. The basic idea is to unzip \PGFPlots\ in a directory of your choice and use configure the Mik\TeX\ Package Manager to use this specific directory with higher priority than its default paths.
See also section~\ref{pgfplots:tds} for more information about separate TDS directories.
\subsubsection{Installation in Any Directory - the \texttt{TEXINPUTS} Variable}
You can simply install \PGFPlots\ anywhere on your disc, for example into
\begin{verbatim}
/foo/bar/pgfplots.
\end{verbatim}
Then, you set the \texttt{TEXINPUTS} variable to
\begin{verbatim}
TEXINPUTS=/foo/bar/pgfplots//:
\end{verbatim}
The trailing~`\texttt{:}' tells \TeX\ to check the default search paths after \lstinline!/foo/bar/pgfplots!. The double slash~`\texttt{//}' tells \TeX\ to search all subdirectories.
If the \texttt{TEXINPUTS} variable already contains something, you can append the line above to the existing \texttt{TEXINPUTS} content.
Furthermore, you should set |TEXDOCS| as well,
\begin{verbatim}
TEXDOCS=/foo/bar/pgfplots//:
\end{verbatim}
so that the \TeX-documentation system finds the files |pgfplots.pdf| and |pgfplotstable.pdf| (on some systems, it is then enough to use |texdoc pgfplots|).
Please refer to your operating systems manual for how to set environment variables.
\subsubsection{Installation Into a Local \texttt{texmf}-Directory}
Copy \PGFPlots\ to a local \texttt{texmf} directory like \lstinline!~/texmf! in your home directory. Then, install \PGFPlots\ into the subdirectory \lstinline!texmf/tex/generic/pgfplots! and run \lstinline!texhash!.
\subsubsection{Installation Into a Local TDS Compliant \texttt{texmf}-Directory}
\label{pgfplots:tds}
A TDS conforming installation will use the same base directory as in the last section. Since \PGFPlots\ comes in TDS conforming directory structure, you can simply unpack the files into a directory of your choice and configure \TeX\ to use this directory as further include path.
Do not forget to run \lstinline!texhash!.
\subsubsection{Installation If Everything Else Fails...}
If \TeX\ still doesn't find your files, you can copy all \lstinline!.sty! and all |.code.tex|-files into your current project's working directory.
Please refer to \url{http://www.ctan.org/installationadvice/} for more information about package installation.
\subsection{Troubleshooting -- Error Messages}
This section discusses some problems which may occur when using \PGFPlots.
Some of the error messages are shown in the index, take a look at the end of this manual (under ``Errors'').
\subsubsection{Problems with available Dimen-registers}
To avoid problems with the many required \TeX-registers for \PGF\ and \PGFPlots, you may want to include
\begin{verbatim}
\usepackage{etex}
\end{verbatim}
as first package. This avoids problems with ``no room for a new dimen''
\index{Error Messages!No room for a new dimen}%
in most cases. It should work with any modern installation of \TeX\ (it activates the e-\TeX\ extensions).
\subsubsection{Dimension Too Large Errors}
The core mathematical engine of \PGF\ relies on \TeX\ registers to perform fast arithmetics. To compute $50+299$, it actually computes |50pt+299pt| and strips the |pt| suffix of the result. Since \TeX\ registers can only contain numbers up to $\pm 16384$, overflow error messages like ``Dimension too large'' occur if the result leaves the allowed range. Normally, this should never happen -- \PGFPlots\ uses a floating point unit with data range $\pm 10^{324}$ and performs all mappings automatically. However, there are some cases where this fails. Some of these cases are:
\begin{enumerate}
\item The axis range (for example, for $x$) becomes \emph{relatively} small. It's no matter if you have absolutely small ranges like $[10^{-17},10^{-16}]$. But if you have an axis range like $[1.99999999,2]$, where a lot of significant digits are necessary, this may be problematic.
\item The |axis equal| key will be confused if $x$ and $y$ have a very different scale.
\item You may have found a bug -- please contact the developers.
\end{enumerate}
\subsubsection{Restrictions for DVI-Viewers and \texttt{dvipdfm}}
\label{sec:drivers}%
\PGF\ is compatible with
\begin{itemize}
\item \lstinline!latex!/\lstinline!dvips!,
\item \lstinline!latex!/\lstinline!dvipdfm!,
\item \lstinline!pdflatex!,
\item $\vdots$
\end{itemize}
However, there are some restrictions: I don't know any DVI viewer which is capable of viewing the output of \PGF\ (and therefor \PGFPlots\ as well). After all, DVI has never been designed to draw something different than text and horizontal/vertical lines. You will need to view the postscript file or the pdf-file.
Furthermore, \PGF\ needs to know a \emph{driver} so that the DVI file can be converted to the desired output. Depending on your system, you need the following options:
\begin{itemize}
\item \lstinline!latex!/\lstinline!dvips! does not need anything special because \lstinline!dvips! is the default driver if you invoke \lstinline!latex!.
\item \lstinline!pdflatex! will also work directly because \lstinline!pdflatex! will be detected automatically.
\item \lstinline!latex!/\lstinline!dvipdfm! requires to use
\begin{verbatim}
\def\pgfsysdriver{pgfsys-dvipdfm.def}
%\def\pgfsysdriver{pgfsys-pdftex.def}
%\def\pgfsysdriver{pgfsys-dvips.def}
\usepackage{pgfplots}.
\end{verbatim}
The uncommented commands could be used to set other drivers explictly.
\end{itemize}
Please read the corresponding sections in~\cite[Section 7.2.1 and 7.2.2]{tikz} if you have further questions. These sections also contain limitations of particular drivers.
The choice which won't produce any problems at all is |pdflatex|.
\subsubsection{Problems with \TeX's Memory Capacities}
\PGFPlots\ can handle small up to medium sized plots. However, \TeX\ has never been designed for data plots -- you will eventually face the problem of small memory capacities. See section~\ref{sec:pgfplots:optimization} for how to enlarge them.
\subsubsection{Problems with Language Settings and Active Characters}
Both, \PGF\ and \PGFPlots\ use a lot of characters -- which may lead to incompatibilites with other packages which define active characters. Compatibility is better than in earlier versions, but may still be an issue. The manual compiles with the |babel| package for english and french, the |german| package does also work. If you experience any trouble, let me know. Sometimes it may work to disable active characters temporarily (|babel| provides such a command).
\subsubsection{Other Problems}
Please contact the authors (preferrably by mail). Visit the webpages shown above to get contact information.
|
