1 files changed, 60 insertions, 18 deletions
diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.preliminaryoptions.tex b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.preliminaryoptions.tex
index 7dded72cd83..a1f759a732b 100644
--- a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.preliminaryoptions.tex
+++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.preliminaryoptions.tex
@@ -1,44 +1,86 @@
 
 \subsection{About Options: Preliminaries}
-\PGFPlots\ knowns a whole lot of key--value options which can be (re-)defined to activate desired features or modified to apply some fine tuning.
+\PGFPlots\ knows a whole lot of key--value options which can be (re)defined to activate desired features or modified to apply some fine-tuning.
+
+A key usually has a value (like a number, a string, or perhaps some macro code). You can assign values to keys (``set keys'') in many places in a \LaTeX\ document. The value will remain effective until it is changed or until the current \TeX\ scope ends (which happens after a closing curly brace `|}|', after |\end|\marg{name} or, for example, after |\addplot|).
 
 \noindent Most keys can be used like
 \begin{codeexample}[code only]
 \begin{tikzpicture}
-\begin{axis}[key=value,key2=value2]
+\begin{axis}[key=value,key2=value2] % axis-wide keys
 ...
 \end{axis}
 \end{tikzpicture}
 \end{codeexample}
-\noindent which changes them for the complete axis. A |key| in this context can be any option defined in this manual, no matter if it has the |/pgfplots/| or the |/tikz/| key prefix. Note that key prefixes can be omitted in almost all cases.
+\noindent which changes them for the complete axis. A |key| in this context can be any option defined in this manual, no matter if it has the |/pgfplots/| or the |/tikz/| key prefix. Note that key prefixes can be omitted in almost all cases. 
+
+A value can usually be provided without curly braces. For example, if the manual contains somethig like `|xmin=|\marg{$x$ coordinate}', you can safely skip the curly braces. The curly braces are mandatory if values contain something which would otherwise confuse the key setup (for example an equal sign `|=|' or a comma `|,|').
 
 Some keys can be changed individually for each plot:
 \begin{codeexample}[code only]
 \begin{tikzpicture}
 \begin{axis}
-\addplot[key=value,key2=value2] ... ;
-\addplot+[key=value,key2=value2] ... ; % keeps the keys which would have been used by default
+% keys valid for single plots:
+\addplot ...;                          % uses the "cycle list" to determine keys
+\addplot[key=value,key2=value2] ... ;  % uses the provided keys (not the "cycle list")
+\addplot+[key=value,key2=value2] ... ; % appends something to the "cycle list"
 \end{axis}
 \end{tikzpicture}
 \end{codeexample}
 
-The basic engine to manage key--value pairs is |pgfkeys| which is part of \pgfname. This engine always has a key name and a key ``path'', which is somehow similar to file name and directory of files. The common ``directory'' (key path) of \PGFPlots\ is `|/pgfplots/|'. Although the key definitions below provide this full path, it is always (well, almost always) enough to skip this prefix -- \PGFPlots\ uses it automatically. The same holds for the prefixes `|/tikz/|' which are common for all \Tikz\ drawing options and `|/pgf/|' which are for the (more or less) low--level commands of \pgfname. All these prefixes can be omitted.
+Besides these two possibilities, it is also possible to work with document-wide keys:
+\begin{codeexample}[code only]
+\section{My Section}
+\pgfplotsset{
+	key=value,
+	key2=value2,
+}
+This section has a common key configuration:
+\begin{tikzpicture}
+	\begin{axis}% uses the key config from above
+	... 
+	\end{axis}
+\end{tikzpicture}
+\end{codeexample}
+\noindent In the example above, the |\pgfplotsset| command changes keys. The changes are permanent and will be used until 
+\begin{itemize}
+	\item you redefine them or
+	\item the current environment (like |\end{figure}|) is ended or
+	\item \TeX\ encounters a closing brace `|}|'.
+\end{itemize}
+This includes document--wide preamble configurations like
+\begin{codeexample}[code only]
+\documentclass{article}
 
-One important concept is the concept of styles. A style is a key which contains one or more other keys. It can be redefined or modified until it is actually used by the internal routines. Each single component of \Tikz\ and \PGFPlots\ can be configured with styles.
+\usepackage{pgfplots}
+\pgfplotsset{
+	xticklabel={$\mathsf{\pgfmathprintnumber{\tick}}$},
+	every axis/.append style={
+		font=\sffamily,
+	},
+}
+...
+\end{codeexample}
+
+The basic engine to manage key--value pairs is |pgfkeys| which is part of \pgfname. This engine always has a key name and a key ``path'', which is somehow similar to file name and directory of files. The common ``directory'' (key path) of \PGFPlots\ is `|/pgfplots/|'. Although the key definitions below provide this full path, it is always (well, almost always) safe to skip this prefix -- \PGFPlots\ uses it automatically. The same holds for the prefixes `|/tikz/|' which are common for all \Tikz\ drawing options and `|/pgf/|' which are for the (more or less) low--level commands of \pgfname. All these prefixes can be omitted.
+
+One important concept is the concept of \emph{styles}. A style is a key which contains one or more other keys. It can be redefined or modified until it is actually used by the internal routines. Each single component of \Tikz\ and \PGFPlots\ can be configured with styles.
 
 For example,
 \begin{codeexample}[code only]
-\pgfplotsset{every axis/.append style={line width=1pt}}
+\pgfplotsset{legend style={line width=1pt}}
 \end{codeexample}
 \noindent
