DOC: clarify usetex versus mathtext#27017
Conversation
| Mathtext improvements | ||
| ===================== | ||
|
|
||
| Mathtext is Matplotlib's native TeX-like mathematics parser (:ref:`mathtext`), |
There was a problem hiding this comment.
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.
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.
"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.
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.
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.
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.
It seems you haven’t pushed yet.
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