pgfplots 1.6.1 (29aug12)

git-svn-id: svn://tug.org/texlive/trunk@27550 c570f23f-e606-0410-a88d-b1316a301751
author: Karl Berry <karl@freefriends.org> 2012-08-30 00:13:50 +0000
committer: Karl Berry <karl@freefriends.org> 2012-08-30 00:13:50 +0000
commit: 8231318d57cff4a8f9fcd70d387a3f00f4513428 (patch)
tree: e99336aabe9de04bad055bcf07814a1a00474a38 /Master/texmf-dist/doc/latex/pgfplots
parent: c16497900d7216f5269a43b9c18ae469820d3cd2 (diff)
71 files changed, 2173 insertions, 982 deletions
diff --git a/Master/texmf-dist/doc/latex/pgfplots/ChangeLog b/Master/texmf-dist/doc/latex/pgfplots/ChangeLog
index 89b6d6e0e7b..66b35538d12 100644
--- a/Master/texmf-dist/doc/latex/pgfplots/ChangeLog
+++ b/Master/texmf-dist/doc/latex/pgfplots/ChangeLog
@@ -1,3 +1,141 @@
+2012-08-23 Christian Feuersaenger <ludewich@users.sourceforge.net>
+	- RELEASED 1.6.1
+
+2012-08-23 Christian Feuersaenger <ludewich@users.sourceforge.net>
+	- fixed incompatibility lualatex, shader=interp, and german package
+
+2012-08-22 Christian Feuersaenger <ludewich@users.sourceforge.net>
+	- RELEASED 1.6 on sourceforge (only)
+
+2012-08-16 Christian Feuersaenger <ludewich@users.sourceforge.net>
+	- fixed support for scopes inside of axes
+
+2012-07-15 Christian Feuersaenger <ludewich@users.sourceforge.net>
+	- fixed (re)scaling of view normal
+
+2012-07-03 Christian Feuersaenger <ludewich@users.sourceforge.net>
+	- fixed bug: 'nan' values in error bar values caused compilation errors.
+	Now, error bars for unbounded coordinates are skipped.
+
+2012-06-24 Christian Feuersaenger <ludewich@users.sourceforge.net>
+	- spent a considerably amount of attention to 'axis equal' in 3d:
+	it works correctly now and the underlying scaling algorithm is much more powerful.
+	This is backwards compatible with 2d axis equal (but not 3d as this was
+	plain wrong)
+
+2012-06-16 Christian Feuersaenger <ludewich@users.sourceforge.net>
+	- provided a suitable legend for quiver plots
+
+2012-06-10 Christian Feuersaenger <ludewich@users.sourceforge.net>
+	- added docs for tikz/mark phase
+
+2012-06-09 Christian Feuersaenger <ludewich@users.sourceforge.net>
+	- fixed bug: restrict y to domain did not work for log axes
+
+2012-05-18 Christian Feuersaenger <ludewich@users.sourceforge.net>
+	- fixed bug: extreme differences between point meta and point meta min/max
+	caused number range problems. The point meta data is now clipped to [0,1000]
+
+2012-05-06 Christian Feuersaenger <ludewich@users.sourceforge.net>
+	- fixed bug: create on use for error bar columns did not work
+	- fixed bug: view dir was rescaled incorrectly 
+	this is a regression; it was not in 1.5.1
+	- added feature 'hist/density' (thanks to Juernjakob Dugge for this contribution!)
+
+2012-05-01 Christian Feuersaenger <ludewich@users.sourceforge.net>
+	- fixed 'scale mode=scale uniformly': intermediate results needed to be computed by FPU
+	- fixed bug: 'colorbar style={ymode=log}' was not processed properly
+
+2012-04-27 Christian Feuersaenger <ludewich@users.sourceforge.net>
+	- 'scale mode=scale uniformly' now also respects user-provided data
+	limits (including \addplot3 graphics).
+	- fixed bug: reversed axes + explicitly provided x,y,z vectors did not
+	work properly in 3d (also affected \addplot3 graphics)
+
+--- the following lines are from a feature branch.
+2011-10-02 Christian Feuersaenger <ludewich@users.sourceforge.net>
+	- the 'clip=plots individually' has been renamed to 'clip mode=global|individual'
+	and 'clip mode=global' is the new default. It is, however, not
+	completely implemented for custom drawing commands
+	
+2011-10-01 Christian Feuersaenger <ludewich@users.sourceforge.net>
+	- fixed bug in recent version: the 'cell picture' was always active
+	- added support for 'set layers' inside of a pgfplots axis
+	- 'axis on top', together with 'activate layers', will now implicitly call 'set layers=axis on top'
+
+2011-09-18 Christian Feuersaenger <ludewich@users.sourceforge.net>
+	- rewrote layer support to be more compatible with pgf and added
+	systematic support for layers, including a useful default configuration
+
+2011-09-14 Christian Feuersaenger <ludewich@users.sourceforge.net>
+	- added feature 'cell picture=true|false|if necessary'
+
+2011-09-04 Christian Feuersaenger <ludewich@users.sourceforge.net>
+	- added feature 'clip=plots individually'
+
+2012-04-21 Christian Feuersaenger <ludewich@users.sourceforge.net>
+	- fixed bug: explicitly provided unit vectors + '* dir=reverse' did not work
+	- improved smith charts docs + provided more styles
+
+2012-04-04 Christian Feuersaenger <ludewich@users.sourceforge.net>
+	- fixed bug: lualatex and shader=interp have been incompatible.
+	I implemented proper binary encoding in lua.
+
+2012-04-02 Christian Feuersaenger <ludewich@users.sourceforge.net>
+	- fixed bug: 'linear regression/variance' key did only work if 'linear
+	regression/variance src' was active as well. Now, it works also without.
+
+2012-04-01 Christian Feuersaenger <ludewich@users.sourceforge.net>
+	- added 'contour/levels' key.
+
+2012-03-04 Christian Feuersaenger <ludewich@users.sourceforge.net>
+	- table package: improved and documented ways to suppress head rows
+
+2012-02-04 Christian Feuersaenger <ludewich@users.sourceforge.net>
+	- fixed bug: compatibility to PGF 2.00 was broken
+
+2012-01-22 Christian Feuersaenger <ludewich@users.sourceforge.net>
+	- fixed bug: fixed combination of transparency + shading in shader=interp
+
+2012-01-01 Christian Feuersaenger <ludewich@users.sourceforge.net>
+	- added support for 'mesh/interior colormap name,shader=interp'
+	it uses shader=faceted interp
+
+2011-10-03 Christian Feuersaenger <ludewich@users.sourceforge.net>
+	- fixed bug in 'mesh/interior colormap name': the data scaling trafo
+	was not respected correctly
+	- fixed bug in 'mesh/interior colormap name': z buffer reversals have not
+	been respected.
+
+2011-10-02 Christian Feuersaenger <ludewich@users.sourceforge.net>
+	- added 'mesh/interior colormap thresh'
+
+2011-09-28 Christian Feuersaenger <ludewich@users.sourceforge.net>
+	- renamed 'mesh/background colormap name' to 'mesh/interior colormap name'
+
+2011-09-28 Christian Feuersaenger <ludewich@users.sourceforge.net>
+	- fixed bug: there was a case were 'shader=faceted interp' was
+	unnecessarily converted to triangles 
+
+2011-09-27 Christian Feuersaenger <ludewich@users.sourceforge.net>
+	- fixed bug: the view direction was not scaled properly.
+
+2011-09-26 Christian Feuersaenger <ludewich@users.sourceforge.net>
+	- worked on 'mesh/background colormap name'. It works partially for
+	'disabledatascaling', although it reveals that the view direction is
+	imprecise.
+
+2011-09-26 Christian Feuersaenger <ludewich@users.sourceforge.net>
+	- fixed bug: 'patch to triangle' for rectangles produced inconsistently
+	oriented triangles
+
+2011-09-25 Christian Feuersaenger <ludewich@users.sourceforge.net>
+	- implemented draft for 'mesh/background colormap name'. 
+	I think it works, but it might be useless because the sampling methods do
+	not produce proper normal vectors.
+
+--- the following lines are from a feature branch.
+
 2011-12-29 Christian Feuersaenger <ludewich@users.sourceforge.net>
 	- RELEASED VERSION 1.5.1
 
diff --git a/Master/texmf-dist/doc/latex/pgfplots/Makefile b/Master/texmf-dist/doc/latex/pgfplots/Makefile
index 23e3e471e83..4f61e6ecb76 100644
--- a/Master/texmf-dist/doc/latex/pgfplots/Makefile
+++ b/Master/texmf-dist/doc/latex/pgfplots/Makefile
@@ -9,11 +9,16 @@ todo: pgfplotstodo.pdf
 pgfplots: pgfplots.pdf
 pgfplotstable: pgfplotstable.pdf
 
+# was: 
+# export TEXMFCNF=.:
+# but it seems as if that is ignored for some reason
+TEXMFCNF_FOR_MEMLIMITS=export TEXMFCNF=~/texmf/mytexcnf:
+
 include pgfplots.makefile
 
 %.pdf: FORCE
 	mkdir -p gnuplot
-	@export TEXMFCNF=.: && $(PDFLATEX) $(@:.pdf=.tex)
+	@$(TEXMFCNF_FOR_MEMLIMITS) && $(PDFLATEX) $(@:.pdf=.tex)
 	@bibtex $(@:.pdf=) || exit 0
 	@makeindex $(@:.pdf=) || exit 0
 	@echo ""
@@ -22,7 +27,7 @@ include pgfplots.makefile
 pgfplots.pdf: $(ALL_FIGURES)
 
 pgfplots.makefile:
-	@export TEXMFCNF=.: && $(PDFLATEX) pgfplots
+	@$(TEXMFCNF_FOR_MEMLIMITS) && $(PDFLATEX) pgfplots
 	
 clean:
 	rm -f *.aux *.ind *.idx *.toc *.out *.log *.ilg *.dvi pgfplots.makefile pgfplots.pdf pgfplotstable.pdf *.djs *.bbl *.blg figures/expensiveexample*
