added documentation for usetex

ddale · ddale · commit 90e1f59d34d6 · 2008-06-08T18:01:58.000Z
added a static_figs directory for scripts that require optional features 
to generate images for the documentation

svn path=/trunk/matplotlib/; revision=5423
diff --git a/doc/_static/tex_demo.png b/doc/_static/tex_demo.png
diff --git a/doc/_static/tex_unicode_demo.png b/doc/_static/tex_unicode_demo.png
diff --git a/doc/devel/outline.rst b/doc/devel/outline.rst
@@ -32,7 +32,7 @@ collections                      ?                    no author    ?
 mathtext                         Michael ?            submitted    John
 fonts et al                      Michael ?            no author    Darren
 pyplot tut                       John                 submitted    Eric ?
-usetex                           Darren               has author   ?
+usetex                           Darren               submitted    ?
 configuration                    Darren               preliminary  ?
 colormapping                     Perry ?              no author    Eric ?
 win32 install                    Charlie ?            no author    Darren
@@ -64,8 +64,7 @@ the canvas                       John                 has author   ?
 the artist                       John                 has author   ?
 transforms                       Michael              submitted    John
 documenting mpl                  Darren               submitted    ?
-coding guide                     John                 submitted    Eric (Darren
-suggests)?
+coding guide                     John                 submitted    Eric ?
 and_much_more                    ?                    ?            ?
 ===============================  ==================== ===========  ===================
 
diff --git a/doc/faq/environment_variables_faq.rst b/doc/faq/environment_variables_faq.rst
@@ -0,0 +1,28 @@
+.. _environment-variables:
+
+*********************
+Environment Variables
+*********************
+
+======================   =======================================================
+Environment Variable     Description
+======================   =======================================================
+.. envvar:: PATH         The list of directories searched to find executable
+                         programs 
+.. envvar:: PYTHONPATH   The list of directories that is searched to find Python
+                         packages and modules
+======================   =======================================================
+
+
+
+
+Setting Environment Variables
+=============================
+
+Linux/OS-X
+----------
+
+
+
+Windows
+-------
diff --git a/doc/faq/index.rst b/doc/faq/index.rst
@@ -14,4 +14,4 @@ Frequently asked questions about matplotlib
    installing_faq.rst
    troubleshooting_faq.rst
    howto_faq.rst
-
+   environment_variables_faq.rst
diff --git a/doc/faq/installing_faq.rst b/doc/faq/installing_faq.rst
@@ -1,8 +1,8 @@
 .. _installing-faq:
 
-==================
+******************
  Installation FAQ
-==================
+******************
 
 How do I report a compilation problem?
 ======================================
diff --git a/doc/static_figs/README b/doc/static_figs/README
@@ -1,4 +1,9 @@
-Scripts that require optional system configurations to generate scripts should go here. The 
-figures will be generated in doc/_static, and will be named based on the name of the script, 
-so we can avoid unintentionally overwriting any existing figures. Please add a line to this 
-file for any additional requirements necessary to generate a new figure.
+Scripts that require optional system configurations to generate scripts should
+go here. The  figures will be generated in doc/_static, and will be named based
+on the name of the script, so we can avoid unintentionally overwriting any
+existing figures. Please add a line to this file for any additional
+requirements necessary to generate a new figure.
+
+tex demos:
+  latex
+  dvipng
diff --git a/doc/static_figs/make.py b/doc/static_figs/make.py
@@ -0,0 +1,58 @@
+#!/usr/bin/env python
+import sys, os, glob
+import matplotlib
+import IPython.Shell
+matplotlib.rcdefaults()
+matplotlib.use('Agg')
+
+mplshell = IPython.Shell.MatplotlibShell('mpl')
+
+def figs():
+    print 'making figs'
+    import matplotlib.pyplot as plt
+    for fname in glob.glob('*.py'):
+        if fname.split('/')[-1] == __file__.split('/')[-1]: continue
+        basename, ext = os.path.splitext(fname)
+        outfile = '../_static/%s.png'%basename
+
+        if os.path.exists(outfile):
+            print '    already have %s'%outfile
+            continue
+        else:
+            print '    building %s'%fname
+        plt.close('all')    # we need to clear between runs
+        mplshell.magic_run(basename)
+        plt.savefig(outfile)
+    print 'all figures made'
+
+
+def clean():
+    patterns = ['#*', '*~', '*.png', '*pyc']
+    for pattern in patterns:
+        for fname in glob.glob(pattern):
+            os.remove(fname)
+    print 'all clean'
+
+
+
+def all():
+    figs()
+
+funcd = {'figs':figs,
+         'clean':clean,
+         'all':all,
+         }
+
+if len(sys.argv)>1:
+    for arg in sys.argv[1:]:
+        func = funcd.get(arg)
+        if func is None:
+            raise SystemExit('Do not know how to handle %s; valid args are'%(
+                    arg, funcd.keys()))
+        func()
+else:
+    all()
+
+
+
+
diff --git a/doc/static_figs/tex_demo.png b/doc/static_figs/tex_demo.png
diff --git a/doc/static_figs/tex_demo.py b/doc/static_figs/tex_demo.py
@@ -0,0 +1 @@
+../mpl_examples/pylab_examples/tex_demo.py
diff --git a/doc/static_figs/tex_unicode_demo.py b/doc/static_figs/tex_unicode_demo.py
@@ -0,0 +1 @@
+../mpl_examples/pylab_examples/tex_unicode_demo.py
diff --git a/doc/users/figures/make.py b/doc/users/figures/make.py
@@ -22,7 +22,7 @@ def figs():
             print '    building %s'%fname
         plt.close('all')    # we need to clear between runs
         mplshell.magic_run(basename)
