Allow "real" LaTeX code for pgf.preamble in matplotlibrc (#12674)

sxntxn · jklymak · commit bd7829d9895a · 2018-11-11T08:18:40.000-08:00
* Allow "real" LaTeX code for pgf.preamble in matplotlibrc

This allows to use the rc key "pgf.preamble" to contain "real" LaTeX
code. As of before this patch, commas are used as parser separators,
causing the PGF backend call to latex to fail, for example at loading
packages which contain options such as:
\usepackage[protrusion=true, expansion=false]{microtype}

Passing a list of strings from within a Python script works fine, and
with this patch it stays this way.

* Python3 only: remove six

* Flake8: add second blank line

* Return "" instead of str()

As per review by anntzer

* Raise ValueError directly

As per review by anntzer

* Add API changes note

* Rename function validate_stringlist_or_string

... to _validate_stringlist_or_string

As per review by anntzer

* Join on '\n'

As per review by tacaswell

* Also apply to text.latex.preamble

* Change documentation in matplotlibrc.template

Update documentation of text.latex.preamble.
Add reference to text.latex.preamble for pgf.preamble.

* Add "What's New" entry

Actually a copy of doc/api/next_api_changes/2018-10-30-rcparams-pgf.preamble-full-LaTeX-support.rst

* Check for Iterable instead of list

... in order to also accept tuples as input, not only lists.
diff --git a/doc/api/next_api_changes/2018-10-30-rcparams-pgf.preamble-full-LaTeX-support.rst b/doc/api/next_api_changes/2018-10-30-rcparams-pgf.preamble-full-LaTeX-support.rst
@@ -0,0 +1,11 @@
+Allow "real" LaTeX code for ``pgf.preamble`` and ``text.latex.preamble`` in matplotlib rc file
+``````````````````````````````````````````````````````````````````````````````````````````````
+
+Previously, the rc file keys ``pgf.preamble`` and ``text.latex.preamble`` were parsed using commmas as separators. This would break valid LaTeX code, such as::
+
+\usepackage[protrusion=true, expansion=false]{microtype}
+
+The parsing has been modified to pass the complete line to the LaTeX system,
+keeping all commas.
+
+Passing a list of strings from within a Python script still works as it used to.
diff --git a/doc/users/next_whats_new/2018-10-30-rcparams-pgf.preamble-full-LaTeX-support.rst b/doc/users/next_whats_new/2018-10-30-rcparams-pgf.preamble-full-LaTeX-support.rst
@@ -0,0 +1,11 @@
+Allow "real" LaTeX code for ``pgf.preamble`` and ``text.latex.preamble`` in matplotlib rc file
+``````````````````````````````````````````````````````````````````````````````````````````````
+
+Previously, the rc file keys ``pgf.preamble`` and ``text.latex.preamble`` were parsed using commmas as separators. This would break valid LaTeX code, such as::
+
+\usepackage[protrusion=true, expansion=false]{microtype}
+
+The parsing has been modified to pass the complete line to the LaTeX system,
+keeping all commas.
+
+Passing a list of strings from within a Python script still works as it used to.
diff --git a/lib/matplotlib/backends/backend_pgf.py b/lib/matplotlib/backends/backend_pgf.py
@@ -59,7 +59,7 @@ def get_fontspec():
 
 def get_preamble():
     """Get LaTeX preamble from rc."""
-    return "\n".join(rcParams["pgf.preamble"])
+    return rcParams["pgf.preamble"]
 
 ###############################################################################
 
diff --git a/lib/matplotlib/rcsetup.py b/lib/matplotlib/rcsetup.py
@@ -175,6 +175,20 @@ def validate_string_or_None(s):
         raise ValueError('Could not convert "%s" to string' % s)
 
 
+def _validate_stringlist_or_string(s):
+    """convert s to string or raise"""
+    if s is None or s == 'None':
+        return ""
+    try:
+        if isinstance(s, str):
+            return s
+        if isinstance(s, Iterable):
+            return '\n'.join([str(i) for i in s])
+        raise ValueError()
+    except ValueError:
+        raise ValueError('Could not convert "%s" to string' % s)
+
+
 def validate_axisbelow(s):
     try:
         return validate_bool(s)
@@ -1115,7 +1129,7 @@ def _validate_linestyle(ls):
     'text.color':          ['black', validate_color],
     'text.usetex':         [False, validate_bool],
     'text.latex.unicode':  [True, validate_bool],
-    'text.latex.preamble': [[], validate_stringlist],
+    'text.latex.preamble': ['', _validate_stringlist_or_string],
     'text.latex.preview':  [False, validate_bool],
     'text.dvipnghack':     [None, validate_bool_maybe_none],
     'text.hinting':        ['auto', validate_hinting],
@@ -1391,7 +1405,7 @@ def _validate_linestyle(ls):
     # use matplotlib rc settings for font configuration
     'pgf.rcfonts':   [True, validate_bool],
     # provide a custom preamble for the latex process
-    'pgf.preamble':  [[], validate_stringlist],
+    'pgf.preamble':  ['', _validate_stringlist_or_string],
 
     # write raster image data directly into the svg file
     'svg.image_inline':     [True, validate_bool],
diff --git a/matplotlibrc.template b/matplotlibrc.template
@@ -229,14 +229,18 @@
 #text.latex.preamble :      ## IMPROPER USE OF THIS FEATURE WILL LEAD TO LATEX FAILURES
                             ## AND IS THEREFORE UNSUPPORTED. PLEASE DO NOT ASK FOR HELP
                             ## IF THIS FEATURE DOES NOT DO WHAT YOU EXPECT IT TO.
-                            ## preamble is a comma separated list of LaTeX statements
-                            ## that are included in the LaTeX document preamble.
-                            ## An example:
-                            ## text.latex.preamble : \usepackage{bm},\usepackage{euler}
+                            ## text.latex.preamble is a single line of LaTeX code that
+                            ## will be passed on to the LaTeX system. It may contain
+                            ## any code that is valid for the LaTeX "preamble", i.e.
+                            ## between the "\documentclass" and "\begin{document}"
+                            ## statements.
+                            ## Note that it has to be put on a single line, which may
+                            ## become quite long.
                             ## The following packages are always loaded with usetex, so
                             ## beware of package collisions: color, geometry, graphicx,
-                            ## type1cm, textcomp. Adobe Postscript (PSSNFS) font packages
-                            ## may also be loaded, depending on your font settings
+                            ## type1cm, textcomp.
+                            ## Adobe Postscript (PSSNFS) font packages may also be
+                            ## loaded, depending on your font settings.
 #text.latex.preview : False
 
 #text.hinting : auto   ## May be one of the following:
@@ -567,7 +571,7 @@
                                ## instead of uuid4
 ### pgf parameter
 #pgf.rcfonts : True
-#pgf.preamble :
+#pgf.preamble :            ## see text.latex.preamble for documentation
 #pgf.texsystem : xelatex
 
 ### docstring params
