Merge pull request matplotlib#16900 from timhoffm/doc-common-texification

Document and test common_texification()

Author: QuLogic

lib/matplotlib/backends/backend_pgf.py

@@ -94,9 +94,15 @@ def repl_mathdefault(m):
 
 
 def common_texification(text):
-    """
+    r"""
     Do some necessary and/or useful substitutions for texts to be included in
     LaTeX documents.
+
+    This distinguishes text-mode and math-mode by replacing the math separator
+    ``$`` with ``\(\displaystyle %s\)``. Escaped math separators (``\$``)
+    are ignored.
+
+    The following characters are escaped in text segments: ``_^$%``
     """
     # Sometimes, matplotlib adds the unknown command \mathdefault.
     # Not using \mathnormal instead since this looks odd for the latex cm font.

lib/matplotlib/tests/test_backend_pgf.py

@@ -13,7 +13,7 @@
 import matplotlib.pyplot as plt
 from matplotlib.testing.compare import compare_images, ImageComparisonFailure
 from matplotlib.testing.decorators import image_comparison, _image_directories
-from matplotlib.backends.backend_pgf import PdfPages
+from matplotlib.backends.backend_pgf import PdfPages, common_texification
 
 baseline_dir, result_dir = _image_directories(lambda: 'dummy func')
 
@@ -89,6 +89,16 @@ def create_figure():
     plt.ylim(0, 1)
 
 
+@pytest.mark.parametrize('plain_text, escaped_text', [
+    (r'quad_sum: $\sum x_i^2$', r'quad\_sum: \(\displaystyle \sum x_i^2\)'),
+    (r'no \$splits \$ here', r'no \$splits \$ here'),
+    ('with_underscores', r'with\_underscores'),
+    ('% not a comment', r'\% not a comment'),
+    ('^not', r'\^not'),
+])
+def test_common_texification(plain_text, escaped_text):
+    assert common_texification(plain_text) == escaped_text
+
 # test compiling a figure to pdf with xelatex
 @needs_xelatex
 @pytest.mark.backend('pgf')