Elaborate on mathtext documentation.

mdboom · mdboom · commit 7426f7f8505b · 2008-05-30T18:59:44.000Z
svn path=/trunk/matplotlib/; revision=5328
diff --git a/doc/users/index.rst b/doc/users/index.rst
@@ -93,6 +93,7 @@ and Macintosh OS X.
 .. toctree::
 
     pyplot_tutorial.rst
+    mathtext.rst
     navigation_toolbar.rst
     customizing.rst
     artists.rst
diff --git a/doc/users/mathtext.rst b/doc/users/mathtext.rst
@@ -0,0 +1,225 @@
+Writing mathematical expressions
+================================
+
+You can use TeX markup in any matplotlib text string; see the
+:mod:`matplotlib.mathtext` module documentation for details.  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).
+
+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
+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
+that you provide.  The mathtext font can be selected with the
+customization variable ``mathtext.fontset``.
+
+Here is a simple example::
+
+    # plain text
+    plt.title('alpha > beta')
+
+produces "alpha > beta".
+
+Whereas this::
+
+    # math text
+    plt.title(r'$\alpha > \beta$')
+
+produces ":math:`\alpha > \beta`".
+
+.. TODO: Include a complete list here
+
+Subscripts and superscripts
+---------------------------
+
+To make subscripts and superscripts, use the ``'_'`` and ``'^'`` symbols::
+
+    r'$\alpha_i > \beta_i$'
+
+.. math::
+
+    \alpha_i > \beta_i
+
+Some symbols automatically put their sub/superscripts under and over
+the operator.  For example, to write the sum of :math:`x_i` from :math:`0` to
+:math:`\infty`, you could do::
+
+    r'$\sum_{i=0}^\infty x_i$'
+
+.. math::
+
+    \sum_{i=0}^\infty x_i
+
+Fractions
+---------
+
+Fractions can be created with the ``\frac{}{}`` command::
+
+    r'$\frac{3}{4}$'
+
+produces
+
+.. math::
+
+    \frac{3}{4}
+
+Fractions can be arbitrarily nested::
+
+    r'$\frac{5 - \frac{1}{x}}{4}$'
+
+produces
+
+.. math::
+
+    \frac{5 - \frac{1}{x}}{4}
+
+Note that special care needs to be taken to place parentheses and brackets around
+fractions.  Doing things the obvious way produces brackets that are
+too small::
+
+    r'$(\frac{5 - \frac{1}{x}}{4})$'
+
+.. math ::
+
+    (\frac{5 - \frac{1}{x}}{4})
+
+The solution is to precede the bracket with ``\left`` and ``\right``
+to inform the parser that those brackets encompass the entire object::
+
+    r'$\left(\frac{5 - \frac{1}{x}}{4}\right)$'
+
+.. math ::
+
+    \left(\frac{5 - \frac{1}{x}}{4}\right)
+
+Radicals
+--------
+
+Radicals can be produced with the ``\sqrt[]{}`` command.  For example:
+
+    r'$\sqrt{2}$'
+
+.. math ::
+
+    \sqrt{2}
+
+Any base can (optionally) be provided inside square brackets.  Note
+that the base must be a simple expression, and can not contain layout
+commands such as fractions or sub/superscripts.
+
+    r'$\sqrt[3]{x}$'
+
+.. math ::
+
+    \sqrt[3]{x}
+
+Fonts
+-----
+
+The default font is *italics* for mathematical symbols.  To change
+fonts, eg, to write "sin" in a Roman font, enclose the text in a font
+command::
+
+    r'$s(t) = \mathcal{A}\mathrm{sin}(2 \omega t)$'
+
+.. math::
+
+    s(t) = \mathcal{A}\mathrm{sin}(2 \omega t)
+
+More conveniently, many commonly used function names that are typeset in a
+Roman font have shortcuts.  So the expression above could be written
+as follows::
+
+    r'$s(t) = \mathcal{A}\sin(2 \omega t)$'
+
+.. math::
+
+    s(t) = \mathcal{A}\sin(2 \omega t)
+
+Here "s" and "t" are variable in italics font (default), "sin" is in
+Roman font, and the amplitude "A" is in calligraphy font.
+
+The choices available with all fonts are:
+
+    =============== =================================
+    Command         Result
+    =============== =================================
+    ``\mathrm``     :math:`\mathrm{Roman}`
+    ``\mathit``     :math:`\mathit{Italic}`
+    ``\mathtt``     :math:`\mathtt{Typewriter}`
+    ``\mathcal``    :math:`\mathcal{CALLIGRAPHY}`
+    =============== =================================
+
+When using the STIX fonts, you also have the choice of:
+
+    ================ =================================
+    Command          Result
+    ================ =================================
+    ``\mathbb``      :math:`\mathbb{Blackboard}`
+    ``\mathcircled`` :math:`\mathcircled{Circled}`
+    ``\mathfrak``    :math:`\mathfrak{Fraktur}`
+    ``\mathsf``      :math:`\mathsf{sans-serif}`
+    ================ =================================
+
+Accents
+-------
+
+An accent command may precede any symbol to add an accent above it.
+There are long and short forms for some of them.
+
+    ============================== =================================
+    Command                        Result
+    ============================== =================================
+    ``\acute a`` or ``\'a``        :math:`\acute a`
+    ``\bar a``                     :math:`\bar a`
+    ``\breve a``                   :math:`\breve a`
+    ``\ddot a`` or ``\"a``         :math:`\ddot a`
+    ``\dot a`` or ``\.a``          :math:`\dot a`
+    ``\grave a`` or ``\\`a``       :math:`\grave a`
+    ``\hat a`` or ``\^a``          :math:`\hat a`
+    ``\tilde a`` or ``\~a``        :math:`\tilde a`
+    ``\vec a``                     :math:`\vec a`
+    ============================== =================================
+
+In addition, there are two special accents that automatically adjust
+to the width of the symbols below:
+
+    ============================== =================================
+    Command                        Result
+    ============================== =================================
+    ``\widehat{xyz}``              :math:`\widehat{xyz}`
+    ``\widetilde{xyz}``            :math:`\widetilde{xyz}`
+    ============================== =================================
+
+
+Symbols
+-------
+
+You can also use a large number of the TeX symbols, as in ``\infty``,
+``\leftarrow``, ``\sum``, ``\int``; see :class:`matplotlib.mathtext` for a
+complete list.
+
+If a particular symbol does not have a name (as is true of many of the
+more obscure symbols in the STIX fonts), Unicode characters can
+also be used::
+
+   ur'Generic symbol: $\u23ce$'
+
+Example
+-------
+
+Here is an example illustrating many of these features in context.
+
+.. literalinclude:: figures/pyplot_mathtext.py
+
+.. image:: figures/pyplot_mathtext.png
+   :scale: 50
+
+
+
diff --git a/doc/users/pyplot_tutorial.rst b/doc/users/pyplot_tutorial.rst
@@ -76,7 +76,7 @@ several ways to set line properties
 
 * Use the setter methods of the ``Line2D`` instance.  ``plot`` returns a list
   of lines; eg ``line1, line2 = plot(x1,y1,x2,x2)``.  Below I have only
-  one line so it is a list of length 1.  I use tuple unpacking in the
+  one line so it is a list of7 length 1.  I use tuple unpacking in the
   ``line, = plot(x, y, 'o')`` to get the first element of the list::
 
       line, = plt.plot(x, y, 'o')
@@ -266,77 +266,3 @@ examples of how to control the alignment and orientation of text.
 
 
 
-Writing mathematical expressions
-================================
-
-You may have noticed in the histogram example above that we slipped a
-little TeX markup into the expression ``r'$\mu=100,\ \sigma=15$')``
-You can use TeX markup in any matplotlib text string; see the
-:mod:`matplotlib.mathtext` module documentation for details.  Note
-that you do not need to have TeX installed, since matplotlib ships
-its own TeX expression parser, layout engine and fonts.  Michael
-Droettboom has implemented the Knuth layout algorithms in python, 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).
-
-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
-interleaved within the same string.  Mathtext can use the Bakoma
-Computer Modern fonts, STIX fonts or a Unicode font that you provide.
-The mathtext font can be selected with the customization variable
-``mathtext.fontset``::
-
-    # plain text
-    plt.title('alpha > beta')
-
-    # math text
-    plt.title(r'$\alpha > \beta$')
-
-
-To make subscripts and superscripts use the '_' and '^' symbols::
-
-    plt.title(r'$\alpha_i > \beta_i$')
-
-You can also use a large number of the TeX symbols, as in ``\infty,
-\leftarrow, \sum, \int``; see :class:`matplotlib.mathtext` for a
-complete list.  The over/under subscript/superscript style is also
-supported.  To write the sum of x_i from 0 to infinity, you could do::
-
-    plt.text(1, -0.6, r'$\sum_{i=0}^\infty x_i$')
-
-The default font is *italics* for mathematical symbols.  To change
-fonts, eg, to write "sin" in a Roman font, enclose the text in a font
-command::
-
-    plt.text(1,2, r's(t) = $\mathcal{A}\mathrm{sin}(2 \omega t)$')
-
-
-Even better, many commonly used function names that are typeset in a
-Roman font have shortcuts.  So the expression above could be written
-as follows::
-
-    plt.text(1,2, r's(t) = $\mathcal{A}\sin(2 \omega t)$')
-
-
-Here "s" and "t" are variable in italics font (default), "sin" is in
-Roman font, and the amplitude "A" is in caligraphy font. The font
-choices are Roman ``\mathrm``, italics ``\mathit``, caligraphy
-``\mathcal``, and typewriter ``\mathtt``.  If using the STIX fonts,
-you also have the choice of blackboard (double-struck) ``\mathbb``,
-circled ``\mathcircled``, Fraktur ``\mathfrak``, script (cursive)
-``\mathscr`` and sans-serif ``\mathsf``.
-
-The following accents are provided: ``\hat``, ``\breve``, ``\grave``,
-``\bar``, ``\acute``, ``\tilde``, ``\vec``, ``\dot``, ``\ddot``.  All
-of them have the same syntax, eg to make an overbar you do ``\bar{o}``
-or to make an o umlaut you do ``\ddot{o}``.
-
-.. literalinclude:: figures/pyplot_mathtext.py
-
-.. image:: figures/pyplot_mathtext.png
-   :scale: 50
-
-
-
-
