From 7490aee8362c589a475035bf86c05b29c894593c Mon Sep 17 00:00:00 2001
From: Nulano <nulano@nulano.eu>
Date: Mon, 19 Feb 2024 20:18:18 +0100
Subject: [PATCH] Show how to use anchors to align text in imagefont
 deprecations

---
 docs/deprecations.rst       | 24 ++++++++++++++++++++++++
 docs/releasenotes/9.2.0.rst | 24 ++++++++++++++++++++++++
 2 files changed, 48 insertions(+)

diff --git a/docs/deprecations.rst b/docs/deprecations.rst
index 74021a218..9efb1316d 100644
--- a/docs/deprecations.rst
+++ b/docs/deprecations.rst
@@ -260,6 +260,30 @@ offset.
     :alt: Demonstration of size height vs bbox top and bottom
     :align: center
 
+If you are using these methods for aligning text, consider using :ref:`text-anchors` instead
+which avoid issues that can occur with non-English text or unusual fonts.
+For example, instead of the following code::
+
+    from PIL import Image, ImageDraw, ImageFont
+
+    font = ImageFont.truetype("Tests/fonts/FreeMono.ttf")
+
+    im = Image.new("RGB", (100, 100))
+    draw = ImageDraw.Draw(im)
+    width, height = draw.textsize("Hello world", font)
+    x, y = (100 - width) / 2, (100 - height) / 2
+    draw.text((x, y), "Hello world", font=font)
+
+Use instead::
+
+    from PIL import Image, ImageDraw, ImageFont
+
+    font = ImageFont.truetype("Tests/fonts/FreeMono.ttf")
+
+    im = Image.new("RGB", (100, 100))
+    draw = ImageDraw.Draw(im)
+    draw.text((100 / 2, 100 / 2), "Hello world", font=font, anchor="mm")
+
 FreeTypeFont.getmask2 fill parameter
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
diff --git a/docs/releasenotes/9.2.0.rst b/docs/releasenotes/9.2.0.rst
index db514068f..e8bf33b60 100644
--- a/docs/releasenotes/9.2.0.rst
+++ b/docs/releasenotes/9.2.0.rst
@@ -97,6 +97,30 @@ offset.
     :alt: Demonstration of size height vs bbox top and bottom
     :align: center
 
+If you are using these methods for aligning text, consider using :ref:`text-anchors` instead
+which avoid issues that can occur with non-English text or unusual fonts.
+For example, instead of the following code::
+
+    from PIL import Image, ImageDraw, ImageFont
+
+    font = ImageFont.truetype("Tests/fonts/FreeMono.ttf")
+
+    im = Image.new("RGB", (100, 100))
+    draw = ImageDraw.Draw(im)
+    width, height = draw.textsize("Hello world", font)
+    x, y = (100 - width) / 2, (100 - height) / 2
+    draw.text((x, y), "Hello world", font=font)
+
+Use instead::
+
+    from PIL import Image, ImageDraw, ImageFont
+
+    font = ImageFont.truetype("Tests/fonts/FreeMono.ttf")
+
+    im = Image.new("RGB", (100, 100))
+    draw = ImageDraw.Draw(im)
+    draw.text((100 / 2, 100 / 2), "Hello world", font=font, anchor="mm")
+
 API Additions
 =============