1 files changed, 9 insertions, 3 deletions

diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.markers-meta.tex b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.markers-meta.tex
index a587e61b55f..c2c4ecc4048 100644
--- a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.markers-meta.tex
+++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.markers-meta.tex
@@ -1307,11 +1307,17 @@ In this case, the \emph{last} entry also needs a terminating `|\\|', but one can
 
 \subsection{Providing Color Data - Point Meta}
 \label{pgfplots:point:meta}
-\PGFPlots\ provides features which modify plots depending on a special coordinate, the ``point meta data''. For example, scatter plots may vary marker colors, size or appearance depending on this special data. Surface and mesh plots are another example: here, the color of a surface patch (or mesh part) depends on ``point meta''.
+\PGFPlots\ provides features which modify plots depending on a special coordinate, the ``point meta data''. For example, scatter plots may vary marker colors, size or appearance depending on this special data. Surface and mesh plots are another example: here, the color of a surface patch (or mesh part) depends on ``point meta''. The ``meta data'' of a node is not the position (which is given as $(x,y)$ or $(x,y,z)$). It is ``some information'' about that node; you could say: it is a specific property of the node. This is commonly called ``meta data''. 
 
-The common idea idea is to tell \PGFPlots\ how to get this data. It is not necessary to provide data explicitly -- in many cases, the data which is used to color surface patches or marker colors is the plot's $y$ or $z$ coordinate. The method used to tell \PGFPlots\ where to find ``point meta data'' is the |point meta| key. 
+In \PGFPlots, every node has its coordinate \emph{and} its meta data. Thus, two--dimensional plots have three values: $x$, $y$, and the |point meta| data. Three--dimensional plots have four values for each coordinate: $x$, $y$, $z$, and the |point meta|. 
 
-A further common idea is the use of color maps: if the point meta data is in the interval $[m_{\text{min}},m_{\text{max}}]$, the point meta coordinate $m = m_{\text{min}}$ will get the lowest color provided by the color map while $m=m_{\text{max}}$ will get the highest color provided by the color map. Any coordinate between this values will be mapped linearly: for example, the mean $m = 1/2 (m_{\text{max}} + m_{\text{min}})$ will get the middle color of the color map. This is why ``point meta'' is sometimes called ``color data''.
+In many cases, |point meta| is interpreted to be color data. To be more precise: it is interpreted to be \emph{scalar} color data which is mapped into the |colormap| (more about this approach in the next paragraphs). However, |point meta| can be anything. Often, it is a single number as in the case of color data. That number is mapped linearly to the interval $[0,1000]$ such that $0$ corresponds to the smallest encountered value and $1000$ corresponds to the largest encountered scalar value. The mapped value is available as |\pgfplotspointmetatransformed|. This special value allows to define some property of the plot: it can be the color (together with |colormap|). It can also be the |line width| in a |mesh| plot (more precisely: the |line width| could be defined to depend on the transformed meta data). The value can also be used to define |mark size|. However, |point meta| data does not necessarily need to be a number. It can be a text label (any text that you like). This is used by |nodes near coords|, for example. It could also contain a tuple like RGB color information (which is not commonly used, however). Thus, |point meta| is really some abstract information about individual coordinates.
+
+Note that there is only \emph{one} |point meta| per point. See the key |visualization depends on| if you need more than one meta data value per coordinate. 
+
+The common idea idea is to tell \PGFPlots\ how to get the meta data. It is not necessary to provide data explicitly -- in many cases, the data which is used to color surface patches or marker colors is the plot's $y$ or $z$ coordinate. The method used to tell \PGFPlots\ where to find ``point meta data'' is the |point meta| key. 
+
+The most common use-case of |point meta| is color information: if the point meta data is in the interval $[m_{\text{min}},m_{\text{max}}]$, the point meta coordinate $m = m_{\text{min}}$ will get the lowest color provided by the color map while $m=m_{\text{max}}$ will get the highest color provided by the color map. As already mentioned, this is accomplished using |\pgfplotspointmetatransformed| $\in [0,1000]$ (per convention). Any coordinate between the smallest and largest values will be mapped linearly: for example, the mean $m = 1/2 (m_{\text{max}} + m_{\text{min}})$ will get the middle color of the color map (it will have |\pgfplotspointmetatransformed| $=500$). This is why ``point meta'' is sometimes called ``color data'' in this manual.
 
 \begin{codeexample}[]
 \begin{tikzpicture}