matplotlib
diff --git a/‎doc/release/prev_whats_new/whats_new_3.11.0.rst‎
Lines changed: 29 additions & 0 deletions b/‎doc/release/prev_whats_new/whats_new_3.11.0.rst‎
Lines changed: 29 additions & 0 deletions
diff --git a/‎galleries/users_explain/text/fonts.py‎
Lines changed: 0 additions & 23 deletions b/‎galleries/users_explain/text/fonts.py‎
Lines changed: 0 additions & 23 deletions
@@ -774,6 +774,35 @@ Text support has been extended to include complex text layout. This support incl
 Note, all advanced features require corresponding font support, and may require
 additional fonts over the builtin DejaVu Sans.
 
+.. admonition:: Remove any pre-shaping workaround
+    :class: important
+
+    Because Matplotlib did not previously reorder text, the usual workaround for
+    Arabic, Persian, Urdu and Hebrew was to reorder the string before passing it in,
+    typically with ``arabic_reshaper`` and ``python-bidi``::
+
+        ax.set_title(get_display(arabic_reshaper.reshape(text)))
+
+    Matplotlib now reorders the string itself, so a string that arrives already in
+    visual order is reordered a second time and is drawn backwards. Nothing is
+    raised, and to a reader who does not read the script the result still looks
+    like correct text, so this is easy to ship without noticing.
+
+    - If you can require Matplotlib 3.11, pass the logical string and delete the
+      pre-processing.
+    - If you support older versions as well, branch on the Matplotlib version and
+      pre-process only on the older one.
+    - If you cannot change the call at all, because the text is handed to a
+      third-party library that calls Matplotlib for you, wrap the pre-processed
+      string in ``LEFT-TO-RIGHT OVERRIDE`` and ``POP DIRECTIONAL FORMATTING``::
+
+          text = ('\N{LEFT-TO-RIGHT OVERRIDE}' + preprocessed +
+                  '\N{POP DIRECTIONAL FORMATTING}')
+
+      That reads correctly on every version. It does not always render
+      identically, because it draws the font's presentation-form glyphs rather
+      than the font's own shaping, and some fonts space those differently.
+
 Specifying font feature tags
 ----------------------------
 
 
@@ -183,27 +183,4 @@
 
 A majority of this work was done by Aitik Gupta supported by Google Summer of
 Code 2021.
-
-Text shaping
-------------
-
-Some scripts cannot be drawn by taking a string one character at a time.  Arabic
-letters change shape depending on their neighbours, and right-to-left text is
-stored in logical order but drawn in visual order.  As of Matplotlib 3.11 this is
-handled for you: FreeType is driven through libraqm, which uses HarfBuzz to shape
-the string and a bidi implementation to reorder it.
-
-Pass the logical string, the one you would read aloud::
-
-    ax.set_title("الإمارات")
-
-Before 3.11 no shaping was done, and the usual workaround was to pre-process the
-string with ``arabic_reshaper`` and ``python-bidi``::
-
-    ax.set_title(get_display(arabic_reshaper.reshape("الإمارات")))
-
-That pre-processing must now be removed.  The string it produces is already in
-visual order, so Matplotlib reorders it a second time and the label is drawn
-backwards.  Nothing is raised, and the output still looks like Arabic to a reader
-who does not read Arabic.
 """  # noqa: E501