-        plt.savefig('%s.png'%basename)
+        plt.savefig(outfile)
     print 'all figures made'
 
 
diff --git a/doc/users/index.rst b/doc/users/index.rst
@@ -16,5 +16,6 @@
     customizing.rst
     artists.rst
     event_handling.rst
+    usetex.rst
 
 
diff --git a/doc/users/usetex.rst b/doc/users/usetex.rst
@@ -0,0 +1,129 @@
+.. _usetex-tutorial:
+
+*************************
+Text Rendering With LaTeX
+*************************
+
+Matplotlib has the option to use LaTeX to manage all text layout.  This
+option is available with the following backends:
+
+* \*Agg
+* PS
+* PDF
+
+The LaTeX option is activated by setting text.usetex : true in your rc
+settings.  Text handling with matplotlib's LaTeX support is slower than
+matplotlib's very capable :ref:`mathtext <mathtext-tutorial>`, but is more
+flexible, since different LaTeX packages (font packages, math packages, etc.)
+can be used. The results can be striking, especially when you take care to use
+the same fonts in your figures as in the main document.
+
+Matplotlib's LaTeX support requires a working LaTeX_ installation, dvipng_
+(which may be included with your LaTeX installation), and Ghostscript_
+(GPL Ghostscript 8.60 or later is recommended). The executables for these
+external dependencies must all be located on your :envvar:`PATH`.
+
+There are a couple of options to mention, which can be changed using :ref:`rc
+settings <customizing-matplotlib>`. Here is an example matplotlibrc file::
+
+  font.family        : serif
+  font.serif         : Times, Palatino, New Century Schoolbook, Bookman, Computer Modern Roman
+  font.sans-serif    : Helvetica, Avant Garde, Computer Modern Sans serif
+  font.cursive       : Zapf Chancery
+  font.monospace     : Courier, Computer Modern Typewriter
+
+  text.usetex        : true
+
+The first valid font in each family is the one that will be loaded. If the
+fonts are not specified, the Computer Modern fonts are used by default. All of
+the other fonts are Adobe fonts. Times and Palatino each have their own
+accompanying math fonts, while the other Adobe serif fonts make use of the
+Computer Modern math fonts. See the PSNFSS_ documentation for more details.
+
+To use LaTeX and select Helvetica as the default font, without editing
+matplotlibrc use::
+
+  from matplotlib import rc
+  rc('font',**{'family':'sans-serif','sans-serif':['Helvetica']})
+  ## for Palatino and other serif fonts use:
+  #rc('font',**{'family':'serif','serif':['Palatino']))
+  rc('text', usetex=True)
+
+Here is the standard example, `tex_demo.py`:
+
+  .. literalinclude:: ../mpl_examples/pylab_examples/tex_demo.py
+
+.. image:: ../_static/tex_demo.png
+
+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.
+
+It is also possible to use unicode strings with the LaTeX text manager, here is
+an example taken from `tex_unicode_demo.py`:
+
+  .. literalinclude:: ../mpl_examples/pylab_examples/tex_unicode_demo.py
+
+.. image:: ../_static/tex_unicode_demo.png
+
+In order to produce encapsulated postscript files that can be embedded in a new
+LaTeX document, the default behavior of matplotlib is to distill the output,
+which removes some postscript operators used by LaTeX that are illegal in an
+eps file. This step produces fonts which may be unacceptable to some users. One
+workaround is to to set ``ps.distiller.res`` to a higher value (perhaps 6000) in
+your rc settings. A better workaround, which requires Poppler_ or Xpdf_, can be
+activated by changing the ``ps.usedistiller`` rc setting to ``xpdf``. This
+alternative produces postscript with text that can be edited in Adobe
+Illustrator, and searched text in pdf documents.
+
+
+= Possible Hangups =
+
+  * On Windows, the PATH environment variable may need to be modified to find
+    the latex, dvipng and ghostscript executables. This is done by going to the
+    control panel, selecting the "system" icon, selecting the "advanced" tab,
+    and clicking the "environment variables" button (and people think Linux is
+    complicated. Sheesh.) Select the PATH variable, and add the appropriate
+    directories.
+
+  * Using MiKTeX with Computer Modern fonts, if you get odd -Agg and PNG
+    results, go to MiKTeX/Options and update your format files
+
+  * The fonts look terrible on screen. You are probably running Mac OS, and
+    there is some funny business with dvipng on the mac. Set text.dvipnghack :
+    True in your matplotlibrc file.
+
+  * On Ubuntu and Gentoo, the base texlive install does not ship with the
+    type1cm package. You may need to install some of the extra packages to get
+    all the goodies that come bundled with other latex distributions.
+
+  * Some progress has been made so Matplotlib uses the dvi files directly for
+    text layout. This allows latex to be used for text layout with the pdf and
+    svg backends, as well as the \*Agg and PS backends. In the future, a latex
+    installation may be the only external dependency.
+
+= In the event that things dont work =
+  * Try deleting `tex.cache` from your :envvar:`MATPLOTLIBDATA` directory
+
+  * Make sure LaTeX, dvipng and ghostscript are each working and on your PATH.
+
+  * Make sure what you are trying to do is possible in a LaTeX document, that
+    your LaTeX syntax is valid and that you are using raw strings if necessary
+    to avoid unintended escape sequences.
+
+  * Most problems reported on the mailing list have been cleared up by
+    upgrading Ghostscript_. If possible, please try upgrading to the latest
+    release before reporting problems to the list.
+
+  * The text.latex.preample rc setting is not officially supported. This option
+    provides lots of flexibility, and lots of ways to cause problems. Please
+    disable this option before reporting problems to the mailing list.
+
+  * If you still need help, please see :ref:`reporting-problems`
+
+.. _LaTeX: http://www.tug.org
+.. _dvipng: http://sourceforge.net/projects/dvipng
+.. _Ghostscript: http://www.cs.wisc.edu/~ghost/
+.. _PSNFSS: http://www.ctan.org/tex-archive/macros/latex/required/psnfss/psnfss2e.pdf
+.. _Poppler: http://poppler.freedesktop.org/
+.. _Xpdf: http://www.foolabs.com/xpdf
diff --git a/examples/pylab_examples/tex_demo.py b/examples/pylab_examples/tex_demo.py
@@ -17,7 +17,8 @@
 
 
 rc('text', usetex=True)