-sets the line width for every axis to |1pt|. 
+sets the line width for every legend to |1pt| by appending `|line width=1pt|' to the existing style for legends. 
+
+There are keys like |legend style|, |ticklabel style|, and |label style| which allow to modify the predefined styles (in this case the styles for legends, ticklabels and axis labels, respectively). They are, in general, equivalent to a \meta{style name}|/.append style={}| command (the only difference is that the |/.append style| thing is a little bit longer). There is also the possibility to define a new style (or to overwrite an already existing one) using |/.style={}|.
 
-There are several other styles predefined to modify the appearance, see section~\ref{sec:styles}.
+There are several other styles predefined to modify the appearance, see Section~\ref{sec:styles}.
 
 \begin{command}{\pgfplotsset\marg{key-value-list}}
-	Defines or sets all options in \marg{key-value-list}. The \meta{key-value-list} can contain any of the options in this manual which have the prefix |/pgfplots/| (you do not need to type the prefix).
+	Defines or sets all options in \meta{key-value-list}. The \meta{key-value-list} can contain any of the options in this manual which have the prefix |/pgfplots/| (however, you do not need to type that prefix).
 	
-	It is a shortcut for |\pgfqkeys{/pgfplots}|\marg{key-value-list}, that means it inserts the prefix |/pgfplots| to any option which has no full path.
+	Inside of \meta{key-value-list}, the prefixes `|/pgfplots/|' which are commonly presented in this manual can be omitted (they are checked automatically).
 
 	This command can be used to define default options for the complete document or a part of the document. For example, 
 \begin{codeexample}[code only]
@@ -62,7 +104,7 @@ There are several other styles predefined to modify the appearance, see section~
 	xlabel=$x$,ylabel=$f(x)$
 }
 \end{codeexample}
-	can be used to set document--wise styles for line specifications, the legend's style and axis labels.
+	can be used to set document-wise styles for line specifications, the legends' style and axis labels. The settings remain in effect until the end of the current environment (like |\end{figure}|) or until you redefine them or until the next closing curly brace `|}|' (whatever comes first).
 
 	You can also define new styles (collections of key--value--pairs) with |/.style| and |/.append style|.
 \begin{codeexample}[code only]
@@ -71,11 +113,11 @@ There are several other styles predefined to modify the appearance, see section~
 	My Style 2/.style={xlabel=$X$, legend entries={4,5,6} }
 }
 \end{codeexample}
-	The |/.style| and |/.append style| key handlers are described in section~\ref{sec:styles} in more detail.
+	The |/.style| and |/.append style| key handlers are described in Section~\ref{sec:styles} in more detail.
 \end{command}
 
 \begin{handler}{{.code}=\marg{\TeX\ code}}
-	Occasionally, the \PGFPlots\ user interface offers to replace parts of its routines. This is accomplished using so called ``code keys''. What it means is to replace the original key and its behavior with new \marg{\TeX\ code}. Inside of \marg{\TeX\ code}, any command can be used. Furthermore, the |#1| pattern will be the argument provided to the key.
+	Occasionally, the \PGFPlots\ user interface offers to replace parts of its routines. This is accomplished using so called ``code keys''. What it means is to replace the original key and its behavior with new \meta{\TeX\ code}. Inside of \meta{\TeX\ code}, any command can be used. Furthermore, the |#1| pattern will be the argument provided to the key.
 
 \begin{codeexample}[]
 \pgfplotsset{
@@ -92,10 +134,10 @@ There are several other styles predefined to modify the appearance, see section~
 \begin{handler}{{.cd}}
 	Each key has a fully qualified name with a (long) prefix, like |/pgfplots/xmin|. However, if the ``current directory'' is |/pgfplots|, it suffices to write just |xmin|. The |/.cd| key handler changes the ``current directory'' in this way.
 
-	The prefixes |/tikz/| and |/pgfplots/| are checked automatically for any argument provided to |\begin{axis}|\oarg{options}  or |\addplot|. So, you won't need to worry about them, just leave them away -- and look closer in case the package doesn't identify the option.
+	The prefixes |/tikz/| and |/pgfplots/| are checked automatically for any argument provided to |\begin{axis}|\oarg{options}  or |\addplot|. So, you won't need to worry about them, just omit them -- and look closer in case the package doesn't identify the option.
 \end{handler}
 
-\subsubsection{Pgfplots Options and \Tikz\ Options}
+\subsubsection{\textsc{Pgfplots} and \Tikz\ Options}
 This section is more or less technical and can be skipped unless one really wants to know more about this topic.
 
 \Tikz\ options and \PGFPlots\ options can be mixed inside of the axis arguments and in any of the associated styles. For example,
@@ -106,7 +148,7 @@ This section is more or less technical and can be skipped unless one really want
 \noindent
 assigns the `|legend columns|' option (a \PGFPlots\ option) and uses `|font|' for drawing the legend (a \Tikz\ option). The point is: |legend columns| needs to be known \emph{before} the legend is typeset whereas |font| needs to be active when the legend is typeset. \PGFPlots\ sorts out any key dependencies automatically:
 
-The axis environments will process any known \PGFPlots\ options, and all `|every|'--styles will be parsed for \PGFPlots\ options. Every unknown option is supposed to be a \Tikz\ option and will be forward to the associated \Tikz\ drawing commands. For example, the `|font=\Large|' above will be used as argument to the legend matrix, and the `|font=\Large|' argument in 
+The axis environments will process any known \PGFPlots\ options, and all `|every|'--styles will be parsed for \PGFPlots\ options. Every unknown option is assumed to be a \Tikz\ option and will be forwarded to the associated \Tikz\ drawing commands. For example, the `|font=\Large|' above will be used as argument to the legend matrix, and the `|font=\Large|' argument in 
 \begin{codeexample}[code only]
 \pgfplotsset{every axis label/.append style={
 	ylabel=Error,xlabel=Dof,font=\Large}}