diff --git a/Master/texmf-dist/doc/latex/pgfplots/README b/Master/texmf-dist/doc/latex/pgfplots/README
new file mode 100644
index 00000000000..dc10b5637af
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/pgfplots/README
@@ -0,0 +1,167 @@
+pgfplots - Create normal/logarithmic plots in two and three dimensions for LaTeX/TeX/ConTeXt.
+
+pgfplotstable - Loads, rounds, formats and postprocesses numerical tables.
+
+PGFPlots draws high--quality function plots in normal or logarithmic scaling
+with a user-friendly interface directly in TeX. The user supplies axis labels,
+legend entries and the plot coordinates for one or more plots and PGFPlots
+applies axis scaling, computes any logarithms and axis ticks and draws the
+plots. It supports line plots, scatter plots, piecewise constant plots, bar
+plots, area plots, mesh-- and surface plots, patch plots, contour plots, quiver
+plots, histogram plots, polar axes, ternary diagrams, smith charts and some
+more.
+
+Pgfplots is based on Till Tantau's package PGF/TikZ (pgf).
+
+Pgfplotstable displays numerical tables rounded to desired precision in various
+display formats, for example scientific format, fixed point format or integer,
+using TeX's math facilities for pretty printing. Furthermore, it provides
+methods for table postprocessing.
+
+Please take a look at 
+  doc/latex/pgfplots/pgfplots.pdf
+and
+  doc/latex/pgfplots/pgfplotstable.pdf.
+
+
+REMARK
+The virus killer Avira Antivir reports the virus HTML/Malicious PDF.Gen in pgfplots.pdf. 
+This is a FALSE ALARM caused by the pgfplots library for interactive,
+clickable plots (based on javascript). It is virus-free.
+
+Copyright 2007-2011 by Christian Feuersaenger.
+
+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.
+
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+
+HISTORY:
+1.6.1:
+- fixed incompatibility lualatex,shader=interp, and german package (introduced in 1.6)
+
+1.6:
+- added support for layered graphics (main use case: multiple axes and layers)
+- added support for second colormap in mesh plots (mesh/interior colormap name)
+- added support for scopes inside of axes
+- contour plots: added ability to provide list of discrete labels (mesh/levels)
+- empty lines are interpreted as interruptions in data plots (was undocumented since 1.4)
+- added more scaling options to 'scale mode=scale uniformly' (affects axis equal in 3d
+  and \addplot3 graphics)
+- fixed wrong implementation of 'axis equal' and 'unit vector ratio' in 3d
+  (backwards compatible for 2d, but not for 3d - the 3d implementation was plain wrong)
+- fixed incompatibility of lualatex and shader=interp
+- fixed bugs/added features around \addplot3 graphics
+- fixed bug: colorbar did not support ymode=log
+- fixed a couple of minor bugs
+- fixed bounding box computation for clip=false,axis lines=none
+
+1.5.1:
+- more operations for FPU library (==, !=,<=,>=,?)
+- fixed bug in usage of decorations in \addplot
+- bugfix for contour prepared format=matlab
+- added 'const plot mark mid' and 'jump mark mid' plot handlers
+- nodes on a plot (\addplot ... node[pos=<fraction>] {};)
+- 'trim axis group left' and 'trim axis group right'
+- bugfixes for polar axes and log+stacked plots
+- added style 'log ticks with fixed point'
+- introduced patched tikz paths to simplify circles and ellipses within an axis
+- patchplots lib: patch type=polygon
+- some more bugfixes
+
+1.5:
+ - Contour plots,
+ - Histograms,
+ - Quiver plots,
+ - patch plots (library)
+      - Triangle Meshes
+      - Bilinear Elements
+      - Quadratic Triangles
+      - Biquadratic Quadrilaterals
+      - Coons Patches
+ - Discrete colorbars,
+ - Table sorting,
+ - Linear regression,
+ - Ternary diagrams,
+      - Tieline Plots
+ - Smith Charts
+ - Polar axes,
+ - Empty lines in input files result in interrupted plots,
+ - PDF user defined coordinate mouse popups
+ - CMYK colormaps and shadings,
+ - new markers and cycle lists
+ - access to axis limits,
+ - \addplot3 graphics: pgfplots draws an appropriate axis for a three-dimensional(!) external png graphics
+ - 3D axes: support to provide explicit unit vectors:
+ 	- explicit unit vectors
+	- explicit unit vectors which are uniformly rescaled to match width/height
+ - 3D axes: improved support for unit vector ratios
+ - improvements of the groupplot styles
+ - preliminary support for (2d) bar plots in 3d axes
+ - new shader 'faceted interp'
+ - table package: 
+ 	- 'every nth row' style
+	- 'comment chars' key to define comment characters in input files
+	- 'skip first n' style
+ - lots of smaller bugfixes (see ChangeLog for details)
+
+
+1.4.1:
+- improved compatibility to gnuplot 4.4
+
+1.4:
+Version 1.4 contains several new features, mostly work on details.
+It fixes many bugs and provides the following improvements:
+- detached legends 
+- detached colorbars
+- ybar (and similar plots) can now be mixed with other plot types 
+  like line plots.
+- improved legend formatting
+- added 'restrict x to domain*' which cups coordinates outside of a specified domain (same for y and z)
+- Added support for linear regression
+- Inline tables,
+- Lots of bug fixes
+
+The next version will make a greater step when it is stable.
+
+
+1.3.1:
+Version 1.3.1 is a bugfix release containing
+- improved parametric plots with gnuplot
+- improved normalsize, small and footnotesize scale styles and added tiny
+- a lot of bugfixes
+
+1.3:
+- improvements for two dimensional visualization, among them
+	- axis equal,
+	- color bars,
+	- nodes near coords,
+	- jumps in plots,
+	- improved description positioning, 
+	- reverseable axis directions,
+	- simpler alignment of adjacent axes,
+	- units and a simplified user interface,
+- new three dimensional line, scatter, mesh and surface plots,
+- a copy of the automatic pdf externalization library, 
+- an improved manual enhanced with a lot of pdf cross references.
+
+1.2.2:
+- fixed a problem with the samples key, 
+- provides some smaller fixes and some manual improvements.
+- added plot graphics.
+
+1.2:
+- completely rewritten math expression parser with extended data range, 
+- colormaps for scatter plots
+- fine tuning for plot parameters.
+- table package has been extended and is now a fully featured table typesetting, computing and postprocessing tool.
+
diff --git a/Master/texmf-dist/doc/latex/pgfplots/TeX-programming-notes.pdf b/Master/texmf-dist/doc/latex/pgfplots/TeX-programming-notes.pdf
index bfa8b972ca6..29e9654abe4 100644
--- a/Master/texmf-dist/doc/latex/pgfplots/TeX-programming-notes.pdf
+++ b/Master/texmf-dist/doc/latex/pgfplots/TeX-programming-notes.pdf
diff --git a/Master/texmf-dist/doc/latex/pgfplots/bugtracker/minimal_0.pdf b/Master/texmf-dist/doc/latex/pgfplots/bugtracker/minimal_0.pdf
deleted file mode 100644
index acd73c30dbc..00000000000
--- a/Master/texmf-dist/doc/latex/pgfplots/bugtracker/minimal_0.pdf
+++ /dev/null
diff --git a/Master/texmf-dist/doc/latex/pgfplots/bugtracker/minimal_0.tex b/Master/texmf-dist/doc/latex/pgfplots/bugtracker/minimal_0.tex
deleted file mode 100644
index 7465efba4b0..00000000000
--- a/Master/texmf-dist/doc/latex/pgfplots/bugtracker/minimal_0.tex
+++ /dev/null
@@ -1,7 +0,0 @@
-
-\documentclass{article}
-
-\begin{document}
-Hallo Welt
-\end{document}
-
diff --git a/Master/texmf-dist/doc/latex/pgfplots/bugtracker/minimal_1.pdf b/Master/texmf-dist/doc/latex/pgfplots/bugtracker/minimal_1.pdf
deleted file mode 100644
index 3f75f3f8085..00000000000
--- a/Master/texmf-dist/doc/latex/pgfplots/bugtracker/minimal_1.pdf
+++ /dev/null
diff --git a/Master/texmf-dist/doc/latex/pgfplots/bugtracker/minimal_1.tex b/Master/texmf-dist/doc/latex/pgfplots/bugtracker/minimal_1.tex
deleted file mode 100644
index 15b4e0d7dfa..00000000000
--- a/Master/texmf-dist/doc/latex/pgfplots/bugtracker/minimal_1.tex
+++ /dev/null
@@ -1,144 +0,0 @@
-
-\documentclass[a4paper]{report}
-\usepackage{pgfplots}
-
-\pgfplotsset{compat=1.3}
-\begin{document}
-\begin{tikzpicture}
-  \begin{axis}[
-    xbar,
-    width=12cm,
-    height=3.5cm,
-    enlarge y limits=0.5,
-    xlabel={\#participants},
-    xmin=0,
-    symbolic y coords={no,yes},
-    ytick=data,
-    nodes near coords,
-    nodes near coords align={horizontal},
-    ]
-    \addplot coordinates {(3,no) (7,yes)};
-  \end{axis}
-\end{tikzpicture}
-
-\begin{tikzpicture}
-  \begin{axis}[
-    xbar,
-    width=12cm,
-    height=3.5cm,
-    enlarge y limits=0.5,
-    xlabel={\#participants},
-    symbolic y coords={no,yes},
-    ytick=data,
-    nodes near coords,
-    nodes near coords align={horizontal},
-    ]
-    \addplot coordinates {(1,no) (9,yes)};
-  \end{axis}
-\end{tikzpicture}
-
-\begin{tikzpicture}
-  \begin{axis}[
-    xbar,
-    width=12cm,
-    height=3.5cm,
-    enlarge y limits=0.5,
-    xlabel={\#participants},
-    xmin=0,
-    symbolic y coords={set A,set B},
-    ytick=data,
-    nodes near coords,
-    nodes near coords align={horizontal},
-    ]
-    \addplot coordinates {(6,set A) (4,set B)};
-  \end{axis}
-\end{tikzpicture}
-
-\begin{tikzpicture}
-  \begin{axis}[
-    ybar,
-    enlargelimits=0.15,
-    xlabel={\# of bananas},
-    ylabel={\#participants},
-    ytick={0,1,2,3},
-    ymin=0,
-    symbolic x coords={1,2,3,4,5,more},
-    nodes near coords,
-    ]
-    \addplot coordinates {(1,1) (2,1) (3,3) (4,2) (5,1) (more,2)};
-  \end{axis}
-\end{tikzpicture}
-
-\begin{tikzpicture}
-  \begin{axis}[
-    ybar stacked,
-    enlargelimits=0.15,
-    legend style={at={(0.5,-0.20)},
-      anchor=north,legend columns=-1},
-    ylabel={\#participants},
-    symbolic x coords={tool1, tool2, tool3, tool4, tool5, tool6, tool7},
-    xtick=data,
-    x tick label style={rotate=45,anchor=east},
-    ]
-    \addplot+[ybar] plot coordinates {(tool1,0) (tool2,2) (tool3,2) (tool4,3) (tool5,0) (tool6,2) (tool7,0)}; % never
-    \addplot+[ybar] plot coordinates {(tool1,0) (tool2,0) (tool3,0) (tool4,3) (tool5,1) (tool6,1) (tool7,0)}; % rarely
-    \addplot+[ybar] plot coordinates {(tool1,6) (tool2,6) (tool3,8) (tool4,2) (tool5,6) (tool6,5) (tool7,6)}; % sometimes
-    \addplot+[ybar] plot coordinates {(tool1,4) (tool2,2) (tool3,0) (tool4,2) (tool5,3) (tool6,2) (tool7,4)}; % often
-    \legend{never, rarely, sometimes, often}
-  \end{axis}
-\end{tikzpicture}
-
-\begin{tikzpicture}
-  \begin{axis}[
-    ybar,
-    enlargelimits=0.15,
-    legend style={at={(0.5,-0.15)},
-      anchor=north,legend columns=-1},
-    ylabel={\#participants},
-    symbolic x coords={tool8,tool9,tool10},
-    xtick=data,
-    nodes near coords,
-    nodes near coords align={vertical},
-    ]
-    \addplot coordinates {(tool8,7) (tool9,9) (tool10,4)};
-    \addplot coordinates {(tool8,4) (tool9,4) (tool10,4)};
-    \addplot coordinates {(tool8,1) (tool9,1) (tool10,1)};
-    \legend{used,understood,not understood}
-  \end{axis}
-\end{tikzpicture}
-
-\begin{tikzpicture}
-  \begin{axis}[
-    ybar,
-    enlargelimits=0.15,
-    legend style={at={(0.5,-0.2)},
-      anchor=north,legend columns=-1},
-    ylabel={\#participants},
-    symbolic x coords={excellent,good,neutral,not good,poor},
-    xtick=data,
-    nodes near coords,
-    nodes near coords align={vertical},
-    x tick label style={rotate=45,anchor=east},
-    ]
-    \addplot coordinates {(excellent,0) (good,8) (neutral,2) (not good,0) (poor,0)};
-  \end{axis}
-\end{tikzpicture}
-
-\begin{tikzpicture}
-  \begin{axis}[
-    ybar,
-    enlargelimits=0.15,
-    legend style={at={(0.5,-0.2)},
-      anchor=north,legend columns=-1},
-    ylabel={\#participants},
-    symbolic x coords={excellent,good,neutral,not good,poor},
-    xtick=data,
-    nodes near coords,
-    nodes near coords align={vertical},
-    x tick label style={rotate=45,anchor=east},
-    ]
-    \addplot coordinates { (excellent,0) (good,7) (neutral,3) (not good,0) (poor,0)};
-  \end{axis}
-\end{tikzpicture}
-\end{document}
-
diff --git a/Master/texmf-dist/doc/latex/pgfplots/bugtracker/minimal_10.pdf b/Master/texmf-dist/doc/latex/pgfplots/bugtracker/minimal_10.pdf
deleted file mode 100644
index cd081384d29..00000000000
--- a/Master/texmf-dist/doc/latex/pgfplots/bugtracker/minimal_10.pdf
+++ /dev/null
diff --git a/Master/texmf-dist/doc/latex/pgfplots/bugtracker/minimal_10.tex b/Master/texmf-dist/doc/latex/pgfplots/bugtracker/minimal_10.tex
deleted file mode 100644
index 3f11c01a719..00000000000
--- a/Master/texmf-dist/doc/latex/pgfplots/bugtracker/minimal_10.tex
+++ /dev/null
@@ -1,37 +0,0 @@
-
-\documentclass{article}
-\usepackage{pgfplots}
-\begin{document}
-\begin{tikzpicture}
-\begin{axis}[
-         small,
-         width=12cm,
-         height=1.8in,
-         ymin=0,
-		 ymax=10,
-         xmin=0,
-		 xmax=2,
-         ybar,
-         ymajorgrids=true,
-         yminorgrids=false,
-         minor y tick num=0,
-         ytick pos=left,
-         xtick pos=left,
-         ytick align=center,
-         yticklabel={$\pgfmathprintnumber{\tick}\%$},
-         xtick align=outside,
-         x tick style={},
-         xticklabel style={rotate=45,anchor=east,font=\scriptsize\sffamily},
-         extra y tick style={tick pos=right, ticklabel pos=right, grid
-style={thick,color=black}},
-         extra y ticks={6.25},
-         extra y tick labels={Extra Label},
-]
-
-%\addplot plot[error bars/.cd,y dir=plus,y explicit,x dir=none] table
-%[x=Index,y expr=100*\thisrow{AvgLocked},y error=Diff]{locked_tabbed.dat};
-
-\end{axis}
-\end{tikzpicture}
-\end{document}
-
diff --git a/Master/texmf-dist/doc/latex/pgfplots/bugtracker/minimal_11.pdf b/Master/texmf-dist/doc/latex/pgfplots/bugtracker/minimal_11.pdf
deleted file mode 100644
index 15c4213f18c..00000000000
--- a/Master/texmf-dist/doc/latex/pgfplots/bugtracker/minimal_11.pdf
+++ /dev/null
diff --git a/Master/texmf-dist/doc/latex/pgfplots/bugtracker/minimal_11.tex b/Master/texmf-dist/doc/latex/pgfplots/bugtracker/minimal_11.tex
deleted file mode 100644
index 3f11c01a719..00000000000
--- a/Master/texmf-dist/doc/latex/pgfplots/bugtracker/minimal_11.tex
+++ /dev/null
@@ -1,37 +0,0 @@
-
-\documentclass{article}
-\usepackage{pgfplots}
-\begin{document}
-\begin{tikzpicture}
-\begin{axis}[
-         small,
-         width=12cm,
-         height=1.8in,
-         ymin=0,
-		 ymax=10,
-         xmin=0,
-		 xmax=2,
-         ybar,
-         ymajorgrids=true,
-         yminorgrids=false,
-         minor y tick num=0,
-         ytick pos=left,
-         xtick pos=left,
-         ytick align=center,
-         yticklabel={$\pgfmathprintnumber{\tick}\%$},
-         xtick align=outside,
-         x tick style={},
-         xticklabel style={rotate=45,anchor=east,font=\scriptsize\sffamily},
-         extra y tick style={tick pos=right, ticklabel pos=right, grid
-style={thick,color=black}},
-         extra y ticks={6.25},
-         extra y tick labels={Extra Label},
-]
-
-%\addplot plot[error bars/.cd,y dir=plus,y explicit,x dir=none] table
-%[x=Index,y expr=100*\thisrow{AvgLocked},y error=Diff]{locked_tabbed.dat};
-
-\end{axis}
-\end{tikzpicture}
-\end{document}
-
diff --git a/Master/texmf-dist/doc/latex/pgfplots/bugtracker/minimal_12.pdf b/Master/texmf-dist/doc/latex/pgfplots/bugtracker/minimal_12.pdf
deleted file mode 100644
index 930337e8a49..00000000000
--- a/Master/texmf-dist/doc/latex/pgfplots/bugtracker/minimal_12.pdf
+++ /dev/null
diff --git a/Master/texmf-dist/doc/latex/pgfplots/bugtracker/minimal_12.tex b/Master/texmf-dist/doc/latex/pgfplots/bugtracker/minimal_12.tex
deleted file mode 100644
index 3f11c01a719..00000000000
--- a/Master/texmf-dist/doc/latex/pgfplots/bugtracker/minimal_12.tex
+++ /dev/null
@@ -1,37 +0,0 @@
-
-\documentclass{article}
-\usepackage{pgfplots}
-\begin{document}
-\begin{tikzpicture}
-\begin{axis}[
-         small,
-         width=12cm,
-         height=1.8in,
-         ymin=0,
-		 ymax=10,
-         xmin=0,
-		 xmax=2,
-         ybar,
-         ymajorgrids=true,
-         yminorgrids=false,
-         minor y tick num=0,
-         ytick pos=left,
-         xtick pos=left,
-         ytick align=center,
-         yticklabel={$\pgfmathprintnumber{\tick}\%$},
-         xtick align=outside,
-         x tick style={},
-         xticklabel style={rotate=45,anchor=east,font=\scriptsize\sffamily},
-         extra y tick style={tick pos=right, ticklabel pos=right, grid
-style={thick,color=black}},
-         extra y ticks={6.25},
-         extra y tick labels={Extra Label},
-]
-
-%\addplot plot[error bars/.cd,y dir=plus,y explicit,x dir=none] table
-%[x=Index,y expr=100*\thisrow{AvgLocked},y error=Diff]{locked_tabbed.dat};
-
-\end{axis}
-\end{tikzpicture}
-\end{document}
-
diff --git a/Master/texmf-dist/doc/latex/pgfplots/bugtracker/minimal_13.pdf b/Master/texmf-dist/doc/latex/pgfplots/bugtracker/minimal_13.pdf
deleted file mode 100644
index 9c05dea1f14..00000000000
--- a/Master/texmf-dist/doc/latex/pgfplots/bugtracker/minimal_13.pdf
+++ /dev/null
diff --git a/Master/texmf-dist/doc/latex/pgfplots/bugtracker/minimal_13.tex b/Master/texmf-dist/doc/latex/pgfplots/bugtracker/minimal_13.tex
deleted file mode 100644
index 3f11c01a719..00000000000
--- a/Master/texmf-dist/doc/latex/pgfplots/bugtracker/minimal_13.tex
+++ /dev/null
@@ -1,37 +0,0 @@
-
-\documentclass{article}
-\usepackage{pgfplots}
-\begin{document}
-\begin{tikzpicture}
-\begin{axis}[
-         small,
-         width=12cm,
-         height=1.8in,
-         ymin=0,
-		 ymax=10,
-         xmin=0,
-		 xmax=2,
-         ybar,
-         ymajorgrids=true,
-         yminorgrids=false,
-         minor y tick num=0,
-         ytick pos=left,
-         xtick pos=left,
-         ytick align=center,
-         yticklabel={$\pgfmathprintnumber{\tick}\%$},
-         xtick align=outside,
-         x tick style={},
-         xticklabel style={rotate=45,anchor=east,font=\scriptsize\sffamily},
-         extra y tick style={tick pos=right, ticklabel pos=right, grid
-style={thick,color=black}},
-         extra y ticks={6.25},
-         extra y tick labels={Extra Label},
-]
-
-%\addplot plot[error bars/.cd,y dir=plus,y explicit,x dir=none] table
-%[x=Index,y expr=100*\thisrow{AvgLocked},y error=Diff]{locked_tabbed.dat};
-
-\end{axis}
-\end{tikzpicture}
-\end{document}
-
diff --git a/Master/texmf-dist/doc/latex/pgfplots/bugtracker/minimal_2.pdf b/Master/texmf-dist/doc/latex/pgfplots/bugtracker/minimal_2.pdf
deleted file mode 100644
index fb0b471b8df..00000000000
--- a/Master/texmf-dist/doc/latex/pgfplots/bugtracker/minimal_2.pdf
+++ /dev/null
diff --git a/Master/texmf-dist/doc/latex/pgfplots/bugtracker/minimal_2.tex b/Master/texmf-dist/doc/latex/pgfplots/bugtracker/minimal_2.tex
deleted file mode 100644
index 3f11c01a719..00000000000
--- a/Master/texmf-dist/doc/latex/pgfplots/bugtracker/minimal_2.tex
+++ /dev/null
@@ -1,37 +0,0 @@
-
-\documentclass{article}
-\usepackage{pgfplots}
-\begin{document}
-\begin{tikzpicture}
-\begin{axis}[
-         small,
-         width=12cm,
-         height=1.8in,
-         ymin=0,
-		 ymax=10,
-         xmin=0,
-		 xmax=2,
-         ybar,
-         ymajorgrids=true,
-         yminorgrids=false,
-         minor y tick num=0,
-         ytick pos=left,
-         xtick pos=left,
-         ytick align=center,
-         yticklabel={$\pgfmathprintnumber{\tick}\%$},
-         xtick align=outside,
-         x tick style={},
-         xticklabel style={rotate=45,anchor=east,font=\scriptsize\sffamily},
-         extra y tick style={tick pos=right, ticklabel pos=right, grid
-style={thick,color=black}},
-         extra y ticks={6.25},
-         extra y tick labels={Extra Label},
-]
-
-%\addplot plot[error bars/.cd,y dir=plus,y explicit,x dir=none] table
-%[x=Index,y expr=100*\thisrow{AvgLocked},y error=Diff]{locked_tabbed.dat};
-
-\end{axis}
-\end{tikzpicture}
-\end{document}
-
diff --git a/Master/texmf-dist/doc/latex/pgfplots/bugtracker/minimal_3.pdf b/Master/texmf-dist/doc/latex/pgfplots/bugtracker/minimal_3.pdf
deleted file mode 100644
index 55d823a5648..00000000000
--- a/Master/texmf-dist/doc/latex/pgfplots/bugtracker/minimal_3.pdf
+++ /dev/null
diff --git a/Master/texmf-dist/doc/latex/pgfplots/bugtracker/minimal_3.tex b/Master/texmf-dist/doc/latex/pgfplots/bugtracker/minimal_3.tex
deleted file mode 100644
index 664ddc7df31..00000000000
--- a/Master/texmf-dist/doc/latex/pgfplots/bugtracker/minimal_3.tex
+++ /dev/null
@@ -1,23 +0,0 @@
-
-\documentclass[10pt]{article}
-
-\usepackage{pgfplots}
-\usepgfplotslibrary{groupplots}
-
-\begin{document}
-
-\begin{tikzpicture}%
-%\begin{axis}[%
-\begin{groupplot}[%
-	group style={group size=1 by 1},%
-]%
-	\nextgroupplot;
-	\node[name=a] at (axis cs:0.1,-1) {N};
-	\addplot coordinates{(0,1) (1,2)};
-\end{groupplot}
-%\end{axis}
-
-\draw (a) circle (5pt);
-\end{tikzpicture}%
-\end{document}
-
diff --git a/Master/texmf-dist/doc/latex/pgfplots/bugtracker/minimal_4.pdf b/Master/texmf-dist/doc/latex/pgfplots/bugtracker/minimal_4.pdf
deleted file mode 100644
index 63d9e554d87..00000000000
--- a/Master/texmf-dist/doc/latex/pgfplots/bugtracker/minimal_4.pdf
+++ /dev/null
diff --git a/Master/texmf-dist/doc/latex/pgfplots/bugtracker/minimal_4.tex b/Master/texmf-dist/doc/latex/pgfplots/bugtracker/minimal_4.tex
deleted file mode 100644
index 664ddc7df31..00000000000
--- a/Master/texmf-dist/doc/latex/pgfplots/bugtracker/minimal_4.tex
+++ /dev/null
@@ -1,23 +0,0 @@
-
-\documentclass[10pt]{article}
-
-\usepackage{pgfplots}
-\usepgfplotslibrary{groupplots}
-
-\begin{document}
-
-\begin{tikzpicture}%
-%\begin{axis}[%
-\begin{groupplot}[%
-	group style={group size=1 by 1},%
-]%
-	\nextgroupplot;
-	\node[name=a] at (axis cs:0.1,-1) {N};
-	\addplot coordinates{(0,1) (1,2)};
-\end{groupplot}
-%\end{axis}
-
-\draw (a) circle (5pt);
-\end{tikzpicture}%
-\end{document}
-
diff --git a/Master/texmf-dist/doc/latex/pgfplots/bugtracker/minimal_5.pdf b/Master/texmf-dist/doc/latex/pgfplots/bugtracker/minimal_5.pdf
deleted file mode 100644
index 4cd0f1e8034..00000000000
--- a/Master/texmf-dist/doc/latex/pgfplots/bugtracker/minimal_5.pdf
+++ /dev/null
diff --git a/Master/texmf-dist/doc/latex/pgfplots/bugtracker/minimal_5.tex b/Master/texmf-dist/doc/latex/pgfplots/bugtracker/minimal_5.tex
deleted file mode 100644
index 3f11c01a719..00000000000
--- a/Master/texmf-dist/doc/latex/pgfplots/bugtracker/minimal_5.tex
+++ /dev/null
@@ -1,37 +0,0 @@
-
-\documentclass{article}
-\usepackage{pgfplots}
-\begin{document}
-\begin{tikzpicture}
-\begin{axis}[
-         small,
-         width=12cm,
-         height=1.8in,
-         ymin=0,
-		 ymax=10,
-         xmin=0,
-		 xmax=2,
-         ybar,
-         ymajorgrids=true,
-         yminorgrids=false,
-         minor y tick num=0,
-         ytick pos=left,
-         xtick pos=left,
-         ytick align=center,
-         yticklabel={$\pgfmathprintnumber{\tick}\%$},
-         xtick align=outside,
-         x tick style={},
-         xticklabel style={rotate=45,anchor=east,font=\scriptsize\sffamily},
-         extra y tick style={tick pos=right, ticklabel pos=right, grid
-style={thick,color=black}},
-         extra y ticks={6.25},
-         extra y tick labels={Extra Label},
-]
-
-%\addplot plot[error bars/.cd,y dir=plus,y explicit,x dir=none] table
-%[x=Index,y expr=100*\thisrow{AvgLocked},y error=Diff]{locked_tabbed.dat};
-
-\end{axis}
-\end{tikzpicture}
-\end{document}
-
diff --git a/Master/texmf-dist/doc/latex/pgfplots/bugtracker/minimal_6.pdf b/Master/texmf-dist/doc/latex/pgfplots/bugtracker/minimal_6.pdf
deleted file mode 100644
index 9f6faa0316b..00000000000
--- a/Master/texmf-dist/doc/latex/pgfplots/bugtracker/minimal_6.pdf
+++ /dev/null
diff --git a/Master/texmf-dist/doc/latex/pgfplots/bugtracker/minimal_6.tex b/Master/texmf-dist/doc/latex/pgfplots/bugtracker/minimal_6.tex
deleted file mode 100644
index 3f11c01a719..00000000000
--- a/Master/texmf-dist/doc/latex/pgfplots/bugtracker/minimal_6.tex
+++ /dev/null
@@ -1,37 +0,0 @@
-
-\documentclass{article}
-\usepackage{pgfplots}
-\begin{document}
-\begin{tikzpicture}
-\begin{axis}[
-         small,
-         width=12cm,
-         height=1.8in,
-         ymin=0,
-		 ymax=10,
-         xmin=0,
-		 xmax=2,
-         ybar,
-         ymajorgrids=true,
-         yminorgrids=false,
-         minor y tick num=0,
-         ytick pos=left,
-         xtick pos=left,
-         ytick align=center,
-         yticklabel={$\pgfmathprintnumber{\tick}\%$},
-         xtick align=outside,
-         x tick style={},
-         xticklabel style={rotate=45,anchor=east,font=\scriptsize\sffamily},
-         extra y tick style={tick pos=right, ticklabel pos=right, grid
-style={thick,color=black}},
-         extra y ticks={6.25},
-         extra y tick labels={Extra Label},
-]
-
-%\addplot plot[error bars/.cd,y dir=plus,y explicit,x dir=none] table
-%[x=Index,y expr=100*\thisrow{AvgLocked},y error=Diff]{locked_tabbed.dat};
-
-\end{axis}
-\end{tikzpicture}
-\end{document}
-
diff --git a/Master/texmf-dist/doc/latex/pgfplots/bugtracker/minimal_7.pdf b/Master/texmf-dist/doc/latex/pgfplots/bugtracker/minimal_7.pdf
deleted file mode 100644
index 950e03d078a..00000000000
--- a/Master/texmf-dist/doc/latex/pgfplots/bugtracker/minimal_7.pdf
+++ /dev/null
diff --git a/Master/texmf-dist/doc/latex/pgfplots/bugtracker/minimal_7.tex b/Master/texmf-dist/doc/latex/pgfplots/bugtracker/minimal_7.tex
deleted file mode 100644
index 1567c1d6eab..00000000000
--- a/Master/texmf-dist/doc/latex/pgfplots/bugtracker/minimal_7.tex
+++ /dev/null
@@ -1,25 +0,0 @@
-
-\documentclass{article}
-
-\usepackage{pgfplots}
-\begin{document}
-\begin{tikzpicture}
-\begin{axis}[axis equal]
-% FokkerDrI_layer_0.patches.dat contains:
-% # each row is one vertex; three consecutive
-% # vertices make one triangle (patch)
-% 105.577	-19.7332	2.85249
-% 88.9233	-21.1254	13.0359
-% 89.2104	-22.1547	1.46467
-% # end of facet 0
-% 105.577	-19.7332	2.85249
-% 105.577	-17.2161	12.146
-% 88.9233	-21.1254	13.0359
-% # end of facet 1
-\addplot3[patch]
-	file
-	{plotdata/FokkerDrI_layer_0.patches.dat};
-\end{axis}
-\end{tikzpicture}
-\end{document}
-
diff --git a/Master/texmf-dist/doc/latex/pgfplots/bugtracker/minimal_8.pdf b/Master/texmf-dist/doc/latex/pgfplots/bugtracker/minimal_8.pdf
deleted file mode 100644
index f341833cb5a..00000000000
--- a/Master/texmf-dist/doc/latex/pgfplots/bugtracker/minimal_8.pdf
+++ /dev/null
diff --git a/Master/texmf-dist/doc/latex/pgfplots/bugtracker/minimal_8.tex b/Master/texmf-dist/doc/latex/pgfplots/bugtracker/minimal_8.tex
deleted file mode 100644
index 664ddc7df31..00000000000
--- a/Master/texmf-dist/doc/latex/pgfplots/bugtracker/minimal_8.tex
+++ /dev/null
@@ -1,23 +0,0 @@
-
-\documentclass[10pt]{article}
-
-\usepackage{pgfplots}
-\usepgfplotslibrary{groupplots}
-
-\begin{document}
-
-\begin{tikzpicture}%
-%\begin{axis}[%
-\begin{groupplot}[%
-	group style={group size=1 by 1},%
-]%
-	\nextgroupplot;
-	\node[name=a] at (axis cs:0.1,-1) {N};
-	\addplot coordinates{(0,1) (1,2)};
-\end{groupplot}
-%\end{axis}
-
-\draw (a) circle (5pt);
-\end{tikzpicture}%
-\end{document}
-
diff --git a/Master/texmf-dist/doc/latex/pgfplots/bugtracker/minimal_9.pdf b/Master/texmf-dist/doc/latex/pgfplots/bugtracker/minimal_9.pdf
deleted file mode 100644
index e61a15b136a..00000000000
--- a/Master/texmf-dist/doc/latex/pgfplots/bugtracker/minimal_9.pdf
+++ /dev/null
diff --git a/Master/texmf-dist/doc/latex/pgfplots/bugtracker/minimal_9.tex b/Master/texmf-dist/doc/latex/pgfplots/bugtracker/minimal_9.tex
deleted file mode 100644
index 3f11c01a719..00000000000
--- a/Master/texmf-dist/doc/latex/pgfplots/bugtracker/minimal_9.tex
+++ /dev/null
@@ -1,37 +0,0 @@
-
-\documentclass{article}
-\usepackage{pgfplots}
-\begin{document}
-\begin{tikzpicture}
-\begin{axis}[
-         small,
-         width=12cm,
-         height=1.8in,
-         ymin=0,
-		 ymax=10,
-         xmin=0,
-		 xmax=2,
-         ybar,
-         ymajorgrids=true,
-         yminorgrids=false,
-         minor y tick num=0,
-         ytick pos=left,
-         xtick pos=left,
-         ytick align=center,
-         yticklabel={$\pgfmathprintnumber{\tick}\%$},
-         xtick align=outside,
-         x tick style={},
-         xticklabel style={rotate=45,anchor=east,font=\scriptsize\sffamily},
-         extra y tick style={tick pos=right, ticklabel pos=right, grid
-style={thick,color=black}},
-         extra y ticks={6.25},
-         extra y tick labels={Extra Label},
-]
-
-%\addplot plot[error bars/.cd,y dir=plus,y explicit,x dir=none] table
-%[x=Index,y expr=100*\thisrow{AvgLocked},y error=Diff]{locked_tabbed.dat};
-
-\end{axis}
-\end{tikzpicture}
-\end{document}
-
diff --git a/Master/texmf-dist/doc/latex/pgfplots/cartesian_phase_diagram.pdf b/Master/texmf-dist/doc/latex/pgfplots/cartesian_phase_diagram.pdf
deleted file mode 100644
index 1557c37bee4..00000000000
--- a/Master/texmf-dist/doc/latex/pgfplots/cartesian_phase_diagram.pdf
+++ /dev/null
diff --git a/Master/texmf-dist/doc/latex/pgfplots/figures/pgfplots-surface-cutoff.png b/Master/texmf-dist/doc/latex/pgfplots/figures/pgfplots-surface-cutoff.png
new file mode 100644
index 00000000000..08f0ba40689
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/pgfplots/figures/pgfplots-surface-cutoff.png
diff --git a/Master/texmf-dist/doc/latex/pgfplots/gallery/Makefile b/Master/texmf-dist/doc/latex/pgfplots/gallery/Makefile
index 27896014114..ce9eb1600c5 100644
--- a/Master/texmf-dist/doc/latex/pgfplots/gallery/Makefile
+++ b/Master/texmf-dist/doc/latex/pgfplots/gallery/Makefile
@@ -4,6 +4,7 @@
 # REQUIREMENTS:
 # make sure TEXINPUTS contains the doc/latex/pgfplots/ tree recursively.
 
+# FIXME : this leads to strange sequences... sort correctly!
 DOC_SRC=$(wildcard ../pgfplots.*.tex) ../pgfplotstable.tex
 # DOC_SRC:=../pgfplotstable.tex
 
@@ -16,11 +17,11 @@ all: prepare
 	$(MAKE) images
 
 prepare: $(DOC_SRC)
-	./extractexamples.pl ./example ./index.html $(DOC_SRC) 
+	./extractexamples.pl ./example ./gallery.html $(DOC_SRC) 
 	touch $@
 
 clean:
-	rm -f ./example* prepare index.html
+	rm -f ./example* prepare gallery.html
 
 
 prepared: $(PREPARED_SRC:%.tex=%.pdf)
@@ -34,6 +35,6 @@ images: $(PREPARED_SRC:%.tex=%.png)
 # %.pdf: %.tex
 
 %.pdf:
-	export TEXINPUTS="$(TEXINPUTS)..:../figures:" && pdflatex -interaction batchmode -halt-on-error -shell-escape $(@:.pdf=) 2>/dev/null 1>/dev/null
+	export TEXINPUTS="$(TEXINPUTS):..:../figures:" && lualatex -interaction batchmode -halt-on-error -shell-escape $(@:.pdf=) 2>/dev/null 1>/dev/null
 	pdfcrop $@ $@ 2>/dev/null 1>/dev/null
 	@rm $(@:.pdf=.log) $(@:.pdf=.aux)
diff --git a/Master/texmf-dist/doc/latex/pgfplots/gallery/extractexamples.pl b/Master/texmf-dist/doc/latex/pgfplots/gallery/extractexamples.pl
index 5576c9ad7fb..1033b3755d6 100644
--- a/Master/texmf-dist/doc/latex/pgfplots/gallery/extractexamples.pl
+++ b/Master/texmf-dist/doc/latex/pgfplots/gallery/extractexamples.pl
@@ -104,6 +104,10 @@ print OUTHTML
 <body>
 <h2>PGFPlots Gallery</h2>
 <h4>The following graphics have been generated with the LaTeX Packages <a href="http://pgfplots.sourceforge.net/pgfplots.pdf">PGFPlots</a> and <a href="http://pgfplots.sourceforge.net/pgfplotstable.pdf">PGFPlotsTable</a>.</h4>
+
+They have been extracted from the reference manuals.
+
+<a href="http://pgfplots.sourceforge.net">PGFPlots Home</a>
 ';
 
 for($j = 2; $j<=$#ARGV; ++$j ) {
@@ -122,7 +126,8 @@ for($j = 2; $j<=$#ARGV; ++$j ) {
 
 	if( $ARGV[$j] =~ m/pgfplotstable.tex/ ) {
 		$largegraphics = 1;
-		$autoheaders = '
+		$autoheaders = $autoheaders.'
+\usepackage{pgfplotstable}
 \usepackage{array}
 \usepackage{colortbl}
 \usepackage{booktabs}
@@ -131,6 +136,13 @@ for($j = 2; $j<=$#ARGV; ++$j ) {
 ';
 	}
 
+	@libName = ($ARGV[$j] =~ m/pgfplots\.libs\.(.*)\.tex/ );
+	if ($#libName >=0 ) {
+		$autoheaders = $autoheaders.'
+\usepgfplotslibrary{'.$libName[0].'}
+';
+	}
+
 	for( $q=0; $q<=$#matches/4; $q++ ) {
 		$prefix = $matches[4*$q];
 		$prefix = "" if not defined($prefix);
@@ -165,6 +177,10 @@ for($j = 2; $j<=$#ARGV; ++$j ) {
 			open(OUTFILE,">",$outfile) or die( "could not open $outfile for writing");
 			print OUTFILE $header;
 			print OUTFILE $autoheaders;
+			print OUTFILE "\\usepackage{pgfplotstable}\n" if ($match =~ /pgfplotstable/);
+			print OUTFILE "\\usepackage{hyperref}\n" if ($match =~ /\\url/);
+			print OUTFILE "\\usepackage{textcomp}\n" if ($match =~ /\\textdegree/);
+			print OUTFILE "\\usepackage{listings}\n" if ($match =~ /\\lst/);
 			print OUTFILE $prefix;
 			print OUTFILE "\n\\begin{document}\n";
 			print OUTFILE $match;
diff --git a/Master/texmf-dist/doc/latex/pgfplots/gibbs_phase_diagram.pdf b/Master/texmf-dist/doc/latex/pgfplots/gibbs_phase_diagram.pdf
deleted file mode 100644
index 93a35341499..00000000000
--- a/Master/texmf-dist/doc/latex/pgfplots/gibbs_phase_diagram.pdf
+++ /dev/null
diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplots-macros.tex b/Master/texmf-dist/doc/latex/pgfplots/pgfplots-macros.tex
index fbb1c10f42c..c018e43613a 100644
--- a/Master/texmf-dist/doc/latex/pgfplots/pgfplots-macros.tex
+++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots-macros.tex
@@ -113,7 +113,7 @@
 		\pgfkeys{/pdflinks/codeexample links=false}%
 	}{}%
 }%
-\pgfkeys{/pgf/images/include external/.code={\href{file:#1}{\pgfimage{#1}}}} % FIXME : NOT FOR THE FINAL VERSION
+%\pgfkeys{/pgf/images/include external/.code={\href{file:#1}{\pgfimage{#1}}}} % FIXME : NOT FOR THE FINAL VERSION
 
 \newif\ifpgfplots@example@is@expensive
 
diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.basic.reference.tex b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.basic.reference.tex
index 09671754622..c88713aff41 100644
--- a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.basic.reference.tex
+++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.basic.reference.tex
@@ -223,6 +223,10 @@ The number is printed using the current number printing options, see the manual
 	The example above initializes an axis and executes the basic level path commands as soon as the axis is ready. The execution of multiple |\path|, |\addplot| and |\pgfplotsextra| commands is in the same sequence as they occur in the environment\footnote{Except for stacked plots where the sequence may be reverse, see the key \texttt{reverse stack plots}.}.%
 \end{command}
 
+\begin{command}{\pgfplotspathaxisoutline}
+	Generates a path which resembles the outline of the current axis. This path is used for clip paths and the background paths (if any).
+\end{command}
+
 \subsection{Specifying Basic Coordinates}
 \label{sec:basic:coordinates}
 
@@ -266,7 +270,8 @@ The number is printed using the current number printing options, see the manual
 		{\pgfplotspointaxisdirectionxy{1}{1}}
 		{\pgfplotspointaxisdirectionxy{0}{2}}
 	};
-	\addplot [only marks,mark=*] coordinates { (0,0) };
+	\addplot [only marks,mark=*] coordinates 
+		{ (0,0) };
 \end{axis}
 \end{tikzpicture}
 \end{codeexample}
@@ -338,7 +343,7 @@ The number is printed using the current number printing options, see the manual
 
 	A direction vector needs to be \emph{added} to some coordinate in order to get a coordinate, compare the documentation for |\pgfplotspointaxisdirectionxy| and |axis direction cs|.
 
-	The argument \meta{x direction of an axis} is processed in (almost) the same way as for |\pgfplotstransformcoordinatex|. The only difference is that \emph{directions} need no shifting transformation. 
+	The argument \meta{x direction of an axis} is processed in (almost) the same way as for the macro which operates on absolute positions, |\pgfplotstransformcoordinatex|. The only difference is that \emph{directions} need no shifting transformation. 
 
 	The result of this command is also available as math method |transformdirectionx| (see the documentation for |axis direction cs|).
 
@@ -439,3 +444,31 @@ The number is printed using the current number printing options, see the manual
 
 \subsection{Accessing Axis Limits}
 It is also possible to access axis limits during the visualization phase, i.e.\ during |\end{axis}|. Please refer to the reference documentation for |xmin| on page~\pageref{page:access:limits}.
+
+\subsection{Layer Access}
+\begin{command}{\pgfplotsonlayer\marg{layer name}}
+    A low-level command which will check if the current axis has layer support activated and, if so, calls |\pgfonlayer|\marg{layer name}.
+
+    There must be a |\endpgfplotsonlayer| to delimit the environment.
+\end{command}
+\begin{command}{\endpgfplotsonlayer}
+    The end of |\pgfplotsonlayer|.
+\end{command}
+
+\begin{command}{\pgfonlayer\marg{layer name}}
+    A low-level command of \PGF\ which will collect everything until the matching |\endpgfonlayer| into layer \meta{layer name}.
+
+    The \meta{layer name} must be active, i.e.\ it must be part of the layer names of |set layers|. 
+    
+    The only special case is if you call |\pgfdeclarelayer{discard}| somewhere: this special layer has a ``magical name'' which serves as |/dev/null| if it is enabled using |\pgfonlayer{discard}|: it does not need to be active and everything assigned to this layer will be thrown away if it is not part of the layer name configuration.
+
+    There must be a |\endpgfonlayer| to delimit the environment.
+\end{command}
+\begin{command}{\endpgfonlayer}
+    The end of |\pgfonlayer|.
+\end{command}
+
+
+\begin{command}{\pgfsetlayers\marg{layer list}}
+	This is a low-level command of \PGF. At the time of this writing, it is the only way to tell \PGF\ which layers it shall use for the current / next picture. It is used implicitly by |set layers|.
+\end{command}
diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.figlist b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.figlist
index a03fe00ac86..72fe5bfd092 100644
--- a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.figlist
+++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.figlist
@@ -31,10 +31,15 @@ figures/expensiveexamplereference_threedim_21
 figures/expensiveexamplereference_threedim_22
 figures/expensiveexamplereference_threedim_23
 figures/expensiveexamplereference_threedim_24
+figures/expensiveexamplereference_threedim_interior_colormap_0
+figures/expensiveexamplereference_threedim_interior_colormap_1
+figures/expensiveexamplereference_threedim_interior_colormap_2
+figures/expensiveexamplereference_threedim_interior_colormap_3
 figures/expensiveexamplereference_threedim_contour_0
 figures/expensiveexamplereference_threedim_contour_1
 figures/expensiveexamplereference_threedim_contour_2
 figures/expensiveexamplereference_threedim_contour_3
+figures/expensiveexamplereference_threedim_contour_4
 figures/expensiveexamplereference_threedim_25
 figures/expensiveexamplereference_threedim_26
 figures/expensiveexamplereference_threedim_27
@@ -61,6 +66,7 @@ figures/expensiveexamplereference_nodes_0
 figures/expensiveexamplereference_nodes_1
 figures/expensiveexamplereference_nodes_2
 figures/expensiveexamplereference_nodes_3
+figures/expensiveexamplepatchplot_0
 figures/expensiveexamplepolar_0
 figures/expensiveexamplememspeed_0
 figures/expensiveexamplememspeed_1
diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.intro.tex b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.intro.tex
index aa84de1bdbd..173ee7656d4 100644
--- a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.intro.tex
+++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.intro.tex
@@ -52,7 +52,7 @@ Each environment is available for \LaTeX, Con{\TeX}t and plain \TeX:
 % for dvipdfm:
 %\def\pgfsysdriver{pgfsys-dvipdfm.def}
 \usepackage{pgfplots}
-\pgfplotsset{compat=1.3}% <-- moves axis labels near ticklabels (respects tick label widths)
+\pgfplotsset{compat=1.6}% <-- moves axis labels near ticklabels (respects tick label widths)
 
 \begin{document}
 \begin{figure}
diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.libs.patchplots.tex b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.libs.patchplots.tex
index c78c71af974..cf23448973a 100644
--- a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.libs.patchplots.tex
+++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.libs.patchplots.tex
@@ -1,4 +1,6 @@
 \subsection{Patchplots Library}
+{
+\tikzset{external/figure name/.add={}{patchplot_}}%
 \label{sec:lib:patchplots}
 \begin{pgfplotslibrary}{patchplots}
 	A library for advanced |patch| plots. It has been designed to visualize shaded isoparametric finite element meshes of higher order. Its core is an interface to the generation of smoothly shaped elements with interpolated color values (based on \texttt{.pdf} Shading Type 6 and \texttt{.pdf} Shading Type 7), with additional (limited) support for constant color filling without shadings.
@@ -176,6 +178,33 @@ coordinates {
 \end{codeexample}
 	\noindent Similar to |triangle quadr|, the edges have the correct quadratic shape -- but the color interpolation is just \emph{bilinear}; using the color values of the corners and ignoring the rest. Again, consider using |patch refines| to improve the color interpolation.
 
+	Note that a function of $(x,y)$ is biquadratic if it is quadratic w.r.t.~$x$ if $y=\text{const}$ and also quadratic w.r.t.~$y$ if $x=\text{const}$. For example, $f(x,y) = x^2-y^2$ is biquadratic. Consequently, we can represent a surface plot of $f$ with just one biquadratic patch -- only the color interpolation is just bilinear. We do so using |\addplot table[z expr=|\meta{expression}|]|:
+\pgfplotsexpensiveexample
+\begin{codeexample}[]
+\begin{tikzpicture}
+    \begin{axis}
+    \addplot3[patch,patch refines=3,
+		shader=faceted interp,
+		patch type=biquadratic] 
+    table[z expr=x^2-y^2]
+    {
+        x  y
+        -2 -2
+        2  -2
+        2  2
+        -2 2
+        0  -2
+        2  0
+        0  2
+        -2 0
+        0  0
+    };
+    \end{axis}
+\end{tikzpicture}
+\end{codeexample}
+	\noindent We see that the shape's boundary is reconstructed exactly using the |biquadratic| patch. In addition, |patch refines| improves the (first order) color interpolation. Details for |patch refines| are discussed in Section~\ref{sec:lib:patchplots:refinement} abd details and limitations regarding superimposed grid lines are discussed in Section~\ref{sec:lib:patchplots:grids}.
+
+
 	The choice \declareandlabel{coons} expects a sequence of one or more Coons patches, made up of $n=12$ points each. A Coons patch is delimited by four cubic B\'ezier curves, with the end points attached to each other -- and the $n$ points provide the required control points for these curves in a specific ordering which is illustrated in the following example:
 \begin{codeexample}[]
 \begin{tikzpicture}
@@ -263,6 +292,7 @@ table[row sep=\\] {
 
 
 \subsubsection{Automatic Patch Refinement and Triangulation}
+\label{sec:lib:patchplots:refinement}
 \PGFPlots\ supports automatic patch refinement for most of its |patch type|s. There are mainly two purposes for patch refinement: to increase the quality of |z buffer=sort| and/or to improve color interpolation for high--order patches. 
 
 \begin{pgfplotskey}{patch refines=\marg{levels} (initially 0)}
@@ -350,6 +380,7 @@ The following example illustrates the effect: the coarse single element on the l
 \end{codeexample}
 
 \subsubsection{Drawing Grids}
+\label{sec:lib:patchplots:grids}
 The |patchplots| library supports grid (|mesh|) visualization in the same way as for two/three--dimensional |mesh|- and |surf| plots. This includes four different approaches: the first is |shader=faceted|, which uses constant fill color and |faceted color| for stroke paths (as we already saw in Section~\ref{sec:lib:patchplots:flat}). The second approach is to use |shader=faceted interp| which uses interpolated shadings for filling and issues stroke paths on top of each interpolated element. The third approach is to issue two |\addplot| commands, one with the filled |patch| plot, and one with a |patch,mesh| style which only draws (colored) grid lines on top of the previous plot. The three approaches are shown below.
 \begin{codeexample}[]
 \begin{tikzpicture}
@@ -428,7 +459,7 @@ coordinates {
 \end{axis}
 \end{tikzpicture}
 \end{codeexample}
-\noindent The approach to draw grids separately is realized by means of two |\addplot| statements; the first using |patch| as before, the second using |patch,mesh|. This configures \PGFPlots\ to visualize just the mesh. Make sure you provide `|mesh|' after `|patch|' since the latter activates filled |surf| visualization. The approach of meshes on top of patches implies to draw grid lines simply over any previous drawing operations. Thus, depth information is lost (as displayed in the first example above). Overlaying grid lines on top of the surface works in special cases (see bottom picture). An approach which always works is to provide the mesh at a fixed $z$ position as displayed in the following example:
+\noindent The approach to draw grids separately is done by means of two |\addplot| statements; the first using |patch| as before, the second using |patch,mesh|. This configures \PGFPlots\ to visualize just the mesh. Make sure you provide `|mesh|' after `|patch|' since the latter activates filled |surf| visualization. The approach of meshes on top of patches implies to draw grid lines simply over any previous drawing operations. Thus, depth information is lost (as displayed in the first example above). Overlaying grid lines on top of the surface works in special cases (see bottom picture). An approach which always works is to provide the mesh at a fixed $z$ position as displayed in the following example:
 %
 \begin{codeexample}[]
 \begin{tikzpicture}
@@ -456,6 +487,7 @@ coordinates {
 \end{codeexample}
 \noindent Here, the first |\addplot3| command is the same as above, just with |shader=interp|. The second reproduces the same geometry, but uses a |z filter| to fix the $z$ coordinate (in this case to $z=1.8$). This effectively overrules all $z$ coordinates.
 
-	Thus, grid lines can be realized either by means of flat fill color with |shader=faceted| (efficient), by means of interpolated fill colors with |shader=faceted interp| (inefficient, see above) or, for special applications, using a separate |patch,mesh| plot which is drawn on top of the patches (efficient). In any case, the mesh visualization considers the |faceted color| which can depend on |mapped color|.
+	Thus, grid lines can be drawn either by means of flat fill color with |shader=faceted| (efficient), by means of interpolated fill colors with |shader=faceted interp| (inefficient, see above) or, for special applications, using a separate |patch,mesh| plot which is drawn on top of the patches (efficient). In any case, the mesh visualization considers the |faceted color| which can depend on |mapped color|.
 
 \end{pgfplotslibrary}
+}
diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.libs.smithchart.tex b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.libs.smithchart.tex
index 40e536b8e0b..7e5a6e61a8e 100644
--- a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.libs.smithchart.tex
+++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.libs.smithchart.tex
@@ -25,13 +25,68 @@
 	The |\begin{smithchart}| environment draws Smith Charts. It accepts the same \meta{options} as |\begin{axis}|. In fact, it is equivalent to |\begin{axis}[|\meta{options}|,axis type=smithchart]|.
 \begin{codeexample}[]
 \begin{tikzpicture}
-	\begin{smithchart}[title=Default Smith Chart]
+	\begin{smithchart}[title=Impedance Smith Chart]
 	\addplot coordinates {(0.5,0.2) (1,0.8) (2,2)};
 	\end{smithchart}
 \end{tikzpicture}
 \end{codeexample}
 	The example above visualizes three data points using the initial configuration of Smith Charts; the data points are interpreted as complex numbers $z = x + j y$ and are mapped using $r(z)$.
 
+	Here, the $x$ coordinate refers to the cycles described by the horizontal line whereas the $y$ coordinate refers to the cycles described by the tick labels on the outside.
+
+\begin{pgfplotskey}{smithchart mirrored=\mchoice{true,false} (initially false)}
+	\PGFPlots\ also supports Admittance Smith Charts. Here, the origin is on the right side of the circle:
+\begin{codeexample}[]
+\begin{tikzpicture}
+	\begin{smithchart}[
+		smithchart mirrored,
+		title=Admittance Smith Chart]
+	\addplot coordinates {(0.5,0.2) (1,0.8) (2,2)};
+	\end{smithchart}
+\end{tikzpicture}
+\end{codeexample}
+\end{pgfplotskey}
+	
+
+	Since \PGFPlots\ can draw two axes on top of each other, a combined Impedance/Admittance Smith Chart is also possible.
+\begin{codeexample}[]
+\begin{tikzpicture}[]
+% First, the Admittance chart:
+\begin{smithchart}[
+	title=Impedance and Admittance Smith Chart,
+	smithchart mirrored,
+	xticklabel shift=-19pt,
+	grid style={blue},
+	ticklabel style={blue},
+	yticklabel around circle,
+]
+\end{smithchart}
+
+% Second, overlay the impedance chart:
+\begin{smithchart}[
+	show origin,
+	grid style={red},
+	ticklabel style={red},
+	yticklabel around circle*,
+]
+\addplot+[black,mark=o,only marks,point meta=explicit symbolic,nodes near coords]
+coordinates {
+	(0.2,0.2) [(2)]
+	(1,0.2) [(1)]
+	};
+
+\addplot+[black,no marks,domain=0.2:1] {0.2};
+
+\addplot+[black,mark=o,only marks,point meta=explicit symbolic,nodes near coords]
+coordinates{
+	(0.2,0.5) [(3)]
+};
+\end{smithchart}
+\end{tikzpicture}
+\end{codeexample}
+	Since such a chart easily becomes crowded, it should be tuned manually by means of ``suitable'' appearance options (if you feel that there is a ``suitable default'', let me know).
+
+	Details for |show origin|, |yticklabel around circle|, and |yticklabel around circle*| can be found later in this section.
 \end{environment}
 
 \subsubsection{Size Control}
@@ -275,6 +330,61 @@ The tick and grid positions for |smithchart| axes are realized by means of three
 \end{codeexample}
 \end{stylekey}
 
+\begin{stylekey}{/pgfplots/yticklabel around circle}
+	This style draws Smith Chart tick labels for imaginary components (the |ytick| arguments) outside of the circle, but rotated to fit the slope of the circle.
+\begin{codeexample}[]
+\begin{tikzpicture}
+	\begin{smithchart}[yticklabel around circle]
+	\end{smithchart}
+\end{tikzpicture}
+\end{codeexample}
+
+	The initial configuration for this style is
+\begin{codeexample}[code only]
+\pgfplotsset{
+	yticklabel around circle/.style={
+		ytick align=center,
+		yticklabel style={
+			rotate=90,
+			sloped like y axis={%
+				execute for upside down={\tikzset{anchor=south west}},
+				%allow upside down,
+				reset nontranslations=false},
+			anchor=south east,
+		}
+	},
+}
+\end{codeexample}
+\end{stylekey}
+
+\begin{stylekey}{/pgfplots/yticklabel around circle*}
+	A variant of |yticklabel around circle| which exchanges the anchors:
+\begin{codeexample}[]
+\begin{tikzpicture}
+	\begin{smithchart}[yticklabel around circle*]
+	\end{smithchart}
+\end{tikzpicture}
+\end{codeexample}
+	If you have two Smith Charts in the same figure, you can overlay them if the first uses |yticklabel around circle| and the second uses |yticklabel around circle*| (see the beginning of this section for an example).
+
+	The initial configuration for this style is
+\begin{codeexample}[code only]
+\pgfplotsset{
+	yticklabel around circle*/.style={
+		ytick align=center,
+		yticklabel style={
+			rotate=90,
+			sloped like y axis={%
+				execute for upside down={\tikzset{anchor=north west}},
+				%allow upside down,
+				reset nontranslations=false},
+			anchor=north east,
+		}
+	}
+}
+\end{codeexample}
+\end{stylekey}
+
 \begin{stylekey}{/pgfplots/every smithchart axis}
 	This style is installed for every Smith Chart. It is defined as
 \begin{codeexample}[code only]
diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.makefile b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.makefile
index 42acbc1be17..0349f8170b3 100644
--- a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.makefile
+++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.makefile
@@ -9,6 +9,7 @@ FORCEREMAKE:
 include $(ALL_FIGURE_NAMES:%=%.dep)
 
 %.dep:
+	mkdir -p $(dir $@)
 	touch $@ # will be filled later.
 
 figures/expensiveexamplereference_addplot_0.pdf: 
@@ -110,6 +111,18 @@ figures/expensiveexamplereference_threedim_23.pdf:
 figures/expensiveexamplereference_threedim_24.pdf: 
 	pdflatex -shell-escape -halt-on-error -interaction=batchmode -jobname "figures/expensiveexamplereference_threedim_24" "\def\tikzexternalrealjob{pgfplots}\input{pgfplots}"
 
+figures/expensiveexamplereference_threedim_interior_colormap_0.pdf: 
+	pdflatex -shell-escape -halt-on-error -interaction=batchmode -jobname "figures/expensiveexamplereference_threedim_interior_colormap_0" "\def\tikzexternalrealjob{pgfplots}\input{pgfplots}"
+
+figures/expensiveexamplereference_threedim_interior_colormap_1.pdf: 
+	pdflatex -shell-escape -halt-on-error -interaction=batchmode -jobname "figures/expensiveexamplereference_threedim_interior_colormap_1" "\def\tikzexternalrealjob{pgfplots}\input{pgfplots}"
+
+figures/expensiveexamplereference_threedim_interior_colormap_2.pdf: 
+	pdflatex -shell-escape -halt-on-error -interaction=batchmode -jobname "figures/expensiveexamplereference_threedim_interior_colormap_2" "\def\tikzexternalrealjob{pgfplots}\input{pgfplots}"
+
+figures/expensiveexamplereference_threedim_interior_colormap_3.pdf: 
+	pdflatex -shell-escape -halt-on-error -interaction=batchmode -jobname "figures/expensiveexamplereference_threedim_interior_colormap_3" "\def\tikzexternalrealjob{pgfplots}\input{pgfplots}"
+
 figures/expensiveexamplereference_threedim_contour_0.pdf: 
 	pdflatex -shell-escape -halt-on-error -interaction=batchmode -jobname "figures/expensiveexamplereference_threedim_contour_0" "\def\tikzexternalrealjob{pgfplots}\input{pgfplots}"
 
@@ -122,6 +135,9 @@ figures/expensiveexamplereference_threedim_contour_2.pdf:
 figures/expensiveexamplereference_threedim_contour_3.pdf: 
 	pdflatex -shell-escape -halt-on-error -interaction=batchmode -jobname "figures/expensiveexamplereference_threedim_contour_3" "\def\tikzexternalrealjob{pgfplots}\input{pgfplots}"
 
+figures/expensiveexamplereference_threedim_contour_4.pdf: 
+	pdflatex -shell-escape -halt-on-error -interaction=batchmode -jobname "figures/expensiveexamplereference_threedim_contour_4" "\def\tikzexternalrealjob{pgfplots}\input{pgfplots}"
+
 figures/expensiveexamplereference_threedim_25.pdf: 
 	pdflatex -shell-escape -halt-on-error -interaction=batchmode -jobname "figures/expensiveexamplereference_threedim_25" "\def\tikzexternalrealjob{pgfplots}\input{pgfplots}"
 
@@ -200,6 +216,9 @@ figures/expensiveexamplereference_nodes_2.pdf:
 figures/expensiveexamplereference_nodes_3.pdf: 
 	pdflatex -shell-escape -halt-on-error -interaction=batchmode -jobname "figures/expensiveexamplereference_nodes_3" "\def\tikzexternalrealjob{pgfplots}\input{pgfplots}"
 
+figures/expensiveexamplepatchplot_0.pdf: 
+	pdflatex -shell-escape -halt-on-error -interaction=batchmode -jobname "figures/expensiveexamplepatchplot_0" "\def\tikzexternalrealjob{pgfplots}\input{pgfplots}"
+
 figures/expensiveexamplepolar_0.pdf: 
 	pdflatex -shell-escape -halt-on-error -interaction=batchmode -jobname "figures/expensiveexamplepolar_0" "\def\tikzexternalrealjob{pgfplots}\input{pgfplots}"
 
diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.pdf b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.pdf
index 937f4c670ed..8abcdab378e 100644
--- a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.pdf
+++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.pdf
diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.preamble.tex b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.preamble.tex
index dcefd3a1da3..ec147b226ab 100644
--- a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.preamble.tex
+++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.preamble.tex
@@ -149,7 +149,7 @@
 
 \graphicspath{{figures/}}
 
-\def\preambleconfig{width=7cm,compat=1.5.1}
+\def\preambleconfig{width=7cm,compat=1.6}
 
 
 \expandafter\pgfplotsset\expandafter{\preambleconfig}
@@ -223,5 +223,5 @@
 
 \author{%
 	Dr.\ Christian Feuers\"anger\\
-	{\footnotesize\texttt{ludewich@users.sourceforge.net}}}%
+	{\footnotesize\texttt{cfeuersaenger@users.sourceforge.net}}}%
 
diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.2dplots.tex b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.2dplots.tex
index 1525e0fe6bb..a35ef1b049f 100644
--- a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.2dplots.tex
+++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.2dplots.tex
@@ -631,6 +631,57 @@ Here, |ybar| yields |/pgfplots/ybar| because it is an argument to the axis, not
 		
 	\end{pgfplotskey}
 
+	\begin{pgfplotskey}{hist/density=\marg{true,false} (initially false)}
+		\textit{An extension by J\"urnjakob Dugge}
+		\vskip\baselineskip
+		Enables density estimation mode. If |hist/density| is active, the resulting data points will be renormalized such that the overall ``mass'' equals~$1$. 
+\begin{codeexample}[]
+\begin{tikzpicture}
+\begin{axis}[small,ymin=0,title=\texttt{hist}]
+\addplot [
+	hist,
+	fill=orange!75,
+	draw=orange!50!black]
+	table [y index=0] {plotdata/pgfplots.randn.dat};
+\end{axis}
+\end{tikzpicture}
+%
+\begin{tikzpicture}
+\begin{axis}[small,ymin=0, title=\texttt{hist=density}]
+\addplot [
+	hist=density,
+	fill=orange!75,
+	draw=orange!50!black]
+	table [y index=0] {plotdata/pgfplots.randn.dat};
+\end{axis}
+\end{tikzpicture}
+\end{codeexample}
+
+
+		The keys |hist/density| and |hist/cumulative| can be combined as well:
+\begin{codeexample}[]
+\begin{tikzpicture}
+\begin{axis}[small,ymin=0, title=\texttt{hist=cumulative}]
+\addplot [
+	hist=cumulative,
+	fill=orange!75,
+	draw=orange!50!black]
+	table [y index=0] {plotdata/pgfplots.randn.dat};
+\end{axis}
+\end{tikzpicture}
+%
+\begin{tikzpicture}
+\begin{axis}[small,ymin=0, title=\texttt{hist=\{cumulative,density\}}]
+\addplot [
+	hist={cumulative,density},
+	fill=orange!75,
+	draw=orange!50!black]
+	table [y index=0] {plotdata/pgfplots.randn.dat};
+\end{axis}
+\end{tikzpicture}
+\end{codeexample}
+	\end{pgfplotskey}
+
 	\begin{stylekey}{/pgfplots/hist/handler (initially ybar interval)}
 		Allows to change the way the generated coordinates are visualized. The |hist/handler| key is a style, so use |hist/handler/.style={const plot}| to change it.
 	\end{stylekey}
@@ -800,13 +851,13 @@ Comb plots are very similar to bar plots except that they employ single horizont
 	% unexpected results here!
 	variable=\t,
 	quiver={
-		u={cos(deg(t))},
-		v={-sin(deg(t))},
+		u={-sin(deg(t))},
+		v={cos(deg(t))},
 		scale arrows=0.5},
 		->,blue]
-	({sin(deg(t))}, {cos(deg(t))});
+	({cos(deg(t))}, {sin(deg(t))});
   \addplot[samples=100, domain=0:2*pi] 
-	({sin(deg(x))}, {cos(deg(x))});
+	({cos(deg(x))}, {sin(deg(x))});
 \end{axis}
 \end{tikzpicture}
 \end{codeexample}
@@ -861,9 +912,38 @@ Comb plots are very similar to bar plots except that they employ single horizont
 	\begin{stylekey}{/pgfplots/quiver/every arrow (initially empty)}
 		Allows to provide individual arrow styles.
 
-		The style can contain any \Tikz\ drawing option. It might depend upon |mapped color| (provided |point meta| has been set).
+		The style can contain any \Tikz\ drawing option. It will be evaluated for every individual arrow and may depend upon anything which is available at visualization time. 
+		
+		In particular, this includes |point meta| data, typically using |\pgfplotspointmetatransformed| $\in [0,1000]$ where~$0$ corresponds to |point meta min| and~$1000$ corresponds to |point meta max|:
+\begin{codeexample}[]
+\begin{tikzpicture}
+% define some constants:
+\def\U{1}
+\def\V{2*x}
+\def\LEN{(sqrt((\U)^2 + (\V)^2)}
+
+\begin{axis}[axis equal image,
+	title=Thickness indicates ``strength''.
+]
+\addplot[blue,
+  point meta={\LEN},
+  quiver={
+   u={(\U)/\LEN}, v={(\V)/\LEN},
+   scale arrows=2,
+   every arrow/.append style={
+    line width=2pt*\pgfplotspointmetatransformed/1000
+   },
+  },
+  -stealth,samples=15,
+] {x^2};
+\end{axis}
+\end{tikzpicture}
+\end{codeexample}
+	\noindent In the example, we have some 2d vector field stored in helper constants |\U| and |\V|. The length of each vector is stored in |\LEN| here. The |quiver| plot as such contains unit length vectors -- and the |\LEN| enters an |every arrow| style to get varying |line width|.
+		
+		An |every arrow| style might also depend upon |mapped color| (provided |point meta| has been set).
 
-		Again, if you don't need individual arrow styles, prefer using a plot style (|cycle list| or argument to |\addplot|) which is more efficient.
+		Again, if you do not need individual arrow styles, prefer using a plot style (|cycle list| or argument to |\addplot|) which is more efficient.
 	\end{stylekey}
 
 	\begin{pgfplotsxycodekeylist}{%
@@ -871,6 +951,24 @@ Comb plots are very similar to bar plots except that they employ single horizont
 		quiver/after arrow}%
 		Advanced keys for more fine tuning of the display. They allow to install some \TeX\ code manually before or after the drawing operations for single arrows. Both are initially empty.
 	\end{pgfplotsxycodekeylist}
+
+	\begin{stylekey}{/pgfplots/quiver/quiver legend}
+		A style which redefines |legend image code| in order to produce a suitable legend for |quiver| plots.
+
+		It is implicitly activated whenever |quiver| plot handlers are selected.
+\begin{codeexample}[]
+\begin{tikzpicture}
+\begin{axis}[tiny]
+\addplot[blue, 
+	quiver={u=1,v=3*x}, 
+	-stealth,
+	samples=15] 
+	{x^3};
+\addlegendentry{Legend}
+\end{axis}
+\end{tikzpicture}
+\end{codeexample}
+	\end{stylekey}
 \end{plottype}
 
 \subsubsection{Stacked Plots}
@@ -1584,7 +1682,26 @@ Please note that |\ifdim| compares \TeX\ lengths, so the example employs the suf
 \subsubsection{Interrupted Plots}
 \index{Interrupted Plots}%
 \label{pgfplots:interrupt}%
-Sometimes it is desirable to draw parts of a single plot separately, without connection between the parts (discontinuities). This can be achieved using the |unbounded coords| key combined with coordinate values |nan|, |inf| or |-inf|.
+Sometimes it is desirable to draw parts of a single plot separately, without connection between the parts (discontinuities). \PGFPlots\ offers two ways to generate interrupted plots: either using |empty line|s or by providing |unbounded coords|.
+
+The first way is simple; it needs no extra key (only |\pgfplotsset{compat=1.4}| or newer in your preamble):
+\begin{codeexample}[]
+\begin{tikzpicture}
+\begin{axis}[
+	title=Interrupted data plot]
+
+	\addplot coordinates {
+		(0,0) (10,50) (20,100) (30,200) 
+
+		(50,600) (60,800) (80,1000)
+	};
+\end{axis}
+\end{tikzpicture}
+\end{codeexample}
+\noindent Here, \PGFPlots\ runs with the default configuration |empty line=auto| which interpretes empty lines as ``jump'' markers. This works for any data input method, i.e.\ using |\addplot coordinates|, |\addplot table|, and |\addplot file|.
+
+
+The second way to generate interrupted plots addresses the case where |empty line|s are unavailable or impossible (due to limitations of the tool generating the data file, for example). In this case, interrupted plots can be achieved using the |unbounded coords| key combined with coordinate values |nan|, |inf| or |-inf|.
 
 \begin{pgfplotskey}{unbounded coords=\mchoice{discard,jump} (initially discard)}
 	This key configures what to do if one or more coordinates of a single point are unbounded. Here, unbounded means it is either $\pm \infty$ (|+inf| or |-inf|) or it has the special ``not--a--number'' value |nan|.
diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.3dplots.tex b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.3dplots.tex
index 86b1f562b2c..b1a41674b22 100644
--- a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.3dplots.tex
+++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.3dplots.tex
@@ -30,7 +30,7 @@ Enough for now, let's continue.
 \begin{addplot3operation}[]{coordinates}{\marg{coordinate list}}
 	The \verbpdfref{\addplot3 coordinates} method works like its two--dimensional variant, \verbpdfref{\addplot coordinates} which is described in all detail on page~\pageref{pgfplots:addplot:coordinates}:
 
-	A long list of coordinates |(|\meta{x}|,|\meta{y}|,|\meta{z}|)| is expected, separated by white spaces. The input list can be either an unordered series of coordinates, for example for scatter or line plots. It can also have matrix structure, in which case an empty input line (which is equivalent to ``|\par|'') marks the end of one matrix row. Matrix structure can also be provided if one of |mesh/rows| or |mesh/cols| is provided explicitly.
+	A long list of coordinates |(|\meta{x}|,|\meta{y}|,|\meta{z}|)| is expected, separated by white spaces. The input list can be either an unordered series of coordinates, for example for scatter or line plots. It can also have matrix structure, in which case an |empty line| (which is equivalent to ``|\par|'') marks the end of one matrix row. Matrix structure can also be provided if one of |mesh/rows| or |mesh/cols| is provided explicitly.
 	
 \long\def\temporarytest{\noexpand\par}
 \begin{codeexample}[newline=\temporarytest]
@@ -47,7 +47,7 @@ Enough for now, let's continue.
 	\end{axis}
 \end{tikzpicture}
 \end{codeexample}
-	\noindent Here, \verbpdfref{\addplot3} reads a matrix with three rows and four columns. The empty lines separate one row from the following.
+	\noindent Here, \verbpdfref{\addplot3} reads a matrix with three rows and four columns. The |empty line|s separate one row from the following.
 
 	As for the two--dimensional |plot coordinates|, it is possible to provide (constant) mathematical expressions inside of single coordinates. The syntax |(|\meta{x}|,|\meta{y}|,|\meta{z}|) |\oarg{meta} can be used just as for two dimensional |plot coordinates| to provide explicit color data; error bars are also supported.
 \end{addplot3operation}
@@ -58,7 +58,7 @@ Enough for now, let's continue.
 	
 	A further column is read after $z_i$ if |point meta=explicit| has been requested, see the documentation of \verbpdfref{\addplot file} on page~\pageref{pgfplots:addplot:file} for details.
 	
-	As for \verbpdfref{\addplot3 coordinates}, an empty line in the file marks the end of one matrix row.
+	As for \verbpdfref{\addplot3 coordinates}, an |empty line| in the file marks the end of one matrix row.
 \begin{codeexample}[]
 \begin{tikzpicture}
 	\begin{axis}
@@ -97,7 +97,7 @@ Enough for now, let's continue.
 \end{addplot3operation}
 
 \begin{pgfplotskeylist}{mesh/rows=\marg{integer},mesh/cols=\marg{integer}}
-	For visualization of mesh or surface plots which need some sort of matrix input, the dimensions of the input matrix need to be known in order to visualize the plots correctly. The matrix structure may be known from end--of--row marks (empty lines as general end--of--scanline markers in the input stream) as has been described above.
+	For visualization of mesh or surface plots which need some sort of matrix input, the dimensions of the input matrix need to be known in order to visualize the plots correctly. The matrix structure may be known from end--of--row marks (|empty line|s as general end--of--scanline markers in the input stream) as has been described above.
 
 	If the matrix structure is not yet known, it is necessary to provide at least one of |mesh/rows| or |mesh/cols| where |mesh/rows| indicates the number of samples for $y$ coordinates whereas |mesh/cols| is the number of samples used for $x$ coordinates (see also |mesh/ordering|). 
 
@@ -148,6 +148,7 @@ Enough for now, let's continue.
 \end{axis}
 \end{tikzpicture}
 \end{codeexample}
+	\noindent Note that |mesh/ordering| is mandatory, even though the size of the matrix can be provided in different ways. The example above uses |empty line|s to mark scanlines. One could also say |mesh/rows=3| and omit the |empty line|s.
 
 	Consequently, |mesh/ordering=|\declaretext{y varies} provides points such that successive $m$=|mesh/rows| points form a column, i.e. the $x$ coordinate is fixed and the $y$ coordinate changes. In this sense, |y varies| is equivalent to \declaretext{colwise} ordering, it is actually a matrix transposition.
 \long\def\temporarytest{\noexpand\par}
@@ -237,7 +238,7 @@ Three dimensional line plots are generated if the input source has no matrix str
 	\end{axis}
 \end{tikzpicture}
 \end{codeexample}
-If there is no value for neither |mesh/rows| nor |mesh/cols| or if one of them is |1|, \PGFPlots\ will draw a line plot. This is also the case if there is no end--of--scanline marker (empty line) in the input stream.
+If there is no value for neither |mesh/rows| nor |mesh/cols| or if one of them is |1|, \PGFPlots\ will draw a line plot. This is also the case if there is no end--of--scanline marker (|empty line|) in the input stream.
 
 For \verbpdfref{\addplot3 expression}, this requires to set |samples y=0| to disable the generation of a mesh.
 \begin{codeexample}[]
@@ -250,6 +251,49 @@ For \verbpdfref{\addplot3 expression}, this requires to set |samples y=0| to dis
 \end{axis}
 \end{tikzpicture}
 \end{codeexample}
+\noindent The example above is a parametric plot by expression, i.e.\ it has three distinct expressions for $x$, $y$, and $z$.
+
+Line plots in three dimensions are also possible for data plots (tables). The most simple case is if you simply provide a series of three--dimensional coordinates which will be connected in the order of appearance:
+\begin{codeexample}[]
+\begin{tikzpicture}
+\begin{axis}
+\addplot3 table {
+	x   y   z
+	0   0   0
+	0.1 0.1 0.1
+	0.1 0.2 0.2
+	0.3 0.3 0.3
+	1   1   1
+	};
+\end{axis}
+\end{tikzpicture}
+\end{codeexample}
+\noindent Note that this plot implicitly has |mesh/rows=1| because it has no end--of--scanline markers (|empty line|s). If in doubt, you can set |mesh/rows=1| explicitly to tell \PGFPlots\ that you have one--dimensional data (and not a matrix).
+
+Line plots from data files are also possible if the data files only contains two coordinates -- and the third should be provided somehow. In this case, the |table/x expr| feature comes into play: it allows to combine data plots and math expressions:
+\begin{codeexample}[]
+\begin{tikzpicture}
+\begin{axis}[
+	xmin=3,xmax=6,
+	extra x ticks={4,5}, 
+	extra x tick style={xticklabel=\empty,grid=major}
+]
+\addplot3 table[x expr=4,y=a,z=b] {
+a  b
+-3 9
+-2 4
+-1 1
+0  0
+1  1
+2  4
+3  9
+};
+\addplot3[red,domain=-3:3,samples y=0] (5,x,x^2);
+\end{axis}
+\end{tikzpicture}
+\end{codeexample}
+\noindent Here, we have two plots in one axis: one data plot from a data table with just two coordinates and one parametric plot. Both denote the same two functions. For the data plot, |x expr=4| assigns the $x$ coordinate, and |y=a,z=b| define how the input columns map to coordinates. Again, the plot implicitly uses |mesh/rows=1| since there is no end--of--scanline marker. The second plot does the same with the short--handed notation |(5,x,x^2)|. It only samples one--dimensional data due to |samples y=0|. Finally, |extra x ticks| configures two additional ticks for the $x$~axis; this is used to display grid lines for these specific ticks. The |xticklabel=\empty| argument avoids overprinted $x$~tick labels at positions $x\in\{4,5\}$.
+
 
 Three dimensional line plots will usually employ lines to connect points (i.e.\ the initial |sharp plot| handler of \Tikz). The |smooth| method of \Tikz\ might also prove be an option. Note that no piecewise constant plot, comb or bar plot handler is supported for three dimensional axes.
 
@@ -685,6 +729,121 @@ The following example uses |mark=cube*| and |z buffer=sort| to place boxes at ea
 	Set |faceted color=none| to disable edge colors.
 \end{pgfplotskey}
 
+{
+\tikzset{external/figure name/.add={}{interior_colormap_}}%
+\tikzset{
+	/pdflinks/search key prefixes in/.add={}{,/pgfplots/mesh/},
+}%
+\begin{pgfplotskeylist}{%
+	mesh/interior colormap=\marg{map name}\marg{colormap specification},%
+	mesh/interior colormap name=\marg{map name}}
+	Allows to use a different |colormap| for the ``other side'' of the surface.
+
+	Each mesh has two sides: one which ``points'' to the view's origin and one which points away from it. This key allows to define a second |colormap| for the side which points away from the view's origin. The motivation is to distinguish between the outer side and the interior parts of a surface:
+\pgfplotsexpensiveexample
+\begin{codeexample}[]
+\begin{tikzpicture}
+\begin{axis}[
+  axis lines=center,
+  axis on top,
+  xlabel={$x$}, ylabel={$y$}, zlabel={$z$},
+  domain=0:1,
+  y domain=0:2*pi,
+  xmin=-1.5, xmax=1.5,
+  ymin=-1.5, ymax=1.5, zmin=0.0,
+  mesh/interior colormap=
+  	{blueblack}{color=(black) color=(blue)},
+  colormap/blackwhite, 
+  samples=10,
+  samples y=40,
+  z buffer=sort,
+ ]
+  \addplot3[surf] 
+  	({x*cos(deg(y))},{x*sin(deg(y))},{x});
+\end{axis}
+\end{tikzpicture}
+\end{codeexample}
+
+	\noindent The |interior colormap| is often the one for the ```inner side''. However, the orientation of the surface depends on its normal vectors: \PGFPlots\ computes them using the right-hand-rule. The right-hand-rule applied to a triangle means to take the first encountered point, point the thumb in direction of the second point and the first finger in direction of the third point. Then, the normal for that triangle is the third finger (i.e.\ the cross--product of the involved oriented edges). For rectangular patches, \PGFPlots\ uses the normal of one of its triangles\footnote{This may change in future versions.}. Consequently, |mesh/interior colormap| will only work if the involved patch segments are consistently oriented. 
+	
+	A patch whose normal vector points into the same direction as the view direction uses the standard |colormap name|. A patch whose normal vector points into the opposite direction (i.e.\ in direction of the viewport) uses |mesh/interior colormap|.
+
+\pgfplotsexpensiveexample
+\begin{codeexample}[]
+\begin{tikzpicture}
+\begin{axis}[
+  	hide axis,
+	xlabel=$x$,ylabel=$y$,
+	mesh/interior colormap name=hot,
+	colormap/blackwhite, 
+ ]
+  \addplot3[domain=-1.5:1.5,surf]
+  	{-exp(-x^2-y^2)};
+\end{axis}
+\end{tikzpicture}
+\end{codeexample}
+
+	The implementation of |mesh/interior colormap| works well for most examples; in particular, if the number of samples is large enough to resolve the boundary between inner and outer colormap. However, it might still produce spurious artifacts:
+\pgfplotsexpensiveexample
+\begin{codeexample}[]
+\begin{tikzpicture}
+\begin{axis}[
+	title=Example needing fine-tuning,
+	xlabel=$x$,
+	ylabel=$y$]
+\addplot3[surf,
+  mesh/interior colormap=
+    {blueblack}{color=(black) color=(blue)},
+  colormap/blackwhite, 
+  domain=0:1] 
+	{sin(deg(8*pi*x))* exp(-20*(y-0.5)^2) 
+	+ exp(-(x-0.5)^2*30 
+		- (y-0.25)^2 - (x-0.5)*(y-0.25))};
+\end{axis}
+\end{tikzpicture}
+\end{codeexample}
+	\noindent The previous example has need for improvement with respect to a couple of aspects: first, it has small overshoots near some of the meshes vertices (especially on top of the hills). These can be fixed using |miter limit=1|. Second, the boundary between blue and black is incorrect. This can be improved by means of an increased sampling density (|samples=31|). In addition, we can configure \PGFPlots\ to move the boundary between the two colormaps in favor of the blue region using |mesh/interior colormap thresh| as follows:
+\pgfplotsexpensiveexample
+\begin{codeexample}[]
+\begin{tikzpicture}
+\begin{axis}[
+	title=Example of before with fine-tuning,
+	xlabel=$x$,
+	ylabel=$y$]
+\addplot3[surf,
+  mesh/interior colormap=
+    {blueblack}{color=(black) color=(blue)},
+  % slightly increase sampling quality (was 25):
+  samples=31,    
+  % avoids overshooting corners:
+  miter limit=1, 
+  % move boundary between inner and outer:
+  mesh/interior colormap thresh=0.1,
+  colormap/blackwhite, 
+  domain=0:1] 
+	{sin(deg(8*pi*x))* exp(-20*(y-0.5)^2) 
+	+ exp(-(x-0.5)^2*30 
+		- (y-0.25)^2 - (x-0.5)*(y-0.25))};
+\end{axis}
+\end{tikzpicture}
+\end{codeexample}
+	\noindent This improves the display.
+	\paragraph{Call for volunteers:} it would be nice if the fine--tuning of these keys would be unnecessary. If someone has well--founded suggestions (like knowledge and perhaps exhaustive experiments) on how to improve the feature, let me know.
+
+	Note that |mesh/interior colormap| cannot be combined with |mesh/refines| currently.
+	
+	Note that |mesh/interior colormap| will increase compilation times due to the computation of normal vectors.
+\end{pgfplotskeylist}
+
+\begin{pgfplotskey}{mesh/interior colormap thresh=\marg{Number between $-1.0$ and $+1.0$} (initially 0)}
+	A threshold which moves the boundary between the |colormap| and |interior colormap| in favor of |colormap| (if the value is negative) or in favor of |interior colormap| (if the value is positive). 
+	
+	The extreme value $-1$ essentially deactivates |interior colormap| whereas the other extreme $+1$ deactivates |colormap|.
+
+	See above for an example.
+\end{pgfplotskey}
+}%
+
 \begin{pgfplotskey}{surf shading/precision=\mchoice{pdf,postscript,ps} (initially postscript)}
 	A key to configure how the low level driver for |shader=interp| writes its data. The choice |pdf| uses 32~bit binary coordinates (which is lossless). The resulting |.pdf| files appear to be correct, but they can't be converted to postscript -- the converter software always complains about an error. 
 
@@ -742,7 +901,7 @@ As mentioned, you can use any of the \PGFPlots\ input methods as long as it yiel
 
 	What happens behind the scenes is that \PGFPlots\ takes the input matrix and writes all encountered coordinates to a temporary file, including the end--of--scanline markers. Then, it generates a small |gnuplot| script and invokes |gnuplot| to compute the contour coordinates, writing everything into a temporary output file. Afterwards, it includes |gnuplot|'s output file just as if you'd write |\addplot3[contour prepared] file |\marg{temporaryfile}|;|.
 
-	All this invocation of |gnuplot|, including input/output file management is transparent to the user. It only requires two things: first of all, it requires matrix data as input\footnote{Note that \texttt{contour gnuplot} processes the input stream only once. Consequently, the temporary file will contain only information which was available before the first point has been seen. The example above works because it contains empty lines as end-of-scanline markers. If you do not provide such markers, you may need to provide two of the three options \texttt{mesh/rows}, \texttt{mesh/cols}, or \texttt{mesh/num points}.}. Second, it requires you to enable system calls. Consider the documentation for \verbpdfref{plot gnuplot} for how to enable system calls.
+	All this invocation of |gnuplot|, including input/output file management is transparent to the user. It only requires two things: first of all, it requires matrix data as input\footnote{Note that \texttt{contour gnuplot} processes the input stream only once. Consequently, the temporary file will contain only information which was available before the first point has been seen. The example above works because it contains |empty line|s as end-of-scanline markers. If you do not provide such markers, you may need to provide two of the three options \texttt{mesh/rows}, \texttt{mesh/cols}, or \texttt{mesh/num points}.}. Second, it requires you to enable system calls. Consider the documentation for \verbpdfref{plot gnuplot} for how to enable system calls.
 
 	There are several fine-tuning parameters of the input/output file management, and it is even possible to invoke different programs than |gnuplot| (even |matlab|). These details are discussed at the end of this section, see below at page~\pageref{key:pgfplots:contour:gnuplot}.
 \end{plottype}
@@ -768,11 +927,36 @@ As mentioned, you can use any of the \PGFPlots\ input methods as long as it yiel
 	Note that |contour/number| has no effect on |contour prepared|.
 \end{pgfplotskey}
 
+\begin{pgfplotskey}{contour/levels=\marg{list of levels} (initially empty)}
+	Configures the number of contour lines which should be produced by any external contouring algorithm by means of a list of discrete levels.
+\pgfplotsexpensiveexample
+\begin{codeexample}[]
+\begin{tikzpicture}
+    \begin{axis}[
+        title={$x \exp(-x^2-y^2)$},
+		domain=-2:2,
+		enlargelimits,
+        view={0}{90},
+    ]
+   \addplot3[
+     contour gnuplot={levels={-0.1,-0.2,-0.6}},
+   	 thick]
+          {exp(0-x^2-y^2)*x};
+    \end{axis}
+\end{tikzpicture}
+\end{codeexample}
+	It is also possible to change the |/pgf/number format| settings, see the documentation for the |contour/every contour label| style below.
+
+	This key has higher precedence than |contour/number|, i.e.\ if both are given, |contour/levels| will be active.
+
+	Note that |contour/levels| has no effect on |contour prepared|.
+\end{pgfplotskey}
+
 \begin{plottype}[/pgfplots]{contour prepared=\textcolor{black}{\marg{{\normalfont options with `\texttt{contour/}' prefix}}}}
 	A plot handler which expects already computed contours on input and visualizes them. It cannot compute contours on its own.
 
 	\begin{pgfplotskey}{contour prepared format=\mchoice{standard,matlab} (initially standard)}
-	There are two accepted input formats. The first is a long sequence of coordinates of the form $(x,y,z)$ where all successive coordinates with the same $z$ value make up a contour level (this is only part of complete truth, see below). The end--of--scanline markers (empty lines in the input) mark an interruption in one contour level.
+	There are two accepted input formats. The first is a long sequence of coordinates of the form $(x,y,z)$ where all successive coordinates with the same $z$ value make up a contour level (this is only part of complete truth, see below). The end--of--scanline markers (|empty line|s in the input) mark an interruption in one contour level.
 
 	For example, |contour prepared format=standard| could be\footnote{This is actually the output from our \texttt{\textbackslash addplot3[contour gnuplot] coordinates} example from above.}
 \begin{codeexample}[]
@@ -803,7 +987,7 @@ As mentioned, you can use any of the \PGFPlots\ input methods as long as it yiel
 	\end{axis}
 \end{tikzpicture}
 \end{codeexample}
-	\noindent Note that the empty lines are not necessary in this case: empty lines make only a difference if they occur within the same contour level (i.e. if the same $z$ value appears above and below of them).
+	\noindent Note that the |empty line|s are not necessary in this case: |empty line|s make only a difference if they occur within the same contour level (i.e. if the same $z$ value appears above and below of them).
 		
 		The choice |contour prepared format=matlab| expects two--dimensional input data where the contour level and the number of elements of the contour line are provided as $x$ and $y$ coordinates, respectively, of a leading point. Such a format is used by |matlab|'s contour algorithms, i.e.\ it resembles the output of the matlab commands |data=contour(...)| or |data=contourc(...)|.
 
@@ -989,7 +1173,7 @@ save 'exporteddata.dat' data -ASCII
 
 		The choice |false| writes no such markers at all. In this case, |script| should contain |mesh/rows| and/or |mesh/cols|.
 
-		The choice |if in input| generates end-of-scanline markers if they appear in the provided input data (either as empty lines or if the user provided at least two of the three options |mesh/rows|, |mesh/cols|, or |mesh/num points| explicitly).
+		The choice |if in input| generates end-of-scanline markers if they appear in the provided input data (either as |empty line|s or if the user provided at least two of the three options |mesh/rows|, |mesh/cols|, or |mesh/num points| explicitly).
 
 		The choice |required| works like |if in input|, but it will fail unless there really was such a marker.
 
@@ -997,9 +1181,13 @@ save 'exporteddata.dat' data -ASCII
 	\end{pgfplotskey}
 
 	\begin{pgfplotskey}{contour external/script=\marg{Code for external program} (initially empty)}
-		Provides template code to generate a script for the external program. Inside of \meta{Code for external program}, the placeholder |\infile| will expand to the temporary input file and |\outfile| to the temporary output file. The temporary |\infile| is a text file containing one point on each line, in the form |x y meta meta|, separated by tabstops. Whenever a scanline is complete, an empty line is issued (but only if these scanline markers are found in the input stream as well). The complete set of scanlines forms a matrix. There are no additional comments or extra characters in the file. The macro |\ordering| will expand to |0| if the matrix is stored in |mesh/ordering=x varies| and |\ordering| will be |1| for |mesh/ordering=y varies|.
+		Provides template code to generate a script for the external program. Inside of \meta{Code for external program}, the placeholder |\infile| will expand to the temporary input file and |\outfile| to the temporary output file. The temporary |\infile| is a text file containing one point on each line, in the form |x y meta meta|, separated by tabstops. Whenever a scanline is complete, an |empty line| is issued (but only if these scanline markers are found in the input stream as well). The complete set of scanlines forms a matrix. There are no additional comments or extra characters in the file. The macro |\ordering| will expand to |0| if the matrix is stored in |mesh/ordering=x varies| and |\ordering| will be |1| for |mesh/ordering=y varies|.
 
 		Inside of \meta{Code for external program}, you can also use |\pgfkeysvalueof{/pgfplots/mesh/rows}| and |\pgfkeysvalueof{/pgfplots/mesh/cols}|; they expand to the matrix' size. Similarly, |\pgfkeysvalueof{/pgfplots/mesh/num points}| expands to the total number of points.
+
+		Inside of \meta{Code for external program}, the macro \declareandlabel{\thecontournumber} is defined to be the value |\pgfkeysvalueof{/pgfplots/contour/number}| and \declareandlabel{\thecontourlevels} contains the value |\pgfkeysvalueof{/pgfplots/contour/levels}|. These two macros simplify conditional code.
+
+		If you need one of the characters [\verb!"|;:#'`!] and some macro package already uses the character for other purposes, you can prepend them with a backslash, i.e. write |\"| instead of |"|.
 	\end{pgfplotskey}
 
 	\begin{pgfplotskey}{contour external/script extension=\marg{extension} (initially script)}
@@ -1019,7 +1207,11 @@ save 'exporteddata.dat' data -ASCII
 		contour external={
 			script={
 				unset surface; 
-				set cntrparam levels \pgfkeysvalueof{/pgfplots/contour/number};
+				\ifx\thecontourlevels\empty
+				set cntrparam levels \thecontournumber;
+				\else
+				set cntrparam levels discrete \thecontourlevels;
+				\fi
 				set contour;
 				set table \"\outfile\"; 
 				splot \"\infile\";
diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.axis-addplot.tex b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.axis-addplot.tex
index 2cbbc623b96..b4a4a6f5296 100644
--- a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.axis-addplot.tex
+++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.axis-addplot.tex
@@ -222,12 +222,56 @@ Thus, you can combine |cycle list| and \meta{options}.
 The distinction is as follows: |\addplot  ...| (without options) lets \PGFPlots\ select colors, markers and linestyles automatically (using |cycle list|). The variant |\addplot+|\oarg{option}| ...| will use the same automatically determined styles, but in addition it uses \meta{options}. Finally, |\addplot|\oarg{options} (without the |+|) uses only the manually provided \meta{options}.
 \end{addplot+}
 
+\begin{pgfplotskey}{empty line=\mchoice{auto,none,scanline,jump} (initially auto)}
+	Controls how empty lines in the input coordinate stream are to be interpreted. You should ensure that you have |\pgfplotsset{compat=1.4}| or newer in your preamble and leave this key at its default |empty line=auto|.
+
+	Empty lines can occur between the coordinates of |\addplot coordinates| or successive rows of the data file input routines |\addplot table| (and |\addplot file|).
+
+	The choice \declaretext{auto} checks if the current plot type is |mesh| or |surf|. If so, it uses |scanline|. If the current plot type is some other plot type (like a standard line plot), it uses |jump|. Note that the value \texttt{auto} for non-mesh plots results in \texttt{none} if |compat=1.3| or older is used. In other words: you have to write |\pgfplotsset{compat=1.4}| or newer to let \PGFPlots\ interpret empty lines as |jump| in standard line plots:
+\begin{codeexample}[]
+\begin{tikzpicture}
+	\begin{axis}[tiny,
+		title={Ignored: compat=1.3},
+		compat=1.3]
+	\addplot table {
+	A B
+	0 0
+	1 1
+
+	1 2
+	2 2
+	};
+	\end{axis}
+\end{tikzpicture}
+\begin{tikzpicture}
+	\begin{axis}[tiny,
+		title={Jump: compat=1.4},
+		compat=1.4]
+	\addplot table {
+	A B
+	0 0
+	1 1
+
+	1 2
+	2 2
+	};
+	\end{axis}
+\end{tikzpicture}
+\end{codeexample}
+
+	The choice \declaretext{scanline} is only useful for |mesh| and |surf|: it is used to decode a matrix from a coordinate stream. If an empty line occurs once every $N$ data points, the ``scanline'' length is~$N$. This information, together with |mesh/ordering| and the total number of points, allows to deduce the matrix size. However, the distance between empty lines has to be consistent: if the first two empty lines have a distance of~$2$ and the next comes after~$5$, \PGFPlots\ will ignore the information and will expect explicit matrix sizes using |mesh/rows| and/or |mesh/cols|. The choice |scanline| is ignored if |mesh input=patches|. It has no effect for other plot types.
+
+	The choice \declaretext{none} will silently discard any empty line in the input stream.
+
+	The choice \declaretext{jump} tells \PGFPlots\ to generate a jump.
+\end{pgfplotskey}
+
 \subsubsection{Coordinate Lists}
 \label{pgfplots:providing:input}
 
 \begin{addplotoperation}[]{coordinates}{\marg{coordinate list}}
 \label{pgfplots:addplot:coordinates}
-The `|plot coordinates|' command is like that provided by \Tikz\ and reads its input data from a sequence of point coordinates, encapsulated in round braces.
+The `|\addplot coordinates|' command is like that provided by \Tikz\ and reads its input data from a sequence of point coordinates, encapsulated in round braces.
 \begin{codeexample}[]
 \begin{tikzpicture}
 \begin{axis}
@@ -239,7 +283,10 @@ The `|plot coordinates|' command is like that provided by \Tikz\ and reads its i
 \end{axis}
 \end{tikzpicture}
 \end{codeexample}
-\noindent The coordinates can be numbers, but they can also contain mathematical expressions like |sin(0.5)| or |\h*8| (assuming you defined |\h| somewhere). However, expressions which involve round braces need to be encapsulated in a further set of curly braces, for example |({sin(0.5)},{cos(0.1)})|.
+
+	You should \empty{only} use this input format if you have short diagrams and you want to provide mathematical expressions for each of the involved coordinates. Any data plots are typically easier to handle using a table format and |\addplot table|.
+
+The coordinates can be numbers, but they can also contain mathematical expressions like |sin(0.5)| or |\h*8| (assuming you defined |\h| somewhere). However, expressions which involve round braces need to be encapsulated in a further set of curly braces, for example |({sin(0.5)},{cos(0.1)})|.
 
 You can also supply error coordinates (reliability bounds) if you are interested in error bars. Simply append the error coordinates with `\declareandlabel{+-} \parg{ex,ey}' (or |+- |\parg{ex,ey,ez}) to the associated coordinate:
 \begin{codeexample}[]
@@ -280,6 +327,8 @@ Furthermore, |coordinates| allows to define ``meta data'' for each coordinate. T
 \end{tikzpicture}
 \end{codeexample}
 Please refer to the documentation of |point meta| on page~\pageref{pgfplots:point:meta} for more information about per point meta data.
+
+	The coordinate stream can contain |empty line|s to tell \PGFPlots\ that the function has jumps. To use it, simply insert an empty line (and ensure that you have |\pgfplotsset{compat=1.4}| or newer in your preamble). See the documentation of |empty line| for details.
 \end{addplotoperation}
 
 \begin{pgfplotskey}{plot coordinates/math parser=\mchoice{true,false} (initially true)}
@@ -288,61 +337,14 @@ Please refer to the documentation of |point meta| on page~\pageref{pgfplots:poin
 	It is necessary to disable |plot coordinates/math parser| if you use some sort of symbolic transformations (i.e. text coordinates).
 \end{pgfplotskey}
 
-\subsubsection{Reading Coordinates From Files}
-
-\begin{addplotoperation}[]{file}{\marg{name}}
-\label{pgfplots:addplot:file}
-\PGFPlots\ supports two ways to read plot coordinates of external files, and one of them is similar to the \Tikz-command `|plot file|'. It is to be used like
-\begin{codeexample}[code only]
-\addplot file {datafile.dat};
-\end{codeexample}
-where \meta{name} is a text file with at least two columns which will be used as $x$ and $y$ coordinates. Lines starting with `|%|' or `|#|' are ignored. Such files are often generated by \textsc{gnuplot}:
-\begin{codeexample}[code only]
-#Curve 0, 20 points
-#x y type
-0.00000 0.00000 i
-0.52632 0.50235 i
-1.05263 0.86873 i
-1.57895 0.99997 i
-...
-9.47368 -0.04889 i
-10.00000 -0.54402 i
-\end{codeexample}
-This listing has been copied from~\cite[section~16.4]{tikz}.
-
-Plot file accepts one optional argument,
-
-\begin{codeexample}[code only]
-\addplot file[skip first] {datafile.dat};
-\end{codeexample}
-
-\noindent
-which allows to skip over a non-comment header line. This allows to read the same input files as |plot table| by skipping over column names. Please note that comment lines do not count as lines here.
-
-The input method |plot file| can also read meta data for every coordinate. As already explained for |plot coordinates| (see above), meta data can be used to change colors or other style parameters for every marker separately. Now, if |point meta| is set to |explicit| or to |explicit symbolic| and the input method is |plot file|, one further element will be read from disk -- for every line. Meta data is always the last element which is read. See page~\pageref{pgfplots:scatter:src} for information and examples about per point meta data and page~\pageref{pgfplots:scatterclasses} for an application example using |scatter/classes|.
-
-
-Plot file is very similar to |plot table|: you can achieve the same effect with
-\begin{codeexample}[code only]
-\addplot table[x index=0,y index=1,header=false] {datafile.dat};
-\end{codeexample}
-\noindent Due to its simplicity, |plot file| is slightly faster while |plot table| allows higher flexibility.
-
-Technical note: every opened file will be protocolled into your log file.
-\end{addplotoperation}
-
-\begin{pgfplotskeylist}{%
-	plot file/skip first=\mchoice{true,false} (initially false),%
-	plot file/ignore first=\mchoice{true,false} (initially false)}
-	The two keys can be provided as arguments to |\addplot file[|\meta{options}|] |\marg{filename}|;| to skip the first non-comment entry in the file. They are equivalent.
-	If you provide them in this context, the prefix |/pgfplots/plot file| can be omitted.
-\end{pgfplotskeylist}
 
 \subsubsection{Reading Coordinates From Tables}
 
-\begin{addplotoperation}[]{table}{\oarg{column selection}\marg{file}}
+\begin{addplotoperation}[]{table}{\oarg{column selection}\marg{file or inline table}}
 \label{pgfplots:addplot:table}
-The use of `|plot table|' is similar in spirit to `|plot file|', but its flexibility is higher. Given a data file like
+This input method is the main input format for any data--based function. It accepts either a file containing data or an inline table provided in curly braces.
+
+Given a data file like
 \begin{codeexample}[code only]
 dof     L2              Lmax            maxlevel
 5       8.31160034e-02  1.80007647e-01  2
@@ -470,8 +472,12 @@ Summary and remarks:
 
 	One application (with several examples how to use this syntax) is line fitting with |create col/linear regression|, see Section~\ref{sec:linefitting} for details.
 
+	\item
+	The table can contain |empty line|s to tell \PGFPlots\ that the function has jumps. To use it, simply insert an empty line (and ensure that you have |\pgfplotsset{compat=1.4}| or newer in your preamble). See the documentation of |empty line| for details.
 	\item Technical note: every opened file will be protocolled into your log file.
+
 \end{itemize}
+
 \end{addplotoperation}
 
 \subsubsection*{Keys To Configure Table Input}
@@ -1140,9 +1146,9 @@ The following list of keys configure |\addplot graphics|. Note that the common p
 
 The |plot graphics| tool of \PGFPlots\ allows to include three--dimensional external graphics: it generates a three--dimensional axis on its own. The idea is to provide a graphics (without descriptions) and use \PGFPlots\ to overlay a three--dimensional axis automatically. This allows to maintain document consistency (making it unnecessary to use different programs within the same document). 
 
-You are probably guessing how this is possible. Well, it needs more user input than two--dimensional external graphics. The cost to include external three dimensional images into \PGFPlots\ is essentially control of a graphics program like |gimp|: you need to identify the 3D coordinates of a couple of points in your image. \PGFPlots\ will then squeeze the graphics correctly, and it reconfigures the axis to ensure a correct display of the result.
+You are probably wondering how this is possible. Well, it needs more user input than two--dimensional external graphics. The cost to include external three dimensional images into \PGFPlots\ is essentially control of a graphics program like |gimp|: you need to identify the 3D coordinates of a couple of points in your image. \PGFPlots\ will then squeeze the graphics correctly, and it reconfigures the axis to ensure a correct display of the result.
 
-\paragraph{Warning:} The feature is only 95\% stable yet and may need some more testing. Use at your own risk.
+\paragraph{Matlab versus other tools:} Although this section is based on Matlab images, the technique to import three--dimensional graphics is independent of Matlab. Thus, if you have a different tool, you need to read all that follows. However, users of Matlab \emph{can use a simplified export mechanism} which has been contributed by J\"urnjakob Dugge. Please skip to section~\ref{sec:plotgraphics3d:matlabscript} on page~\pageref{sec:plotgraphics3d:matlabscript} if you use Matlab to generate the graphics files (although you may want to take a brief look at the examples on the following pages to learn about flexibility or legends).
 
 Let's start with two examples. Suppose you generate a surface plot with Matlab and want to include it in \PGFPlots. We have the matlab script
 \begin{codeexample}[code only]
@@ -1228,7 +1234,7 @@ Once these four point coordinates are gathered, we find Matlab's surface plot in
 \end{axis}
 \end{tikzpicture}
 \end{codeexample}
-\noindent \PGFPlots\ uses the four input points to compute appropriate |x|, |y| and |z| unit vectors (and the origin in graphics coordinates). These four vectors (with two components each) can be computed as a result of a linear system of size $8\times 8$, that is why you need to provide four input points (each has two coordinates). \PGFPlots\ computes the unit vectors of the imported graphics, and afterwards it rescales the result such that it fits into the specified |width| and |height|. This rescaling respects the |unit vector ratio| (more precisely, it uses |scale mode=scale uniformly| instead of |scale mode=stretch to fill|). Consequently, the freedom to change the view of a three--dimensional axis which contains a projected graphics is considerably smaller than before. Surprisingly, you can still change axis limits and |width| and |height| -- \PGFPlots\ will take care of a correct display of your imported graphics.
+\noindent \PGFPlots\ uses the four input points to compute appropriate |x|, |y| and |z| unit vectors (and the origin in graphics coordinates). These four vectors (with two components each) can be computed as a result of a linear system of size $8\times 8$, that is why you need to provide four input points (each has two coordinates). \PGFPlots\ computes the unit vectors of the imported graphics, and afterwards it rescales the result such that it fits into the specified |width| and |height|. This rescaling respects the |unit vector ratio| (more precisely, it uses |scale mode=scale uniformly| instead of |scale mode=stretch to fill|). Consequently, the freedom to change the view of a three--dimensional axis which contains a projected graphics is considerably smaller than before. Surprisingly, you can still change axis limits and |width| and |height| -- \PGFPlots\ will take care of a correct display of your imported graphics. Since version~1.6, you can also change |zmin| and/or |zmax| -- \PGFPlots\ will respect your changes as good as it can.
 
 Here is a further example. Suppose we are given the three--dimensional visualization
 
@@ -1265,7 +1271,7 @@ It has been generated by matlab (I only added transparency to the background wit
 \end{codeexample}
 \noindent Note that I provided \emph{five} three--dimensional coordinates here, but the last entry has no |=>| mapping to two--dimensional canvas coordinates. Thus, it is only used to update the bounding box (see the reference manual for the |points| key for details).
 
-The example above is clipped because \PGFPlots\ could not rescale the graphics automatically. Changing the ratio between |width| and |height| improves the display:
+The example above leads to a relatively small image and much ``empty space''. This is due to the |scale mode=scale uniformly| implementation of \PGFPlots: it decided that the best way is to enlarge the involved axis limits. Here, ``best way'' means to satisfy |width|/|height| constraints combined with minimally enlarged (never shrinked) axis limits. The remaining degrees of freedom are |width|, |height|, and the axis limits. In our case, changing the ratio between |width| and |height| improves the display:
 
 \begin{codeexample}[]
 \begin{tikzpicture}
@@ -1291,7 +1297,11 @@ The example above is clipped because \PGFPlots\ could not rescale the graphics a
 \end{axis}
 \end{tikzpicture}
 \end{codeexample}
-\noindent What happens is that \PGFPlots\ \emph{only} rescales the $z$ axis. This has the effect that the axes are all scaled by a single scaling factor (using |scale mode=scale uniformly|), skewing is avoided. In this approach, you can only modify |width| and |height| to provide more freedom.
+\noindent What happens is that \PGFPlots\ selects a \emph{single} scaling factor which is applied to all units as they have been deduced from the |points| key. This ensures that the imported graphics fits correctly into the axis. In addition, \PGFPlots\ does its best to satisfy the remaining constraints. 
+
+The complete description of how \PGFPlots\ scales the axis can be found in the documentation for |scale mode=scale uniformly|. Here is just a brief summary: \PGFPlots\ assumes that the prescribed |width| and |height| have to be satisfied. To this end, it rescales the projected unit vectors (i.e.\ the space which is taken up for each unit in $x$, $y$, and $z$) and it can modify the axis limits. In the default configuration |scale uniformly strategy=auto|, \PGFPlots\ will \emph{never} shrink axis limits.  
+
+\paragraph{Compatibility remark:} Note that the scaling capabilities have been improved for \PGFPlots\ version~1.6. In previous versions, only |scale uniformly strategy=change vertical limits| was available which lead to clipped axes. In short: please consider writing |\pgfplotsset{compat=1.6}| or newer into your document to benefit from the improved scaling. If you have |\pgfplotsset{compat=1.5}| or older, the outcome for |\addplot3 graphics| will be different.
 
 We consider a third example which has been generated by the Matlab code
 \begin{codeexample}[code only]
@@ -1342,15 +1352,126 @@ We proceed as before and collect four points, each with 3d logical coordinates (
 \end{axis}
 \end{tikzpicture}
 \end{codeexample}
+\noindent Note that it has non-standard data aspect ratio which is respected by \PGFPlots\ automatically.
+
+
+\subsubsection*{External Three-Dimensional Graphics and Matlab}
+
+\textit{An extension by J\"urnjakob Dugge}
+\vskip\baselineskip
+
+\noindent
+\label{sec:plotgraphics3d:matlabscript}
+The procedure to map three--dimensional logical coordinates to two--dimensional canvas coordinates is tedious.
+
+J\"urnjakob Dugge contributed a script which does most of the logic and your work is reduced to a copy--paste job. With his permission, I post the contribution here. 
+
+The idea is to start a simple script which \emph{records} mappings for any coordinates which have been clicked by the user. It works as follows:
+
+\begin{enumerate}
+	\item Create the Matlab plot, say, using
+\begin{codeexample}[code only]
+hist3(randn(10000,2)) % some random data
+set(get(gca,'child'),'FaceColor','interp','CDataMode','auto'); % colors
+% make sure the "print" paper format is the same as the screen paper format:
+set(gcf,'PaperPositionMode','auto') 
+\end{codeexample}
+
+	\item Save the following code as |pgfplotscsconversion.m|:
+\begin{codeexample}[code only]
+function pgfplotscsconversion
+
+% Hook into the Data Cursor "click" event
+h = datacursormode(gcf);
+set(h,'UpdateFcn',@myupdatefcn,'SnapToDataVertex','off');
+datacursormode on
 
-\paragraph{Technical points:} the following issues might arise while working with \verbpdfref{\addplot3} |graphics|:
+% select four points in plot using mouse
+
+% The function that gets called on each Data Cursor click
+function [txt] = myupdatefcn(obj,event_obj)
+
+% Get the screen resolution, in dots per inch
+dpi = get(0,'ScreenPixelsPerInch');
+
+% Get the click position in pixels, relative to the lower left of the
+% screen
+screen_location=get(0,'PointerLocation');
+
+% Get the position of the plot window, relative to the lower left of
+% the screen
+figurePos = get(gcf,'Position');
+
+% Get the data coordinates of the cursor
+pos = get(event_obj,'Position');
+
+% Format the data and figure coordinates. The factor "72.27/dpi" is
+% necessary to convert from pixels to TeX points (72.27 poins per inch)
+display(['(',num2str(pos(1)),',',num2str(pos(2)),',',num2str(pos(3)),') => (', ...
+   num2str((screen_location(1)-figurePos(1))*72.27/dpi),',', ...
+   num2str((screen_location(2)-figurePos(2))*72.27/dpi),')'])
+
+% Format the tooltip display
+txt = {['X: ',num2str(pos(1))],['Y: ',num2str(pos(2))],['Z: ',num2str(pos(3))]};
+\end{codeexample}
+	
+	Run |pgfplotscsconversion|, click on four points in your plot. Preferably select non-colinear points near the edges of the plot. Copy and paste the four lines that were written to the Matlab command window.
+
+	Make sure that the first two points have different $X$ and $Y$ values on screen (i.e.\ image canvas coordinates).
+	\item Export the plot as an image
+\begin{codeexample}[code only]
+axis off
+print -dpng matlabout -r400 % PNG called "matlabout.png" with 400 dpi resolution
+\end{codeexample}
+
+Note that |pdf| output of Matlab is clumsy. It might be best to export to |eps| first, followed by a conversion from |eps| to |pdf|.
+
+\emph{If} you really want to use |pdf| output of Matlab, you may need to set the paper size to match the figure size by yourself, since the PDF driver does not automatically adjust the size:
+
+\begin{codeexample}[code only]
+% It might be better to use print -depsc  followed by epstopdf. 
+% Use this if you (really) want to use print -dpdf:
+currentScreenUnits=get(gcf,'Units')     % Get current screen units
+currentPaperUnits=get(gcf,'PaperUnits') % Get current paper units
+set(gcf,'Units',currentPaperUnits)      % Set screen units to paper units
+plotPosition=get(gcf,'Position')        % Get the figure position and size
+set(gcf,'PaperSize',plotPosition(3:4))  % Set the paper size to the figure size
+set(gcf,'Units',currentScreenUnits)     % Restore the screen units
+
+print -dpdf matlabout      % PDF called "matlabout.pdf"
+\end{codeexample}
+\item Include the image in your \PGFPlots\ axis. If you selected points on the plot corners, your |xmin|, |xmax|, |ymin| and |ymax| should be set automatically, otherwise you may want to provide those yourself. Also, adjustments of |width| and |height| might be of interest to get the right vertical placement of the plot. Consider changing |zmin| and/or |zmax| to fit your needs (preferrably only one of them; otherwise \PGFPlots\ may be unable to fix the |height|).
+\end{enumerate}
+
+This contribution is from
+
+\noindent
+\url{http://tex.stackexchange.com/questions/52987/3-dimensional-histogram-in-pgfplots} .
+
+
+
+\subsubsection*{Summary: External Three-Dimensional Graphics}
+As has been shown in the previous sections, \verbpdfref{\addplot3} |graphics| allows to include three-dimensional graphics and \PGFPlots\ overlays a flexible axis with all its power. The cost to do so is
+\begin{enumerate}
+	\item collect both logical three--dimensional coordinates \emph{and} image--internal two--dimensional coordinates for \emph{four points} of your graphics.
+
+	In Matlab, this can be simplified by the tool mentioned on page~\pageref{sec:plotgraphics3d:matlabscript}.
+
+	\item If your axes form a right--handed--coordinate system, that is all. If not, also add |x dir=reverse| for any reversed axes.
+\end{enumerate}
+
+\noindent
+Consider the following list of you encounter problems while working with \verbpdfref{\addplot3} |graphics|:
 \begin{itemize}
 	\item It must be possible to deduce the origin and the three (two--dimensional) unit vectors from the four provide |points|; otherwise the algorithm will fail. 
 	
 	The algorithm should detect any deficiancies. However, if you encounter strange ``Dimension too large'' messages here, you can try other arguments in |points|. Take a look into your log file, it will probably indicate the source of problems (or use the |debug| key).
 
 	\item \PGFPlots\ uses the first two points to squeeze the graphics into the desired coordinates (which implies that they should not have the same canvas $X$ or $Y$ coordinates). It verifies that the remaining |points| arguments are projected correctly.
-	\item The resulting scaling by means of |scale mode=scale uniformly| will only rescale the $z$ axis. You may need to adjust |width| and |height| (both of them) if the result is unsatisfactory (see the example above).
+	\item The resulting scaling by means of |scale mode=scale uniformly| will try to satisfy all scaling constraints. You can change these constraints by modifying |width|, |height|, |xmin|, |xmax|, |ymin|, |ymax|, |zmin|, |zmax| and/or any combination of these parameters. See also |unit rescale keep size| which controls the flexibility of limit changes. There is also a key |scale uniformly strategy| which allows to select a different scaling strategy.
+	 
+	\item The image should have a ``right--handed--coordinate system'': you should be able to take your right hand, point your thumb in direction of the $x$ axis, your first finger in direction of~$y$, and your second finger in direction of the $z$~axis. If that is impossible, once of your axes is reversed and you need to communicate that to \PGFPlots\ explicitly by means of the |x dir=reverse| key (and its variants).
+
 	\item There is a |debug| key to investigate what the algorithm is doing:
 \begin{pgfplotskey}{plot graphics/debug=\marg{true,false} (initially false)}
 	If you provide |\addplot3 graphics[debug,points={...}]|, \PGFPlots\ will provide debug information onto your terminal and into the logfile. It will also generate extra files containing the determined unit vectors and the linear system used to derive them (one such file for every |\addplot3 graphics| statement, the filename will be the graphics file name and |.dat| appended).
@@ -1360,4 +1481,58 @@ We proceed as before and collect four points, each with 3d logical coordinates (
 \end{itemize}
 }
 
+\subsubsection{Reading Coordinates From Files}
+
+\begin{addplotoperation}[]{file}{\marg{name}}
+\label{pgfplots:addplot:file}
+\paragraph{Deprecation note:} If you have data files, you should generally use |\addplot table|. The input type |\addplot file| is almost the same, but considerably less powerful. It is only kept for backwards compatibility.
+
+
+The |\addplot file| input mechanism is similar to the \Tikz-command `|plot file|'. It is to be used like
+\begin{codeexample}[code only]
+\addplot file {datafile.dat};
+\end{codeexample}
+where \meta{name} is a text file with at least two columns which will be used as $x$ and $y$ coordinates. Lines starting with `|%|' or `|#|' are ignored. Such files are often generated by \textsc{gnuplot}:
+\begin{codeexample}[code only]
+#Curve 0, 20 points
+#x y type
+0.00000 0.00000 i
+0.52632 0.50235 i
+1.05263 0.86873 i
+1.57895 0.99997 i
+...
+9.47368 -0.04889 i
+10.00000 -0.54402 i
+\end{codeexample}
+This listing has been copied from~\cite[section~16.4]{tikz}.
+
+Plot file accepts one optional argument,
+
+\begin{codeexample}[code only]
+\addplot file[skip first] {datafile.dat};
+\end{codeexample}
+
+\noindent
+which allows to skip over a non-comment header line. This allows to read the same input files as |plot table| by skipping over column names. Please note that comment lines do not count as lines here.
+
+The input method |plot file| can also read meta data for every coordinate. As already explained for |plot coordinates| (see above), meta data can be used to change colors or other style parameters for every marker separately. Now, if |point meta| is set to |explicit| or to |explicit symbolic| and the input method is |plot file|, one further element will be read from disk -- for every line. Meta data is always the last element which is read. See page~\pageref{pgfplots:scatter:src} for information and examples about per point meta data and page~\pageref{pgfplots:scatterclasses} for an application example using |scatter/classes|.
+
+
+Plot file is very similar to |plot table|: you can achieve the same effect with
+\begin{codeexample}[code only]
+\addplot table[x index=0,y index=1,header=false] {datafile.dat};
+\end{codeexample}
+\noindent Due to its simplicity, |plot file| is slightly faster while |plot table| allows higher flexibility.
+
+Technical note: every opened file will be protocolled into your log file.
+
+	The file can contain |empty line|s to tell \PGFPlots\ that the function has jumps. To use it, simply insert an empty line (and ensure that you have |\pgfplotsset{compat=1.4}| or newer in your preamble). See the documentation of |empty line| for details.
+\end{addplotoperation}
+
+\begin{pgfplotskeylist}{%
+	plot file/skip first=\mchoice{true,false} (initially false),%
+	plot file/ignore first=\mchoice{true,false} (initially false)}
+	The two keys can be provided as arguments to |\addplot file[|\meta{options}|] |\marg{filename}|;| to skip the first non-comment entry in the file. They are equivalent.
+	If you provide them in this context, the prefix |/pgfplots/plot file| can be omitted.
+\end{pgfplotskeylist}
 }%
diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.axisdescription.tex b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.axisdescription.tex
index 0e7dc2f4705..6f805573d05 100644
--- a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.axisdescription.tex
+++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.axisdescription.tex
@@ -1617,6 +1617,8 @@ In some applications, more than one $y$ axis is used if the $x$ range is the sam
 
 \begin{codeexample}[]
 \begin{tikzpicture}
+  % let both axes use the same layers
+  \pgfplotsset{set layers}
   \begin{axis}[
     scale only axis,
     xmin=-5,xmax=5,
@@ -1640,6 +1642,7 @@ In some applications, more than one $y$ axis is used if the $x$ range is the sam
 \begin{enumerate}
 	\item Scaling. You should set |scale only axis| because this forces equal dimensions for both axis, without respecting any labels.
 	\item Same $x$ limits. You should set those limits explicitly.
+	\item You need to tell \PGFPlots\ that it should share the same graphics layers for both axes. In this case, \PGFPlots\ will draw plots of the first axis and of the second axis onto the same layer. It will also draw background(s) into the background layer and descriptions into the foreground layer. Use the key |\pgfplotsset{set layers}| in front of the first axis to prepare the complete picture for layered graphics.
 \end{enumerate}
 You may want to consider different legend styles.
 It is also possible to use only the axis, without any plots:
@@ -1647,6 +1650,8 @@ It is also possible to use only the axis, without any plots:
 \begin{codeexample}[]
 % \usepackage{textcomp}
 \begin{tikzpicture}
+  % let both axes use the same layers
+  \pgfplotsset{set layers}
   \begin{axis}[
     scale only axis,
     xmin=-5,xmax=5,
@@ -2230,166 +2235,3 @@ Thus, typing |\ref|\marg{name} somewhere outside of the axis, maybe even outside
 	\end{stylekey}
 \end{pgfplotskey}
 
-\subsubsection{Scaling Descriptions: Predefined Styles}
-\label{sec:scaling:styles}
-It is reasonable to change font sizes, marker sizes etc. together with the overall plot size: Large plots should also have larger fonts and small plots should have small fonts and a smaller distance between ticks.
-
-\begin{keylist}{
-	/tikz/font=\mchoice{\textbackslash normalfont,\textbackslash small,\textbackslash tiny,$\dotsc$},
-	/pgfplots/max space between ticks=\marg{integer},
-	/pgfplots/try min ticks=\marg{integer},
-	/tikz/mark size=\marg{integer}}
-	These keys should be adjusted to the figure's dimensions. Use 
-\begin{codeexample}[code only]
-\pgfplotsset{tick label style={font=\footnotesize},
-	label style={font=\small},
-	legend style={font=\small}
-}
-\end{codeexample}
-	to provide different fonts for different descriptions.
-
-	The keys |max space between ticks| and |try min ticks| are described on page~\pageref{maxspacebetweenticks} and configure the approximate distance and number of successive tick labels (in |pt|). Please omit the |pt| suffix here.
-\end{keylist}
-
-There are a couple of predefined scaling styles which set some of these options:
-
-\begin{stylekey}{/pgfplots/normalsize}
-	Re-initialises the standard scaling options of \PGFPlots.
-
-\begin{codeexample}[]
-\begin{tikzpicture}
-	\begin{axis}[normalsize,
-		title=A ``normalsize'' figure,
-		xlabel=The $x$ axis,
-		ylabel=The $y$ axis,
-		minor tick num=1,
-		legend entries={Leg}]
-		\addplot {max(4*x,7*x)};
-	\end{axis}
-\end{tikzpicture}
-\end{codeexample}
-
-	The initial setting is
-\begin{codeexample}[code only]
-\pgfplotsset{
-	normalsize/.style={
-		/pgfplots/width=240pt,
-		/pgfplots/height=207pt,
-		/pgfplots/max space between ticks=35
-	}
-}
-\end{codeexample}
-\end{stylekey}
-
-\begin{stylekey}{/pgfplots/small}
-	Redefines several keys such that the axis is ``smaller''.
-
-\begin{codeexample}[]
-\begin{tikzpicture}
-	\begin{axis}[small,
-		title=A ``small'' figure,
-		xlabel=The $x$ axis,
-		ylabel=The $y$ axis,
-		minor tick num=1,
-		legend entries={Leg}]
-		\addplot {x^2};
-	\end{axis}
-\end{tikzpicture}
-\end{codeexample}
-	The initial setting is
-\begin{codeexample}[code only]
-\pgfplotsset{
-	small/.style={
-		width=6.5cm,
-		height=,
-		tick label style={font=\footnotesize},
-		label style={font=\small},
-		max space between ticks=25,
-	}
-}
-\end{codeexample}
-Feel free to redefine the scaling -- the option may still be useful to get more ticks without typing too much. You could, for example, set |small,width=6cm|.
-\end{stylekey}
-
-\begin{stylekey}{/pgfplots/footnotesize}
-	Redefines several keys such that the axis is even smaller. The tick labels will have |\footnotesize|.
-
-\begin{codeexample}[]
-\begin{tikzpicture}
-	\begin{axis}[footnotesize,
-		title=A ``footnotesize'' figure,
-		xlabel=The $x$ axis,
-		ylabel=The $y$ axis,
-		minor tick num=1,
-		legend entries={Leg}]
-		\addplot+[const plot]
-			coordinates {
-			(0,0) (1,1) (3,3) (5,10)
-		};
-	\end{axis}
-\end{tikzpicture}
-\end{codeexample}
-	The initial setting is
-\begin{codeexample}[code only]
-\pgfplotsset{
-	footnotesize/.style={
-		width=5cm,
-		height=,
-		legend style={font=\footnotesize},
-		tick label style={font=\footnotesize},
-		label style={font=\small},
-		title style={font=\small},
-		every axis title shift=0pt,
-		max space between ticks=15,
-		every mark/.append style={mark size=8},
-		major tick length=0.1cm,
-		minor tick length=0.066cm,
-	},
-}
-\end{codeexample}
-As for |small|, it can be convenient to set |footnotesize| and set |width| afterwards.
-
-You will need |compat=1.3| or newer for this to work.
-\end{stylekey}
-
-\begin{stylekey}{/pgfplots/tiny}
-	Redefines several keys such that the axis is very small. Most descriptions will have |\tiny| as fontsize.
-
-\begin{codeexample}[]
-\begin{tikzpicture}
-	\begin{axis}[tiny,
-		title=A ``tiny'' figure,
-		xlabel=The $x$ axis,
-		ylabel=The $y$ axis,
-		minor tick num=1,
-		legend entries={Leg}]
-		\addplot+[const plot]
-			coordinates {
-			(0,0) (1,1) (3,3) (5,10)
-		};
-	\end{axis}
-\end{tikzpicture}
-\end{codeexample}
-	The initial setting is
-\begin{codeexample}[code only]
-\pgfplotsset{
-	tiny/.style={
-		width=4cm,
-		height=,
-		legend style={font=\tiny},
-		tick label style={font=\tiny},
-		label style={font=\tiny},
-		title style={font=\footnotesize},
-		every axis title shift=0pt,
-		max space between ticks=12,
-		every mark/.append style={mark size=6},
-		major tick length=0.1cm,
-		minor tick length=0.066cm,
-		every legend image post/.append style={scale=0.8},
-    },
-}
-\end{codeexample}
-As for |small|, it can be convenient to use |tiny,width=4.5cm| to adjust the width.
-
-You will need |compat=1.3| or newer for this to work.
-\end{stylekey}
diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.coordfiltering.tex b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.coordfiltering.tex
index 4aa02209c7a..a546a1acbf2 100644
--- a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.coordfiltering.tex
+++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.coordfiltering.tex
@@ -83,6 +83,8 @@ There is also a style key which simplifies selection by index, see below.
 	A style which appends an |x filter| which discards all but each $n$th input coordinate.
 \index{Downsampling}
 
+	This downsampling works fairly well. It can be used to reduce a huge amount of coordinates from an input file. In this case, you should also set |filter discard warning=false| to avoid repeated notifications about skipped coordinates and |unbounded coords=discard| such that \PGFPlots\ should silently forget any discarded points (rather than generated interrupted plots).
+
 	Note that there is also a |mark repeat| style which applies the same operation to plot marks only.
 
 	\paragraph{Technical note}: this style usually applies to $x$ coordinates (i.e.\ it counts $x$ coordinates). In case you want to apply it to something like |hist/data| or |quiver/u|, you can 
@@ -141,7 +143,7 @@ There is also a style key which simplifies selection by index, see below.
 	A low--level (technical) key which allows to apply the |restrict * to ...| features also to something like |hist/data|.
 
 	For example,
-	|@restrict to domain={hist/data}{}{0:1}{0}| applies the domain-restriction to the histogram-input |hist/data|. The final `|0|' means that it works as the key |restrict x to domain=0:1|, i.e.\ it skips everything which is outside of $[0,1]$.  In a similar way, 
+	|@restrict to domain={hist/data}{}{0:1}{0}| applies the domain-restriction to the histogram-input |hist/data|. The final `|0|' means that it works in a similar way as the key |restrict x to domain=0:1|, i.e.\ it skips everything which is outside of $[0,1]$.  In a similar way, 
 	|@restrict to domain={hist/data}{}{0:1}{1}| applies the functionality of |restrict x to domain*=0:1| to |hist/data|: it truncates values outside of $[0,1]$ to the domain's end-points.
 
 	The \meta{filter name} is expected to be a coordinate name like |x|, |y|, |z| (or |hist/data|).
diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.layers.tex b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.layers.tex
new file mode 100644
index 00000000000..8fdcfbb20df
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.layers.tex
@@ -0,0 +1,215 @@
+\subsection{Layers}
+{
+\tikzset{external/figure name/.add={}{layers_}}%
+
+It is important that several parts of an axis are drawn ``on top'' of others. Usually, \PGFPlots\ ensures this by drawing them in a suitable sequence (usually background followed by grid lines, followed by tick lines and tick labels, followed by plots and finally axis descriptions). While this works reasonable in most cases, there are cases where more control is desired. One common use-case is if multiple axes shall be drawn into the same picture: here, the sequence from above should be applied to all involved axes simultaneously. 
+
+\subsubsection{Summary}
+This section is the technical reference for using and customizing layered graphics in \PGFPlots. As such, it is hard reading.
+
+For most purposes, the following is \emph{completely} sufficient for you: If you want to enable layered graphics, put the following statement into the |tikzpicture| which is supposed to have layered graphics:
+
+\begin{codeexample}[code only]
+\begin{tikzpicture}
+	\pgfplotsset{set layers}
+	\begin{axis}
+		...
+	\end{axis}
+
+	% perhaps a second axis which should use the same layers?
+	\begin{axis}
+		...
+	\end{axis}
+\end{tikzpicture}
+\end{codeexample}
+\noindent This enables layered graphics for that specific |tikzpicture|. 
+
+You may want layered graphics if you have multiple axes in the same picture, of if you have specific needs for your plot.
+
+Consider reading |on layer| if you want to move particular elements of your axis to a different layer.
+
+
+\subsubsection{Using Predefined Layers}
+The main key to control layered graphics with \PGFPlots\ is |set layers|:
+
+\pgfkeys{
+	/pgfmanual/gray key prefixes/.add={/pgfplots/layers/,}{},
+}
+
+\begin{pgfplotskey}{set layers=\mchoice{none,\normalfont\meta{layer configuration name}} (initially none)}
+   This key enables layered graphics for either the current axis or for all following axes. 
+
+   Enabling layered graphics has the effect that the order in which graphical elements are given is unrelated to the ordering in which they will be drawn. The main benefit is if you have multiple axes in the same figure: the axes can share the same layers.
+
+   The invocation |set layers=none| disables layered graphics.
+
+   The invocation |set layers| (without equal sign and without arguments) is the same as if you would write |set layers=||default|.
+
+   In all other cases, |set layers| expects a \meta{layer configuration name}. There are two predefined configurations available (the prefix |/pgfplots/layers/| is optional):
+
+   \begin{pgfplotskey}{layers/standard}
+   	A layer configuration which defines the layers \texttt{axis background}, \texttt{axis grid}, \texttt{axis ticks}, \texttt{axis lines}, \texttt{axis tick labels}, \texttt{main}, \texttt{axis descriptions}, \texttt{axis foreground}. They are drawn in the order of appearance.
+   \end{pgfplotskey}
+
+   \begin{pgfplotskey}{layers/axis on top}
+   	A layer configuration which uses the same layer names as |layers/standard|, but with a different sequence: \texttt{axis background}, \texttt{main}, \texttt{axis grid}, \texttt{axis ticks}, \texttt{axis lines}, \texttt{axis tick labels}, \texttt{axis descriptions}, \texttt{axis foreground}.
+
+	This layer is automatically used if the key |axis on top| is used together with |set layers=|\meta{any layer configuration name}.
+   \end{pgfplotskey}
+  	
+	As soon as the key |set layers=|\meta{layer configuration name} is encountered, \PGFPlots\ starts the \pgfname\ command |\pgfsetlayers|\marg{layer names} with the layer names of the respective configuration. Usually, this \emph{replaces} the current layer configuration of the embedding |tikzpicture|. Furthermore, |set layers| stores the name of \meta{layer configuration name} such that every following |axis| knows how to map graphical elements to layer names.
+	
+	
+	The fact that layer configurations are properties of a complete |tikzpicture| (whereas an axis is only one of multiple graphical elements of that picture), they need to be given at one of several supported positions:
+    \begin{enumerate}
+        \item Directly within the picture:
+\begin{codeexample}[code only]
+\begin{tikzpicture}
+	\pgfplotsset{set layers=default}
+	\begin{axis}
+		...
+	\end{axis}
+\end{tikzpicture}
+\end{codeexample}
+	\noindent This option explicitly tells the reader of your source code that a significant portion of your picture has been changed: the complete picture has and uses a \meta{layer configuration name} (in this case |default|).
+
+	 \item As option for one or more axes which is/are directly within the picture:
+\begin{codeexample}[code only]
+\begin{tikzpicture}
+	\begin{axis}[set layers]
+		...
+	\end{axis}
+\end{tikzpicture}
+\end{codeexample}
+		Here, \PGFPlots\ implicitly communicates its layer configuration to the enclosing |tikzpicture|. Thus, the effect of |set layers| is \emph{not local to an axis}; it survives until |\end{tikzpicture}|. Any other option only survives until |\end{axis}|.
+
+		In this case, only the \emph{last} activated layer configuration will apply to the picture.
+
+    \paragraph{Limitation: no environments or local \TeX\ groups allowed.} Standard usages as within the examples of this manual will always work. But since the layer name configuration is essentially part of a \PGF\ picture (at a low level), one cannot arbitrarily set them; \PGF\ will complain if they are changed within some nested \TeX\ groups or \LaTeX\ environments. Typically, you will never need to worry about this. 
+
+	In short, the following examples are \emph{forbidden} because the axis is within locally nested groups. 
+\begin{codeexample}[code only]
+\begin{tikzpicture}
+	{% FORBIDDEN! Consider using case (1) above!
+		\begin{axis}[set layers]
+			...
+		\end{axis}
+	}
+\end{tikzpicture}
+\end{codeexample}
+\begin{codeexample}[code only]
+\begin{tikzpicture}
+	\begin{scope} % FORBIDDEN! Consider using case (1) above!
+		\begin{axis}[set layers]
+			...
+		\end{axis}
+	\end{scope}
+\end{tikzpicture}
+\end{codeexample}
+	\noindent These examples are forbidden because the layer configuration will be cleared by the `|}|' of the first forbidden example and by the `|\end{scope}|' of the second example. A solution would be one of the different placement options (i.e. choice (1.) or (3.)).
+
+	\item outside of any picture:
+\begin{codeexample}[code only]
+\pgfplotsset{set layers=default}
+\begin{tikzpicture}
+	\begin{axis}
+		...
+	\end{axis}
+\end{tikzpicture}
+\end{codeexample}
+	\noindent This choice configures the layer configuration for \emph{every} following |tikzpicture|. 
+
+    \end{enumerate}
+
+
+    \paragraph{Limitation: axis alignment restricted to inner anchors.} This applies only if you changed the default value of |anchor| (which is |anchor=south west|).
+    Any axis which uses layered graphics should use one of the following values of |anchor|: |north|, |north west|, |west|, |south west|, |south|, |south east|, |east|, |north east|, |north|, |center|, |origin|, |above origin|, |left of origin|, |right of origin|, |below origin|. In case you really need another anchor, \PGFPlots\ requires the use of |cell picture=true|, causing the layers to be local for that specific axis.
+	
+	The technical background for this limitation is a hen-and-egg problem: outer anchors (like |outer south west|) are only available \emph{after} the complete axis has been generated -- and layers can only be drawn after each drawing instruction has been issued. The technical keys for further reading are |cell picture=false| or |cell picture=if necessary| (one of them is active for layered graphics).
+\end{pgfplotskey}
+
+\begin{command}{\pgfplotssetlayers}
+    An alias for |\pgfplotsset{set layers}|. It activates the |layers/default| layer configuration.
+     
+\end{command}
+\begin{command}{\pgfplotssetlayers\marg{layer configuration name}}
+    An alias for |\pgfplotsset{set layers=|\marg{layer configuration name}|}|.
+\end{command}
+
+\begin{handler}{{.define layer set}=\marg{ordered layer names}\marg{style definitions}}
+	Allows to define a new layer set configuration named \meta{key}. Afterwards, \meta{key} is a valid argument for |set layers=|\meta{key}.
+
+	The first argument \meta{ordered layer names} is a comma-separated list of layer names. The names are arbitrary, and |\pgfdeclarelayer| will be called for every encountered argument\footnote{To be more precise: \texttt{set layers} calls \texttt{\textbackslash pgfdeclarelayer} when it uses \meta{ordered layer names}.}. There is just one ``magic'' name: the layer |main| should be part of every \meta{ordered layer names} as it will contain every graphical element which is not associated with a specific layer.
+
+	The second argument \meta{style definitions} contains options -- just as if you would have written \meta{key}|/.style=|\marg{style definitions}. The \meta{style definitions} are supposed to contain \PGFPlots\ style redefinitions which make use of each encountered element of \meta{ordered layer names}. This is probably best explained by an example: the |layers/standard| layer configuration is defined by
+\begin{codeexample}[code only]
+\pgfplotsset{
+    layers/standard/.define layer set=
+		{axis background,axis grid,axis ticks,axis lines,axis tick labels,main,%
+			axis descriptions,axis foreground}
+		{
+			grid style=         {/pgfplots/on layer=axis grid},
+			tick style=         {/pgfplots/on layer=axis ticks},
+			axis line style=    {/pgfplots/on layer=axis lines},
+			label style=        {/pgfplots/on layer=axis descriptions},
+			legend style=       {/pgfplots/on layer=axis descriptions},
+			title style=        {/pgfplots/on layer=axis descriptions},
+			colorbar style=     {/pgfplots/on layer=axis descriptions},
+			ticklabel style=    {/pgfplots/on layer=axis tick labels},
+			axis background@ style={/pgfplots/on layer=axis background},
+			3d box foreground style={/pgfplots/on layer=axis foreground},
+		},
+}
+\end{codeexample}
+	\noindent This definition declares a couple of layers, and it adjusts \PGFPlots\ styles by adding |on layer| commands. The arguments for |on layer| are the elements of \meta{ordered layer names}.
+
+	Note that if you have an element in \meta{ordered layer names} which is never referenced inside of \meta{style definitions}, this layer will always be empty. In other words: the \emph{only} reference to the names in \meta{ordered layer names} is \meta{style definitions}, \PGFPlots\ has no hard-coded magic layer names (except for |main| as explained above).
+
+    Since the second argument \meta{style definitions} defines \meta{key} to be a normal style key, one can simply use \meta{key} in order to set \meta{style definitions}. This allows to inherit them. For example, the |layers/axis on top| layer configuration is defined by means of
+\begin{codeexample}[code only]
+\pgfplotsset{
+	/pgfplots/layers/axis on top/.define layer set=
+        {axis background,main,axis grid,axis ticks,axis lines,axis tick labels,%
+            axis descriptions,axis foreground}
+        {/pgfplots/layers/standard}
+}
+\end{codeexample}
+    \noindent i.e.\ it only redefines the \emph{sequence} of the layers and re-uses the style definitions of |layers/standard|.
+
+    Any number of layer configurations can be defined. 
+\end{handler}
+
+
+\subsubsection{Changing the Layer of Graphical Elements}
+There are a couple of keys which change the layer of a graphical element. 
+
+\begin{pgfplotskey}{on layer=\marg{layer name}}
+    Providing this key somewhere in a \PGFPlots\ style or inside of a \PGFPlots\ axis will change the layer for all graphical elements for which the style applies.
+
+    For example,
+\begin{codeexample}[code only]
+...
+\begin{axis}[set layers,grid style={/pgfplots/on layer=axis foreground}]
+...
+\end{codeexample}
+    \noindent will change the layer for any grid lines to |axis foreground|.
+
+    The argument \meta{layer name} is expected to be part of the current layer configuration, i.e.\ the argument of |set layers| should contain it.
+
+	Note that if you have two \emph{plots} with different values of |on layer|, you may also want to enable |clip mode=clip individual| or to deactivate clipping altogether using |clip=false|. Clipping options need to be provided as option to the axis, not to the plot. The technical background is that clip paths needs to be replicated for the layer on which the drawing is supposed to happen -- otherwise they will be applied to the wrong layer.
+\end{pgfplotskey}
+
+\begin{pgfplotskey}{mark layer=\mchoice{auto,like plot,\meta{layer name}} (initially auto)}
+	An advanced key which defines the layer for plot |mark|s. It is typically the best choice to leave it at |auto|.
+
+	If you write |\addplot[on layer=|\meta{layer name}|]|, the
+    layer will be used for the complete plot. Plot marks are treated with special care, so you can define an own layer for plot marks. 
+
+    The initial choice \declaretext{auto} will automatically define a ``suitable'' choice, leaving the responsability with \PGFPlots. Here, ``suitable'' means to respect |clip mode| and |clip marker paths| in a way such that plot marks will not be clipped even though the default layer for your plot will be clipped. 
+
+    The choice \declaretext{like plot} will pack the marks onto the same layer as the plot they belong to. This might cause clipped markers, i.e.\ markers which are only displayed partially if they are close to the boundary of the axis.
+
+    Finally, one can provide any \meta{layer name}, just as for |on layer| -- but the layer can be different from the layer used for the plot.
+\end{pgfplotskey}
+
+}
diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.linefitting.tex b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.linefitting.tex
index 1264ce8fc62..a0f81128a19 100644
--- a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.linefitting.tex
+++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.linefitting.tex
@@ -52,6 +52,8 @@ This section documents the attempts of \PGFPlots\ to fit lines to input coordina
 	The example above has two plots: one showing the data and one containing the |linear regression| line. We use |y={create col/linear regression={}}| here, which means to create a new column\footnote{The \texttt{y=\{create col/} feature is available for any other \PGFPlotstable\ postprocessing style, see the \texttt{create on use} documentation in the \PGFPlotstable\ manual.} containing the regression values automatically. 
 	As arguments, we need to provide the $y$ column name explicitly\footnote{In fact, \PGFPlots\ sees that there are only two columns and uses the second by default. But you need to provide it if there are at least 3 columns.}. The $x$ value is determined from context: |linear regression| is evaluated inside of |\addplot table|, so it uses the same $x$ as |\addplot table| (i.e.\ if you write |\addplot table[x=|\marg{col name}|]|, the regression will also use \meta{col name} as its |x| input). Furthermore, it shows the line parameters $a$ and $b$ in the legend.
 
+	Note that the uncommented line with |\xdef\slope{\pgfplotstableregressiona}| is useful if you have \emph{more than one} regression line: it copies the value of |\pgfplotstableregressiona| (in this case) into a new global variable called `|\slope|'. This allows to use `|\slope|' instead of |\pgfplotstableregressiona| -- even after |\pgfplotstableregressiona| has been overwritten.
+
 
 
 	The following \meta{key-value-config} keys are accepted as comma--separated list:
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 a2cf31dec0e..a587e61b55f 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
@@ -150,6 +150,31 @@ Note that each of the provided marks can be rotated freely by means of |mark opt
 \begin{key}{/tikz/mark repeat=\marg{integer} (initially empty)}
 	Allows to draw only each $n$th |mark| where $n$ is provided as \meta{integer}.
 \end{key}
+
+\begin{key}{/tikz/mark phase=\marg{integer $p$} (initially 1)}
+	This option allows to control which markers are drawn. It is primarily used together with the \Tikz\ option |mark repeat=|$r$: it tells \tikzname\ that the first mark to be draw should be the $p$th, followed by the $(p + r)$th, then
+	the $(p + 2r)$th, and so on.
+\begin{codeexample}[]
+\begin{tikzpicture}
+	\begin{axis}[tiny]
+	\addplot+[scatter] {sin(deg(x))};	
+	\end{axis}
+\end{tikzpicture}
+\begin{tikzpicture}
+	\begin{axis}[tiny]
+	\addplot+[scatter,
+	  mark repeat=3,mark phase=2]
+	  {sin(deg(x))};	
+	\end{axis}
+\end{tikzpicture}
+\end{codeexample}
+	Here, $p=1$ is the first point (the one with |\coordindex|$=0$).
+\end{key}
+
+\begin{key}{/tikz/mark indices=\marg{index list} (initially empty)}
+	Allows to draw only the marker whose index numbers are in the argument list.
+\end{key}
+
 \begin{key}{/pgf/mark color=\marg{color} (initially empty)}
 	Defines the \emph{additional} fill color for the |halfcircle|, |halfcircle*|, |halfdiamond*| and |halfsquare*| markers. An empty value uses |white| (which is the initial configuration). The value |none| disables filling for this part.
 
@@ -761,7 +786,7 @@ Available color maps are shown below.
 \end{codeexample}
 The usage of the result \meta{\textbackslash macro} is a little bit low--level.
 
-	\paragraph{Attention:} \PGF\ shadings are always represented with respect to the RGB color space. Consequently, even CMYK \meta{colormap name}s will result in an RGB shading specification when using this method\footnote{In case \PGF\ should someday support CMYK shadings and you still see this remark, you can define \texttt{\textbackslash def\textbackslash pgfplotscolormaptoshadingspectorgb\{0\}}.}.
+	\paragraph{Attention:} \PGF\ shadings are always represented with respect to the RGB color space. Consequently, even CMYK \meta{colormap name}s will result in an RGB shading specification when using this method\footnote{In case \PGF\ should someday support CMYK shadings and you still see this remark, you can add the macro definition \texttt{\textbackslash def\textbackslash pgfplotscolormaptoshadingspectorgb\{0\}} to your preamble.}.
 \end{command}
 
 
diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.miscellaneous.tex b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.miscellaneous.tex
index 6ce239cd815..c7c6b01f607 100644
--- a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.miscellaneous.tex
+++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.miscellaneous.tex
@@ -50,7 +50,7 @@ This axis option allows to invoke \meta{commands} after each |\addplot| command.
 Allows to add customized code which is executed at the beginning of each plot visualization. In contrast to |execute at begin plot|, this happens not immediately during |\addplot|, but late during the postprocessing of |\end{axis}| when actual drawing commands are generated.
 
 One possible application is shown below: suppose you want to use |\usepackage{ocg}| in order to switch layers dynamically, for example in a beamer package. This can be implemented as follows:
-% \usepackage[pdftex]{ocg}
+% \usepackage[pdftex]{pgfplots_ocg_copy}
 \begin{codeexample}[]
 % requires \usepackage[pdftex]{ocg}
 \begin{tikzpicture}
diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.numberformatting.tex b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.numberformatting.tex
index 640b162ef18..e92e1b133be 100644
--- a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.numberformatting.tex
+++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.numberformatting.tex
@@ -72,8 +72,10 @@ This section provides a brief survey about the most frequently used aspects of n
 \end{codeexample}
 
 \begin{codeexample}[]
-\pgfmathprintnumber
-	[1000 sep={\,},fixed,precision=6,1000 sep in fractionals]{1000000.123456}
+\pgfmathprintnumber[
+  1000 sep={\,},fixed,precision=6,
+  1000 sep in fractionals]
+	 {1000000.123456}
 \end{codeexample}
 
 	\noindent Each of these keys requires the prefix `|/pgf/number format/|' when used inside of a \PGFPlots\ style (try |/pgf/number format/.cd,|\meta{number formatting keys} to use the same prefix for many \meta{number formatting keys}).
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 a1f759a732b..7a11b05981f 100644
--- a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.preliminaryoptions.tex
+++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.preliminaryoptions.tex
@@ -14,7 +14,7 @@ A key usually has a value (like a number, a string, or perhaps some macro code).
 \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. 
 
-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 `|,|').
+A value can usually be provided without curly braces. For example, if the manual contains something 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]
diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.scaling.tex b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.scaling.tex
index c5c8537a8d5..8b6f77d101f 100644
--- a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.scaling.tex
+++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.scaling.tex
@@ -1,59 +1,94 @@
 
 \subsection{Scaling Options}
+There are a various options which control or change the scaling of an axis. Here, ``scaling'' typically means two aspects: first, the unit vector size in each direction and second, the displayed limits in each direction. Both together control the size of the axis box. In addition, axis descriptions change the size. However, \PGFPlots\ scales only units and determines limits. It does not scale axis descriptions by default in order to keep consistent font sizes between the text and the figure.
 
-\begin{pgfplotskey}{width=\marg{dimen}}
-Sets the width of the final picture to \marg{dimen}. If no |height| is specified, scaling will respect aspect ratios.
+Often, one wishes to provide the target size only and let \PGFPlots\ do the rest. This is the default; it scales the axis to |width| and |height|. If you provide one of these options, the axis will be rescaled while keeping the aspect ratio. 
 
-\paragraph{Remarks:} 
-\begin{itemize}
-	\item The scaling only affects the width of one unit in $x$-direction or the height for one unit in $y$-direction. Axis labels and tick labels won't be resized, but their size is used to determine the axis scaling.
+Occasionally, one wants to provide unit vectors explicitly to ensure that one unit takes a prescribed amount of space. This is possible by means of the |x|, |y|, and |z| keys. In such a case, the |width| and |height| options will be ignored (or only applied for the unspecified unit vectors).
 
-	\item You can use the |scale=|\marg{number} option,
-\begin{codeexample}[code only]
-\begin{tikzpicture}[scale=2]
-\begin{axis}
-...
+Another common approach is to enforce specific |unit vector ratio|s: for example by specifying that each unit should take the same amount of space using |axis equal|. Here, \PGFPlots\ scales the lengths of all vectors uniformly, i.e.\ it applies the same scale to each vector. This is done by means of the |scale mode| configuration which is basically one of |scale mode=stretch to fill| or |scale mode=scale uniformly|: \PGFPlots\ tries to satisfy the prescribed |width| and |height| arguments by finding a \emph{common} scaling factor. In addition, it attempts to enlarge the limits individually to fit into the prescribed dimensions.
+
+In addition, you can use the option |/pgfplots/scale| to simply scale all final units up by some prescribed factor. This does not change text labels. 
+
+If needed, you can also supply |/tikz/scale| to an axis. This will scale the complete resulting image, including all text labels.
+
+\subsubsection{Common Scaling Options}
+All common options mentioned in the previous paragraphs are described here.
+
+\begin{pgfplotskey}{width=\marg{dimen} (initially empty)}
+Sets the width of the final picture to \marg{dimen}. 
+
+Any non-empty dimension like |width=5cm| sets the desired target width. Any \TeX\ unit is accepted (like |200pt| or |5in|).
+
+An empty value |width={}| means ``use default width or rescale proportionally to |height|''. In this case, \PGFPlots\ uses the value of |\axisdefaultwidth| as target quantity. However, if the |height| key has been set, \PGFPlots\ will rescale the |\axisdefaultwidth| in a way which keeps the ratio between |\axisdefaultwidth| and |\axisdefaultheight|. This allows to specify just one of |width| and |height| and keep aspect ratios.
+
+Consequently, if you specify just |width=5cm| but leave the default |height={}|, the scaling will respect the initial aspect ratio.
+
+The scaling affects the unit vectors for $x$, $y$, and $z$. It does not change the size of text labels or axis descriptions.
+\begin{codeexample}[]
+\begin{tikzpicture}
+\begin{axis}[width=5cm]
+	\addplot {x};
 \end{axis}
 \end{tikzpicture}
 \end{codeexample}
-	to scale the complete picture.
 
-	\item The \Tikz-options |x| and |y| which set the unit dimensions in $x$ and $y$ directions can be specified as arguments to |\begin{axis}[x=1.5cm,y=2cm]| if needed (see below). These settings override the |width| and |height| options.
+Please note that \PGFPlots\ only estimates the size needed for axis- and tick labels. The estimate assumes a fixed amount of space for anything which is outside of the axis box. This has the effect that the final images may be slightly larger or slightly smaller than the prescribed dimensions. However, the fixed amount is always the same; it is set to~|45pt|. That means that multiple pictures with the same target dimensions will have the same size for their axis boxes -- even if the size for descriptions varies.
 
-	\item You can also force a fixed width/height of the axis (without looking at labels) with
-\begin{codeexample}[code only]
+It is also possible to scale the \emph{axis box} to the prescribed width/height. In that case, the total width will be larger due to the axis descriptions. However, the axis box fills the desired dimensions exactly.
+\begin{codeexample}[]
 \begin{tikzpicture}
 \begin{axis}[width=5cm,scale only axis]
-	...
+	\addplot {x};
 \end{axis}
 \end{tikzpicture}
 \end{codeexample}
 
-	\item Please note that up to the writing of this manual, \PGFPlots\ only estimates the size needed for axis- and tick labels. It does not include legends which have been placed outside of the axis\footnote{I.e. the `\texttt{width}' option will not work as expected, but the bounding box is still ok.}. This may be fixed in future versions.
+	\paragraph{Note:} changing |width| and/or |height| changes \emph{only} the unit vector sizes. In particular, it does not change the font size for any axis description, nor does it change the default spacing between adjacent tick labels. It is best-practice to use |width|/|height| for ``small'' changes, i.e.\ changes for which the font size should remain the same. Consider using one of the styles |normalsize|, |small|, |footnotesize|, or |tiny| which are described in Section~\ref{sec:scaling:styles} on page~\pageref{sec:scaling:styles}, and \emph{then} change to your desired dimensions if you need a different ``quality'' of scaling.
+
+	\begin{command}{\axisdefaultwidth}
+		This macro defines the default width. It is preset to |240pt|.
 
-	Use the |x=|\marg{dimension}, |y=|\marg{dimension} and |scale only axis| options if the scaling happens to be wrong.
-\end{itemize}
+		This default width defines the aspect ratio which will be used whenever just one of |width| or |height| is specified: the aspect ratio is the ratio between |\axisdefaultwidth| and |\axisdefaultheight|.
+
+		You can change it using
+\begin{codeexample}[code only]
+\def\axisdefaultwidth{10cm}
+\end{codeexample}
+	\end{command}
 \end{pgfplotskey}
 
-\begin{pgfplotskey}{height=\marg{dimen}}
-	See |width|.
+\begin{pgfplotskey}{height=\marg{dimen} (initially empty)}
+	Works in the same way as |width| except that an empty value |height={}| defaults to ``use either |\axisdefaultheight| or scale proportionally if just |width| has been changed''.
+
+	\begin{command}{\axisdefaultheight}
+		This macro defines the default height. It is preset to |207pt|.	
+
+		See |\axisdefaultwidth|.
+	\end{command}
 \end{pgfplotskey}
 
 \begin{pgfplotskey}{scale only axis=\mchoice{true,false} (initially false)}
-If |scale only axis| is enabled, label, tick and legend dimensions won't influence the size of the axis rectangle, that means |width| and |height| apply only to the axis rectangle.
+If |scale only axis| is enabled, |width| and |height| apply only to the axis rectangle. Consequently, the resulting figure is larger that |width| and |height| (because of any axis descriptions). However, the axis box has exactly the prescribed target dimensions.
 
 If |scale only axis=false| (the default), \PGFPlots\ will try to produce the desired width \emph{including} labels, titles and ticks.
 \end{pgfplotskey}
 
 \begin{pgfplotsxykeylist}{
-	\x=\marg{dimen},
+	\x=\marg{dimen} (initially empty),
 	\x={\{(\meta{x},\meta{y})\}}}
-Sets the unit vectors for $x$ (or $y$). Every logical plot coordinate $(x,y)$ is drawn at the position
+Allows to provide zero, one, two, or three of the target unit vectors. 
+
+In this context, a ``unit vector'' is a two--dimensional vector which defines the projection onto the canvas:
+every logical plot coordinate $(x,y)$ is drawn at the canvas position
 \[ x \cdot \begin{bmatrix} e_{xx} \\ e_{xy} \end{bmatrix} + y \cdot \begin{bmatrix} e_{yx} \\ e_{yy} \end{bmatrix}. \]
 The unit vectors $e_x$ and $e_y$ determine the paper position in the current (always two dimensional) image.
+For a standard three--dimensional axis, a plot coordinate $(x,y,z)$ is drawn at 
+\[ x \cdot \begin{bmatrix} e_{xx} \\ e_{xy} \end{bmatrix} + y \cdot \begin{bmatrix} e_{yx} \\ e_{yy} \end{bmatrix} + z \cdot \begin{bmatrix} e_{zx} \\ e_{zy} \end{bmatrix}. \]
 
-The key |x=|\marg{dimen} simply sets $e_x = (\meta{dimen},0)^T $ while |y=|\marg{dimen} sets $e_y = (0,\meta{dimen})^T$.
-Here, \marg{dimen} is any \TeX\ size like |1mm|, |2cm| or |5pt|. Note that you should not use negative values for \meta{dimen} (consider using |x dir| and its variants to reverse axis directions).
+The initial setting assigns empty values to each of these keys, i.e. |x={},y={},z={}|. In this case, \PGFPlots\ is free to choose these vectors as best. To this end, it uses |width|, |height|, |scale mode|, |plot box ratio|, |unit vector ratio|, |view|, and the axis limits.
+
+The key |x=|\marg{dimen} simply sets $e_x = (\meta{dimen},0)^T $ while |y=|\marg{dimen} sets $e_y = (0,\meta{dimen})^T$. Using |z=|\marg{dimen} results in $e_z = (\meta{dimen},\meta{dimen})^T$. In this context, \meta{dimen} is any \TeX\ size like |1mm|, |2cm| or |5pt|. Note that you should not use negative values for \meta{dimen} (consider using |x dir| and its variants to reverse axis directions).
 \begin{codeexample}[]
 \begin{tikzpicture}
 \begin{axis}[x=1cm,y=1cm]
@@ -70,7 +105,17 @@ Here, \marg{dimen} is any \TeX\ size like |1mm|, |2cm| or |5pt|. Note that you s
 \end{tikzpicture}
 \end{codeexample}
 
-The second syntax, |x={(|\meta{x}|,|\meta{y}|)}| sets $e_x = (\meta{x},\meta{y})^T$ explicitly\footnote{Please note that you need extra curly braces around the vector. Otherwise, the comma will be interpreted as separator for the next key-value pair.}; the corresponding |y| key works similarly. This allows to define skewed or rotated axes.
+Note that if you change the unit vector for just one direction, the other vector(s) will be chosen by \PGFPlots\ -- and scaled in order to fill the prescribed |width| and |height| as best as \PGFPlots\ can (but see remarks for three--dimensional plots at the end of this key).
+\begin{codeexample}[]
+\begin{tikzpicture}
+\begin{axis}[x=1cm,
+	title=Height is deduced from height option]
+\addplot expression[domain=0:3] {2*x};
+\end{axis}
+\end{tikzpicture}
+\end{codeexample}
+
+The second syntax, |x={(|\meta{x}|,|\meta{y}|)}| sets $e_x = (\meta{x},\meta{y})^T$ explicitly\footnote{Please note that you need extra curly braces around the vector. Otherwise, the comma will be interpreted as separator for the next key-value pair.}. The corresponding keys for |y| and |z| work in a similar way. This allows to define skewed or rotated axes.
 
 \begin{codeexample}[]
 \begin{tikzpicture}
@@ -90,9 +135,8 @@ The second syntax, |x={(|\meta{x}|,|\meta{y}|)}| sets $e_x = (\meta{x},\meta{y})
 \end{tikzpicture}
 \end{codeexample}
 
-	Setting $x$ explicitly overrides the |width| option. Setting $y$ explicitly overrides the |height| option.
 
-	Setting |x| and/or |y| for logarithmic axis will set the dimension used for $1 \cdot e \approx 2.71828$.
+	Setting |x| and/or |y| for logarithmic axis will set the dimension used for $1 \cdot e \approx 2.71828$ (or whatever has been set as |log basis x|).
 
 	Please note that it is \emph{not} possible to specify |x| as argument to |tikzpicture|. The option 
 \begin{codeexample}[code only]
@@ -102,13 +146,15 @@ The second syntax, |x={(|\meta{x}|,|\meta{y}|)}| sets $e_x = (\meta{x},\meta{y})
 \end{axis}
 \end{tikzpicture}
 \end{codeexample}
-	won't have any effect because an axis rescales its coordinates (see the |width| option).
+	does not have any effect because an axis rescales its coordinates (see the |width| option).
 
+	Note that providing unit vectors explicitly usually causes \PGFPlots\ to ignore any other scaling options. In other words: if you say |y=0.1cm|, \PGFPlots\ will use $(0\text{cm},0.1\text{cm})$ as $y$ projection vector. However, if you add |scale mode=scale uniformly|, you allow \PGFPlots\ to change the \emph{lengths} of your vectors. Of course, it will keep their relative directions and relative sizes. In this case, \PGFPlots\ will try to determine a good common scaling factor \emph{and} it will try to change the axis limits in order to fill the prescribed |width| and |height| (see the documentation for |scale mode| for details).
 \begin{codeexample}[]
 \begin{tikzpicture}
 \begin{axis}[
-	x={(1cm,-0.5cm)},
-	y=1cm,
+	title=Allow to rescale \emph{lengths},
+	x={(0.1cm,-0.05cm)},
+	y=0.1cm,
 	z=0cm,
 	axis on top,
 	scale mode=scale uniformly,
@@ -117,6 +163,9 @@ The second syntax, |x={(|\meta{x}|,|\meta{y}|)}| sets $e_x = (\meta{x},\meta{y})
 \end{axis}
 \end{tikzpicture}
 \end{codeexample}
+	\noindent In the example above, \PGFPlots\ decided that it should only rescale units -- at the expensive of the |width| constraint.
+
+\paragraph{Changes to font sizes:} see also Section~\ref{sec:scaling:styles} if you want to change font sizes or the density of tick labels in a simple way.
 
 \paragraph{Explicit units for 3D axes:} As of version~1.5, it is also possible to supply unit vectors to three-dimensional axes. In this case, the following extra assumptions need to be satisfied:
 \begin{enumerate}
@@ -125,28 +174,15 @@ The second syntax, |x={(|\meta{x}|,|\meta{y}|)}| sets $e_x = (\meta{x},\meta{y})
 
 	Consider using |x dir=reverse| or its variants in case you want to reverse directions.
 
-	\item For three-dimensional axes, \PGFPlots\ computes a view direction out of the provided unit vectors. The view direction is required to realize the |z buffer| feature (i.e.\ to decide about depths)\footnote{\PGFPlots\ provides a debug option called \texttt{view dir=\marg{x}\marg{y}\marg{z}} to override the view direction, should that ever be interesting.}.
+	\item For three-dimensional axes, \PGFPlots\ computes a view direction out of the provided unit vectors. The view direction is required to allow the |z buffer| feature (i.e.\ to decide about depths)\footnote{\PGFPlots\ provides a debug option called \texttt{view dir=\marg{x}\marg{y}\marg{z}} to override the view direction, should that ever be interesting.}.
 \end{enumerate}
-This feature is used to realize the \verbpdfref{\addplot3 graphics} feature, compare the examples in Section~\ref{sec:plotgraphics3d} on page~\pageref{sec:plotgraphics3d}.
+This feature is used to for the \verbpdfref{\addplot3 graphics} feature, compare the examples in Section~\ref{sec:plotgraphics3d} on page~\pageref{sec:plotgraphics3d}.
 
 \paragraph{Limitations:} Unfortunately, skewed axes are \textbf{not available for bar plots}.
 \index{Errors!Skewed axes and bar plots}%
 \index{Bar Plots!Skewed axes problems}%
 \end{pgfplotsxykeylist}
 
-\begin{pgfplotskey}{scale mode=\mchoice{auto,none,stretch to fill,scale uniformly} (initially auto)}
-	Specifies how |width|, |height|, and the three unit vector keys |x|, |y|, and |z| are combined to produce the final image.
-
-	The initial choice \declaretext{auto} chooses one of the other possible choices depending on the actual context. More precisely, it is the same as |none| if at least one of |x|, |y|, or |z| is provided (meaning that these keys are the final unit size). If no unit is provided, it defaults to |stretch to fill|.
-
-	The choice |none| does not apply any rescaling at all. Use this if prescribed lengths of |x|, |y| (and perhaps |z|) should be used. In other words: it ignores |width| and |height|. In this case, you may want to set |x post scale| and its variants to rescale units manually.
-
-	The choice |stretch to fill| takes |x|, |y|, and |z| as they have been found (either from user input or from some automatic processing) and rescales the axis with two \emph{separate} scales: one which results in the proper |width| and one which results in the proper |height|. As a consequence, the unit vectors are modified and distorted such that the final image fits into the prescribed dimensions. This is usually what one expects unless one provides unit directions explicitly.
-	
-	The choice |scale uniformly| is similar -- but it applies only \emph{one} scaling factor to fit into the prescribed dimensions. This scaling factor will be the same for both, |width| and |height|. Naturally, this will result in unsatisfactory results because either the final width or the final height will not be met. Therefore, this choice will enlarge or shrink limits to get the desired dimensions. Thus, the unit vectors have exactly the same size \emph{relations and angles} as they had before the scaling; only their magnitude is changed uniformly. But due to the given constraints, parts of the image may be empty or may no longer be visible. In case the outcome needs manual improvements, you can improve the visibility by modifying |width| and/or |height| (more freedom is not supported for this choice). Note that \PGFPlots\ implements this rescaling \textbf{if and only if} $e_{yx} = 0$ (for two--dimensional axes) or $e_{zx} = 0$ (for three-dimensional axes). In other words: for two--dimensional axes, the |y| vector has to be parallel to the canvas $y$ direction and for three-dimensional axes, the same holds for the |z| vector. The idea is to rescale only the vertical part of one unit vector and to change the limits of that respective axis simultaneously. The |scale uniformly| choice is used to realize the \verbpdfref{\addplot3 graphics} feature, see the documentation in Section~\ref{sec:plotgraphics3d} on page~\pageref{sec:plotgraphics3d} for its examples.
-
-\end{pgfplotskey}
-
 \begin{pgfplotsxykey}{\x mode=\mchoice{normal,linear,log} (initially normal)}
 	Allows to choose between linear (=normal) or logarithmic axis scaling or logplots for each $x,y,z$-combination.
 
@@ -194,6 +230,15 @@ This feature is used to realize the \verbpdfref{\addplot3 graphics} feature, com
 \end{tikzpicture}
 \end{codeexample}
 
+\begin{codeexample}[]
+\begin{tikzpicture}
+\begin{axis}[axis equal,small,view={45}{35.26}]
+\addplot3[mark=cube, blue, mark size=1cm] 
+	coordinates {(0,0,0)};
+\end{axis}
+\end{tikzpicture}
+\end{codeexample}
+
 	The configuration |axis equal=true| is actually just a style which sets |unit vector ratio=1 1 1,unit rescale keep size=true|.
 \end{pgfplotskey}
 
@@ -252,53 +297,79 @@ This feature is used to realize the \verbpdfref{\addplot3 graphics} feature, com
 	Trailing values of |1| can be omitted, i.e.\ |unit vector ratio=2 1| is the same as |unit vector ratio=2|; and |unit vector ratio=3 2 1| is the same as |unit vector ratio=3 2|.
 	An empty value |unit vector ratio={}| disables unit vector rescaling.
 
+	Note that an active |unit vector ratio| will implicitly set |scale mode=scale uniformly|\footnote{This has been introduced in version 1.6. For older versions, the axis equal feature produced wrong results for three--dimensional axes.}.
+
 	\begin{pgfplotskeylist}{%
 		unit vector ratio*=\marg{rx ry rz},
-		unit rescale keep size=\marg{true,false} (initially true)}
+		unit rescale keep size=\mchoice{true,false,unless limits declared} (initially unless limits declared)}
 	In the default configuration, \PGFPlots\ maintains the original axis dimensions even though |unit vector ratio| involves different scalings. 
+	\label{key:unit:rescale:keep:size}
 
 	It does so by enlarging the limits.
 \begin{codeexample}[]
 \begin{tikzpicture}
 	\begin{axis}[footnotesize,xlabel=$x$,ylabel=$y$,unit vector ratio=]
-	\addplot3[surf,samples=10,domain=0:1] {(1-x)*y};
+	\addplot3[surf,z buffer=sort,samples=15, 
+		variable=\u, variable y=\v, 
+		domain=0:180, y domain=0:360]
+           ({cos(u)*sin(v)}, {sin(u)*sin(v)}, {cos(v)});
 	\end{axis}
 \end{tikzpicture}
 \begin{tikzpicture}
 	\begin{axis}[footnotesize,xlabel=$x$,ylabel=$y$,unit vector ratio=1 1 1]
-	\addplot3[surf,samples=10,domain=0:1] {(1-x)*y};
+	\addplot3[surf,z buffer=sort,samples=15, 
+		variable=\u, variable y=\v, 
+		domain=0:180, y domain=0:360]
+           ({cos(u)*sin(v)}, {sin(u)*sin(v)}, {cos(v)});
 	\end{axis}
 \end{tikzpicture}
 \begin{tikzpicture}
 	\begin{axis}[footnotesize,xlabel=$x$,ylabel=$y$,unit vector ratio=0.25 0.5]
-	\addplot3[surf,samples=10,domain=0:1] {(1-x)*y};
+	\addplot3[surf,z buffer=sort,samples=15, 
+		variable=\u, variable y=\v, 
+		domain=0:180, y domain=0:360]
+           ({cos(u)*sin(v)}, {sin(u)*sin(v)}, {cos(v)});
 	\end{axis}
 \end{tikzpicture}
 \end{codeexample}
 	\noindent The example above has the same plot, with three different unit ratios. The first has no limitations (it is the default configuration). The second uses the same length for each unit vector and enlarges the limits in order to maintain the same dimensions. The third example has an $x$ unit which is $\nicefrac14$ the length of a $z$ unit, and an $y$~unit which is $\nicefrac12$ the length of a $z$~unit.
 
+	\PGFPlots\ does its best to respect the involved scaling options (the prescribed |width| and |height|, the |unit vector ratio|, and any specified axis limits). In the case above, it enlarged the horizontal limits and kept the $z$~limit as-is. See |scale mode| and its documentation for details about the involved algorithm and its parameters.
+
 	The |unit rescale keep size=false| key, or, equivalently, |unit vector ratio*=...|, does not enlarge limits:
 \begin{codeexample}[]
 \begin{tikzpicture}
 	\begin{axis}[footnotesize,xlabel=$x$,ylabel=$y$,unit vector ratio=]
-	\addplot3[surf,samples=10,domain=0:1] {(1-x)*y};
+	\addplot3[surf,z buffer=sort,samples=15, 
+		variable=\u, variable y=\v, 
+		domain=0:180, y domain=0:360]
+           ({cos(u)*sin(v)}, {sin(u)*sin(v)}, {cos(v)});
 	\end{axis}
 \end{tikzpicture}
 \begin{tikzpicture}
 	\begin{axis}[footnotesize,xlabel=$x$,ylabel=$y$,
 		unit rescale keep size=false,
 		unit vector ratio=1 1 1]
-	\addplot3[surf,samples=10,domain=0:1] {(1-x)*y};
+	\addplot3[surf,z buffer=sort,samples=15, 
+		variable=\u, variable y=\v, 
+		domain=0:180, y domain=0:360]
+           ({cos(u)*sin(v)}, {sin(u)*sin(v)}, {cos(v)});
 	\end{axis}
 \end{tikzpicture}
 \begin{tikzpicture}
 	\begin{axis}[footnotesize,xlabel=$x$,ylabel=$y$,
 		unit vector ratio*=0.25 0.5, % the '*' implies 'unit rescale keep size=false'
 	]
-	\addplot3[surf,samples=10,domain=0:1] {(1-x)*y};
+	\addplot3[surf,z buffer=sort,samples=15, 
+		variable=\u, variable y=\v, 
+		domain=0:180, y domain=0:360]
+           ({cos(u)*sin(v)}, {sin(u)*sin(v)}, {cos(v)});
 	\end{axis}
 \end{tikzpicture}
 \end{codeexample}
+	The key |unit rescale keep size| also affects |scale mode=scale uniformly| (which is closely related to |axis equal|).
+
+	Here is the reference of the value of |unit rescale keep size|: the value \declaretext{true} means that \PGFPlots\ will enlarge limits in order to keep the size. It will try to respect user provided limits, but if the user provided \emph{all} limits, it will \emph{override} the user-provided limits and will rescale them. Thus, |true| gives higher priority to the axis size than to user-provided limits. The choice \declaretext{false} will never rescale axis limits. The choice \declaretext{unless limits declared} is a mixture: it will enlarge limits unless the user provided them. If the user provides all limits explicitly, this choice is the same as |false|.
 	\end{pgfplotskeylist}
 \end{pgfplotskey}
 
@@ -335,3 +406,224 @@ This feature is used to realize the \verbpdfref{\addplot3 graphics} feature, com
 \end{tikzpicture}
 \end{codeexample}
 \end{pgfplotsxykeylist}
+
+\subsubsection{Scaling Descriptions: Predefined Styles}
+\label{sec:scaling:styles}
+It is reasonable to change font sizes, marker sizes etc. together with the overall plot size: Large plots should also have larger fonts and small plots should have small fonts and a smaller distance between ticks.
+
+\begin{keylist}{
+	/tikz/font=\mchoice{\textbackslash normalfont,\textbackslash small,\textbackslash tiny,$\dotsc$},
+	/pgfplots/max space between ticks=\marg{integer},
+	/pgfplots/try min ticks=\marg{integer},
+	/tikz/mark size=\marg{integer}}
+	These keys should be adjusted to the figure's dimensions. Use 
+\begin{codeexample}[code only]
+\pgfplotsset{tick label style={font=\footnotesize},
+	label style={font=\small},
+	legend style={font=\small}
+}
+\end{codeexample}
+	to provide different fonts for different descriptions.
+
+	The keys |max space between ticks| and |try min ticks| are described on page~\pageref{maxspacebetweenticks} and configure the approximate distance and number of successive tick labels (in |pt|). Please omit the |pt| suffix here.
+\end{keylist}
+
+There are a couple of predefined scaling styles which set some of these options:
+
+\begin{stylekey}{/pgfplots/normalsize}
+	Re-initialises the standard scaling options of \PGFPlots.
+
+\begin{codeexample}[]
+\begin{tikzpicture}
+	\begin{axis}[normalsize,
+		title=A ``normalsize'' figure,
+		xlabel=The $x$ axis,
+		ylabel=The $y$ axis,
+		minor tick num=1,
+		legend entries={Leg}]
+		\addplot {max(4*x,7*x)};
+	\end{axis}
+\end{tikzpicture}
+\end{codeexample}
+
+	The initial setting is
+\begin{codeexample}[code only]
+\pgfplotsset{
+	normalsize/.style={
+		/pgfplots/width=240pt,
+		/pgfplots/height=207pt,
+		/pgfplots/max space between ticks=35
+	}
+}
+\end{codeexample}
+\end{stylekey}
+
+\begin{stylekey}{/pgfplots/small}
+	Redefines several keys such that the axis is ``smaller''.
+
+\begin{codeexample}[]
+\begin{tikzpicture}
+	\begin{axis}[small,
+		title=A ``small'' figure,
+		xlabel=The $x$ axis,
+		ylabel=The $y$ axis,
+		minor tick num=1,
+		legend entries={Leg}]
+		\addplot {x^2};
+	\end{axis}
+\end{tikzpicture}
+\end{codeexample}
+	The initial setting is
+\begin{codeexample}[code only]
+\pgfplotsset{
+	small/.style={
+		width=6.5cm,
+		height=,
+		tick label style={font=\footnotesize},
+		label style={font=\small},
+		max space between ticks=25,
+	}
+}
+\end{codeexample}
+Feel free to redefine the scaling -- the option may still be useful to get more ticks without typing too much. You could, for example, set |small,width=6cm|.
+\end{stylekey}
+
+\begin{stylekey}{/pgfplots/footnotesize}
+	Redefines several keys such that the axis is even smaller. The tick labels will have |\footnotesize|.
+
+\begin{codeexample}[]
+\begin{tikzpicture}
+	\begin{axis}[footnotesize,
+		title=A ``footnotesize'' figure,
+		xlabel=The $x$ axis,
+		ylabel=The $y$ axis,
+		minor tick num=1,
+		legend entries={Leg}]
+		\addplot+[const plot]
+			coordinates {
+			(0,0) (1,1) (3,3) (5,10)
+		};
+	\end{axis}
+\end{tikzpicture}
+\end{codeexample}
+	The initial setting is
+\begin{codeexample}[code only]
+\pgfplotsset{
+	footnotesize/.style={
+		width=5cm,
+		height=,
+		legend style={font=\footnotesize},
+		tick label style={font=\footnotesize},
+		label style={font=\small},
+		title style={font=\small},
+		every axis title shift=0pt,
+		max space between ticks=15,
+		every mark/.append style={mark size=8},
+		major tick length=0.1cm,
+		minor tick length=0.066cm,
+	},
+}
+\end{codeexample}
+As for |small|, it can be convenient to set |footnotesize| and set |width| afterwards.
+
+You will need |compat=1.3| or newer for this to work.
+\end{stylekey}
+
+\begin{stylekey}{/pgfplots/tiny}
+	Redefines several keys such that the axis is very small. Most descriptions will have |\tiny| as fontsize.
+
+\begin{codeexample}[]
+\begin{tikzpicture}
+	\begin{axis}[tiny,
+		title=A ``tiny'' figure,
+		xlabel=The $x$ axis,
+		ylabel=The $y$ axis,
+		minor tick num=1,
+		legend entries={Leg}]
+		\addplot+[const plot]
+			coordinates {
+			(0,0) (1,1) (3,3) (5,10)
+		};
+	\end{axis}
+\end{tikzpicture}
+\end{codeexample}
+	The initial setting is
+\begin{codeexample}[code only]
+\pgfplotsset{
+	tiny/.style={
+		width=4cm,
+		height=,
+		legend style={font=\tiny},
+		tick label style={font=\tiny},
+		label style={font=\tiny},
+		title style={font=\footnotesize},
+		every axis title shift=0pt,
+		max space between ticks=12,
+		every mark/.append style={mark size=6},
+		major tick length=0.1cm,
+		minor tick length=0.066cm,
+		every legend image post/.append style={scale=0.8},
+    },
+}
+\end{codeexample}
+As for |small|, it can be convenient to use |tiny,width=4.5cm| to adjust the width.
+
+You will need |compat=1.3| or newer for this to work.
+\end{stylekey}
+
+
+\subsubsection{Scaling Strategies}
+	The content of this section is quite involved -- and its knowledge is typically unnecessary because by default, \PGFPlots\ controls the involved stuff automatically. You may want to skip this section.
+
+\begin{pgfplotskey}{scale mode=\mchoice{auto,none,stretch to fill,scale uniformly} (initially auto)}
+	Specifies how to choose the (individual) unit vector scaling factors, their length ratios, and perhaps the axis limits in order to fill the prescribed |width| and |height|.
+	
+	The |scale mode| implementation expects some ``initial'' set of unit vectors. This initial set of unit vectors is determined as follows: for standard two--dimensional axes, it is simply the unit cube $e_x=(1\text{pt},0\text{pt})^T$, $e_y=(0\text{pt},1\text{pt})^T$, $e_z=0$. For three--dimensional axes, it is the outcome of the two keys |view| and |plot box ratio|. If you provided units explicitly by means of one of |x|, |y|, or |z|, this value is the initial unit vector.
+	
+	In addition, it expects ``initial'' axis limits (i.e.\ values of |xmin|, |xmax|, etc.). The initial axis limits are those limits which have been deduced from your data or which have been provided explicitly. Furthermore, the initial axis limits already include changes of the |enlargelimits| key.
+
+	Given the initial set of unit vectors and the initial axis limits, the |scale mode| implementation is a kind of ``post--processor'' which creates modified unit vectors and modified axis limits in order to satisfy all specified constraints. These constraints are |width|, |height|, and |unit vector ratio|.
+
+	The initial choice \declaretext{auto} tells \PGFPlots\ to take full control over this key. It chooses one of the other possible choices depending on the actual context. The choice |auto| evaluates to |scale uniformly| if |unit vector ratio| is set. Otherwise it evaluates to |stretch to fill|.
+
+	The choice \declaretext{none} does not apply any rescaling at all. Use this if prescribed lengths of |x|, |y| (and perhaps |z|) should be used. In other words: it ignores |width| and |height|. In this case, you may want to set |x post scale| and its variants to rescale units manually. See also |disabledatascaling|.
+
+	The choice \declaretext{stretch to fill} takes the initial unit vectors and rescales the unit vectors with two \emph{separate} scales: one which results in the proper |width| and one which results in the proper |height|. As a consequence, the unit vectors are modified and distorted such that the final image fits into the prescribed dimensions. This is usually what one expects unless one provides unit directions explicitly. This mode does not change axis limits. Note that if one of the unit vectors has been provided explicitly, \PGFPlots\ will not change it. It will only change the remaining axis limits. This mode contradicts |axis equal| or |unit vector ratio|.
+	
+	The choice \declaretext{scale uniformly} takes the initial unit vectors and applies only \emph{one} scaling factor to all units. In this case, there is just \emph{one} common scaling factor for both |width| and |height|. Naturally, this will result in unsatisfactory results because either the final width or the final height will not be met. Therefore, this choice will adjust axis limits to get the desired dimensions. Thus, the unit vectors have exactly the same size \emph{relations and angles} as they had before the scaling; only their magnitude is changed uniformly. In addition, axis limits may be changed (with individual scaling factors for each axis limit). Note that if unit vectors have been provided explicitly, \PGFPlots\ can still rescale it with this choice -- it will keep the relative directions and size ratios. The choice |scale uniformly| tries its best to modify the degrees of freedom in a ``useful'' way. The precise meaning of ``useful'' is the |scale uniformly strategy| key.
+
+	\begin{pgfplotskey}{scale uniformly strategy=\mchoice{auto,units only,change vertical limits,\\change horizontal limits} (initially auto)}
+		The |scale uniformly| method requires to determine one \emph{common} scaling factor which rescales every axis \emph{unit}. In addition, it allows one scaling factor \emph{for each axis limit}, i.e.\ up to three.
+
+		The constraints for this search are that we want to satisfy the |width|/|height| constraint, have as few rescaling as possible and that we do not want to reduce limits (as this could possibly hide data points).
+
+		The choice \declaretext{auto} chooses one of the other possibilities automatically. Depending on whether we have two dimensions or three dimensions, it compares the available methods and chooses the one which does not reduce limits and which involves the fewest rescaling (i.e.\ it may compare the outcome of the other strategies). This is the default. If you keep the choice |auto|, you do not have to worry about the remaining choices. Note that manually provided axis limits will not be modified.
+
+		The choice \declaretext{units only} will not enlarge axis limits. It will only rescale the units. To this end, it chooses the scaling factor such that the \emph{smaller} target dimension is filled as desired. In other words: if |width| $< $ |height|, it will scale to satisfy the |width| constraint. The |height| constraint will be ignored. The case $>$ will be done the other way round. The choice |units only| typically results in a square axis as it takes the initial set of unit vectors (which are typically the unit box) and scales them with a common scaling factor. Consequently, you can choose |units only| if you want a boxed axis. You can still change axis limits manually, however.
+
+		The choice \declaretext{change vertical limits} chooses a common scaling factor for the unit vectors on order to satisfy the |width| (!) constraint. This common scaling factor is similar to |units only| -- but |units only| can also decide to satisfy the |height| constraint whereas  |change vertical limits| will scale unit vectors to satisfy |width|. In order to satisfy the |height| constraint, |change vertical limits| modifies just the vertical limits. For two--dimensional axes, this is |ymin| and |ymax|. For three--dimensional axes, this is |zmin| and |zmax|. Clearly, there is a chance that it will \emph{decrease} the displayed range -- in this case, parts of the image will be clipped away. This method \emph{assumes} that the vertical axis has not been rotated (i.e.\ that $e_{yx}=0$ or $e_{zx}=0$, respectively). It refuses to work and falls back to |units only| for rotates axes. Choose |change vertical limits| if you want the image (i.e.\ the actual content) as wide as possible. You can modify |width| and |height| to improve its outcome. Note that manually specified axis limits will not be changed, see below for details.
+
+		The choice \declaretext{change horizontal limits} attempts a similar approach, but for the horizontal limits: it determines one suitable scaling factor which is applied to all unit vectors and modifies horizontal axis limits to satisfy the remaining constraints. For two--dimensional axes, this is quite simple because we typically have $e_{xy} = 0$ (i.e.\ the $x$ unit vector has vanishing $y$ component) and $e_{yx}=0$ such that \PGFPlots\ can change axis limits easily. If a two--dimensional axis has an $x$ unit with $e_{xy} \neq 0$, the method is not applicable and falls back to |units only|. For three--dimensional axes, it assumes that the $z$ vector is not rotated, i.e.\ $e_{zy} = 0$ and tries to change limits for both $x$ and $y$. This choice is much more involved because here, $x$ and $y$ components are coupled. Consequently, the common unit scaling factor and the two involved axis limit compensation factors for $x$ and $y$ are tightly coupled as well. \PGFPlots\ solves a system of non--linear equations iteratively to arrive at a suitable solution for all three scalings. Use this method if |change vertical limits| would clip away parts of the image (because it reduced the displayed range) and you do not want to change |width| and |height|. The choice |change horizontal limits| will typically result in more empty space in the resulting figure. But it will not clip away content. Manually specified axis limits will not be changed, see below for details.
+
+	\end{pgfplotskey}
+
+	\paragraph{Manually provided axis limits:} Any manually provided arguments for |xmin| and its variants are considered to be immutable; \PGFPlots\ will not change them. If you assign |xmin|, \PGFPlots\ will only change |xmax| and vice--versa. If you assign both |xmin| and |xmax|, \PGFPlots\ will not change $x$~limits at all. Note that if you assign both |xmin| and |xmax|, \PGFPlots\ will simply skip the scaling and will give up on the constraints. It will not try to compensate the lack of scaling opportunities by changing $y$~limits, for example. This has the positive effect that assigning limits does not change the complete appearance of your axis.  The allowed set of changes to axis limits can be configured with the following key.
+
+	\paragraph{Interaction with }|enlargelimits|: Note that |enlargelimits| and |scale mode| are independent of another: the outcome of |enlargelimits| is used as ``initial axis limits'' and these limits may be changed by |scale mode| (even if you said |enlargelimits=false|). See the documentation of |enlargelimits| for details on this interaction.
+
+	\begin{pgfplotskey}{
+		unit rescale keep size=\mchoice{true,false,unless limits declared} (initially unless limits declared)}
+		In the default configuration \declaretext{unless limits declared}, unit rescaling may cause changes to the axis limits in order to keep the figure's size intact. However, only those limits which have not been declared manually are subject to rescaling: if you say |xmin=1|, only |xmax| and the limits for $y$ and $z$ are free to change.
+
+		Setting |unit rescale keep size=|\declaretext{false} will \emph{disable} the modification of axis limits altogether, i.e.\ axis limits will not be rescaled to compensate scalings on unit vectors.
+
+		Setting |unit rescale keep size=|\declaretext{true} will always rescale limits, even if they have been declared manually.
+		
+		This key mainly affects |scale mode=scale uniformly|. This, in turn, is used for |axis equal| and |\addplot3 graphics|.
+
+		See also the addition documentation for this key and related examples on page~\pageref{key:unit:rescale:keep:size}.
+	\end{pgfplotskey}
+
+	The |scale uniformly| choice is implicitly used for |axis equal| and for the \verbpdfref{\addplot3 graphics} feature, see the documentation in Section~\ref{sec:plotgraphics3d} on page~\pageref{sec:plotgraphics3d} for its examples. Note that the common case is that the initial unit vectors form the unit cube (i.e.\ those before scaling, see above). In this case, |scale uniformly| is the same as |axis equal|.
+\end{pgfplotskey}
+
diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.specifyrange.tex b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.specifyrange.tex
index 5dc32cc749d..b6da2d73a6d 100644
--- a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.specifyrange.tex
+++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.specifyrange.tex
@@ -117,7 +117,8 @@ Axis limits can be increased automatically using the |enlargelimits| option.
 	This option has nothing to do with path clipping, it only affects how the axis limits are computed.
 \end{pgfplotskey}
 
-\begin{pgfplotsxykeylist}{enlarge \x\ limits=\mchoice{auto,true,false,upper,lower,\meta{val},value=\meta{val},abs value=\meta{val},\\ abs=\meta{val},rel=\meta{val}} (initially auto),
+\begin{pgfplotsxykeylist}{%
+	enlarge \x\ limits=\mchoice{auto,true,false,upper,lower,\meta{val},value=\meta{val},abs value=\meta{val},\\ abs=\meta{val},rel=\meta{val}} (initially auto),
 	enlargelimits=\meta{common value}}
 Enlarges the axis size for one axis (or all of them for |enlargelimits|) somewhat if enabled.
 
@@ -190,6 +191,7 @@ You can set |xmin|, |xmax| and |ymin|, |ymax| to the minimum/maximum values of y
 \end{tikzpicture}
 \end{codeexample}
 
+	Note that |enlargelimits| is applied before any changes to axis limits are considered as part of |scale mode|: |enlargelimits| will always be applied. Afterwards, the choice |scale mode=scale uniformly| will enlarge limits once more in order to satisfy all scaling constraints. The two limit enlargements are independent of each other, i.e.\ even if you say |enlargelimits=false|, |scale mode| will still increase axis limits if this seems to be necessary. See |scale mode| (especially |scale mode=units only|) and |unit rescale keep size| for detail on how to disable limit enlargement caused by |scale mode|.
 \end{pgfplotsxykeylist}
 
 \begin{pgfplotsxykeylist}{%
diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.symbolic-transformations.tex b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.symbolic-transformations.tex
index 5c1d36ee684..8a30dbfc371 100644
--- a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.symbolic-transformations.tex
+++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.symbolic-transformations.tex
@@ -71,6 +71,28 @@ It is possible to provide a string dictionary to \PGFPlots. An input coordinate
 	
 	The effect of the transformation is simply that input coordinates can be elements of the dictionary and tick labels will be chosen out of this dictionary as well.
 
+	Note that |symbolic x coords| is more-or-less equivalent to explicitly provided |xtick| positions and |xticklabels|:
+\begin{codeexample}[]
+\begin{tikzpicture}
+\begin{axis}[
+	xtick={0,1,2,...,20},
+	xticklabels={a,b,c,d,e,f,g,h,i},
+	xticklabel style={
+		anchor=base,
+		yshift=-\baselineskip
+	},
+	]
+	\addplot+[smooth] coordinates {
+		(0,42)
+		(1,50)
+		(2,80)
+		(5,60)
+		(6,62)
+		(8,90)};
+\end{axis}
+\end{tikzpicture}
+\end{codeexample}
+	\noindent The difference is that the approach with |symbolic x coords| is simpler to read whereas the |xtick| approach is simpler with respect to coordinate arithmetics (for example to increase limits using |enlargelimits|). The |xticklabel style| here is an attempt to align all tick labels at their base line (which would be useful for |symbolic x coords| as well as soon as labels have characters which exceed the baseline).
 
 	\paragraph{See also} the option to add tick and/or grid lines at every encountered coordinate using |xtick=data| (or |minor xtick=data|).
 \end{pgfplotsxykeylist}
diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.technicalinternals.tex b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.technicalinternals.tex
new file mode 100644
index 00000000000..d0300d9c559
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.technicalinternals.tex
@@ -0,0 +1,66 @@
+\subsection{Technical Internals}
+{
+\tikzset{external/figure name/.add={}{techinternals_}}%
+
+This section describes keys which are usually set by internal routines -- it is typically unnecessary to use them. However, they may impose limitations or influence performance. Such cases are documented clearly in other sections of this manual. This here is the reference on the involved internals.
+
+\begin{pgfplotskey}{cell picture=\mchoice{true,false,if necessary} (initially true)}
+	This key is set automatically by \PGFPlots\ if necessary (for example by |set layers|).
+
+	Typically, \PGFPlots\ creates a so-called ``cell picture''. A cell picture is a separate picture which is typeset into a node. Finally, the node is shifted to fulfill special |anchor| requirements. The necessity for a cell picture is given if the |anchor| of an axis is only known after the complete axis has been drawn.
+
+	The initial choice \declaretext{true} means that \PGFPlots\ will create a cell picture for every axis. This allows all |anchor|s, but it is unsuited if multiple graphics layers are desired or if one wants SVG export. In order to create a cell picture, \PGFPlots\ interrupts the embedding |tikzpicture|, draws a new |tikzpicture|, and finally typesets the result into a node.
+
+	The choice \declaretext{false} tells \PGFPlots\ to draw its paths directly into the embedding |tikzpicture|. Such an approach is necessary if the axis shall use layers of the embedding |tikzpicture|. This is possible if and only if the |anchor| can be determined without actually drawing the complete axis. If so, \PGFPlots\ will modify the transformation matrix in advance. Note that axes with |cell picture=false| will \emph{contain} all the usual anchors -- the only difference is that the axis itsself can only use one of the following anchors for its alignment: |north|, |north west|, |west|, |south west|, |south|, |south east|, |east|, |north east|, |north|, |center|, |origin|, |above origin|, |left of origin|, |right of origin|, |below origin|.
+
+	The choice \declaretext{if necessary} will check if the chosen anchor is one of the list above. If so, it will use |cell picture=false|. Otherwise, it will use |cell picture=true|.
+
+\end{pgfplotskey}
+
+\begin{pgfplotskey}{clip mode=\mchoice{global,individual} (initially global)}
+	This key controls how \PGFPlots\ implements the |clip=true| feature (which is on by default). Its primary motivation is control where markers are placed: are markers on top of everything else (choice |global|) or are they overdrawn by following plots (choice |individual|)?
+	
+
+	The choice \declaretext{global} tells \PGFPlots\ to install one single clip path for the complete picture\footnote{The choice \texttt{clip mode=global} was the only supported clipping mechanism up to and including version 1.5.}.
+	In order to avoid clipped marker paths, any markers are processed after the clip path has been closed, i.e.\ on a separate layer (see |clip marker paths|). An unexpected side--effect is that marks are on top of plots, even if the plots have been added after the markers.
+
+	The choice \declaretext{individual} instructs \PGFPlots\ to install a separate clip path for \emph{every} |\addplot| command. Consequently, the plot will be clipped. But most importantly, its markers will be drawn immediately after the clip path has been deactivated.
+
+	An unexpected side--effect of |clip mode=individual| is that 
+	\begin{enumerate}
+		\item the resulting pdf will be slightly larger due to the repeated paths,
+		\item custom drawing instruction like |\node| or |\draw| need to be clipped \emph{manually}: use
+\begin{codeexample}[]
+\begin{tikzpicture}
+	\begin{axis}[
+		clip mode=individual,
+	]
+	\addplot+[samples=3] {x^2};
+
+	\begin{scope}
+		\clip \pgfextra{\pgfplotspathaxisoutline};
+
+		\draw (axis cs:-20,15) -- (axis cs:20,15);
+
+		\draw (axis cs:-20,20) -- (axis cs:20,20);
+	\end{scope}
+
+	\addplot+[samples=2] {x};
+	\end{axis}
+\end{tikzpicture}
+\end{codeexample}
+		\noindent to install a custom clip path around your |\draw| instructions for such a use--case. Here, the path instruction |\pgfplotspathaxisoutline| results in a path of the axis outline, i.e.\ the path which is used for the background paths or for clipping. Since it is a basic level macro, it needs to be encapsulated by |\pgfextra|.
+	\end{enumerate}
+
+	Note that |clip marker paths| can lead to the same result as |clip mode=individual| if the plot does not reach the boundaries.
+\end{pgfplotskey}
+
+\begin{pgfplotskey}{compat/show suggested version=\mchoice{true,false} (initially true)}
+	If enabled, \PGFPlots\ will show you which value for |compat=|\meta{version} results in the largest active feature set and highest quality.
+	
+	This key will generate a warning if the current version is so old that the quality degrades seriously.
+
+	The notification will be printed to your |.log| file (during |\end{document}|).
+\end{pgfplotskey}
+}
+
diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.tex b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.tex
index 7cdb4f99da7..40788fdbe73 100644
--- a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.tex
+++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.tex
@@ -26,5 +26,7 @@
 \input pgfplots.reference.linefitting.tex
 \input pgfplots.reference.miscellaneous.tex
 \input pgfplots.reference.tikzinteroperability.tex
+\input pgfplots.reference.layers.tex
+\input pgfplots.reference.technicalinternals.tex
 
 }
diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.tickoptions.tex b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.tickoptions.tex
index c0f213634fa..00cd439a0c0 100644
--- a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.tickoptions.tex
+++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.tickoptions.tex
@@ -739,14 +739,14 @@ If the code is empty, no tick scale label will be drawn (and no space is consume
 \makeatletter
 \let\itsinitial=\pgfplots@scale@ticks@below@exponent
 \makeatother
-\begin{pgfplotskey}{scale ticks below=\marg{exponent} (initially \itsinitial)}
+\begin{pgfplotskey}{scale ticks below exponent=\marg{exponent} (initially \itsinitial)}
 Allows fine tuning of the `|scaled ticks|' algorithm: if the axis limits are of magnitude $10^e$ and $e<$\meta{exponent}, the common prefactor~$10^e$ will be factored out. The default is 
 \end{pgfplotskey}
 
 \makeatletter
 \let\itsinitial=\pgfplots@scale@ticks@above@exponent
 \makeatother
-\begin{pgfplotskey}{scale ticks above=\marg{exponent} (initially \itsinitial)}
+\begin{pgfplotskey}{scale ticks above exponent=\marg{exponent} (initially \itsinitial)}
 Allows fine tuning of the '|scaled ticks|' algorithm: if the axis limits are of magnitude $10^e$ and $e>$\meta{exponent}, the common prefactor~$10^e$ will be factored out.
 \end{pgfplotskey}
 
diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.resources.tex b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.resources.tex
index 86a1d0194f4..f9a4886a168 100644
--- a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.resources.tex
+++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.resources.tex
@@ -38,12 +38,13 @@
 
 \pgfplotsexpensiveexample
 \begin{codeexample}[]
+% huger graphs are possible; consider lualatex
 \begin{tikzpicture}
 \begin{axis}[
-	title=$120 \times 120$ Smooth Surface,
+	title=$80 \times 80$ Smooth Surface,
 	xlabel=$x$,
 	ylabel=$y$]
-\addplot3[surf,samples=120,shader=interp,domain=0:1] 
+\addplot3[surf,samples=80,shader=interp,domain=0:1] 
 	{sin(deg(8*pi*x))* exp(-20*(y-0.5)^2) 
 	+ exp(-(x-0.5)^2*30 
 		- (y-0.25)^2 - (x-0.5)*(y-0.25))};
@@ -60,7 +61,16 @@ The default settings of most \TeX-distributions are quite restrictive, so it may
 
 Usually, the log--file or the final error message contains a summary about the used resources, giving a hint which parameter needs to be increased.
 
+\subsubsection{LuaLa\TeX}
+One solution which works quite well is to switch the La\TeX\ executable: if you have a decent \TeX\ distribution, you will have the |lualatex| executable as well. This, in turn, uses dynamic memory allocation such that it usually has enough memory for any \PGFPlots\ axis.
+
+The LuaLa\TeX\ executable |lualatex| is supposed to be almost compatible with |pdflatex|. 
+
+This approach works for any platform.
+
 \subsubsection{Mik\TeX}
+If you are running Mik\TeX\ and you do not want to (or cannot switch) to |lualatex|, you can proceed as follows.
+
 For Mik\TeX, memory limits can be increased in two ways. The first is to use command line switches:
 \begin{codeexample}[code only]
 pdflatex 
@@ -70,7 +80,7 @@ pdflatex
 \end{codeexample}
 \noindent Experiment with these settings if Mik\TeX\ runs out of memory. Usually, one doesn't invoke |pdflatex| manually: there is a development aid which does all the invocations, so this one needs to be adjusted. 
 
-Sometimes it might be better to adjust the Mik\TeX\ configuration file permanently, for example to avoid reconfiguring the \TeX\ development program. This can be realized using the command
+Sometimes it might be better to adjust the Mik\TeX\ configuration file permanently, for example to avoid reconfiguring the \TeX\ development program. This can be implemented using the command
 \begin{codeexample}[code only]
 initexmf --edit-config-file=pdflatex
 \end{codeexample}
@@ -85,6 +95,8 @@ Thanks to ``LeSpocky'' for his documentation in
 \url{http://blog.antiblau.de/2009/04/21/speicherlimits-von-miktex-erhoehen}.
 
 \subsubsection{\TeX Live or similar installations}
+In addition to the option to switch to |lualatex|, you can proceed as follows to keep existing |dvips| or |pdflatex| workflows.
+
 For Unix installations, one needs to adjust config files. This can be done as follows:
 \begin{enumerate}
 	\item Locate |texmf.cnf| on your system. On my Ubuntu installation, it is in 
@@ -147,7 +159,7 @@ export TEXMFCNF=~/texmf/mytexcnf:
 Unfortunately, \TeX\ does not allow arbitrary memory limits, there is an upper bound hard coded in the executables.
 
 \subsection{Reducing Typesetting Time}
-\PGFPlots\ does a lot of computations ranging from abstract coordinate computations to low level |.pdf| drawing commands (realized by \PGF). For complex plots, this may take a considerable time -- especially for 3D plots.
+\PGFPlots\ does a lot of computations ranging from abstract coordinate computations to low level |.pdf| drawing commands (implemented by \PGF). For complex plots, this may take a considerable time -- especially for 3D plots.
 
 One possibility to reduce typesetting time is to tell \PGF\ to generate single, temporary |.pdf| (or |.eps|) documents for a subset (or all) graphics in one run and re-use these temporary images in successive runs. For \PGFPlots, this is the most effective way to reduce typesetting time. It can be accomplished using the |external| library described in Section~\ref{sec:pgfplots:export}.
 }
diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.tex b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.tex
index 0196ebbe729..c010a3c790c 100644
--- a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.tex
+++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.tex
@@ -19,7 +19,9 @@
 %
 %
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+% SEE pgfplots-macros.tex as well!
 \input{pgfplots.preamble.tex}
+
 %\RequirePackage[german,english,francais]{babel}
 
 \def\matlabcolormaptext{This colormap is similar to one shipped with Matlab (\textregistered) under a similar name.}
@@ -60,7 +62,7 @@
 	%\\{\small Attention: you are using an unstable development version.}
 }
 
-%\includeonly{pgfplots.libs}
+%\includeonly{pgfplots.reference,pgfplots.basic.reference}
 
 
 \begin{document}
@@ -120,7 +122,7 @@ This section contains information about upgrades, the team, the installation (in
 
 \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.00$. 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.
+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:
@@ -138,12 +140,16 @@ This release provides a lot of improvements which can be found in all detail in
 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.5.1}
+\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.
@@ -160,7 +166,7 @@ Here is a list of changes introduced in recent versions of \PGFPlots:
 
 	Since this affects the spacing, it is not enabled be default.
 
-	\item \PGFPlots\ 1.3 now supports reversed axes. It is no longer necessary to use workarounds with negative units.
+	\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.
@@ -178,11 +184,11 @@ Here is a list of changes introduced in recent versions of \PGFPlots:
 \end{enumerate}
 I apologize for any inconvenience caused by these changes.
 
-\begin{pgfplotskey}{compat=\mchoice{1.5.1,1.5,1.4,1.3,pre 1.3,default,newest} (initially default)}
+\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.5.1}
+\pgfplotsset{compat=1.6}
 \end{codeexample}
 	allows to choose between backwards compatibility and most recent features.
 
@@ -196,12 +202,20 @@ I apologize for any inconvenience caused by these changes.
 \end{codeexample}
 	\noindent in order to restrict the compatibility setting to the actual context (in this case, the |figure| environment).
 
-	Use |\pgfplotsset{compat=default}| to restore the factory settings.
+	The the output of your |.log| file to see the suggested value for |compat|.
 
-	The setting |\pgfplotsset{compat=newest}| will always use features of the most recent version. This might result in small changes in the document's appearance. Note that it is generally a good idea to select the most recent version which is compatible with your document. This ensures that future changes will still be compatible with your document.
+	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/general=\meta{version}}
+	\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
@@ -225,12 +239,20 @@ I apologize for any inconvenience caused by these changes.
 
 	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: they might introduce slight scaling differences in order to improve the accuracy.
+	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}
@@ -239,7 +261,7 @@ I apologize for any inconvenience caused by these changes.
 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 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!
+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.
 
diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplotsexample.pdf b/Master/texmf-dist/doc/latex/pgfplots/pgfplotsexample.pdf
index e592d8a615c..2e250f51e75 100644
--- a/Master/texmf-dist/doc/latex/pgfplots/pgfplotsexample.pdf
+++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplotsexample.pdf
diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplotsexample.tex b/Master/texmf-dist/doc/latex/pgfplots/pgfplotsexample.tex
index 074e7738125..de2478c02bf 100644
--- a/Master/texmf-dist/doc/latex/pgfplots/pgfplotsexample.tex
+++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplotsexample.tex
@@ -3,7 +3,7 @@
 % for dvipdfm:
 %\def\pgfsysdriver{pgfsys-dvipdfm.def}
 \usepackage{pgfplots}
-\pgfplotsset{compat=1.3}% <-- moves axis labels near ticklabels (respects tick label widths)
+\pgfplotsset{compat=1.6}% <-- moves axis labels near ticklabels (respects tick label widths)
 
 \begin{document}
 \begin{figure}
diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplotstable.pdf b/Master/texmf-dist/doc/latex/pgfplots/pgfplotstable.pdf
index ec463c59f91..027e8106b63 100644
--- a/Master/texmf-dist/doc/latex/pgfplots/pgfplotstable.pdf
+++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplotstable.pdf
diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplotstable.tex b/Master/texmf-dist/doc/latex/pgfplots/pgfplotstable.tex
index caf37fc33ac..42a058d40a7 100644
--- a/Master/texmf-dist/doc/latex/pgfplots/pgfplotstable.tex
+++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplotstable.tex
@@ -330,6 +330,8 @@ level,dof,error1,error2,info,{grad(log(dof),log(error2))},quot(error1)
 	The choice \declaretext{false} is identical to this last case, i.e.\ even if the first line contains strings, they won't be recognised as column names.
 
 	Finally, the choice \declaretext{has colnames} is the opposite of |false|: it assumes that the first non--comment line \emph{contains} column names. In other words: even if only numbers are contained in the first line, they are considered to be column \emph{names}.
+
+	Note that this key only configures headers in \emph{input} tables. To configure \emph{output} headers, you may want to look at |every head row|.
 \end{key}
 
 \begin{pgfplotskey}{table/format=\mchoice{auto,inline,file} (initially auto)}
@@ -758,6 +760,8 @@ A style which is installed for every column with odd column index (starting with
 \label{pgfplotstable:page:tablerow}
 \begin{command}{\pgfplotstablerow}
 	During the evaluation of row or column options, this command expands to the current row's index.
+
+	Note that it will have the special value $-1$ for the header row.
 \end{command}
 \begin{command}{\pgfplotstablecols}
 	During the evaluation of row or column options, this command expands to the total number of columns in the output table.
@@ -946,6 +950,22 @@ $3$ & $2$ & $2$ & $3 d\delta$ \\
 
 \begin{stylekey}{/pgfplots/table/every head row}	
 	A style which is installed for each first row in the tabular. This can be used to adjust options for column names or to add extra lines/colours.
+
+\begin{codeexample}[]
+\pgfplotstabletypeset[
+  % suppress the header row 'col1  col2  col3':
+  every head row/.style={output empty row},
+  col sep=comma,
+  columns/col1/.style={string type,column type=r},
+  columns/col2/.style={string type,column type=l},
+  columns/col3/.style={string type,column type=l},
+  ]
+{
+	col1,col2,col3
+	Col A,B,C
+	The first column,E,F
+}
+\end{codeexample}
 \end{stylekey}
 
 \begin{stylekey}{/pgfplots/table/every first row}	
@@ -1013,6 +1033,21 @@ $3$ & $2$ & $2$ & $3 d\delta$ \\
 	Note that |every nth row/.style 2 args=...| is the same as |every nth row=...|.
 \end{keylist}
 
+\begin{stylekey}{/pgfplots/table/output empty row}
+	A style which suppresses output for the current row. 
+
+	This style is evaluated very late, after all column-specific content modifications have been applied. It is equivalent to 
+\begin{codeexample}[code only]
+\pgfplotstableset{
+	output empty row/.style={
+		typeset cell/.style={@cell content={}}
+	},
+}
+\end{codeexample}
+
+	See |every head row| for an application.
+\end{stylekey}
+
 \subsection{Configuring Single--Cell Appearance: Styles}
 Besides the possibilities to change column styles and row styles, there are also a couple of styles to change single cells.
 \begin{stylekey}{/pgfplots/table/every row \meta{rowindex} column \meta{colindex}}
@@ -1090,7 +1125,37 @@ The following keys allow changes of alignment (|begin table|) and |font| and the
 }
 \end{codeexample}
 
-	It is also possible to \emph{change} the value. For example,
+	Note that |longtable| allows the use of \emph{replicated headers} for multi-page tables\index{Multi-page} by means of its \declareandlabel{\endhead} macro:\index{Replicate headers}
+\begin{codeexample}[code only]
+% replicate column names on top of every page of a multi-page table:
+\pgfplotstableset{
+	row sep=\\,
+	begin table=\begin{longtable},
+	end table=\end{longtable},
+	every head row/.append style={after row=\endhead},
+}
+\end{codeexample}
+
+	If the first page should have a different header, you can use \declareandlabel{\endfirsthead} provided by the |longtable| package:
+\begin{codeexample}[code only]
+% replicate column names on top of every page of a multi-page table,
+% but with different values for first page:
+\pgfplotstableset{
+	row sep=\\,
+	begin table=\begin{longtable},
+	end table=\end{longtable},
+	every head row/.append style={after row={%
+		    \caption{The caption}%
+			\endfirsthead
+			\multicolumn{3}{c}{{\bfseries \tablename\ \thetable{} -- continued from previous page}} \\
+			\endhead
+		},
+	},
+}
+\end{codeexample}
+	\noindent The preceding example uses the |longtable| macros |\caption|, |\endfirsthead|, |\thetable|, and |\endhead|. In addition, it requires to provide the number of columns (|{3}| in this case) \emph{explicitly}.
+
+	It is also possible to \emph{change} the value of |begin table|. For example,
 \begin{codeexample}[code only]
 \pgfplotstableset{
 	begin table/.add={}{[t]},
diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplotstodo.pdf b/Master/texmf-dist/doc/latex/pgfplots/pgfplotstodo.pdf
index 6a2b52c5979..8c4aab7bc8b 100644
--- a/Master/texmf-dist/doc/latex/pgfplots/pgfplotstodo.pdf
+++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplotstodo.pdf
diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplotstodo.tex b/Master/texmf-dist/doc/latex/pgfplots/pgfplotstodo.tex
index cf93843552b..731e28ed67d 100644
--- a/Master/texmf-dist/doc/latex/pgfplots/pgfplotstodo.tex
+++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplotstodo.tex
@@ -28,99 +28,84 @@
 \begin{document}
 \maketitle
 \tableofcontents
+
 \section{Tests}
 
+ATTENTION: fix the buggy styles for axis lines=center in 3d
+
 last test verifications:
 
 \begin{tabular}{lllll}
 					&	pgf	CVS	&	pgf 2.10	& pgf	2.00	&pgf 2.00+compat=default\\
-pgfplotstests		&	for 1.5.1	&	for 1.5.1		& for 1.4		&2009-12-30					\\
-manual				&	for 1.5.1	&	for 1.5.1		& for 1.5		&	\\
-pgfplotstable.pdf	&	for 1.5.1	&	for 1.5.1		& for 1.5\\
-example	latex		&	for 1.5	&	for 1.5     & 2009-12-30					\\
-example	context		&	for 1.5.1	&	for 1.5.1     & 2009-12-30				\\
-example	plain tex	&	for 1.5.1	&	for 1.5.1     & 2009-12-30				\\
-tests context		&	for 1.4	&   for 1.5.1\\
+pgfplotstests		&	for 1.6	&	for 1.6		& for 1.4		&2009-12-30					\\
+manual				&	for 1.6	&	for 1.6		& for 1.5		&	\\
+pgfplotstable.pdf	&	for 1.6	&	for 1.6		& for 1.5\\
+example	latex		&	for 1.6	&	for 1.5     & 2009-12-30					\\
+example	context		&	for 1.6	&	for 1.5.1     & 2009-12-30				\\
+example	plain tex	&	for 1.6	&	for 1.5.1     & 2009-12-30				\\
+tests context		&	for 1.6	&   for 1.5.1\\
 \end{tabular}
 
-\section{Future work}
-\begin{itemize}
-\item docs: replace `\verb|row sep=\\|' by newlines, it should work now!\ok
-\item docs: search for FIXME
-\item hist 98\%  \ok
-\item quiver 95\%  \ok
-\item contours 95\% ready.
-  	add "labels=if less than X" ?
-
-	contour gnuplot currently works if and only if the mesh contains end-of-scanline markers and is in ordering x varies (everything gnuplot-specific)
-
-	documentation is incomplete \ok
-\item[perhaps] contour filled 10\% ready 
-\item plot graphics 3D:
-	\begin{itemize}
-		\item Documentation \ok
-		\item datascaling
-	\end{itemize}
-\item patch plots lib: 95\%
+\section{Documentation todo}
+\begin{bugtracker}
+\begin{doctodo}[+]
+	layers: 
+	\begin{enumerate}
+		\item \ok motivation and use-cases
+		\item \ok simple example
+		\item \ok multi-axis discussion
+		\item \ok tikz integration
+		\item \ok explain how to merge custom layers and pgfplots layers (and say that pgfplots overwrites layers of tikz)
+		\item \ok specialties: defining own layer sets
+		\item \ok limitations: show list of supported anchors and explain implications of cell picture
+	\end{enumerate}
+	
 
-	\begin{itemize}
-		\item 
-	implement displacement input
-		\item bug for quad rectangle in middle point
-		\item \ok perhaps 1d quadratic/cubic patches (simple)?
-		\item \ok color data per patch, also for connectivity data
-		\item document 'shader=flat' in patchplot lib
-		\item document miter limit and line join options. miter limit=1 is good, use it\ok
-
-		$\rightarrow$ perhaps \verb|miter limit=1| as initial config for \verb|patch| plots?\ok
-	\end{itemize}
-\item polar axes: 90\% ready
-	\begin{itemize}
-  	\item Documentation \ok 
-	\item missing feature: input of cartesian coords \ok
-	\item special cases \ok (?)
-	\item tests
-	\end{itemize}
-\item ternary: 95\% ready
-	\begin{itemize}
-  	\item but there are still quite a lot of feature request concerning them
-	\item konnodalplots 90\% ready
-	\end{itemize}
-\item smith charts: 90\% ready
-  now
+	the clipping of marker paths should always be active - but at least for layered graphics. It also needs a better UI
 
-  \begin{itemize}
-  	\item the huge smith chart is sub-optimal
-  	\item perhaps enough for the first stable?
-\end{itemize}
-\item internal coordmath framework: 80\% ready, but not used everywhere and
-  undocumented
-\item layer graphics support for axes 0\% (should be easy, implement in new branch)
-	\begin{itemize}
-		\item new key \verb|/pgfplots/on layer| and \verb|/pgfplots/use layers=<sequence>| (or empty value)
-		\item give the key a family such that it won't be extracted from styles
-		\item the \verb|use layers| activates that stuff. Perhaps it can be set automatically somehow?
-		Perhaps with advanced key filtering? Or I provide an error message if \verb|on layer| is used although \verb|use layers| is off.
-		\item provide a set of positions where the \verb|on layer| key is checked
-	\end{itemize}
-\item view configuration:
-	\begin{itemize}
-		\item \ok document gnuplot import/export
-		\item view matrix input?
-	\end{itemize}
-\item check 'empty lines' feature -> should have compat mode
-\item new public axis API is 90\% complete:
-  	 documentation is missing
-  	 log scaling is difficult, still
-\item Bugfixes
+	TODO:
 	\begin{itemize}
-		\item what about 'scale' transformations? Are they correct?
+		\item implement 'clip mode=individual' for axis paths
+
+		FIXME : is there are good reason why \verb|clip mode=global| is a bad choice for the default!? 
+
+		Perhaps the layered graphics feature can be shipped in a first version -- with \verb|clip mode=global|. It is simpler anyway.
+
+		\item \ok document 'mark layer'
 	\end{itemize}
-\end{itemize}
+\end{doctodo}
+
+\begin{doctodo}[+]
+	document benefits of using lualatex (memory limits)
+\end{doctodo}
 
+\begin{doctodo}
+	document installation requirements when using lualatex (LUAINPUTS should contain pgfplots install dir)
+\end{doctodo}
 
-\section{Documentation todo}
-\begin{bugtracker}
+\begin{doctodo}[+]
+	pgfplotstable: document that 
+\begin{verbatim}
+\pgfplotstabletypeset[
+  typeset cell/.append code={%
+		\ifnum\pgfplotstablerow<0
+			\pgfkeyssetvalue{/pgfplots/table/@cell content}{}%
+		\fi
+  },
+  outfile={table},
+  header=false,
+  columns/0/.style={string type,column type=r},
+  columns/1/.style={string type,column type=l},
+  columns/2/.style={string type,column type=l}
+  ]
+\end{verbatim}
+	can be used to eliminate the displayed header line.
+
+\end{doctodo}
+
+\begin{doctodo}[+]
+	\verb|smithchart mirrored| is undocumented! see \url{https://sourceforge.net/tracker/?func=detail&atid=1060657&aid=3486928&group_id=224188}
+\end{doctodo}
 
 \begin{doctodo}[+]
 	document that \verb|axis lines=none| is essentially an alias for \verb|hide axis| .
@@ -169,7 +154,7 @@ tests context		&	for 1.4	&   for 1.5.1\\
 \end{doctodo}
 
 
-\begin{doctodo}
+\begin{doctodo}[+]
 	document some FAQ for number formatting options.
 
 	This should contain how to get non-exponential number printing for log axes
@@ -214,7 +199,7 @@ document the possibiliy of skewed 3d axes by means of manually provided unit vec
 	mentioning of point meta is missing .
 \end{doctodo}
 
-\begin{doctodo}
+\begin{doctodo}[+]
 	document the new 'data cs' feature
 \end{doctodo}
 
@@ -412,20 +397,16 @@ beschreiben waere so mein Tip
 \end{minimal}
 \end{doctodo}
 
-\begin{doctodo}[-]
+\begin{doctodo}[+]
   release notes:
 	mention improvements of 'shader=interp'
 \end{doctodo}
 
-\begin{doctodo}[-]
-  new 'output cs' feature (when it is finished)
-\end{doctodo}
-
 \begin{doctodo}[+]
   There is a typo on section 4.5.12: "As for for dimensional patch plots "
 \end{doctodo}
 
-\begin{doctodo}[-]
+\begin{doctodo}[+]
   quiver: the tests have a further pretty example where quiver is on top of
   a surf, attached to z =2 or so.
 \end{doctodo}
@@ -443,14 +424,16 @@ beschreiben waere so mein Tip
 \end{doctodo}
 
 \begin{doctodo}[-]
-  try a bar plot with individually shaded bars
+  try a bar plot with individually shaded bars 
+
+  FIXME : collect details
 \end{doctodo}
 
 \begin{doctodo}[+]
   document 'contour prepared', 'contour external' and 'contour gnuplot'.
 \end{doctodo}
 
-\begin{doctodo}[-]
+\begin{doctodo}[+]
   contour external: Do not forget the \verb|\", \'| etc special handling .
 \end{doctodo}
 
@@ -479,11 +462,11 @@ beschreiben waere so mein Tip
 	+ do not forget 'cartesian cs' and its applications
 \end{doctodo}
 
-\begin{doctodo}[-]
+\begin{doctodo}[+]
   document frac whole format
 \end{doctodo}
 
-\begin{doctodo}[-]
+\begin{doctodo}[+]
   document /pgfplots/empty line
 \end{doctodo}
 
@@ -513,7 +496,7 @@ beschreiben waere so mein Tip
   tracingstuff.
 \end{doctodo}
 
-\begin{doctodo}[-]
+\begin{doctodo}[+]
   document how to fix dimension too large problems: restrict to domain for
   example
 \end{doctodo}
@@ -528,7 +511,7 @@ beschreiben waere so mein Tip
   instead
 \end{doctodo}
 
-\begin{doctodo}[-]
+\begin{doctodo}[+]
   pgfplotstable: show how to use '\verb|\begin{longtable}|'
 \end{doctodo}
 
@@ -543,7 +526,7 @@ beschreiben waere so mein Tip
 \section{Bugs/Features in PGF/TikZ}
 \begin{bugtracker}
 
-\begin{pgfbug}
+\begin{pgfbug}[+]
 	number printer: apply 
             \verb|set thousands separator={\cdot}| also to fractional parts:
 \begin{minimal}
@@ -652,7 +635,7 @@ Thanks!
 
 \end{pgfbug}
 
-\begin{pgfbug}[open]
+\begin{pgfbug}[closed]
 	\verb|\pgfmathdivide@{-0.8}{1.00002}\pgfmathresult| yields
 
 	\makeatletter
@@ -725,16 +708,16 @@ Thanks!
   implement \verb|\pgfmathfloattocount|
 \end{pgfbug}
 
-\begin{pgfbug}[-]
+\begin{pgfbug}[+]
   external lib: think whether it is possible to provide the real jobname
   without explicit user input. Idea: transport it as TeX code argument to pdflatex
 \end{pgfbug}
 
-\begin{pgfbug}[-]
+\begin{pgfbug}[+]
   provide '$\times$' or more general formatting rules to number printer
 \end{pgfbug}
 
-\begin{pgfbug}[-]
+\begin{pgfbug}[+]
   code 2 args doesn't work correctly with spaces between the arguments!?
 \end{pgfbug}
 
@@ -760,7 +743,7 @@ Thanks!
   it seems fadings don't work correctly with externalization!? 
 \end{pgfbug}
 
-\begin{pgfbug}[-]
+\begin{pgfbug}[+]
   include addition of Christophe Jorssen for MD5 checksums in external lib
 \end{pgfbug}
 
@@ -816,7 +799,7 @@ Thanks!
   'text height=1em' realisieren mit [node font units]1em 
 \end{pgfbug}
 
-\begin{pgfbug}[-]
+\begin{pgfbug}[+]
   compatiblity code todo:
   	- the example for plot graphics (with view=0{90}) doesn't work.
 	$\leadsto$ that's the '\verb|exp(0-x^2)|' bug which is still in pgf 2.00!
@@ -828,7 +811,153 @@ Thanks!
 % BUGS
 \section{Bugs in PGFPlots}
 
+
 \begin{bugtracker}
+
+\begin{bug}
+	new layered graphics stuff: the style changes of the layer config are read too later; it is impossible to overwrite them within the same axis (for example using \verb|set layers,tick style={on layer=...}|)
+\end{bug}
+
+\begin{bug}
+	improper alignment of x tick labels which have different baselines or different heights.
+
+	Idea: introduce \verb|\strut|
+
+	\url{https://sourceforge.net/tracker/?func=detail&aid=3516368&group_id=224188&atid=1060656}
+\end{bug}
+
+\begin{bug}[prio=9,closed]
+	SCALING PROBLEMS in 3d:
+
+	\begin{itemize}
+		\item 
+	the plot box ratio and axis equal feature both need to imply \verb|scale mode=scale uniformly|. But it is still wrong; even if one activates the correct scale mode.
+
+	The problem: the axis equal stuff operates on the projected unit vectors and applies different scalings. 
+		\item combining plot box ratio and explicit limits seems to corrupt the display (?)
+	\end{itemize}
+\end{bug}
+
+\begin{bug}
+	x tick scale label for style \verb|tiny| has an unsuitable shift
+\end{bug}
+
+\begin{bug}
+	the3d clip path is sometimes bad: perhaps it should be the bounding box instead!?
+	
+	\includegraphics[width=\textwidth]{figures/pgfplots-surface-cutoff.png}
+\end{bug}
+
+\begin{bug}
+	Internal coordmath framework: it is not used everywhere
+\end{bug}
+
+\begin{bug}
+	stacked plots + log basis y + log  does not work.
+\begin{minimal}
+\begin{tikzpicture}
+     \begin{axis}[ymode=log
+                , ybar stacked
+                , log basis y=10
+                 ]
+          \addplot coordinates {(0,1e5)};
+          \addplot coordinates {(0,9e5)};
+     \end{axis}
+\end{tikzpicture}
+\end{minimal}
+	The problem is documented as FIXME in pgfplotsstackedpltos.code.tex
+
+	suggested fix: refactor the log and exp methods: always provide the requested basis explicitly, and provide some `prepare log basis' method to improve performance. Do not attach the log basis to the coord math.
+\end{bug}
+
+\begin{bug}
+	\verb|log number format code| is a global variable and cannot be set for individual axes.
+
+	This applies to \verb|log ticks with fixed point| as well.
+\end{bug}
+
+\begin{bug}
+	One cannot manually load a table inside of a pgfplots axis if it contains empty lines: the scanline callback is active
+\end{bug}
+
+\begin{bug}
+	\verb|ybar legend| does not contain \verb|ybar| (sourceforge 3482770)
+\end{bug}
+
+\begin{bug}
+	\verb|refstyle| does only include partial information of the reference style. (sourceforge 3482770)
+\end{bug}
+
+\begin{bug}
+	Using square brackets as first char inside of \verb|\legend| leads to a failure: \verb|\legend{[\ion{Ne}{2}],...}|.
+
+	Cause: the \verb|\legend| command does not properly insert \verb|[]| in front of every entry (as it ought to).
+\end{bug}
+
+\begin{bug}
+	Adding \verb|error bars/.cd| to \verb|\addplot| options causes the \verb|\ref| image to fail. 
+
+	The problem is the key filtering apparently: it discards the \verb|/pgfplots/.cd| but leaves the \verb|error bars/.cd|.
+\end{bug}
+
+\begin{bug}
+	quiver plots: the clip path does not respect arrow paths
+\end{bug}
+
+\begin{bug}
+	
+	The default label placement for axis lines=center in 3d appears to be wrong
+\begin{verbatim}
+\begin{tikzpicture}
+\begin{axis}[
+  axis lines=center,
+  axis on top,
+  xlabel={$x$}, ylabel={$y$}, zlabel={$z$},
+  domain=0:1,
+  y domain=0:2*pi,
+  xmin=-1.5, xmax=1.5,
+  ymin=-1.5, ymax=1.5, zmin=0.0,
+  mesh/interior colormap=
+  	{blueblack}{color=(black) color=(blue)},
+  colormap/blackwhite, 
+  samples=10,
+  samples y=40,
+  z buffer=sort,
+ ]
+  \addplot3[surf] 
+  	({x*cos(deg(y))},{x*sin(deg(y))},{x});
+\end{axis}
+\end{tikzpicture}
+\end{verbatim}
+
+	Potential fixes: (a) redefine \verb|right of origin| and its friends for 3d; (b) do not use the \verb|right of origin| things, prefer \verb|rel axis cs=1,0.5,0.5|. Problem: \verb|rel axis cs| must know where the fractions to find the origin (keep in mind that a rel axis value of $0$ means ``lower end''). Perhaps some ``constant'' value should expand to the fraction for zero? 
+\end{bug}
+
+\begin{bug}
+	Alignment bug: axis x line=middle combined with a yshift shifts the xlabel incorrectly:
+\begin{minimal}
+\documentclass{report}
+\usepackage{pgfplots}
+\pgfplotsset{compat=1.3}
+
+\begin{document}
+  \begin{tikzpicture}
+  	\draw (0,0) circle (5pt);
+    \begin{scope}[yshift=-3cm]
+    \begin{axis}[width=10cm,height=3cm,xlabel={$x$},
+        axis x line = middle]
+      \addplot coordinates {
+        (0,1) (1,-1) (2,1)
+      };
+    \end{axis}
+    \end{scope}
+  \end{tikzpicture}
+\end{document} 
+\end{minimal}
+	Using \verb|xlabel style = {yshift=3cm}| in the plot will correctly
+position the x label (to its default position). 
+\end{bug}
+
 \begin{bug}
 	Using \verb|hide axis| or \verb|axis lines=none| causes the axis to vanish -- but it will still consume space in the bounding box!
 	
@@ -867,6 +996,7 @@ Thanks!
 
 	See \verb|unittest_hideaxis*|.
 
+	Seems to be better now (with the axis equal scaling fix)
 \end{bug}
 
 \begin{bug}[+]
@@ -881,7 +1011,7 @@ Thanks!
 	\verb|https://sourceforge.net/tracker/index.php?func=detail&aid=3457210&group_id=224188&atid=1060656|
 \end{bug}
 
-\begin{bug}
+\begin{bug}[+]
 	nodes near coords is broken for layer branch
 \end{bug}
 
@@ -893,7 +1023,7 @@ Thanks!
 	xbar and nodes near coords does not automatically align the nodes, see \verb|http://tex.stackexchange.com/questions/31701/pgfplots-nodes-near-coords-on-xbar-chart-is-off|
 \end{bug}
 
-\begin{bug}
+\begin{bug}[+]
 	view direction is imprecise. It seems as if the $z$ direction is wrong.
 
 	See the recent commits on branch \verb|mesh_bg_colormap|
@@ -913,7 +1043,7 @@ Thanks!
 	\verb|\pgfplotsforeachungrouped| cannot be combined with three or more arguments like \verb|\foreach|
 \end{bug}
 
-\begin{bug}
+\begin{bug}[+]
 	If one specifies \verb|\scope| within an axis, the plots (partially) use their variables, but legends do not.
 \begin{minimal}
 \documentclass{article}
@@ -2062,12 +2192,26 @@ and you can remark that colour filling overlaps x- and y-axis ! So I suggest tha
 \begin{bugtracker}
 
 \begin{feature}
+	Layered graphics: consider drawing tick lines which are on the ``outer part'' of the axis on the foreground layer.
+
+	See
+	\verb|http://tex.stackexchange.com/questions/31708/draw-a-bivariate-normal-distribution-in-tikz/31713#31713| for a motivation (the tick lines are hidden by the surface)
+\end{feature}
+
+\begin{feature}
+	filled contour plots (prototype is 10\% ready)
+\end{feature}
+
+\begin{feature}
+	allow support for units in \verb|bar width| and \verb|bar shift| (compare the implementation for circles/ellipses)
+\end{feature}
+
+\begin{feature}[+]
 	improve support for circle / ellipse paths inside of an axis
 
 	compare \url{http://www.digipedia.pl/usenet/thread/16719/198}
 
 	\url{http://sourceforge.net/mailarchive/forum.php?thread_name=D595FD68-AFAB-4C1C-8B9D-A2F84D1A0598\%40mac.com&forum_name=pgfplots-features}
-
 \end{feature}
 
 \begin{feature}
@@ -2096,13 +2240,15 @@ and you can remark that colour filling overlaps x- and y-axis ! So I suggest tha
 	provide a way to provide more customization to stacked plots as in
 	
 	\verb|http://tex.stackexchange.com/questions/13627/pgfplots-multiple-shifted-stacked-plots-in-one-diagram|
+
+	(stacked and clustered bar charts)
 \end{feature}
 
 \begin{feature}
 	the \verb|empty line| feature should produce a log notice when it finds an empty line in compat mode.
 \end{feature}
 
-\begin{feature}
+\begin{feature}[+]
 	smith charts: provide the same as now, but mirrored (concentric from left end rather then right end)
 \end{feature}
 
@@ -2218,7 +2364,7 @@ If there would be a search path like \verb|\graphicspath| for graphics it would
 \end{feature}
 
 
-\begin{feature}[-]
+\begin{feature}[+]
   plot graphics for 3D axes.
 \end{feature}
 
@@ -2242,6 +2388,10 @@ If there would be a search path like \verb|\graphicspath| for graphics it would
   discontinuity in the middle of a plot
   (as an example see the phase diagram of water
   \url{http://pruffle.mit.edu/3.00/Lecture_29_web/img20.gif})
+
+  \url{http://peltiertech.com/images/2011-11/Ybroken.png}
+
+  \url{http://tex.stackexchange.com/questions/46422/axis-break-in-pgfplots}
 \end{feature}
 
 \begin{feature}[-]
author	Karl Berry <karl@freefriends.org>	2012-08-30 00:13:50 +0000
committer	Karl Berry <karl@freefriends.org>	2012-08-30 00:13:50 +0000
commit	8231318d57cff4a8f9fcd70d387a3f00f4513428 (patch)
tree	e99336aabe9de04bad055bcf07814a1a00474a38 /Master/texmf-dist/doc/latex/pgfplots
parent	c16497900d7216f5269a43b9c18ae469820d3cd2 (diff)