-figure(1)
+rc('font', family='serif')
+figure(1, figsize=(6,4))
 ax = axes([0.1, 0.1, 0.8, 0.7])
 t = arange(0.0, 1.0+0.01, 0.01)
 s = cos(2*2*pi*t)+2
diff --git a/examples/pylab_examples/tex_unicode_demo.py b/examples/pylab_examples/tex_unicode_demo.py
@@ -11,14 +11,13 @@
 from matplotlib.pyplot import figure, axes, plot, xlabel, ylabel, title, \
      grid, savefig, show
 
-figure(1)
+figure(1, figsize=(6,4))
 ax = axes([0.1, 0.1, 0.8, 0.7])
 t = arange(0.0, 1.0+0.01, 0.01)
 s = cos(2*2*pi*t)+2
 plot(t, s)
 
 xlabel(r'\textbf{time (s)}')
-s = unicode(r'\textit{Velocity (�/sec)}','latin-1')
 ylabel(unicode(r'\textit{Velocity (�/sec)}','latin-1'),fontsize=16)
 title(r"\TeX\ is Number $\displaystyle\sum_{n=1}^\infty\frac{-e^{i\pi}}{2^n}$!",
       fontsize=16, color='r')

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+../mpl_examples/pylab_examples/tex_demo.py`