-
-
Notifications
You must be signed in to change notification settings - Fork 7.9k
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
Conversation
@@ -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`), |
There was a problem hiding this comment.
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
Mathtext is Matplotlib's native TeX-like mathematics parser (:ref:`mathtext`), | |
Clarify that Mathtext is Matplotlib's native TeX-like mathematics parser (:ref:`mathtext`), |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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`).
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
ooops....
c4f6c6a
to
7d89a38
Compare
…017-on-v3.8.x Backport PR #27017 on branch v3.8.x (DOC: clarify usetex versus mathtext)
Closes #26968 (probably) by explaining difference between mathtext and usetex.
PR summary
PR checklist