summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/pgfplots/pgfplots.preliminaries.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/latex/pgfplots/pgfplots.preliminaries.tex')
-rw-r--r--Master/texmf-dist/doc/latex/pgfplots/pgfplots.preliminaries.tex148
1 files changed, 148 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.preliminaries.tex b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.preliminaries.tex
new file mode 100644
index 00000000000..b3c7384d94c
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.preliminaries.tex
@@ -0,0 +1,148 @@
+\section[About PGFPlots: Preliminaries]{About {\normalfont\PGFPlots}: Preliminaries}
+This section contains information about upgrades, the team, the installation (in case you need to do it manually) and troubleshooting. You may skip it completely except for the upgrade remarks.
+
+\PGFPlots\ is built completely on \Tikz/\PGF. Knowledge of \Tikz\ will simplify the work with \PGFPlots, although it is not required.
+
+However, note that this library requires at least \PGF\ version $2.10$. At the time of this writing, many \TeX-distributions still contain the older \PGF\ version $1.18$, so it may be necessary to install a recent \PGF\ prior to using \PGFPlots.
+
+\subsection{Components}
+\PGFPlots\ comes with two components:
+\begin{enumerate}
+ \item the plotting component (which you are currently reading) and
+ \item the \PGFPlotstable\ component which simplifies number formatting and postprocessing of numerical tables. It comes as a separate package and has its own manual \href{file:pgfplotstable.pdf}{pgfplotstable.pdf}.
+\end{enumerate}
+
+\subsection{Upgrade remarks}
+This release provides a lot of improvements which can be found in all detail in \texttt{ChangeLog} for interested readers. However, some attention is useful with respect to the following changes.
+
+\subsubsection{New Optional Features}
+\PGFPlots\ has been written with backwards compatibility in mind: old \TeX\ files should compile without modifications and without changes in the appearance. However, new features occasionally lead to a different behavior. In such a case, \PGFPlots\ will deactivate the new feature\footnote{In case of broken backwards compatibility, we apologize -- and ask you to submit a bug report. We will take care of it.}.
+
+Any new features or bugfixes which cause backwards compatibility problems need to be activated \emph{manually} and \emph{explicitly}. In order to do so, you should use
+\begin{codeexample}[code only]
+\usepackage{pgfplots}
+\pgfplotsset{compat=1.6}
+\end{codeexample}
+\noindent in your preamble. This will configure the compatibility layer.
+
+You should have at least |compat=1.3|. The suggested value is printed to the |.log| file after running \TeX.
+
+Here is a list of changes introduced in recent versions of \PGFPlots:
+\begin{enumerate}
+ \item \PGFPlots\ 1.6 added new options for more accurate scaling and more scaling options for |\addplot3 graphics|. These are enabled with |compat=1.6| or higher.
+
+ \item \PGFPlots\ 1.5.1 interpretes circle- and ellipse radii as \PGFPlots\ coordinates (older versions used \pgfname\ unit vectors which have no direct relation to \PGFPlots). In other words: starting with version 1.5.1, it is possible to write |\draw circle[radius=5]| inside of an axis. This requires |\pgfplotsset{compat=1.5.1}| or higher.
+
+ Without this compatibility setting, circles and ellipses use low--level canvas units of \pgfname\ as in earlier versions.
+
+ \item \PGFPlots\ 1.5 uses |log origin=0| as default (which influences logarithmic bar plots or stacked logarithmic plots). Older versions keep |log origin=infty|. This requires |\pgfplotsset{compat=1.5}| or higher.
+
+ \item \PGFPlots\ 1.4 has fixed several smaller bugs which might produce differences of about $1$--$2\text{pt}$ compared to earlier releases. This requires |\pgfplotsset{compat=1.4}| or higher.
+
+ \item \PGFPlots\ 1.3 comes with user interface improvements. The technical distinction between ``behavior options'' and ``style options'' of older versions is no longer necessary (although still fully supported).
+
+ This is always activated.
+
+ \item \PGFPlots\ 1.3 has a new feature which allows to \emph{move axis labels tight to tick labels} automatically. This is strongly recommended. It requires |\pgfplotsset{compat=1.3}| or higher.
+
+ Since this affects the spacing, it is not enabled be default.
+
+ \item \PGFPlots\ 1.3 supports reversed axes. It is no longer necessary to use workarounds with negative units.
+\pgfkeys{/pdflinks/search key prefixes in/.add={/pgfplots/,}{}}
+
+ Take a look at the |x dir=reverse| key.
+
+ Existing workarounds will still function properly. Use |\pgfplotsset{compat=1.3}| or higher together with |x dir=reverse| to switch to the new version.
+\end{enumerate}
+
+\subsubsection{Old Features Which May Need Attention}
+\begin{enumerate}
+ \item The |scatter/classes| feature produces proper legends as of version 1.3. This may change the appearance of existing legends of plots with |scatter/classes|.
+
+ \item Starting with \PGFPlots\ $1.1$, |\tikzstyle| should \emph{no longer be used} to set \PGFPlots\ options.
+
+ Although |\tikzstyle| is still supported for some older \PGFPlots\ options, you should replace any occurance of |\tikzstyle| with |\pgfplotsset{|\meta{style name}|/.style={|\meta{key-value-list}|}}| or the associated |/.append style| variant. See Section~\ref{sec:styles} for more detail.
+\end{enumerate}
+I apologize for any inconvenience caused by these changes.
+
+\begin{pgfplotskey}{compat=\mchoice{1.6,1.5.1,1.5,1.4,1.3,pre 1.3,default} (initially default)}
+ The preamble configuration
+\begin{codeexample}[code only]
+\usepackage{pgfplots}
+\pgfplotsset{compat=1.6}
+\end{codeexample}
+ allows to choose between backwards compatibility and most recent features.
+
+ Occasionally, you might want to use different versions in the same document. Then, provide
+\begin{codeexample}[code only]
+\begin{figure}
+ \pgfplotsset{compat=1.4}
+ ...
+ \caption{...}
+\end{figure}
+\end{codeexample}
+ \noindent in order to restrict the compatibility setting to the actual context (in this case, the |figure| environment).
+
+ The the output of your |.log| file to see the suggested value for |compat|.
+
+ Use |\pgfplotsset{compat=default}| to restore the factory settings.
+
+ Although typically unnecessary, it is also possible to activate only selected changes and keep compatibility to older versions in general:
+ \begin{pgfplotskeylist}{%
+ compat/path replacement=\meta{version},%
+ compat/labels=\meta{version},%
+ compat/scaling=\meta{version},%
+ compat/scale mode=\meta{version},%
+ compat/empty line=\meta{version},%
+ compat/plot3graphics=\meta{version},%
+ compat/general=\meta{version}%
+ }
+ Let us assume that we have a document with |\pgfplotsset{compat=1.3}| and you want to keep it this way.
+
+ In addition, you realized that version 1.5.1 supports circles and ellipses. Then, use
+\begin{codeexample}[]
+% preamble:
+\pgfplotsset{compat=1.3,compat/path replacement=1.5.1}
+\begin{tikzpicture}
+\begin{axis}[
+ extra x ticks={-2,2},
+ extra y ticks={-2,2},
+ extra tick style={grid=major}]
+ \addplot {x};
+ \draw (axis cs:0,0) circle[radius=2];
+\end{axis}
+\end{tikzpicture}
+\end{codeexample}
+
+ All of these keys accept the possible values of the |compat| key.
+
+ The |compat/path replacement| key controls how radii of circles and ellipses are interpreted.
+
+ The |compat/labels| key controls how axis labels are aligned: either uses adjacent to ticks or with an absolute offset.
+
+ The |compat/scaling| key controls some bugfixes introduced in version 1.4 and 1.6: they might introduce slight scaling differences in order to improve the accuracy.
+
+ The |compat/plot3graphics| controls new features for |\addplot3 graphics|.
+
+ The |compat/scale mode| allows to enable/disable the warning ``The content of your 3d axis has CHANGED compared to previous versions'' because the |axis equal| and |unit vector ratio| features where broken for all versions before~1.6 and have been fixed in~1.6.
+
+ The |compat/empty line| allows to write empty lines into input files in order to generate a jump. This requires |compat=1.4| or newer. See |empty line| for details.
+
+ The |compat/general| key currently only activates |log origin|.
+
+ The detailed effects can be seen on the beginning of this section.
+ \end{pgfplotskeylist}
+
+ The value \meta{version} can be |default|, |pre 1.3|, |1.3|, |1.4|, |1.5|, |1.5.1|, |1.6|, and |newest|. The value |default| is the same as |pre 1.3| (up to insignificant changes). The use of |newest| is strongly \emph{discouraged}: it might cause changes in your document, depending on the current version of \PGFPlots. Please inspect your |.log| file to see suggestions for the best possible version.
+\end{pgfplotskey}
+
+\subsection{The Team}
+\PGFPlots\ has been written mainly by Christian Feuersänger with many improvements of Pascal Wolkotte and Nick Papior Andersen as a spare time project. We hope it is useful and provides valuable plots.
+
+If you are interested in writing something but don't know how, consider reading the auxiliary manual \href{file:TeX-programming-notes.pdf}{TeX-programming-notes.pdf} which comes with \PGFPlots. It is far from complete, but maybe it is a good starting point (at least for more literature).
+
+\subsection{Acknowledgements}
+I thank God for all hours of enjoyed programming. I thank Pascal Wolkotte and Nick Papior Andersen for their programming efforts and contributions as part of the development team. I thank J\"urnjakob Dugge for his contribution of |hist/density|, matlab scripts for \verbpdfref{\addplot3} |graphics|, excellent user forum help and helpful bug reports. I thank Stefan Tibus, who contributed the |plot shell| feature. I thank Tom Cashman for the contribution of the |reverse legend| feature. Special thanks go to Stefan Pinnow whose tests of \PGFPlots\ lead to numerous quality improvements. Furthermore, I thank Dr.~Schweitzer for many fruitful discussions and Dr.~Meine for his ideas and suggestions. Special thanks go to Markus B\"ohning for proof-reading all the manuals of \PGF, \PGFPlots, and \PGFPlotstable. Thanks as well to the many international contributors who provided feature requests or identified bugs or simply improvements of the manual!
+
+Last but not least, I thank Till Tantau and Mark Wibrow for their excellent graphics (and more) package \PGF\ and \Tikz, which is the base of \PGFPlots.
+