diff options
Diffstat (limited to 'Master/texmf-dist/doc/latex/pgfplots/pgfplots.preliminaries.tex')
-rw-r--r-- | Master/texmf-dist/doc/latex/pgfplots/pgfplots.preliminaries.tex | 148 |
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. + |