-
Notifications
You must be signed in to change notification settings - Fork 60
Expand file tree
/
Copy pathMEP14.html
More file actions
1059 lines (822 loc) · 53.8 KB
/
MEP14.html
File metadata and controls
1059 lines (822 loc) · 53.8 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
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!DOCTYPE html>
<html lang="en" data-content_root="../../" >
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<title>MEP14: Text handling — Matplotlib 3.10.5 documentation</title>
<script data-cfasync="false">
document.documentElement.dataset.mode = localStorage.getItem("mode") || "";
document.documentElement.dataset.theme = localStorage.getItem("theme") || "";
</script>
<!-- Loaded before other Sphinx assets -->
<link href="../../_static/styles/theme.css?digest=dfe6caa3a7d634c4db9b" rel="stylesheet" />
<link href="../../_static/styles/bootstrap.css?digest=dfe6caa3a7d634c4db9b" rel="stylesheet" />
<link href="../../_static/styles/pydata-sphinx-theme.css?digest=dfe6caa3a7d634c4db9b" rel="stylesheet" />
<link href="../../_static/vendor/fontawesome/6.5.2/css/all.min.css?digest=dfe6caa3a7d634c4db9b" rel="stylesheet" />
<link rel="preload" as="font" type="font/woff2" crossorigin href="../../_static/vendor/fontawesome/6.5.2/webfonts/fa-solid-900.woff2" />
<link rel="preload" as="font" type="font/woff2" crossorigin href="../../_static/vendor/fontawesome/6.5.2/webfonts/fa-brands-400.woff2" />
<link rel="preload" as="font" type="font/woff2" crossorigin href="../../_static/vendor/fontawesome/6.5.2/webfonts/fa-regular-400.woff2" />
<link rel="stylesheet" type="text/css" href="../../_static/pygments.css?v=03e43079" />
<link rel="stylesheet" type="text/css" href="../../_static/css/style.css?v=86e00652" />
<link rel="stylesheet" type="text/css" href="../../_static/graphviz.css?v=4ae1632d" />
<link rel="stylesheet" type="text/css" href="../../_static/plot_directive.css" />
<link rel="stylesheet" type="text/css" href="../../_static/copybutton.css?v=76b2166b" />
<link rel="stylesheet" type="text/css" href="../../_static/sg_gallery.css?v=d2d258e8" />
<link rel="stylesheet" type="text/css" href="../../_static/sg_gallery-binder.css?v=f4aeca0c" />
<link rel="stylesheet" type="text/css" href="../../_static/sg_gallery-dataframe.css?v=2082cf3c" />
<link rel="stylesheet" type="text/css" href="../../_static/sg_gallery-rendered-html.css?v=1277b6f3" />
<link rel="stylesheet" type="text/css" href="../../_static/sphinx-design.min.css?v=95c83b7e" />
<link rel="stylesheet" type="text/css" href="../../_static/mpl.css?v=d3052f62" />
<!-- Pre-loaded scripts that we'll load fully later -->
<link rel="preload" as="script" href="../../_static/scripts/bootstrap.js?digest=dfe6caa3a7d634c4db9b" />
<link rel="preload" as="script" href="../../_static/scripts/pydata-sphinx-theme.js?digest=dfe6caa3a7d634c4db9b" />
<script src="../../_static/vendor/fontawesome/6.5.2/js/all.min.js?digest=dfe6caa3a7d634c4db9b"></script>
<script src="../../_static/documentation_options.js?v=a0d90012"></script>
<script src="../../_static/doctools.js?v=9bcbadda"></script>
<script src="../../_static/sphinx_highlight.js?v=dc90522c"></script>
<script src="../../_static/clipboard.min.js?v=a7894cd8"></script>
<script src="../../_static/copybutton.js?v=ccdb6887"></script>
<script src="../../_static/design-tabs.js?v=f930bc37"></script>
<script data-domain="matplotlib.org" defer="defer" src="https://views.scientific-python.org/js/script.js"></script>
<script>DOCUMENTATION_OPTIONS.pagename = 'devel/MEP/MEP14';</script>
<script>
DOCUMENTATION_OPTIONS.theme_version = '0.15.4';
DOCUMENTATION_OPTIONS.theme_switcher_json_url = 'https://matplotlib.org/devdocs/_static/switcher.json?v3.10.5-19-gb17b062388';
DOCUMENTATION_OPTIONS.theme_switcher_version_match = '3.10.5';
DOCUMENTATION_OPTIONS.show_version_warning_banner = true;
</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.10.5 documentation"
href="../../_static/opensearch.xml"/>
<link rel="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="en"/>
<meta name="docbuild:last-update" content="Jul 31, 2025"/>
</head>
<body data-bs-spy="scroll" data-bs-target=".bd-toc-nav" data-offset="180" data-bs-root-margin="0px 0px -60%" data-default-mode="">
<div id="pst-skip-link" class="skip-link d-print-none"><a href="#main-content">Skip to main content</a></div>
<div id="pst-scroll-pixel-helper"></div>
<button type="button" class="btn rounded-pill" id="pst-back-to-top">
<i class="fa-solid fa-arrow-up"></i>Back to top</button>
<input type="checkbox"
class="sidebar-toggle"
id="pst-primary-sidebar-checkbox"/>
<label class="overlay overlay-primary" for="pst-primary-sidebar-checkbox"></label>
<input type="checkbox"
class="sidebar-toggle"
id="pst-secondary-sidebar-checkbox"/>
<label class="overlay overlay-secondary" for="pst-secondary-sidebar-checkbox"></label>
<div class="search-button__wrapper">
<div class="search-button__overlay"></div>
<div class="search-button__search-container">
<form class="bd-search d-flex align-items-center"
action="../../search.html"
method="get">
<i class="fa-solid fa-magnifying-glass"></i>
<input type="search"
class="form-control"
name="q"
id="search-input"
placeholder="Search the docs ..."
aria-label="Search the docs ..."
autocomplete="off"
autocorrect="off"
autocapitalize="off"
spellcheck="false"/>
<span class="search-button__kbd-shortcut"><kbd class="kbd-shortcut__modifier">Ctrl</kbd>+<kbd>K</kbd></span>
</form></div>
</div>
<div class="pst-async-banner-revealer d-none">
<aside id="bd-header-version-warning" class="d-none d-print-none" aria-label="Version warning"></aside>
</div>
<header class="bd-header navbar navbar-expand-lg bd-navbar d-print-none">
<div class="bd-header__inner bd-page-width">
<button class="pst-navbar-icon sidebar-toggle primary-toggle" aria-label="Site navigation">
<span class="fa-solid fa-bars"></span>
</button>
<div class="col-lg-3 navbar-header-items__start">
<div class="navbar-item">
<a class="navbar-brand logo" href="https://matplotlib.org/stable/">
<img src="../../_static/logo_light.svg" class="logo__image only-light" alt="Matplotlib 3.10.5 documentation - Home"/>
<script>document.write(`<img src="../../_static/logo_dark.svg" class="logo__image only-dark" alt="Matplotlib 3.10.5 documentation - Home"/>`);</script>
</a></div>
</div>
<div class="col-lg-9 navbar-header-items">
<div class="me-auto navbar-header-items__center">
<div class="navbar-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="../../users/index.html">User guide</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="../../gallery/index.html">Examples</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="../index.html">Contribute</a>
</li>
<li class="nav-item">
<a class="reference internal nav-link" href="../../users/release_notes.html">Releases</a>
</li>
</ul></div>
</div>
<div class="navbar-header-items__end">
<div class="navbar-item navbar-persistent--container">
<script>
document.write(`
<button class="btn btn-sm pst-navbar-icon search-button search-button__button" title="Search" aria-label="Search" data-bs-placement="bottom" data-bs-toggle="tooltip">
<i class="fa-solid fa-magnifying-glass fa-lg"></i>
</button>
`);
</script>
</div>
<div class="navbar-item">
<script>
document.write(`
<button class="btn btn-sm nav-link pst-navbar-icon theme-switch-button" title="light/dark" aria-label="light/dark" data-bs-placement="bottom" data-bs-toggle="tooltip">
<i class="theme-switch fa-solid fa-sun fa-lg" data-mode="light"></i>
<i class="theme-switch fa-solid fa-moon fa-lg" data-mode="dark"></i>
<i class="theme-switch fa-solid fa-circle-half-stroke fa-lg" data-mode="auto"></i>
</button>
`);
</script></div>
<div class="navbar-item">
<script>
document.write(`
<div class="version-switcher__container dropdown">
<button id="pst-version-switcher-button-2"
type="button"
class="version-switcher__button btn btn-sm dropdown-toggle"
data-bs-toggle="dropdown"
aria-haspopup="listbox"
aria-controls="pst-version-switcher-list-2"
aria-label="Version switcher list"
>
Choose version <!-- this text may get changed later by javascript -->
<span class="caret"></span>
</button>
<div id="pst-version-switcher-list-2"
class="version-switcher__menu dropdown-menu list-group-flush py-0"
role="listbox" aria-labelledby="pst-version-switcher-button-2">
<!-- dropdown will be populated by javascript on page load -->
</div>
</div>
`);
</script></div>
<div class="navbar-item"><ul class="navbar-icon-links"
aria-label="Icon Links">
<li class="nav-item">
<a href="https://gitter.im/matplotlib/matplotlib" title="Gitter" class="nav-link pst-navbar-icon" rel="noopener" target="_blank" data-bs-toggle="tooltip" data-bs-placement="bottom"><i class="fa-brands fa-gitter fa-lg" aria-hidden="true"></i>
<span class="sr-only">Gitter</span></a>
</li>
<li class="nav-item">
<a href="https://discourse.matplotlib.org" title="Discourse" class="nav-link pst-navbar-icon" rel="noopener" target="_blank" data-bs-toggle="tooltip" data-bs-placement="bottom"><i class="fa-brands fa-discourse fa-lg" aria-hidden="true"></i>
<span class="sr-only">Discourse</span></a>
</li>
<li class="nav-item">
<a href="https://github.com/matplotlib/matplotlib" title="GitHub" class="nav-link pst-navbar-icon" rel="noopener" target="_blank" data-bs-toggle="tooltip" data-bs-placement="bottom"><i class="fa-brands fa-github fa-lg" aria-hidden="true"></i>
<span class="sr-only">GitHub</span></a>
</li>
<li class="nav-item">
<a href="https://twitter.com/matplotlib/" title="Twitter" class="nav-link pst-navbar-icon" rel="noopener" target="_blank" data-bs-toggle="tooltip" data-bs-placement="bottom"><i class="fa-brands fa-twitter fa-lg" aria-hidden="true"></i>
<span class="sr-only">Twitter</span></a>
</li>
</ul></div>
</div>
</div>
<div class="navbar-persistent--mobile">
<script>
document.write(`
<button class="btn btn-sm pst-navbar-icon search-button search-button__button" title="Search" aria-label="Search" data-bs-placement="bottom" data-bs-toggle="tooltip">
<i class="fa-solid fa-magnifying-glass fa-lg"></i>
</button>
`);
</script>
</div>
<button class="pst-navbar-icon sidebar-toggle secondary-toggle" aria-label="On this page">
<span class="fa-solid fa-outdent"></span>
</button>
</div>
</header>
<div class="bd-container">
<div class="bd-container__inner bd-page-width">
<div class="bd-sidebar-primary bd-sidebar">
<div class="sidebar-header-items sidebar-primary__section">
<div class="sidebar-header-items__center">
<div class="navbar-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="../../users/index.html">User guide</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="../../gallery/index.html">Examples</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="../index.html">Contribute</a>
</li>
<li class="nav-item">
<a class="reference internal nav-link" href="../../users/release_notes.html">Releases</a>
</li>
</ul></div>
</div>
<div class="sidebar-header-items__end">
<div class="navbar-item">
<script>
document.write(`
<button class="btn btn-sm nav-link pst-navbar-icon theme-switch-button" title="light/dark" aria-label="light/dark" data-bs-placement="bottom" data-bs-toggle="tooltip">
<i class="theme-switch fa-solid fa-sun fa-lg" data-mode="light"></i>
<i class="theme-switch fa-solid fa-moon fa-lg" data-mode="dark"></i>
<i class="theme-switch fa-solid fa-circle-half-stroke fa-lg" data-mode="auto"></i>
</button>
`);
</script></div>
<div class="navbar-item">
<script>
document.write(`
<div class="version-switcher__container dropdown">
<button id="pst-version-switcher-button-3"
type="button"
class="version-switcher__button btn btn-sm dropdown-toggle"
data-bs-toggle="dropdown"
aria-haspopup="listbox"
aria-controls="pst-version-switcher-list-3"
aria-label="Version switcher list"
>
Choose version <!-- this text may get changed later by javascript -->
<span class="caret"></span>
</button>
<div id="pst-version-switcher-list-3"
class="version-switcher__menu dropdown-menu list-group-flush py-0"
role="listbox" aria-labelledby="pst-version-switcher-button-3">
<!-- dropdown will be populated by javascript on page load -->
</div>
</div>
`);
</script></div>
<div class="navbar-item"><ul class="navbar-icon-links"
aria-label="Icon Links">
<li class="nav-item">
<a href="https://gitter.im/matplotlib/matplotlib" title="Gitter" class="nav-link pst-navbar-icon" rel="noopener" target="_blank" data-bs-toggle="tooltip" data-bs-placement="bottom"><i class="fa-brands fa-gitter fa-lg" aria-hidden="true"></i>
<span class="sr-only">Gitter</span></a>
</li>
<li class="nav-item">
<a href="https://discourse.matplotlib.org" title="Discourse" class="nav-link pst-navbar-icon" rel="noopener" target="_blank" data-bs-toggle="tooltip" data-bs-placement="bottom"><i class="fa-brands fa-discourse fa-lg" aria-hidden="true"></i>
<span class="sr-only">Discourse</span></a>
</li>
<li class="nav-item">
<a href="https://github.com/matplotlib/matplotlib" title="GitHub" class="nav-link pst-navbar-icon" rel="noopener" target="_blank" data-bs-toggle="tooltip" data-bs-placement="bottom"><i class="fa-brands fa-github fa-lg" aria-hidden="true"></i>
<span class="sr-only">GitHub</span></a>
</li>
<li class="nav-item">
<a href="https://twitter.com/matplotlib/" title="Twitter" class="nav-link pst-navbar-icon" rel="noopener" target="_blank" data-bs-toggle="tooltip" data-bs-placement="bottom"><i class="fa-brands fa-twitter fa-lg" aria-hidden="true"></i>
<span class="sr-only">Twitter</span></a>
</li>
</ul></div>
</div>
</div>
<div class="sidebar-primary-items__start sidebar-primary__section">
<div class="sidebar-primary-item">
<nav class="bd-docs-nav bd-links"
aria-label="Section Navigation">
<p class="bd-links__title" role="heading" aria-level="1">Section Navigation</p>
<div class="bd-toc-item navbar-nav"><ul class="nav bd-sidenav">
<li class="toctree-l1"><a class="reference internal" href="../contribute.html">Contributing guide</a></li>
</ul>
<ul class="nav bd-sidenav">
<li class="toctree-l1"><a class="reference internal" href="../development_setup.html">Setting up Matplotlib for development</a></li>
</ul>
<ul class="nav bd-sidenav">
<li class="toctree-l1"><a class="reference internal" href="../development_workflow.html">Development workflow</a></li>
</ul>
<ul class="nav bd-sidenav">
<li class="toctree-l1"><a class="reference internal" href="../troubleshooting.html">Troubleshooting</a></li>
</ul>
<ul class="nav bd-sidenav">
<li class="toctree-l1 has-children"><a class="reference internal" href="../coding_guide.html">Coding guidelines</a><details><summary><span class="toctree-toggle" role="presentation"><i class="fa-solid fa-chevron-down"></i></span></summary><ul>
<li class="toctree-l2"><a class="reference internal" href="../license.html">Licenses for contributed code</a></li>
</ul>
</details></li>
<li class="toctree-l1"><a class="reference internal" href="../api_changes.html">API guidelines</a></li>
<li class="toctree-l1"><a class="reference internal" href="../testing.html">Testing</a></li>
</ul>
<ul class="nav bd-sidenav">
<li class="toctree-l1"><a class="reference internal" href="../document.html">Write 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="../tag_guidelines.html">Tagging guidelines</a><details><summary><span class="toctree-toggle" role="presentation"><i class="fa-solid fa-chevron-down"></i></span></summary><ul>
<li class="toctree-l2"><a class="reference internal" href="../tag_glossary.html">Tag Glossary</a></li>
</ul>
</details></li>
</ul>
<ul class="nav bd-sidenav">
<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="../pr_guide.html">Pull request guidelines</a></li>
</ul>
<ul class="current nav bd-sidenav">
<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="../communication_guide.html">Community management guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="../min_dep_policy.html">Dependency version policy</a></li>
<li class="toctree-l1 current active has-children"><a class="reference internal" href="index.html">Matplotlib Enhancement Proposals</a><details open="open"><summary><span class="toctree-toggle" role="presentation"><i class="fa-solid fa-chevron-down"></i></span></summary><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>
</details></li>
</ul>
</div>
</nav></div>
</div>
<div class="sidebar-primary-items__end sidebar-primary__section">
</div>
<div id="rtd-footer-container"></div>
</div>
<main id="main-content" class="bd-main" role="main">
<div class="bd-content">
<div class="bd-article-container">
<div class="bd-header-article d-print-none">
<div class="header-article-items header-article__inner">
<div class="header-article-items__start">
<div class="header-article-item">
<nav aria-label="Breadcrumb" class="d-print-none">
<ul class="bd-breadcrumbs">
<li class="breadcrumb-item breadcrumb-home">
<a href="../../index.html" class="nav-link" aria-label="Home">
<i class="fa-solid fa-home"></i>
</a>
</li>
<li class="breadcrumb-item"><a href="../index.html" class="nav-link">Contribute</a></li>
<li class="breadcrumb-item"><a href="index.html" class="nav-link">Matplotlib Enhancement Proposals</a></li>
<li class="breadcrumb-item active" aria-current="page">MEP14: Text handling</li>
</ul>
</nav>
</div>
</div>
</div>
</div>
<div id="searchbox"></div>
<article class="bd-article">
<section id="mep14-text-handling">
<h1>MEP14: Text handling<a class="headerlink" href="#mep14-text-handling" title="Link to this heading">#</a></h1>
<nav class="contents local" 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>
</nav>
<section id="status">
<h2><a class="toc-backref" href="#id1" role="doc-backlink">Status</a><a class="headerlink" href="#status" title="Link to this heading">#</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" role="doc-backlink">Branches and Pull requests</a><a class="headerlink" href="#branches-and-pull-requests" title="Link to this heading">#</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" role="doc-backlink">Abstract</a><a class="headerlink" href="#abstract" title="Link to this heading">#</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" role="doc-backlink">Detailed description</a><a class="headerlink" href="#detailed-description" title="Link to this heading">#</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 cannot 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://pango.gnome.org">pango</a>/<a class="reference external" href="https://github.com/harfbuzz/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://github.com/harfbuzz/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 cannot 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 internal" href="../../users/explain/customizing.html?highlight=font.family#matplotlibrc-sample"><span class="std std-ref"><span class="pre">rcParams["font.family"]</span></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" role="doc-backlink">Implementation</a><a class="headerlink" href="#implementation" title="Link to this heading">#</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="w"> </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="w"> </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="w"> </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="w"> </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="w"> </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="w"> </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="w"> </span><span class="nf">get_metrics</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="w"> </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="w"> </span><span class="nf">get_spans</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="w"> </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="w"> </span><span class="nf">get_image</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="w"> </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="w"> </span><span class="nf">get_rectangles</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="w"> </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="w"> </span><span class="nf">get_path</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="w"> </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="w"> </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="w"> </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="w"> </span><span class="nf">get_chars</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="w"> </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="w"> </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="w"> </span><span class="nf">get_path</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="w"> </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>
<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>
</li>
<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" role="doc-backlink">Backward compatibility</a><a class="headerlink" href="#backward-compatibility" title="Link to this heading">#</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" role="doc-backlink">Alternatives</a><a class="headerlink" href="#alternatives" title="Link to this heading">#</a></h2>
<p>TBD</p>
</section>
</section>
</article>
</div>
<div class="bd-sidebar-secondary bd-toc"><div class="sidebar-secondary-items sidebar-secondary__inner">
<div class="sidebar-secondary-item">
<div
id="pst-page-navigation-heading-2"
class="page-toc tocsection onthispage">
<i class="fa-solid fa-list"></i> On this page
</div>
<nav class="bd-toc-nav page-toc" aria-labelledby="pst-page-navigation-heading-2">
<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></div>
</div>
<footer class="bd-footer-content">