Skip to content

DOC: clarify usetex versus mathtext #27017

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.

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
Oct 8, 2023

Conversation

jklymak
Copy link
Member

@jklymak jklymak commented Oct 6, 2023

Closes #26968 (probably) by explaining difference between mathtext and usetex.

PR summary

PR checklist

@story645 story645 added the Documentation: user guide files in galleries/users_explain or doc/users label Oct 6, 2023
@@ -327,6 +327,9 @@ This allows users to set the location of the legend in a more flexible and consi
Mathtext improvements
=====================

Mathtext is Matplotlib's native TeX-like mathematics parser (:ref:`mathtext`),
Copy link
Member

@timhoffm timhoffm Oct 6, 2023

Choose a reason for hiding this comment

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

I'm unclear what the statement should communicate. Is it intended as a general description to give context what mathtext is? That'd be a bit odd. We don't have such descriptions for other what's new sections.
Or does it document the improvement in this PR? In that case I suggest

Suggested change
Mathtext is Matplotlib's native TeX-like mathematics parser (:ref:`mathtext`),
Clarify that Mathtext is Matplotlib's native TeX-like mathematics parser (:ref:`mathtext`),

Copy link
Member

Choose a reason for hiding this comment

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

I think here @jklymak is specifically adding the context. In the issue it's supposed to be closing #26968, the issue poster was trying to use a mathtext feature while also setting usetex as true.

Copy link
Member

Choose a reason for hiding this comment

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

Granted, we could also be probably be more direct "These features are additions to :ref:Mathtext <mathtext> and may not work if :ref:usetex<usetex is set to True" since this is a what's new.

Copy link
Member Author

Choose a reason for hiding this comment

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

"mathtext" is jargon, so it would be nice to define it, at least by a link. None of the code provided helps with the context either, since it could easily apply to usetex labels.

Copy link
Member

@timhoffm timhoffm Oct 7, 2023

Choose a reason for hiding this comment

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

Ah, I see, this is an intro paragraph to a set of changes. While we typically don’t have that, I acknowledge your point on giving context. I’m +/-0 on this. Fundamentally, we can’t explain every concept of the library again in the changelog (e.g. we also don’t explain what a formatter is even though not all users will be familiar with that concept).
I’d be in favor of only linking, but not explaining. - Possibly even just link the “mathtext” word in the individual improvement messages.

But I withdraw from the discussion now. I’ve added my view and leave it up to you to decide this topic.

Copy link
Member Author

Choose a reason for hiding this comment

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

I don't believe just putting a link in would have helped the OP (why would you click a link for something you think you understand) and folks are often confused by the difference between usetex and mathtext; there is a whole community that always have usetex=True, and probably forget that Matplotlib has mathtext handling. I don't think it hurts to explicitly remind them here.

Copy link
Member Author

Choose a reason for hiding this comment

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

I changed this sentence to be:

Improvements are to Mathtext, Matplotlib's native TeX-like mathematics parser
(see :ref:`mathtext`, not to be confused with Matplotlib using LaTeX directly:
:ref:`usetex`).

Copy link
Member

Choose a reason for hiding this comment

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

It seems you haven’t pushed yet.

Copy link
Member Author

Choose a reason for hiding this comment

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

ooops....

@jklymak jklymak force-pushed the doc-clarify-usetex-mathtext branch from c4f6c6a to 7d89a38 Compare October 8, 2023 14:49
@timhoffm timhoffm added this to the v3.8.1 milestone Oct 8, 2023
@timhoffm timhoffm merged commit d17bfe8 into matplotlib:main Oct 8, 2023
meeseeksmachine pushed a commit to meeseeksmachine/matplotlib that referenced this pull request Oct 8, 2023
rcomer added a commit that referenced this pull request Oct 8, 2023
…017-on-v3.8.x

Backport PR #27017 on branch v3.8.x (DOC: clarify usetex versus mathtext)
@ksunden ksunden mentioned this pull request Nov 2, 2023
5 tasks
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Documentation: user guide files in galleries/users_explain or doc/users Documentation
Projects
None yet
Development

Successfully merging this pull request may close these issues.

[Bug]: matplotlib 3.8: new mathtext feature "\text" fails.
3 participants