Skip to content

Improve usetex and pgf troubleshooting docs. #30040

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
May 12, 2025
Merged

Improve usetex and pgf troubleshooting docs. #30040

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions doc/install/dependencies.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
""""""""""""""""""

Expand Down
7 changes: 4 additions & 3 deletions galleries/users_explain/text/pgf.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
31 changes: 11 additions & 20 deletions galleries/users_explain/text/usetex.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Comment on lines +135 to +136
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

can you give an example of what this means, particularly for dvipng?

Copy link
Contributor Author

@anntzer anntzer May 12, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'll claim this text is at least not worse than the previous one, and that a more detailed description of $PATH (probably something like "shutil.which("foo") returns something else than None) should go to environment_variables_faq.rst, but this can be done as a separate PR.

(Also, the dependency on dvipng may be removed soon, see #30039.)

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
Expand All @@ -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/
Expand Down