-
Notifications
You must be signed in to change notification settings - Fork 60
Expand file tree
/
Copy pathMEP14.html
More file actions
917 lines (835 loc) · 44.4 KB
/
MEP14.html
File metadata and controls
917 lines (835 loc) · 44.4 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="X-UA-Compatible" content="IE=Edge" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
<title>MEP14: Text handling — Matplotlib 3.5.2 documentation</title>
<!-- Loaded before other Sphinx assets -->
<link href="../../_static/styles/theme.css?digest=1999514e3f237ded88cf" rel="stylesheet">
<link href="../../_static/styles/pydata-sphinx-theme.css?digest=1999514e3f237ded88cf" rel="stylesheet">
<link rel="stylesheet"
href="../../_static/vendor/fontawesome/5.13.0/css/all.min.css">
<link rel="preload" as="font" type="font/woff2" crossorigin
href="../../_static/vendor/fontawesome/5.13.0/webfonts/fa-solid-900.woff2">
<link rel="preload" as="font" type="font/woff2" crossorigin
href="../../_static/vendor/fontawesome/5.13.0/webfonts/fa-brands-400.woff2">
<link rel="stylesheet" type="text/css" href="../../_static/pygments.css" />
<link rel="stylesheet" type="text/css" href="../../_static/css/style.css" />
<link rel="stylesheet" type="text/css" href="../../_static/graphviz.css" />
<link rel="stylesheet" type="text/css" href="../../_static/plot_directive.css" />
<link rel="stylesheet" type="text/css" href="../../_static/copybutton.css" />
<link rel="stylesheet" type="text/css" href="../../_static/sg_gallery.css" />
<link rel="stylesheet" type="text/css" href="../../_static/sg_gallery-binder.css" />
<link rel="stylesheet" type="text/css" href="../../_static/sg_gallery-dataframe.css" />
<link rel="stylesheet" type="text/css" href="../../_static/sg_gallery-rendered-html.css" />
<link rel="stylesheet" type="text/css" href="../../_static/panels-main.c949a650a448cc0ae9fd3441c0e17fb0.css" />
<link rel="stylesheet" type="text/css" href="../../_static/panels-variables.06eb56fa6e07937060861dad626602ad.css" />
<link rel="stylesheet" type="text/css" href="../../_static/mpl.css?v3.5.2-3-g2e7af710d5" />
<!-- Pre-loaded scripts that we'll load fully later -->
<link rel="preload" as="script" href="../../_static/scripts/pydata-sphinx-theme.js?digest=1999514e3f237ded88cf">
<script data-url_root="../../" id="documentation_options" src="../../_static/documentation_options.js"></script>
<script src="../../_static/jquery.js"></script>
<script src="../../_static/underscore.js"></script>
<script src="../../_static/doctools.js"></script>
<script src="../../_static/clipboard.min.js"></script>
<script src="../../_static/copybutton.js"></script>
<link rel="canonical" href="https://matplotlib.org/stable/devel/MEP/MEP14.html" />
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Matplotlib 3.5.2 documentation"
href="../../_static/opensearch.xml"/>
<link rel="shortcut icon" href="../../_static/favicon.ico"/>
<link rel="search" title="Search" href="../../search.html" />
<link rel="next" title="MEP15: Fix axis autoscaling when limits are specified for one axis only" href="MEP15.html" />
<link rel="prev" title="MEP13: Use properties for Artists" href="MEP13.html" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<meta name="docsearch:language" content="None">
<script data-domain="matplotlib.org" defer="defer" src="https://views.scientific-python.org/js/script.js"></script>
</head>
<body data-spy="scroll" data-target="#bd-toc-nav" data-offset="60">
<div class="container-fluid" id="banner"></div>
<nav class="navbar navbar-light navbar-expand-lg bg-light fixed-top bd-navbar" id="navbar-main"><div class="container-xl">
<div id="navbar-start">
<a class="navbar-brand" href="../../index.html">
<img src="../../_static/logo2.svg" class="logo" alt="logo">
</a>
</div>
<button class="navbar-toggler" type="button" data-toggle="collapse" data-target="#navbar-collapsible" aria-controls="navbar-collapsible" aria-expanded="false" aria-label="Toggle navigation">
<span class="navbar-toggler-icon"></span>
</button>
<div id="navbar-collapsible" class="col-lg-9 collapse navbar-collapse">
<div id="navbar-center" class="mr-auto">
<div class="navbar-center-item">
<ul id="navbar-main-elements" class="navbar-nav">
<li class="nav-item">
<a class="reference internal nav-link" href="../../plot_types/index.html">Plot types</a>
</li>
<li class="nav-item">
<a class="reference internal nav-link" href="../../gallery/index.html">Examples</a>
</li>
<li class="nav-item">
<a class="reference internal nav-link" href="../../tutorials/index.html">Tutorials</a>
</li>
<li class="nav-item">
<a class="reference internal nav-link" href="../../api/index.html">Reference</a>
</li>
<li class="nav-item">
<a class="reference internal nav-link" href="../../users/index.html">User guide</a>
</li>
<li class="nav-item">
<a class="reference internal nav-link" href="../index.html">Develop</a>
</li>
<li class="nav-item">
<a class="reference internal nav-link" href="../../users/release_notes.html">Release notes</a>
</li>
</ul>
</div>
</div>
<div id="navbar-end">
<div class="navbar-end-item">
<ul id="navbar-icon-links" class="navbar-nav" aria-label="Icon Links">
<li class="nav-item">
<a class="nav-link" href="https://gitter.im/matplotlib/matplotlib" rel="noopener" target="_blank" title="gitter">
<span><i class="fab fa-gitter"></i></span>
<label class="sr-only">gitter</label>
</a>
</li>
<li class="nav-item">
<a class="nav-link" href="https://discourse.matplotlib.org" rel="noopener" target="_blank" title="discourse">
<span><i class="fab fa-discourse"></i></span>
<label class="sr-only">discourse</label>
</a>
</li>
<li class="nav-item">
<a class="nav-link" href="https://github.com/matplotlib/matplotlib" rel="noopener" target="_blank" title="GitHub">
<span><i class="fab fa-github-square"></i></span>
<label class="sr-only">GitHub</label>
</a>
</li>
<li class="nav-item">
<a class="nav-link" href="https://twitter.com/matplotlib/" rel="noopener" target="_blank" title="twitter">
<span><i class="fab fa-twitter-square"></i></span>
<label class="sr-only">twitter</label>
</a>
</li>
</ul>
</div>
</div>
</div>
</div>
</nav>
<div class="container-xl">
<div class="row">
<!-- Only show if we have sidebars configured, else just a small margin -->
<div class="col-12 col-md-3 bd-sidebar">
<div class="sidebar-start-items"><form class="bd-search d-flex align-items-center" action="../../search.html" method="get">
<i class="icon fas fa-search"></i>
<input type="search" class="form-control" name="q" id="search-input" placeholder="Search the docs ..." aria-label="Search the docs ..." autocomplete="off" >
</form><nav class="bd-links" id="bd-docs-nav" aria-label="Main navigation">
<div class="bd-toc-item active">
<ul class="current nav bd-sidenav">
<li class="toctree-l1">
<a class="reference internal" href="../contributing.html">
Contributing
</a>
</li>
<li class="toctree-l1">
<a class="reference internal" href="../triage.html">
Bug triaging and issue curation
</a>
</li>
<li class="toctree-l1">
<a class="reference internal" href="../development_setup.html">
Setting up Matplotlib for development
</a>
</li>
<li class="toctree-l1">
<a class="reference internal" href="../testing.html">
Testing
</a>
</li>
<li class="toctree-l1">
<a class="reference internal" href="../documenting_mpl.html">
Writing documentation
</a>
</li>
<li class="toctree-l1">
<a class="reference internal" href="../style_guide.html">
Documentation style guide
</a>
</li>
<li class="toctree-l1 has-children">
<a class="reference internal" href="../gitwash/index.html">
Working with
<em>
Matplotlib
</em>
source code
</a>
<input class="toctree-checkbox" id="toctree-checkbox-1" name="toctree-checkbox-1" type="checkbox"/>
<label for="toctree-checkbox-1">
<i class="fas fa-chevron-down">
</i>
</label>
<ul>
<li class="toctree-l2">
<a class="reference internal" href="../gitwash/git_intro.html">
Introduction
</a>
</li>
<li class="toctree-l2">
<a class="reference internal" href="../gitwash/git_install.html">
Install git
</a>
</li>
<li class="toctree-l2">
<a class="reference internal" href="../gitwash/following_latest.html">
Following the latest source
</a>
</li>
<li class="toctree-l2">
<a class="reference internal" href="../gitwash/patching.html">
Making a patch
</a>
</li>
<li class="toctree-l2 has-children">
<a class="reference internal" href="../gitwash/git_development.html">
Git for development
</a>
<input class="toctree-checkbox" id="toctree-checkbox-2" name="toctree-checkbox-2" type="checkbox"/>
<label for="toctree-checkbox-2">
<i class="fas fa-chevron-down">
</i>
</label>
<ul>
<li class="toctree-l3">
<a class="reference internal" href="../gitwash/forking_hell.html">
Making your own copy (fork) of Matplotlib
</a>
</li>
<li class="toctree-l3">
<a class="reference internal" href="../gitwash/set_up_fork.html">
Set up your fork
</a>
</li>
<li class="toctree-l3">
<a class="reference internal" href="../gitwash/configure_git.html">
Configure git
</a>
</li>
<li class="toctree-l3">
<a class="reference internal" href="../gitwash/development_workflow.html">
Development workflow
</a>
</li>
<li class="toctree-l3">
<a class="reference internal" href="../gitwash/maintainer_workflow.html">
Maintainer workflow
</a>
</li>
</ul>
</li>
<li class="toctree-l2">
<a class="reference internal" href="../gitwash/git_resources.html">
git resources
</a>
</li>
<li class="toctree-l2">
<a class="reference internal" href="../gitwash/dot2_dot3.html">
Two and three dots in difference specs
</a>
</li>
</ul>
</li>
<li class="toctree-l1">
<a class="reference internal" href="../coding_guide.html">
Pull request guidelines
</a>
</li>
<li class="toctree-l1">
<a class="reference internal" href="../release_guide.html">
Release guide
</a>
</li>
<li class="toctree-l1">
<a class="reference internal" href="../dependencies.html">
Dependencies
</a>
</li>
<li class="toctree-l1">
<a class="reference internal" href="../min_dep_policy.html">
Minimum version of dependencies policy
</a>
</li>
<li class="toctree-l1 current active has-children">
<a class="reference internal" href="index.html">
Matplotlib Enhancement Proposals
</a>
<input checked="" class="toctree-checkbox" id="toctree-checkbox-3" name="toctree-checkbox-3" type="checkbox"/>
<label for="toctree-checkbox-3">
<i class="fas fa-chevron-down">
</i>
</label>
<ul class="current">
<li class="toctree-l2">
<a class="reference internal" href="template.html">
MEP Template
</a>
</li>
<li class="toctree-l2">
<a class="reference internal" href="MEP08.html">
MEP8: PEP8
</a>
</li>
<li class="toctree-l2">
<a class="reference internal" href="MEP09.html">
MEP9: Global interaction manager
</a>
</li>
<li class="toctree-l2">
<a class="reference internal" href="MEP10.html">
MEP10: Docstring consistency
</a>
</li>
<li class="toctree-l2">
<a class="reference internal" href="MEP11.html">
MEP11: Third-party dependencies
</a>
</li>
<li class="toctree-l2">
<a class="reference internal" href="MEP12.html">
MEP12: Improve Gallery and Examples
</a>
</li>
<li class="toctree-l2">
<a class="reference internal" href="MEP13.html">
MEP13: Use properties for Artists
</a>
</li>
<li class="toctree-l2 current active">
<a class="current reference internal" href="#">
MEP14: Text handling
</a>
</li>
<li class="toctree-l2">
<a class="reference internal" href="MEP15.html">
MEP15: Fix axis autoscaling when limits are specified for one axis only
</a>
</li>
<li class="toctree-l2">
<a class="reference internal" href="MEP19.html">
MEP19: Continuous Integration
</a>
</li>
<li class="toctree-l2">
<a class="reference internal" href="MEP21.html">
MEP21: color and cm refactor
</a>
</li>
<li class="toctree-l2">
<a class="reference internal" href="MEP22.html">
MEP22: Toolbar rewrite
</a>
</li>
<li class="toctree-l2">
<a class="reference internal" href="MEP23.html">
MEP23: Multiple Figures per GUI window
</a>
</li>
<li class="toctree-l2">
<a class="reference internal" href="MEP24.html">
MEP24: Negative radius in polar plots
</a>
</li>
<li class="toctree-l2">
<a class="reference internal" href="MEP25.html">
MEP25: Serialization
</a>
</li>
<li class="toctree-l2">
<a class="reference internal" href="MEP26.html">
MEP26: Artist styling
</a>
</li>
<li class="toctree-l2">
<a class="reference internal" href="MEP27.html">
MEP27: Decouple pyplot from backends
</a>
</li>
<li class="toctree-l2">
<a class="reference internal" href="MEP28.html">
MEP28: Remove Complexity from Axes.boxplot
</a>
</li>
<li class="toctree-l2">
<a class="reference internal" href="MEP29.html">
MEP29: Text light markup
</a>
</li>
</ul>
</li>
</ul>
<ul class="nav bd-sidenav">
<li class="toctree-l1">
<a class="reference internal" href="../license.html">
Licenses
</a>
</li>
<li class="toctree-l1">
<a class="reference internal" href="../color_changes.html">
Default color changes
</a>
</li>
</ul>
</div>
</nav>
</div>
<div class="sidebar-end-items">
</div>
</div>
<div class="d-none d-xl-block col-xl-2 bd-toc">
<div class="toc-item">
<div class="tocsection onthispage mt-5 pt-1 pb-3">
<i class="fas fa-list"></i> On this page
</div>
<nav id="bd-toc-nav">
<ul class="visible nav section-nav flex-column">
<li class="toc-h2 nav-item toc-entry">
<a class="reference internal nav-link" href="#status">
Status
</a>
</li>
<li class="toc-h2 nav-item toc-entry">
<a class="reference internal nav-link" href="#branches-and-pull-requests">
Branches and Pull requests
</a>
</li>
<li class="toc-h2 nav-item toc-entry">
<a class="reference internal nav-link" href="#abstract">
Abstract
</a>
</li>
<li class="toc-h2 nav-item toc-entry">
<a class="reference internal nav-link" href="#detailed-description">
Detailed description
</a>
</li>
<li class="toc-h2 nav-item toc-entry">
<a class="reference internal nav-link" href="#implementation">
Implementation
</a>
</li>
<li class="toc-h2 nav-item toc-entry">
<a class="reference internal nav-link" href="#backward-compatibility">
Backward compatibility
</a>
</li>
<li class="toc-h2 nav-item toc-entry">
<a class="reference internal nav-link" href="#alternatives">
Alternatives
</a>
</li>
</ul>
</nav>
</div>
<div class="toc-item">
</div>
</div>
<main class="col-12 col-md-9 col-xl-7 py-md-5 pl-md-5 pr-md-4 bd-content" role="main">
<div>
<section id="mep14-text-handling">
<h1>MEP14: Text handling<a class="headerlink" href="#mep14-text-handling" title="Permalink to this headline">#</a></h1>
<div class="contents local topic" id="contents">
<ul class="simple">
<li><p><a class="reference internal" href="#status" id="id1">Status</a></p></li>
<li><p><a class="reference internal" href="#branches-and-pull-requests" id="id2">Branches and Pull requests</a></p></li>
<li><p><a class="reference internal" href="#abstract" id="id3">Abstract</a></p></li>
<li><p><a class="reference internal" href="#detailed-description" id="id4">Detailed description</a></p></li>
<li><p><a class="reference internal" href="#implementation" id="id5">Implementation</a></p></li>
<li><p><a class="reference internal" href="#backward-compatibility" id="id6">Backward compatibility</a></p></li>
<li><p><a class="reference internal" href="#alternatives" id="id7">Alternatives</a></p></li>
</ul>
</div>
<section id="status">
<h2><a class="toc-backref" href="#id1">Status</a><a class="headerlink" href="#status" title="Permalink to this headline">#</a></h2>
<ul class="simple">
<li><p><strong>Discussion</strong></p></li>
</ul>
</section>
<section id="branches-and-pull-requests">
<h2><a class="toc-backref" href="#id2">Branches and Pull requests</a><a class="headerlink" href="#branches-and-pull-requests" title="Permalink to this headline">#</a></h2>
<p>Issue #253 demonstrates a bug where using the bounding box rather than
the advance width of text results in misaligned text. This is a minor
point in the grand scheme of things, but it should be addressed as
part of this MEP.</p>
</section>
<section id="abstract">
<h2><a class="toc-backref" href="#id3">Abstract</a><a class="headerlink" href="#abstract" title="Permalink to this headline">#</a></h2>
<p>By reorganizing how text is handled, this MEP aims to:</p>
<ul class="simple">
<li><p>improve support for Unicode and non-ltr languages</p></li>
<li><p>improve text layout (especially multi-line text)</p></li>
<li><p>allow support for more fonts, especially non-Apple-format TrueType
fonts and OpenType fonts.</p></li>
<li><p>make the font configuration easier and more transparent</p></li>
</ul>
</section>
<section id="detailed-description">
<h2><a class="toc-backref" href="#id4">Detailed description</a><a class="headerlink" href="#detailed-description" title="Permalink to this headline">#</a></h2>
<p><strong>Text layout</strong></p>
<p>At present, matplotlib has two different ways to render text:
"built-in" (based on FreeType and our own Python code), and "usetex"
(based on calling out to a TeX installation). Adjunct to the
"built-in" renderer there is also the Python-based "mathtext" system
for rendering mathematical equations using a subset of the TeX
language without having a TeX installation available. Support for
these two engines in strewn about many source files, including every
backend, where one finds clauses like</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">if</span> <span class="n">rcParams</span><span class="p">[</span><span class="s1">'text.usetex'</span><span class="p">]:</span> <span class="c1"># do one thing else: # do another</span>
</pre></div>
</div>
<p>Adding a third text rendering approach (more on that later) would
require editing all of these places as well, and therefore doesn't
scale.</p>
<p>Instead, this MEP proposes adding a concept of "text engines", where
the user could select one of many different approaches for rendering
text. The implementations of each of these would be localized to
their own set of modules, and not have little pieces around the whole
source tree.</p>
<p>Why add more text rendering engines? The "built-in" text rendering
has a number of shortcomings.</p>
<ul class="simple">
<li><p>It only handles right-to-left languages, and doesn't handle many
special features of Unicode, such as combining diacriticals.</p></li>
<li><p>The multiline support is imperfect and only supports manual
line-breaking -- it can not break up a paragraph into lines of a
certain length.</p></li>
<li><p>It also does not handle inline formatting changes in order to
support something like Markdown, reStructuredText or HTML. (Though
rich-text formatting is contemplated in this MEP, since we want to
make sure this design allows it, the specifics of a rich-text
formatting implementation is outside of the scope of this MEP.)</p></li>
</ul>
<p>Supporting these things is difficult, and is the "full-time job" of a
number of other projects:</p>
<ul class="simple">
<li><p><a class="reference external" href="https://www.pango.org/">pango</a>/<a class="reference external" href="https://www.freedesktop.org/wiki/Software/HarfBuzz/">harfbuzz</a></p></li>
<li><p><a class="reference external" href="https://doc.qt.io/archives/qt-4.8/qtextlayout.html">QtTextLayout</a></p></li>
<li><p><a class="reference external" href="https://docs.microsoft.com/en-ca/windows/win32/directwrite/introducing-directwrite">Microsoft DirectWrite</a></p></li>
<li><p><a class="reference external" href="https://developer.apple.com/library/archive/documentation/StringsTextFonts/Conceptual/CoreText_Programming/Overview/Overview.html">Apple Core Text</a></p></li>
</ul>
<p>Of the above options, it should be noted that <a class="reference external" href="https://www.freedesktop.org/wiki/Software/HarfBuzz/">harfbuzz</a> is designed
from the start as a cross platform option with minimal dependencies,
so therefore is a good candidate for a single option to support.</p>
<p>Additionally, for supporting rich text, we could consider using
<a class="reference external" href="https://webkit.org/">WebKit</a>, and possibly whether than
represents a good single cross-platform option. Again, however, rich
text formatting is outside of the scope of this project.</p>
<p>Rather than trying to reinvent the wheel and add these features to
matplotlib's "built-in" text renderer, we should provide a way to
leverage these projects to get more powerful text layout. The
"built-in" renderer will still need to exist for reasons of ease of
installation, but its feature set will be more limited compared to the
others. [TODO: This MEP should clearly decide what those limited
features are, and fix any bugs to bring the implementation into a
state of working correctly in all cases that we want it to work. I
know @leejjoon has some thoughts on this.]</p>
<p><strong>Font selection</strong></p>
<p>Going from an abstract description of a font to a file on disk is the
task of the font selection algorithm -- it turns out to be much more
complicated than it seems at first.</p>
<p>The "built-in" and "usetex" renderers have very different ways of
handling font selection, given their different technologies. TeX
requires the installation of TeX-specific font packages, for example,
and can not use TrueType fonts directly. Unfortunately, despite the
different semantics for font selection, the same set of font
properties are used for each. This is true of both the
<a class="reference internal" href="../../api/font_manager_api.html#matplotlib.font_manager.FontProperties" title="matplotlib.font_manager.FontProperties"><code class="xref py py-obj docutils literal notranslate"><span class="pre">FontProperties</span></code></a> class and the font-related <a class="reference internal" href="../../api/matplotlib_configuration_api.html#matplotlib.rcParams" title="matplotlib.rcParams"><code class="xref py py-obj docutils literal notranslate"><span class="pre">rcParams</span></code></a> (which
basically share the same code underneath). Instead, we should define
a core set of font selection parameters that will work across all text
engines, and have engine-specific configuration to allow the user to
do engine-specific things when required. For example, it is possible
to directly select a font by name in the "built-in" using
<code class="docutils literal notranslate"><a class="reference external" href="../../tutorials/introductory/customizing.html?highlight=font.family#a-sample-matplotlibrc-file"><span class="pre">rcParams["font.family"]</span></a></code> (default: <code class="docutils literal notranslate"><span class="pre">['sans-serif']</span></code>), but the same is not possible with "usetex". It may be
possible to make it easier to use TrueType fonts by using XeTeX, but
users will still want to use the traditional metafonts through TeX
font packages. So the issue still stands that different text engines
will need engine-specific configuration, and it should be more obvious
to the user which configuration will work across text engines and
which are engine-specific.</p>
<p>Note that even excluding "usetex", there are different ways to find
fonts. The default is to use the font list cache in <a class="reference internal" href="../../api/font_manager_api.html#module-matplotlib.font_manager" title="matplotlib.font_manager"><code class="xref py py-mod docutils literal notranslate"><span class="pre">font_manager</span></code></a>
which matches fonts using our own algorithm based on the <a class="reference external" href="http://www.w3.org/TR/CSS2/fonts.html#algorithm">CSS font
matching algorithm</a>.
It doesn't always do the same thing as the native font selection
algorithms on Linux (<a class="reference external" href="https://www.freedesktop.org/wiki/Software/fontconfig/">fontconfig</a>), Mac and
Windows, and it doesn't always find all of the fonts on the system
that the OS would normally pick up. However, it is cross-platform,
and always finds the fonts that ship with matplotlib. The Cairo and
MacOSX backends (and presumably a future HTML5-based backend)
currently bypass this mechanism and use the OS-native ones. The same
is true when not embedding fonts in SVG, PS or PDF files and opening
them in a third-party viewer. A downside there is that (at least with
Cairo, need to confirm with MacOSX) they don't always find the fonts
we ship with matplotlib. (It may be possible to add the fonts to
their search path, though, or we may need to find a way to install our
fonts to a location the OS expects to find them).</p>
<p>There are also special modes in the PS and PDF to only use the core
fonts that are always available to those formats. There, the font
lookup mechanism must only match against those fonts. It is unclear
whether the OS-native font lookup systems can handle this case.</p>
<p>There is also experimental support for using <a class="reference external" href="https://www.freedesktop.org/wiki/Software/fontconfig/">fontconfig</a> for font
selection in matplotlib, turned off by default. fontconfig is the
native font selection algorithm on Linux, but is also cross platform
and works well on the other platforms (though obviously is an
additional dependency there).</p>
<p>Many of the text layout libraries proposed above (pango, QtTextLayout,
DirectWrite and CoreText etc.) insist on using the font selection
library from their own ecosystem.</p>
<p>All of the above seems to suggest that we should move away from our
self-written font selection algorithm and use the native APIs where
possible. That's what Cairo and MacOSX backends already want to use,
and it will be a requirement of any complex text layout library. On
Linux, we already have the bones of a <a class="reference external" href="https://www.freedesktop.org/wiki/Software/fontconfig/">fontconfig</a> implementation
(which could also be accessed through pango). On Windows and Mac we
may need to write custom wrappers. The nice thing is that the API for
font lookup is relatively small, and essentially consist of "given a
dictionary of font properties, give me a matching font file".</p>
<p><strong>Font subsetting</strong></p>
<p>Font subsetting is currently handled using ttconv. ttconv was a
standalone commandline utility for converting TrueType fonts to
subsetted Type 3 fonts (among other features) written in 1995, which
matplotlib (well, I) forked in order to make it work as a library. It
only handles Apple-style TrueType fonts, not ones with the Microsoft
(or other vendor) encodings. It doesn't handle OpenType fonts at all.
This means that even though the STIX fonts come as .otf files, we have
to convert them to .ttf files to ship them with matplotlib. The Linux
packagers hate this -- they'd rather just depend on the upstream STIX
fonts. ttconv has also been shown to have a few bugs that have been
difficult to fix over time.</p>
<p>Instead, we should be able to use FreeType to get the font outlines
and write our own code (probably in Python) to output subsetted fonts
(Type 3 on PS and PDF and paths on SVG). Freetype, as a popular and
well-maintained project, handles a wide variety of fonts in the wild.
This would remove a lot of custom C code, and remove some code
duplication between backends.</p>
<p>Note that subsetting fonts this way, while the easiest route, does
lose the hinting in the font, so we will need to continue, as we do
now, provide a way to embed the entire font in the file where
possible.</p>
<p>Alternative font subsetting options include using the subsetting
built-in to Cairo (not clear if it can be used without the rest of
Cairo), or using <a class="reference external" href="https://fontforge.org">fontforge</a> (which is a heavy and not terribly
cross-platform dependency).</p>
<p><strong>Freetype wrappers</strong></p>
<p>Our FreeType wrapper could really use a reworking. It defines its own
image buffer class (when a Numpy array would be easier). While
FreeType can handle a huge diversity of font files, there are
limitations to our wrapper that make it much harder to support
non-Apple-vendor TrueType files, and certain features of OpenType
files. (See #2088 for a terrible result of this, just to support the
fonts that ship with Windows 7 and 8). I think a fresh rewrite of
this wrapper would go a long way.</p>
<p><strong>Text anchoring and alignment and rotation</strong></p>
<p>The handling of baselines was changed in 1.3.0 such that the backends
are now given the location of the baseline of the text, not the bottom
of the text. This is probably the correct behavior, and the MEP
refactoring should also follow this convention.</p>
<p>In order to support alignment on multi-line text, it should be the
responsibility of the (proposed) text engine to handle text alignment.
For a given chunk of text, each engine calculates a bounding box for
that text and the offset of the anchor point within that box.
Therefore, if the va of a block was "top", the anchor point would be
at the top of the box.</p>
<p>Rotating of text should always be around the anchor point. I'm not
sure that lines up with current behavior in matplotlib, but it seems
like the sanest/least surprising choice. [This could be revisited
once we have something working]. Rotation of text should not be
handled by the text engine -- that should be handled by a layer
between the text engine and the rendering backend so it can be handled
in a uniform way. [I don't see any advantage to rotation being
handled by the text engines individually...]</p>
<p>There are other problems with text alignment and anchoring that should
be resolved as part of this work. [TODO: enumerate these].</p>
<p><strong>Other minor problems to fix</strong></p>
<p>The mathtext code has backend-specific code -- it should instead
provide its output as just another text engine. However, it's still
desirable to have mathtext layout inserted as part of a larger layout
performed by another text engine, so it should be possible to do this.
It's an open question whether embedding the text layout of an
arbitrary text engine in another should be possible.</p>
<p>The text mode is currently set by a global rcParam ("text.usetex") so
it's either all on or all off. We should continue to have a global
rcParam to choose the text engine ("text.layout_engine"), but it
should under the hood be an overridable property on the <a class="reference internal" href="../../api/text_api.html#matplotlib.text.Text" title="matplotlib.text.Text"><code class="xref py py-obj docutils literal notranslate"><span class="pre">Text</span></code></a> object,
so the same figure can combine the results of multiple text layout
engines if necessary.</p>
</section>
<section id="implementation">
<h2><a class="toc-backref" href="#id5">Implementation</a><a class="headerlink" href="#implementation" title="Permalink to this headline">#</a></h2>
<p>A concept of a "text engine" will be introduced. Each text engine
will implement a number of abstract classes. The <code class="docutils literal notranslate"><span class="pre">TextFont</span></code> interface
will represent text for a given set of font properties. It isn't
necessarily limited to a single font file -- if the layout engine
supports rich text, it may handle a number of font files in a family.
Given a <code class="docutils literal notranslate"><span class="pre">TextFont</span></code> instance, the user can get a <code class="docutils literal notranslate"><span class="pre">TextLayout</span></code> instance,
which represents the layout for a given string of text in a given
font. From a <code class="docutils literal notranslate"><span class="pre">TextLayout</span></code>, an iterator over <code class="docutils literal notranslate"><span class="pre">TextSpan</span></code>s is returned
so the engine can output raw editable text using as few spans as
possible. If the engine would rather get individual characters, they
can be obtained from the <code class="docutils literal notranslate"><span class="pre">TextSpan</span></code> instance:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">TextFont</span><span class="p">(</span><span class="n">TextFontBase</span><span class="p">):</span>
<span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">font_properties</span><span class="p">):</span>
<span class="sd">"""</span>
<span class="sd"> Create a new object for rendering text using the given font properties.</span>
<span class="sd"> """</span>
<span class="k">pass</span>
<span class="k">def</span> <span class="nf">get_layout</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">s</span><span class="p">,</span> <span class="n">ha</span><span class="p">,</span> <span class="n">va</span><span class="p">):</span>
<span class="sd">"""</span>
<span class="sd"> Get the TextLayout for the given string in the given font and</span>
<span class="sd"> the horizontal (left, center, right) and verticalalignment (top,</span>
<span class="sd"> center, baseline, bottom)</span>
<span class="sd"> """</span>
<span class="k">pass</span>
<span class="k">class</span> <span class="nc">TextLayout</span><span class="p">(</span><span class="n">TextLayoutBase</span><span class="p">):</span>
<span class="k">def</span> <span class="nf">get_metrics</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="sd">"""</span>
<span class="sd"> Return the bounding box of the layout, anchored at (0, 0).</span>
<span class="sd"> """</span>
<span class="k">pass</span>
<span class="k">def</span> <span class="nf">get_spans</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="sd">"""</span>
<span class="sd"> Returns an iterator over the spans of different in the layout.</span>
<span class="sd"> This is useful for backends that want to editable raw text as</span>
<span class="sd"> individual lines. For rich text where the font may change,</span>
<span class="sd"> each span of different font type will have its own span.</span>
<span class="sd"> """</span>
<span class="k">pass</span>
<span class="k">def</span> <span class="nf">get_image</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="sd">"""</span>
<span class="sd"> Returns a rasterized image of the text. Useful for raster backends,</span>
<span class="sd"> like Agg.</span>
<span class="sd"> In all likelihood, this will be overridden in the backend, as it can</span>
<span class="sd"> be created from get_layout(), but certain backends may want to</span>
<span class="sd"> override it if their library provides it (as freetype does).</span>
<span class="sd"> """</span>
<span class="k">pass</span>
<span class="k">def</span> <span class="nf">get_rectangles</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="sd">"""</span>
<span class="sd"> Returns an iterator over the filled black rectangles in the layout.</span>
<span class="sd"> Used by TeX and mathtext for drawing, for example, fraction lines.</span>
<span class="sd"> """</span>
<span class="k">pass</span>
<span class="k">def</span> <span class="nf">get_path</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="sd">"""</span>
<span class="sd"> Returns a single Path object of the entire laid out text.</span>
<span class="sd"> [Not strictly necessary, but might be useful for textpath</span>
<span class="sd"> functionality]</span>
<span class="sd"> """</span>
<span class="k">pass</span>
<span class="k">class</span> <span class="nc">TextSpan</span><span class="p">(</span><span class="n">TextSpanBase</span><span class="p">):</span>
<span class="n">x</span><span class="p">,</span> <span class="n">y</span> <span class="c1"># Position of the span -- relative to the text layout as a whole</span>
<span class="c1"># where (0, 0) is the anchor. y is the baseline of the span.</span>
<span class="n">fontfile</span> <span class="c1"># The font file to use for the span</span>
<span class="n">text</span> <span class="c1"># The text content of the span</span>
<span class="k">def</span> <span class="nf">get_path</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="k">pass</span> <span class="c1"># See TextLayout.get_path</span>
<span class="k">def</span> <span class="nf">get_chars</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="sd">"""</span>
<span class="sd"> Returns an iterator over the characters in the span.</span>
<span class="sd"> """</span>
<span class="k">pass</span>
<span class="k">class</span> <span class="nc">TextChar</span><span class="p">(</span><span class="n">TextCharBase</span><span class="p">):</span>
<span class="n">x</span><span class="p">,</span> <span class="n">y</span> <span class="c1"># Position of the character -- relative to the text layout as</span>
<span class="c1"># a whole, where (0, 0) is the anchor. y is in the baseline</span>
<span class="c1"># of the character.</span>
<span class="n">codepoint</span> <span class="c1"># The unicode code point of the character -- only for informational</span>
<span class="c1"># purposes, since the mapping of codepoint to glyph_id may have been</span>
<span class="c1"># handled in a complex way by the layout engine. This is an int</span>
<span class="c1"># to avoid problems on narrow Unicode builds.</span>
<span class="n">glyph_id</span> <span class="c1"># The index of the glyph within the font</span>
<span class="n">fontfile</span> <span class="c1"># The font file to use for the char</span>
<span class="k">def</span> <span class="nf">get_path</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="sd">"""</span>
<span class="sd"> Get the path for the character.</span>
<span class="sd"> """</span>
<span class="k">pass</span>
</pre></div>
</div>
<p>Graphic backends that want to output subset of fonts would likely
build up a file-global dictionary of characters where the keys are
(fontname, glyph_id) and the values are the paths so that only one
copy of the path for each character will be stored in the file.</p>
<p>Special casing: The "usetex" functionality currently is able to get
Postscript directly from TeX to insert directly in a Postscript file,
but for other backends, parses a DVI file and generates something more
abstract. For a case like this, <code class="docutils literal notranslate"><span class="pre">TextLayout</span></code> would implement
<code class="docutils literal notranslate"><span class="pre">get_spans</span></code> for most backends, but add <code class="docutils literal notranslate"><span class="pre">get_ps</span></code> for the Postscript
backend, which would look for the presence of this method and use it
if available, or fall back to <code class="docutils literal notranslate"><span class="pre">get_spans</span></code>. This kind of special
casing may also be necessary, for example, when the graphics backend
and text engine belong to the same ecosystem, e.g. Cairo and Pango, or
MacOSX and CoreText.</p>
<p>There are three main pieces to the implementation:</p>
<ol class="arabic simple">
<li><p>Rewriting the freetype wrapper, and removing ttconv.</p></li>
</ol>
<blockquote>
<div><ol class="loweralpha simple">
<li><p>Once (1) is done, as a proof of concept, we can move to the
upstream STIX .otf fonts</p></li>
<li><p>Add support for web fonts loaded from a remote URL. (Enabled by using freetype for font subsetting).</p></li>
</ol>
</div></blockquote>
<ol class="arabic simple" start="2">
<li><p>Refactoring the existing "builtin" and "usetex" code into separate text engines and to follow the API outlined above.</p></li>
<li><p>Implementing support for advanced text layout libraries.</p></li>
</ol>
<p>(1) and (2) are fairly independent, though having (1) done first will
allow (2) to be simpler. (3) is dependent on (1) and (2), but even if
it doesn't get done (or is postponed), completing (1) and (2) will
make it easier to move forward with improving the "builtin" text
engine.</p>
</section>
<section id="backward-compatibility">
<h2><a class="toc-backref" href="#id6">Backward compatibility</a><a class="headerlink" href="#backward-compatibility" title="Permalink to this headline">#</a></h2>
<p>The layout of text with respect to its anchor and rotation will change
in hopefully small, but improved, ways. The layout of multiline text
will be much better, as it will respect horizontal alignment. The
layout of bidirectional text or other advanced Unicode features will
now work inherently, which may break some things if users are
currently using their own workarounds.</p>
<p>Fonts will be selected differently. Hacks that used to sort of work
between the "builtin" and "usetex" text rendering engines may no
longer work. Fonts found by the OS that weren't previously found by
matplotlib may be selected.</p>
</section>
<section id="alternatives">
<h2><a class="toc-backref" href="#id7">Alternatives</a><a class="headerlink" href="#alternatives" title="Permalink to this headline">#</a></h2>
<p>TBD</p>
</section>
</section>
</div>
</main>
</div>
</div>
<!-- Scripts loaded after <body> so the DOM is not blocked -->
<div id="unreleased-message"> You are reading an old version of the documentation (v3.5.2). For the latest version see <a href="https://matplotlib.org/stable/devel/MEP/MEP14.html">https://matplotlib.org/stable/devel/MEP/MEP14.html</a></div>
<script src="../../_static/scripts/pydata-sphinx-theme.js?digest=1999514e3f237ded88cf"></script>
<footer class="footer mt-5 mt-md-0">
<div class="container">
<div class="footer-item">
<p class="copyright">
© Copyright 2002 - 2012 John Hunter, Darren Dale, Eric Firing, Michael Droettboom and the Matplotlib development team; 2012 - 2022 The Matplotlib development team.<br>
</p>
</div>
<div class="footer-item">
<p class="sphinx-version">
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 4.5.0.<br>
</p>
</div>
</div>
</footer>
</body>
</html>