Improve usetex and pgf troubleshooting docs.

anntzer · anntzer · commit dd4d635cea67 · 2025-05-12T08:13:01.000+02:00
- Merge "Troubleshooting" and "Possible hangups".
- Don't list $PATH issues twice.
- Remove mention of dvipng for pgf (which doesn't use dvipng).
- Be more generic re: missing latex packages (this applies to all
  texlive installs, and the required list is given elsewhere).
diff --git a/doc/install/dependencies.rst b/doc/install/dependencies.rst
@@ -422,6 +422,8 @@ Python packages and must be installed separately.
 * a LaTeX distribution, e.g. `TeX Live <https://www.tug.org/texlive/>`_ or
   `MikTeX <https://miktex.org/>`_
 
+.. _tex-dependencies:
+
 LaTeX dependencies
 """"""""""""""""""
 
diff --git a/galleries/users_explain/text/pgf.py b/galleries/users_explain/text/pgf.py
@@ -209,9 +209,10 @@
 Troubleshooting
 ===============
 
-* 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
+* Make sure LaTeX is working and on your :envvar:`PATH` (for raster output,
+  pdftocairo or ghostscript is also required).  The :envvar:`PATH` environment
+  variable may need to be modified (in particular on Windows) to include the
+  directories containing the executable. See :ref:`environment-variables` and
   :ref:`setting-windows-environment-variables` for details.
 
 * Sometimes the font rendering in figures that are saved to png images is
diff --git a/galleries/users_explain/text/usetex.py b/galleries/users_explain/text/usetex.py
@@ -124,24 +124,6 @@
 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 :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
-  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.
-
 .. _usetex-troubleshooting:
 
 Troubleshooting
@@ -150,8 +132,11 @@
 * 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
-  :envvar:`PATH`.
+* Make sure LaTeX, dvipng, and Ghostscript are each working and on your
+  :envvar:`PATH`.  The :envvar:`PATH` environment variable may need to
+  be modified (in particular on Windows) to include the directories
+  containing the executables. See :ref:`environment-variables` and
+  :ref:`setting-windows-environment-variables` for details.
 
 * 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
@@ -161,6 +146,12 @@
   option provides lots of flexibility, and lots of ways to cause
   problems. Please disable this option before reporting problems.
 
+* Using MiKTeX with Computer Modern fonts, if you get odd \*Agg and PNG
+  results, go to MiKTeX/Options and update your format files.
+
+* Some required LaTeX packages, such as type1cm, may be missing from minimalist
+  TeX installs.  Required packages are listed at :ref:`tex-dependencies`.
+
 * If you still need help, please see :ref:`reporting-problems`.
 
 .. _dvipng: http://www.nongnu.org/dvipng/
