matplotlib
diff --git a/‎examples/text_labels_and_annotations/text_alignment.py
Lines changed: 36 additions & 5 deletions b/‎examples/text_labels_and_annotations/text_alignment.py
Lines changed: 36 additions & 5 deletions
diff --git a/‎lib/matplotlib/text.py
Lines changed: 12 additions & 4 deletions b/‎lib/matplotlib/text.py
Lines changed: 12 additions & 4 deletions
@@ -1,13 +1,44 @@
 """
-===================
-Precise text layout
-===================
+==============
+Text alignment
+==============
 
-You can precisely layout text in data or axes coordinates.  This example shows
-you some of the alignment and rotation specifications for text layout.
+Texts are aligned relative to their anchor point depending on the properties
+``horizontalalignment`` and ``verticalalignment``.
 """
 
 import matplotlib.pyplot as plt
+import numpy as np
+
+y = [0.21, 0.33, 0.5, 0.558, 0.785]
+x = [0.17, 0.5, 0.855]
+X, Y = np.meshgrid(x, y)
+
+fig, ax = plt.subplots(dpi=100)
+ax.set(xlim=(0, 1), ylim=(0, 1), xticks=[], yticks=[])
+ax.spines[:].set_visible(False)
+ax.text(0.5, 0.5, 'plot', fontsize=128, ha='center', va='center', zorder=1)
+ax.hlines(y, x[0], x[-1], color='grey')
+ax.vlines(x, y[0], y[-1], color='grey')
+ax.plot(X.ravel(), Y.ravel(), 'o')
+pad_x = 0.02
+pad_y = 0.04
+ax.text(x[0] - pad_x, y[0], 'bottom', ha='right', va='center')
+ax.text(x[0] - pad_x, y[1], 'baseline', ha='right', va='center')
+ax.text(x[0] - pad_x, y[2], 'center', ha='right', va='center')
+ax.text(x[0] - pad_x, y[3], 'center_baseline', ha='right', va='center')
+ax.text(x[0] - pad_x, y[4], 'top', ha='right', va='center')
+ax.text(x[0], y[0] - pad_y, 'left', ha='center', va='top')
+ax.text(x[1], y[0] - pad_y, 'center', ha='center', va='top')
+ax.text(x[2], y[0] - pad_y, 'right', ha='center', va='top')
+ax.set_xlabel('horizontalalignment')
+ax.set_ylabel('verticalalignment', labelpad=45)
+ax.set_title('Relative position of text anchor point depending on alignment')
+plt.show()
+
+
+#############################################################################
+# The following plot uses this to align text relative to a plotted rectangle.
 
 fig, ax = plt.subplots()
 
 
@@ -132,6 +132,10 @@ def __init__(self,
         """
         Create a `.Text` instance at *x*, *y* with string *text*.
 
+        The text is aligned relative to the anchor point (*x*, *y*) according
+        to ``horizontalalingment`` (default: 'left') and ``verticalalignment``
+        (default: 'bottom'). See also :doc:`/gallery/text/text_alignment`.
+
         Valid keyword arguments are:
 
         %(Text:kwdoc)s
@@ -956,11 +960,13 @@ def set_color(self, color):
 
     def set_horizontalalignment(self, align):
         """
-        Set the horizontal alignment to one of
+        Set the horizontal alignment relative to the anchor point.
+
+        See also :doc:`/gallery/text/text_alignment`.
 
         Parameters
         ----------
-        align : {'center', 'right', 'left'}
+        align : {'left', 'center', 'right'}
         """
         _api.check_in_list(['center', 'right', 'left'], align=align)
         self._horizontalalignment = align
@@ -1194,11 +1200,13 @@ def set_transform_rotates_text(self, t):
 
     def set_verticalalignment(self, align):
         """
-        Set the vertical alignment.
+        Set the vertical alignment relative to the anchor point.
+
+        See also :doc:`/gallery/text/text_alignment`.
 
         Parameters
         ----------
-        align : {'center', 'top', 'bottom', 'baseline', 'center_baseline'}
+        align : {'bottom', 'baseline', 'center', 'center_baseline', 'top'}
         """
         _api.check_in_list(
             ['top', 'bottom', 'center', 'baseline', 'center_baseline'],