Revision: 5423
http://matplotlib.svn.sourceforge.net/matplotlib/?rev=5423&view=rev
Author: dsdale
Date: 2008-06-08 11:01:58 -0700 (Sun, 08 Jun 2008)
Log Message:
-----------
added documentation for usetex
added a static_figs directory for scripts that require optional features
to generate images for the documentation
Modified Paths:
--------------
trunk/matplotlib/doc/devel/outline.rst
trunk/matplotlib/doc/faq/index.rst
trunk/matplotlib/doc/faq/installing_faq.rst
trunk/matplotlib/doc/static_figs/README
trunk/matplotlib/doc/users/figures/make.py
trunk/matplotlib/doc/users/index.rst
trunk/matplotlib/examples/pylab_examples/tex_demo.py
trunk/matplotlib/examples/pylab_examples/tex_unicode_demo.py
Added Paths:
-----------
trunk/matplotlib/doc/_static/tex_demo.png
trunk/matplotlib/doc/_static/tex_unicode_demo.png
trunk/matplotlib/doc/faq/environment_variables_faq.rst
trunk/matplotlib/doc/static_figs/make.py
trunk/matplotlib/doc/static_figs/tex_demo.png
trunk/matplotlib/doc/static_figs/tex_demo.py
trunk/matplotlib/doc/static_figs/tex_unicode_demo.py
trunk/matplotlib/doc/users/usetex.rst
Added: trunk/matplotlib/doc/_static/tex_demo.png
===================================================================
(Binary files differ)
Property changes on: trunk/matplotlib/doc/_static/tex_demo.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: trunk/matplotlib/doc/_static/tex_unicode_demo.png
===================================================================
(Binary files differ)
Property changes on: trunk/matplotlib/doc/_static/tex_unicode_demo.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Modified: trunk/matplotlib/doc/devel/outline.rst
===================================================================
--- trunk/matplotlib/doc/devel/outline.rst 2008-06-08 02:25:39 UTC (rev
5422)
+++ trunk/matplotlib/doc/devel/outline.rst 2008-06-08 18:01:58 UTC (rev
5423)
@@ -32,7 +32,7 @@
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 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 ? ? ?
=============================== ==================== ===========
===================
Added: trunk/matplotlib/doc/faq/environment_variables_faq.rst
===================================================================
--- trunk/matplotlib/doc/faq/environment_variables_faq.rst
(rev 0)
+++ trunk/matplotlib/doc/faq/environment_variables_faq.rst 2008-06-08
18:01:58 UTC (rev 5423)
@@ -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
+-------
Modified: trunk/matplotlib/doc/faq/index.rst
===================================================================
--- trunk/matplotlib/doc/faq/index.rst 2008-06-08 02:25:39 UTC (rev 5422)
+++ trunk/matplotlib/doc/faq/index.rst 2008-06-08 18:01:58 UTC (rev 5423)
@@ -14,4 +14,4 @@
installing_faq.rst
troubleshooting_faq.rst
howto_faq.rst
-
+ environment_variables_faq.rst
Modified: trunk/matplotlib/doc/faq/installing_faq.rst
===================================================================
--- trunk/matplotlib/doc/faq/installing_faq.rst 2008-06-08 02:25:39 UTC (rev
5422)
+++ trunk/matplotlib/doc/faq/installing_faq.rst 2008-06-08 18:01:58 UTC (rev
5423)
@@ -1,8 +1,8 @@
.. _installing-faq:
-==================
+******************
Installation FAQ
-==================
+******************
How do I report a compilation problem?
======================================
Modified: trunk/matplotlib/doc/static_figs/README
===================================================================
--- trunk/matplotlib/doc/static_figs/README 2008-06-08 02:25:39 UTC (rev
5422)
+++ trunk/matplotlib/doc/static_figs/README 2008-06-08 18:01:58 UTC (rev
5423)
@@ -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
Added: trunk/matplotlib/doc/static_figs/make.py
===================================================================
--- trunk/matplotlib/doc/static_figs/make.py (rev 0)
+++ trunk/matplotlib/doc/static_figs/make.py 2008-06-08 18:01:58 UTC (rev
5423)
@@ -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()
+
+
+
+
Property changes on: trunk/matplotlib/doc/static_figs/make.py
___________________________________________________________________
Name: svn:executable
+ *
Added: trunk/matplotlib/doc/static_figs/tex_demo.png
===================================================================
(Binary files differ)
Property changes on: trunk/matplotlib/doc/static_figs/tex_demo.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: trunk/matplotlib/doc/static_figs/tex_demo.py
===================================================================
--- trunk/matplotlib/doc/static_figs/tex_demo.py
(rev 0)
+++ trunk/matplotlib/doc/static_figs/tex_demo.py 2008-06-08 18:01:58 UTC
(rev 5423)
@@ -0,0 +1 @@
+link ../mpl_examples/pylab_examples/tex_demo.py
\ No newline at end of file
Property changes on: trunk/matplotlib/doc/static_figs/tex_demo.py
___________________________________________________________________
Name: svn:special
+ *
Added: trunk/matplotlib/doc/static_figs/tex_unicode_demo.py
===================================================================
--- trunk/matplotlib/doc/static_figs/tex_unicode_demo.py
(rev 0)
+++ trunk/matplotlib/doc/static_figs/tex_unicode_demo.py 2008-06-08
18:01:58 UTC (rev 5423)
@@ -0,0 +1 @@
+link ../mpl_examples/pylab_examples/tex_unicode_demo.py
\ No newline at end of file
Property changes on: trunk/matplotlib/doc/static_figs/tex_unicode_demo.py
___________________________________________________________________
Name: svn:special
+ *
Modified: trunk/matplotlib/doc/users/figures/make.py
===================================================================
--- trunk/matplotlib/doc/users/figures/make.py 2008-06-08 02:25:39 UTC (rev
5422)
+++ trunk/matplotlib/doc/users/figures/make.py 2008-06-08 18:01:58 UTC (rev
5423)
@@ -22,7 +22,7 @@
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'
Modified: trunk/matplotlib/doc/users/index.rst
===================================================================
--- trunk/matplotlib/doc/users/index.rst 2008-06-08 02:25:39 UTC (rev
5422)
+++ trunk/matplotlib/doc/users/index.rst 2008-06-08 18:01:58 UTC (rev
5423)
@@ -16,5 +16,6 @@
customizing.rst
artists.rst
event_handling.rst
+ usetex.rst
Added: trunk/matplotlib/doc/users/usetex.rst
===================================================================
--- trunk/matplotlib/doc/users/usetex.rst (rev 0)
+++ trunk/matplotlib/doc/users/usetex.rst 2008-06-08 18:01:58 UTC (rev
5423)
@@ -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
\ No newline at end of file
Modified: trunk/matplotlib/examples/pylab_examples/tex_demo.py
===================================================================
--- trunk/matplotlib/examples/pylab_examples/tex_demo.py 2008-06-08
02:25:39 UTC (rev 5422)
+++ trunk/matplotlib/examples/pylab_examples/tex_demo.py 2008-06-08
18:01:58 UTC (rev 5423)
@@ -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
Modified: trunk/matplotlib/examples/pylab_examples/tex_unicode_demo.py
===================================================================
--- trunk/matplotlib/examples/pylab_examples/tex_unicode_demo.py
2008-06-08 02:25:39 UTC (rev 5422)
+++ trunk/matplotlib/examples/pylab_examples/tex_unicode_demo.py
2008-06-08 18:01:58 UTC (rev 5423)
@@ -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 (\xB0/sec)}','latin-1')
ylabel(unicode(r'\textit{Velocity (\xB0/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')
This was sent by the SourceForge.net collaborative development platform, the
world's largest Open Source development site.
-------------------------------------------------------------------------
Check out the new SourceForge.net Marketplace.
It's the best place to buy or sell services for
just about anything Open Source.
http://sourceforge.net/services/buy/index.php
_______________________________________________
Matplotlib-checkins mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/matplotlib-checkins
