added usetex review

jdh2358 · jdh2358 · commit 39c3d3bc74e5 · 2008-06-11T01:26:29.000Z
svn path=/trunk/matplotlib/; revision=5467
diff --git a/doc/devel/coding_guide.rst b/doc/devel/coding_guide.rst
@@ -1,12 +1,12 @@
 .. _coding-guide:
 
 ************
-Coding Guide
+Coding guide
 ************
 
 .. _version-control:
 
-Version Control
+Version control
 ===============
 
 svn checkouts
@@ -35,18 +35,25 @@ in mind.
 
 * if your changes are non-trivial, please make an entry in the
   :file:`CHANGELOG`
-* if you change the API, please document it in :file:`API_CHANGES`, and
-  consider posting to mpl-devel
-* Are your changes python2.4 compatible?  We are still trying to
-  support 2.4, so avoid features new to 2.5
+
+* if you change the API, please document it in :file:`API_CHANGES`,
+  and consider posting to `mpl-devel
+  <http://lists.sourceforge.net/mailman/listinfo/matplotlib-devel>`_
+
+* Are your changes python2.4 compatible?  We still support 2.4, so
+  avoid features new to 2.5
+
 * Can you pass :file:`examples/tests/backend_driver.py`?  This is our
   poor man's unit test.
+
 * If you have altered extension code, do you pass
   :file:`unit/memleak_hawaii.py`?
+
 * if you have added new files or directories, or reorganized existing
   ones, are the new files included in the match patterns in
   :file:`MANIFEST.in`.  This file determines what goes into the source
   distribution of the mpl build.
+
 * Keep the maintenance branch and trunk in sync where it makes sense.
   If there is a bug on both that needs fixing, use `svnmerge.py
   <http://www.orcaware.com/svn/wiki/Svnmerge.py>`_ to keep them in
@@ -58,6 +65,7 @@ in mind.
         svnmerge/svnmerge.py
 
   * get a svn copy of the maintenance branch and the trunk (see above)
+
   * Michael advises making the change on the branch and committing
     it.  Make sure you svn upped on the trunk and have no local
     modifications, and then from the svn trunk do::
@@ -87,7 +95,7 @@ in mind.
 
 .. _style-guide:
 
-Style Guide
+Style guide
 ===========
 
 Importing and name spaces
@@ -278,7 +286,7 @@ forced to use ``**kwargs``.  An example is
 
 .. _docstrings:
 
-Documentation and Docstrings
+Documentation and docstrings
 ============================
 
 matplotlib uses artist introspection of docstrings to support
diff --git a/doc/devel/documenting_mpl.rst b/doc/devel/documenting_mpl.rst
@@ -1,10 +1,10 @@
 .. _documenting-matplotlib:
 
 **********************
-Documenting Matplotlib
+Documenting matplotlib
 **********************
 
-Getting Started
+Getting started
 ===============
 
 The documentation for matplotlib is generated from ReStructured Text
@@ -33,7 +33,7 @@ arguments to build everything.
 The output produced by Sphinx can be configured by editing the `conf.py`
 file located in the `doc/`.
 
-Organization of Matplotlib's Documentation
+Organization of matplotlib's documentation
 ==========================================
 
 The actual ReStructured Text files are kept in `doc/users`, `doc/devel`,
@@ -96,7 +96,13 @@ Figures
 Each guide will have its own `figures/` directory for scripts to generate images
 to be included in the dcoumentation. It is not necessary to explicitly save
 the figure in the script, a figure will be saved with the same name as the
-filename when the documentation is generated.
+filename when the documentation is generated.  For example, use::
+
+    .. literalinclude:: figures/pyplot_simple.py
+
+    .. image:: figures/pyplot_simple.png
+    :scale: 75
+
 
 Any figures that rely on optional system configurations should be generated
 with a script residing in doc/static_figs. The resulting figures will be saved
@@ -105,6 +111,8 @@ avoid unintentionally overwriting any existing figures. Please add a line to
 the README in doc/static-figs for any additional requirements necessary to
 generate a new figure.
 
+
+
 .. _referring-to-mpl-docs:
 
 Referring to mpl documents
@@ -131,6 +139,8 @@ directory, I use the symlink directory.  For example, from
    .. literalinclude:: ../mpl_data/matplotlibrc
 
 
+
+
 .. _internal-section-refs:
 
 Internal section references
@@ -161,6 +171,13 @@ hyphens to separate words.
 
 .. _emacs-helpers:
 
+Section names, etc
+==================
+
+For everything but top level chapters, please use ``Upper lower`` for
+section titles, eg ``Possible hangups`` rather than ``Possible
+Hangups``
+
 Emacs helpers
 =============
 
@@ -182,7 +199,7 @@ Some helpful functions::
     C-c TAB - rst-toc-insert
 
       Insert table of contents at point
-    
+
     C-c C-u - rst-toc-update
 
         Update the table of contents at point
diff --git a/doc/devel/outline.rst b/doc/devel/outline.rst
@@ -28,7 +28,7 @@ legends                          ?                    no author    ?
 animation                        John                 has author   ?
 collections                      ?                    no author    ?
 text - mathtext                  Michael              in review    John
-text - usetex                    Darren               submitted    ?
+text - usetex                    Darren               in review    John
 text - annotations               John                 submitted    ?
 fonts et al                      Michael ?            no author    Darren
 pyplot tut                       John                 submitted    Eric
@@ -177,4 +177,40 @@ include them as formal review notes.
    sub-packages with the gamut of licenses, GPL to MIT?
 
 
+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.
+
+#. ``= 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
+   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
+   ``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
+   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
+   list posts, etc)::
+
+    .. _usetex-postscript:
+
+    Postscript options
+    ==================
+
+Looks good!
diff --git a/doc/users/usetex.rst b/doc/users/usetex.rst
@@ -52,21 +52,30 @@ matplotlibrc use::
 
 Here is the standard example, `tex_demo.py`:
 
-  .. literalinclude:: ../mpl_examples/pylab_examples/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.
 
+.. _usetex-unicode:
+
+usetex with unicode
+===================
 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
+.. literalinclude:: ../mpl_examples/pylab_examples/tex_unicode_demo.py
 
 .. image:: ../_static/tex_unicode_demo.png
 
+.. _usetex-postscript:
+
+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
@@ -77,50 +86,59 @@ 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.
 
+.. _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.
 
-= Possible Hangups =
+* Using MiKTeX with Computer Modern fonts, if you get odd -Agg and PNG
+  results, go to MiKTeX/Options and update your format files
 
-  * 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.
+* 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.
 
-  * Using MiKTeX with Computer Modern fonts, if you get odd -Agg and PNG
-    results, go to MiKTeX/Options and update your format files
+* 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.
 
-  * 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.
+* 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.
 
-  * 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.
+.. _usetex-troubleshooting:
 
-  * 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.
+Trouble shooting
+================
 
-= In the event that things dont work =
-  * Try deleting `tex.cache` from your `~/.matplotlib` directory
+* Try deleting `tex.cache` from your `~/.matplotlib` directory
 
-  * 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 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.
+* 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.
+* 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.
+* 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`
+* If you still need help, please see :ref:`reporting-problems`
 
 .. _LaTeX: http://www.tug.org
 .. _dvipng: http://sourceforge.net/projects/dvipng
