dviread.Text specifies individual glyphs in parsed dvi files; this is
used by the pdf and svg backends (via textpath, for svg) to parse the
result of usetex-compiled strings and embed the right glyphs at the
right places in the output file (as a reminder, agg currenly uses dvipng
to rasterize the dvi file, and the ps backend relies on pstricks).
Unfortunately, if third-party backends (e.g. mplcairo) want to do use
the same strategy as pdf/svg, then they need to jump through a few hoops
(e.g. understand PsfontsMap and find_tex_font) and use some private APIs
(_parse_enc), as explained below. Try to improve the situation, by
adding some methods on the Text class (which may later allow deprecating
PsfontsMap and find_tex_font as public API).

First, the actual font to be used is speficied via the.font
attribute, which itself has a.texname which itself must be used as
a key intoPsfontsMap(find_tex_font("pdftex.map")) to get the actual
font path (and some other info). Instead, just provide a.font_path
property. pdftex.map can also require that the font be "slanted" or
"extended" (that's some of the "other info), lift that as well to
.font_effects. The.font attribute has a.size; also we can lift
up to.font_size. Altogether, this will allow making.font private
(later) -- except for the fact that Text is a namedtuple so deprecating
fields is rather annoying.

The trickiest part is actually specifying what glyph to select from the
font. dvi just gives us an integer, whose interpretation depends again
on pdftex.map. If pdftex.map specifies "no encoding" for the font, then
the integer is the "native glyph index" of the font, and should be
passed as-is to FreeType's FT_Load_Char (after selecting the native
charmap). If pdftex.map does specify an encoding, then that's a file
that needs to be separately loaded, parsed (with _parse_enc), and
ultimately converts the index into a glyph name (which can be passed to
FreeType's FT_Load_Glyph). Altogether, from the PoV of the end user,
the "glyph specification" is thus either an int (a native charmap index)
or a str (a glyph name); thus, provide.glyph_spec which is that API.

As an example of using that API, see the changes to textpath.py.

I probably won't have too much time to hash out the best API here (well, I'm OK with the one I wrote, but perhaps better choices are possible) in the coming days, but just posting this out in response to#22127, as this is, I think, the way towards tightening the dviread public API while consolidating the useful functionality for third parties.

PR Summary

PR Checklist

Tests and Styling

• Has pytest style unit tests (andpytest passes).
• IsFlake 8 compliant (installflake8-docstrings and runflake8 --docstring-convention=all).

Documentation

• New features are documented, with examples if plot related.
• New features have an entry indoc/users/next_whats_new/ (follow instructions in README.rst there).
• API changes documented indoc/api/next_api_changes/ (follow instructions in README.rst there).
• Documentation is sphinx and numpydoc compliant (the docs shouldbuild without error).