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
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
|
% 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. 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 configure the Mik\TeX\ Package Manager to use this specific directory with higher priority than its default paths. If you want to do this, start the Mik\TeX\ Settings using ``Start $\gg$ Programs $\gg$ Mik\TeX\ $\gg$ Settings''. There, use the ``Roots'' menu section. It contains the Mik\TeX\ Package directory as initial configuration. Use ``Add'' to select the directory in which the unzipped \PGFPlots\ tree resides. Then, move the newly added path to the list's top using the ``Up'' button. Then press ``Ok''. For Mik\TeX\ 2.8, you may need to uncheck the ``Show Mik\TeX-maintained root directories'' button to see the newly installed path.
Mik\TeX\ complains if the provided directory is not TDS conform (see Section~\ref{pgfplots:tds} for details), so you can't provide a wrong directory here. This method does also work for other packages, but some packages may need some directory restructuring before Mik\TeX\ accepts them.
\subsubsection{Installation of Linux Packages}
At the time of this writing, I am unaware of \PGFPlots\ packages for recent stable Linux distributions. For Ubuntu, there are unofficial Ubuntu Package Repositories which can be added to the Ubuntu Package Tools. The idea is: add a simple URL to the Ubuntu Package Tool, run update and the installation takes place automatically. These URLs are maintained as PPA on Ubuntu Servers.
The \PGFPlots\ download area on sourceforge contains recent links about Ubuntu Package Repositories, go to
\url{http://sourceforge.net/projects/pgfplots/files}
and download the readme files with recent links.
\subsubsection{Installation in Any Directory - the \texttt{TEXINPUTS} Variable}
You can simply install \PGFPlots\ anywhere on your harddrive, 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 TDS Compliant \texttt{texmf}-Directory}
\label{pgfplots:tds}
\PGFPlots\ comes in a ``\TeX\ Directory Structure'' (TDS) conforming directory structure, so you can simply unpack the files into a directory which is searched by \TeX\ automatically. Such directories are |~/texmf| on Linux systems, for example.
Copy \PGFPlots\ to a local \texttt{texmf} directory like \lstinline!~/texmf!. You need at least the \PGFPlots\ directories |tex/generic/pgfplots| and |tex/latex/pgfplots|. Then, run \lstinline!texhash! (or some equivalent path-updating command specific to your \TeX\ distribution).
The TDS consists of several sub directories which are searched separately, depending on what has been requested: the sub directories |doc/latex/|\meta{package} are used for (\LaTeX) documentation, the sub-directories |doc/generic/|\meta{package} for documentation which apply to \LaTeX\ and other \TeX\ dialects (like plain \TeX\ and Con\TeX t which have their own, respective sub-directories) as well.
Similarly, the |tex/latex/|\meta{package} sub-directories are searched whenever \LaTeX\ packages are requested. The |tex/generic/|\meta{package} sub-directories are searched for packages which work for \LaTeX\ \emph{and} other \TeX\ dialects.
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 (perhaps all |.def| files as well) into your current project's working directory. In fact, you need everything which is in the |tex/latex/pgfplots| and |tex/generic/pgfplots| sub directories.
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.
I guess I can't help here: you may need to prepare the data somehow before \PGFPlots\ processes it.
\item This may happen as well if you only view a very small portion of the data range.
This happens, for example, if your input data ranges from $x\in [0,10^6]$, and you say |xmax=10|.
Consider using the |restrict x to domain*=|\meta{min}|:|\meta{max} key in such a case, where the \meta{min} and \meta{max} should be (say) four times of your axis limits (see page~\pageref{key:restrict:x:to:domain} for details).
\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.
Then, the DVI/pdf combination doesn't support all types of shadings (for example, the |shader=interp| is only available for |dvips| and |pdftex| drivers).
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 explicitly.
\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 active characters -- which may lead to incompatibilities 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 read the mailing list at
\url{http://sourceforge.net/projects/pgfplots/support}.
\noindent Perhaps someone has also encountered your problem before, and maybe he came up with a solution.
Please write a note on the mailing list if you have a different problem. In case it is necessary to contact the authors directly, consider the addresses shown on the title page of this document.
|
