From 90cac37a771ee803737d2ab2b320e55ee8ffbc88 Mon Sep 17 00:00:00 2001
From: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com>
Date: Tue, 19 May 2026 15:51:49 +0200
Subject: [PATCH] DOC: Improve multiple example

- add explanations
- use an example that shows more of the multiline effect
- move the "spacing test" to a separate plot to de-emphasize it. Possibly this should be an actual test not an example. But that can be decided later.
---
 .../text_labels_and_annotations/multiline.py  | 84 ++++++++++++-------
 1 file changed, 54 insertions(+), 30 deletions(-)

diff --git a/galleries/examples/text_labels_and_annotations/multiline.py b/galleries/examples/text_labels_and_annotations/multiline.py
index e9ce81fe6526..08a318871b56 100644
--- a/galleries/examples/text_labels_and_annotations/multiline.py
+++ b/galleries/examples/text_labels_and_annotations/multiline.py
@@ -1,45 +1,69 @@
 """
-=========
-Multiline
-=========
+==============
+Multiline text
+==============
 
+Texts may contain newlines to create multiline text.
+
+The text alignment of the individual lines can be controlled by the
+``multialignment`` parameter. If not set, the alignment of the lines is inferred from
+the ``horizontalalignment`` and ``verticalalignment`` parameters, which primarily
+control the alignment of the bounding box of the text to its anchor point; e.g. if the
+text has the anchor point to its right, all text lines will be aligned to the right
+so that they pick up that anchor point.
+
+When using mutli-line labels, it is recommended to use a layout manager (e.g.
+``layout="constrained"``) to ensure that there is enough space for the labels..
 """
 import matplotlib.pyplot as plt
-import numpy as np
 
-fig, (ax0, ax1) = plt.subplots(ncols=2, figsize=(7, 4))
+fig, ax = plt.subplots(layout="constrained")
+
+ax.bar(range(6), [0.3, 0.5, 0.8, 1.5, 2.5, 8], alpha=0.3)
+
+ax.set_ylabel('labels are centered,\nso is their multi-line text by default')
+ax.set_xlabel('xlabel with\nmultialignment="left"', multialignment="left")
 
-ax0.set_aspect(1)
-ax0.plot(np.arange(10))
-ax0.set_xlabel('this is an xlabel\n(with newlines!)')
-ax0.set_ylabel('this is vertical\ntest', multialignment='center')
-ax0.text(2, 7, 'this is\nyet another test',
-         rotation=45,
-         horizontalalignment='center',
-         verticalalignment='top',
-         multialignment='center')
+ax.text(
+    4.5, 6,
+    'these lines\n'
+    'are right aligned\n'
+    'because of horizontalalignment',
+    horizontalalignment='right',
+)
+
+ax.text(
+    4.5, 4,
+    'but\n'
+    'we can override this\n'
+    'with an explicit multialingment="left"',
+    horizontalalignment='right',
+    multialignment='left',
+)
+
+plt.show()
 
-ax0.grid()
 
+# %%
+# Each line has the same height irrespective of the used characters unless
+# there is math text involved, which may need more vertical space
 
-ax1.text(0.29, 0.4, "Mat\nTTp\n123", size=18,
-         va="baseline", ha="right", multialignment="left",
-         bbox=dict(fc="none"))
+fig, ax = plt.subplots()
 
-ax1.text(0.34, 0.4, "Mag\nTTT\n123", size=18,
-         va="baseline", ha="left", multialignment="left",
-         bbox=dict(fc="none"))
+ax.text(0.1, 0.4, "Mat\nTTp\n123", size=18,
+        va="baseline", bbox=dict(fc="none", ec="tab:orange"))
 
-ax1.text(0.95, 0.4, "Mag\nTTT$^{A^A}$\n123", size=18,
-         va="baseline", ha="right", multialignment="left",
-         bbox=dict(fc="none"))
+ax.text(0.3, 0.4, "Mag\nTTT\n123", size=18,
+        va="baseline", bbox=dict(fc="none", ec="tab:orange"))
 
-ax1.set_xticks([0.2, 0.4, 0.6, 0.8, 1.],
-               labels=["Jan\n2009", "Feb\n2009", "Mar\n2009", "Apr\n2009",
-                       "May\n2009"])
+ax.text(0.5, 0.4, "Mag\nTTT$^{A^A}$\n123", size=18,
+        va="baseline", bbox=dict(fc="none", ec="tab:orange"))
 
-ax1.axhline(0.4)
-ax1.set_title("test line spacing for multiline text")
+ax.axhline(0.4)
+ax.set_title("test line spacing for multiline text")
+ax.set_xlim(0, 0.7)
+ax.yaxis.minorticks_on()
+ax.yaxis.set_tick_params(which="minor", grid_color="0.9")
+ax.grid(which="both")
 
-fig.subplots_adjust(bottom=0.25, top=0.75)
 plt.show()