From 7dae6fca92f1bc4b678a402b0577144492704d90 Mon Sep 17 00:00:00 2001
From: cananoo <2059997196@qq.com>
Date: Thu, 27 Aug 2026 21:10:02 +0800
Subject: [PATCH] [ci skip] docs: clarify Raqm text preprocessing (#9907)

---
 docs/reference/ImageDraw.rst | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/docs/reference/ImageDraw.rst b/docs/reference/ImageDraw.rst
index faa3a236f45..70dccc1f9c0 100644
--- a/docs/reference/ImageDraw.rst
+++ b/docs/reference/ImageDraw.rst
@@ -399,6 +399,15 @@ Methods
 
     Draw a shape.
 
+.. note::
+
+    When libraqm is available, Pillow performs complex text layout, including
+    shaping and bidirectional text handling, itself. Do not pre-process text
+    with ``arabic_reshaper`` and ``python-bidi`` in this case, as applying the
+    same processing twice produces incorrect results. Use
+    :py:func:`PIL.features.check` with ``"raqm"`` to determine whether
+    libraqm is available before deciding whether pre-processing is needed.
+
 .. py:method:: ImageDraw.text(xy, text, fill=None, font=None, anchor=None, spacing=4, align="left", direction=None, features=None, language=None, stroke_width=0, stroke_fill=None, embedded_color=False, font_size=None)
 
     Draws the string at the given position.