Menu
▾
▴
SF.net SVN: matplotlib: [5483] trunk/matplotlib/doc
|
From: <ds...@us...> - 2008-06-12 14:48:56
|
Revision: 5483
http://matplotlib.svn.sourceforge.net/matplotlib/?rev=5483&view=rev
Author: dsdale
Date: 2008-06-12 07:48:18 -0700 (Thu, 12 Jun 2008)
Log Message:
-----------
responded to JDH review comments on usetex.rst
Modified Paths:
--------------
trunk/matplotlib/doc/devel/outline.rst
trunk/matplotlib/doc/faq/environment_variables_faq.rst
trunk/matplotlib/doc/faq/howto_faq.rst
trunk/matplotlib/doc/users/customizing.rst
trunk/matplotlib/doc/users/usetex.rst
Modified: trunk/matplotlib/doc/devel/outline.rst
===================================================================
--- trunk/matplotlib/doc/devel/outline.rst 2008-06-12 14:39:09 UTC (rev 5482)
+++ trunk/matplotlib/doc/devel/outline.rst 2008-06-12 14:48:18 UTC (rev 5483)
@@ -32,7 +32,7 @@
text - annotations John submitted ?
fonts et al Michael ? no author Darren
pyplot tut John submitted Eric
-configuration Darren preliminary ?
+configuration Darren submitted ?
win32 install Charlie ? no author Darren
os x install Charlie ? no author ?
linux install Darren has author ?
@@ -245,27 +245,48 @@
Review of :ref:`usetex-tutorial`:
-#. In the section on the ps distiller, you might mention that it is
- the rasterization which some users find objectionable, and the
- distiller pram (eg 6000) is a dpi setting for the rasterizer. Not
- everyone will immediately grasp the controversy surrounding dumping
- high res bitmaps into a ps file.
+#. DONE - In the section on the ps distiller, you might mention that it is the
+ rasterization which some users find objectionable, and the distiller pram
+ (eg 6000) is a dpi setting for the rasterizer. Not everyone will
+ immediately grasp the controversy surrounding dumping high res bitmaps into
+ a ps file.
-#. ``= Possible Hangups =`` - this is moin, not rest. I have fixed
- this already, just wanted to point it out. Also, for everything
- but top level chapters, I refer ``Upper lower`` for section
- titles, eg ``Possible hangups``.
+#. DONE - ``= Possible Hangups =`` - this is moin, not rest. I have
+ fixed this already, just wanted to point it out. Also, for everything but
+ top level chapters, I refer ``Upper lower`` for section titles, eg
+ ``Possible hangups``.
-#. in the troubleshooting section, could you add a FAQ showing how to
+#. DONE - in the troubleshooting section, could you add a FAQ showing how to
find their .matplotlib dir (matplotlib.get_data_path) and link to
- it. Also link to the PATH var and properly format
- ``text.latex.preample``. For the dirs, do we want `tex.cache` or
+ it.
+
+ I think you mean mpl.get_configdir. I added this to the faq/HOWTO, and
+ linked to it from usetex.rst and customizing.rst. I also added the
+ MPLCONFIGDIR environment variable to environment_variables_faq.rst.
+
+ DONE - Also link to the PATH var and properly format
+ ``text.latex.preample``.
+
+ DONE - For the dirs, do we want `tex.cache` or
``tex.cache``? I've been using the latter. We could use rest
specific markup for files and dirs, but I've been resisting goin
whle hog onthe markup... But we may eventually decide that is the
better choice.
-#. try and use internal reference links for every section and be
+ I think we should use the directive provided by sphinx::
+
+ :file:`tex.cache`
+
+ I don't think that looks too ugly in ascii, its clear what it means. If you
+ don't like it, I think we should use::
+
+ ``tex.cache``
+
+ which is formatted most
+ similarly to the :file: directive in html. Let me know if you don't want to
+ use the file directive.
+
+#. DONE - try and use internal reference links for every section and be
generous with the sections. Eg, I added a section headers and
internal linka for the postscript and unicode sections (we will
want to be able to refer people to these easily from FAQs and mail
@@ -277,3 +298,5 @@
==================
Looks good!
+
+Thanks!
Modified: trunk/matplotlib/doc/faq/environment_variables_faq.rst
===================================================================
--- trunk/matplotlib/doc/faq/environment_variables_faq.rst 2008-06-12 14:39:09 UTC (rev 5482)
+++ trunk/matplotlib/doc/faq/environment_variables_faq.rst 2008-06-12 14:48:18 UTC (rev 5483)
@@ -17,10 +17,17 @@
The list of directories that is added to Python's standard search list when
importing packages and modules
+.. envvar:: MPLCONFIGDIR
-Setting Environment Variables in Linux
-======================================
+ This is the directory used to store user customizations to matplotlib, as
+ well as some caches to improve performance. If :envvar:`MPLCONFIGDIR` is not
+ defined, :file:`{HOME}/.matplotlib` is used by default.
+
+.. _setting-linux-osx-environment-variables:
+Setting Environment Variables in Linux and OS-X
+===============================================
+
To list the current value of :envvar:`PYTHONPATH`, which may be empty, try::
echo $PYTHONPATH
@@ -71,6 +78,7 @@
To make your changes available in the future, add the commands to your
`~/.cshrc` file.
+.. _setting-windows-environment-variables:
Setting Environment Variables in Windows
========================================
Modified: trunk/matplotlib/doc/faq/howto_faq.rst
===================================================================
--- trunk/matplotlib/doc/faq/howto_faq.rst 2008-06-12 14:39:09 UTC (rev 5482)
+++ trunk/matplotlib/doc/faq/howto_faq.rst 2008-06-12 14:48:18 UTC (rev 5483)
@@ -4,6 +4,25 @@
HOWTO
*****
+.. _locating-matplotlib-config-dir:
+
+Where is my .matplotlib directory?
+==================================
+
+Each user has a :file:`.matplotlib/` directory which may contain a
+:ref:`matplotlibrc <customizing-with-matplotlibrc-files>` file and various
+caches to improve matplotlib's performance. To locate your :file:`.matplotlib/`
+directory, use :func:`matplotlib.get_configdir`:
+
+ >>> import matplotlib as mpl
+ >>> mpl.get_configdir()
+ '/home/darren/.matplotlib'
+
+This directory is generally located in your :envvar:`HOME` directory, but if
+you would like to use a configuration directory other than
+:file:`{HOME}/.matplotlib/`, you can do so by specifying the location in your
+:envvar:`MPLCONFIGDIR` environment variable.
+
.. _howto-ticks:
How do I configure the tick linewidths?
Modified: trunk/matplotlib/doc/users/customizing.rst
===================================================================
--- trunk/matplotlib/doc/users/customizing.rst 2008-06-12 14:39:09 UTC (rev 5482)
+++ trunk/matplotlib/doc/users/customizing.rst 2008-06-12 14:48:18 UTC (rev 5483)
@@ -4,6 +4,8 @@
Customizing matplotlib
**********************
+.. _customizing-with-matplotlibrc-files:
+
The matplotlibrc File
=====================
@@ -16,8 +18,8 @@
1. :file:`matplotlibrc` in the current working directory, usually used for
specific customizations that you do not want to apply elsewhere.
-2. :file:`{HOME}/.matplotlib/matplotlibrc`, for the user's default
- customizations
+2. :file:`.matplotlib/matplotlibrc`, for the user's default customizations. See
+ :ref:`locating-matplotlib-config-dir`.
3. :file:`{INSTALL}/matplotlib/mpl-data/matplotlibrc`, where :file:`{INSTALL}`
is something like :file:`/usr/lib/python2.5/site-packages` on Linux, and
maybe :file:`C:\Python25\Lib\site-packages` on Windows. Every time you
@@ -27,6 +29,8 @@
See below for a sample :ref:`matplotlibrc file<matplotlibrc-sample>`.
+.. _customizing-with-dynamic-rc-settings:
+
Dynamic rc Settings
===================
Modified: trunk/matplotlib/doc/users/usetex.rst
===================================================================
--- trunk/matplotlib/doc/users/usetex.rst 2008-06-12 14:39:09 UTC (rev 5482)
+++ trunk/matplotlib/doc/users/usetex.rst 2008-06-12 14:48:18 UTC (rev 5483)
@@ -79,38 +79,40 @@
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
+eps file. This step produces results which may be unacceptable to some users,
+because the text is coarsely rasterized and converted to bitmaps, which are not
+scalable like standard postscript, and the text is not searchable. One
+workaround is to to set ``ps.distiller.res`` to a higher value (perhaps 6000)
+in your rc settings, which will produce larger files but may look better and
+scale reasonably. 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.
+alternative produces postscript without rasterizing text, so it scales
+properly, can be edited in Adobe Illustrator, and searched text in pdf
+documents.
.. _usetex-hangups:
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.
+* On Windows, the :envvar:`PATH` environment variable may need to be modified
+ to include the directories containing the latex, dvipng and ghostscript
+ executables. See :ref:`environment-variables` and
+ :ref:`setting-windows-environment-variables` for details.
-* Using MiKTeX with Computer Modern fonts, if you get odd -Agg and PNG
+* 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.
+* The fonts look terrible on screen. You are probably running Mac OS, and there
+ is some funny business with older versions of 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
+* 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
@@ -118,12 +120,15 @@
.. _usetex-troubleshooting:
-Trouble shooting
-================
+Troubleshooting
+===============
-* Try deleting `tex.cache` from your `~/.matplotlib` directory
+* Try deleting your :file:`.matplotlib/tex.cache` directory. If you don't know
+ where to find :file:`.matplotlib`, see
+ :ref:`locating-matplotlib-config-dir`.
-* Make sure LaTeX, dvipng and ghostscript are each working and on your PATH.
+* Make sure LaTeX, dvipng and ghostscript are each working and on your
+ :envvar:`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
@@ -133,7 +138,7 @@
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
+* The ``text.latex.preamble`` 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.
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
