responded to JDH review comments on usetex.rst

ddale · ddale · commit 3a5398f9ba09 · 2008-06-12T14:48:18.000Z
svn path=/trunk/matplotlib/; revision=5483
diff --git a/doc/devel/outline.rst b/doc/devel/outline.rst
@@ -32,7 +32,7 @@ text - usetex                    Darren               in review    John
 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 @@ usetex user's guide-- reviewed by JDH
 
 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 @@ Review of :ref:`usetex-tutorial`:
     ==================
 
 Looks good!
+
+Thanks!
diff --git a/doc/faq/environment_variables_faq.rst b/doc/faq/environment_variables_faq.rst
@@ -17,9 +17,16 @@ Environment Variables
   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::
 
@@ -71,6 +78,7 @@ first or last? To append to an existing environment variable::
 To make your changes available in the future, add the commands to your
 `~/.cshrc` file.
 
+.. _setting-windows-environment-variables:
 
 Setting Environment Variables in Windows
 ========================================
diff --git a/doc/faq/howto_faq.rst b/doc/faq/howto_faq.rst
@@ -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?
diff --git a/doc/users/customizing.rst b/doc/users/customizing.rst
@@ -4,6 +4,8 @@
 Customizing matplotlib
 **********************
 
+.. _customizing-with-matplotlibrc-files:
+
 The matplotlibrc File
 =====================
 
@@ -16,8 +18,8 @@ locations, in the following order:
 
 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 @@ locations, in the following order:
 
 See below for a sample :ref:`matplotlibrc file<matplotlibrc-sample>`.
 
+.. _customizing-with-dynamic-rc-settings:
+
 Dynamic rc Settings
 ===================
 
diff --git a/doc/users/usetex.rst b/doc/users/usetex.rst
@@ -79,51 +79,56 @@ Postscript options
 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
   external dependency.
 
 .. _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 @@ Trouble shooting
   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.
