Make escaped $ work in non-usetex mode

mdboom · mdboom · commit 40e5efd96b99 · 2008-12-15T17:58:43.000Z
svn path=/trunk/matplotlib/; revision=6613
diff --git a/doc/users/mathtext.rst b/doc/users/mathtext.rst
@@ -3,17 +3,19 @@
 Writing mathematical expressions
 ================================
 
-You can use TeX markup in any matplotlib text string.  Note that you
-do not need to have TeX installed, since matplotlib ships its own TeX
-expression parser, layout engine and fonts.  The layout engine is a
-fairly direct adaptation of the layout algorithms in Donald Knuth's
-TeX, so the quality is quite good (matplotlib also provides a
-``usetex`` option for those who do want to call out to TeX to generate
-their text (see :ref:`usetex-tutorial`).
-
-Any text element can use math text.  You need to use raw strings
-(preceed the quotes with an ``'r'``), and surround the string text
-with dollar signs, as in TeX.  Regular text and mathtext can be
+You can use a subset TeX markup in any matplotlib text string by
+placing it inside a pair of dollar signs ($).
+
+Note that you do not need to have TeX installed, since matplotlib
+ships its own TeX expression parser, layout engine and fonts.  The
+layout engine is a fairly direct adaptation of the layout algorithms
+in Donald Knuth's TeX, so the quality is quite good (matplotlib also
+provides a ``usetex`` option for those who do want to call out to TeX
+to generate their text (see :ref:`usetex-tutorial`).
+
+Any text element can use math text.  You should use raw strings
+(preceed the quotes with an ``'r'``), and surround the math text with
+dollar signs ($), as in TeX.  Regular text and mathtext can be
 interleaved within the same string.  Mathtext can use the Computer
 Modern fonts (from (La)TeX), `STIX <http://www.aip.org/stixfonts/>`_
 fonts (with are designed to blend well with Times) or a Unicode font
@@ -35,6 +37,26 @@ Whereas this::
 
 produces ":math:`\alpha > \beta`".
 
+.. note::
+   Mathtext should be placed between a pair of dollar signs ($).  To
+   make it easy to display monetary values, e.g. "$100.00", if a
+   single dollar sign is present in the entire string, it will be
+   displayed verbatim as a dollar sign.  This is a small change from
+   regular TeX, where the dollar sign in non-math text would have to
+   be escaped ('\$').
+
+.. note::
+   While the syntax inside the pair of dollar signs ($) aims to be
+   TeX-like, the text outside does not.  In particular, characters
+   such as::
+
+     # $ % & ~ _ ^ \ { } \( \) \[ \]
+
+   have special meaning outside of math mode in TeX.  Therefore, these
+   characters will behave differently depending on the rcParam
+   ``text.usetex`` flag.  See the :ref:`usetex tutorial
+   <usetex-tutorial>` for more information.
+
 Subscripts and superscripts
 ---------------------------
 
diff --git a/doc/users/text_intro.rst b/doc/users/text_intro.rst
@@ -18,8 +18,8 @@ You have total control over every text property (font size, font
 weight, text location and color, etc) with sensible defaults set in
 the rc file.  And significantly for those interested in mathematical
 or scientific figures, matplotlib implements a large number of TeX
-math symbols and commands, to support mathematical expressions
-anywhere in your figure.
+math symbols and commands, to support :ref:`mathematical expressions
+<mathtext-tutorial>` anywhere in your figure.
 
 
 Basic text commands
diff --git a/doc/users/usetex.rst b/doc/users/usetex.rst
@@ -59,6 +59,14 @@ Note that display math mode (``$$ e=mc^2 $$``) is  not supported, but adding the
 command ``\displaystyle``, as in `tex_demo.py`, will produce the same
 results.
 
+.. note::
+   Certain characters require special escaping in TeX, such as::
+
+     # $ % & ~ _ ^ \ { } \( \) \[ \]
+
+   Therefore, these characters will behave differently depending on
+   the rcParam ``text.usetex`` flag.
+
 .. _usetex-unicode:
 
 usetex with unicode
diff --git a/lib/matplotlib/offsetbox.py b/lib/matplotlib/offsetbox.py
@@ -548,7 +548,7 @@ def get_window_extent(self, renderer):
 
 
     def get_extent(self, renderer):
-        ismath = self._text.is_math_text(self._text._text)
+        clean_line, ismath = self._text.is_math_text(self._text._text)
         _, h_, d_ = renderer.get_text_width_height_descent(
             "lp", self._text._fontproperties, ismath=False)
 
@@ -558,30 +558,30 @@ def get_extent(self, renderer):
         line = info[0][0] # first line
 
         _, hh, dd = renderer.get_text_width_height_descent(
-            line, self._text._fontproperties, ismath=ismath)
+            clean_line, self._text._fontproperties, ismath=ismath)
 
 
         self._baseline_transform.clear()
         if len(info) > 1 and self._multilinebaseline: # multi line
             d = h-(hh-dd)  # the baseline of the first line
             d_new = 0.5 * h  - 0.5 * (h_ - d_)
-            
+
             self._baseline_transform.translate(0, d - d_new)
             d = d_new
-            
+
         else: # single line
 
             h_d = max(h_ - d_, h-dd)
 
             if self.get_minimumdescent():
                 ## to have a minimum descent, #i.e., "l" and "p" have same
-                ## descents. 
+                ## descents.
                 d = max(dd, d_)
             else:
                 d = dd
 
             h = h_d + d
-            
+
         return w, h, 0., d
 
 
diff --git a/lib/matplotlib/text.py b/lib/matplotlib/text.py
@@ -248,8 +248,9 @@ def _get_layout(self, renderer):
 
         baseline = None
         for i, line in enumerate(lines):
+            clean_line, ismath = self.is_math_text(line)
             w, h, d = renderer.get_text_width_height_descent(
-                line, self._fontproperties, ismath=self.is_math_text(line))
+                clean_line, self._fontproperties, ismath=ismath)
             if baseline is None:
                 baseline = h - d
             whs[i] = w, h
@@ -480,8 +481,9 @@ def draw(self, renderer):
                 y = y + posy
                 if renderer.flipy():
                     y = canvash-y
+                clean_line, ismath = self.is_math_text(line)
 
-                renderer.draw_tex(gc, x, y, line,
+                renderer.draw_tex(gc, x, y, clean_line,
                                   self._fontproperties, angle)
             return
 
@@ -490,10 +492,11 @@ def draw(self, renderer):
             y = y + posy
             if renderer.flipy():
                 y = canvash-y
+            clean_line, ismath = self.is_math_text(line)
 
-            renderer.draw_text(gc, x, y, line,
+            renderer.draw_text(gc, x, y, clean_line,
                                self._fontproperties, angle,
-                               ismath=self.is_math_text(line))
+                               ismath=ismath)
 
     def get_color(self):
         "Return the color of the text"
@@ -875,15 +878,18 @@ def is_math_text(self, s):
         """
         Returns True if the given string *s* contains any mathtext.
         """
-        if rcParams['text.usetex']: return 'TeX'
-
         # Did we find an even number of non-escaped dollar signs?
         # If so, treat is as math text.
         dollar_count = s.count(r'$') - s.count(r'\$')
-        if dollar_count > 0 and dollar_count % 2 == 0:
-            return True
+        even_dollars = (dollar_count > 0 and dollar_count % 2 == 0)
+
+        if rcParams['text.usetex']:
+            return s, 'TeX'
 
-        return False
+        if even_dollars:
+            return s, True
+        else:
+            return s.replace(r'\$', '$'), False
 
     def set_fontproperties(self, fp):
         """
