From d55d07af701d7e082a729c6dc69448f32f3935bc Mon Sep 17 00:00:00 2001
From: Stefan Monnier <monnier@iro.umontreal.ca>
Date: Sat, 10 Apr 2021 20:06:21 -0400
Subject: [PATCH] * lisp/net/shr.el (shr-insert-document): Explain why
 bidi-display-reordering

---
 lisp/net/shr.el | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/lisp/net/shr.el b/lisp/net/shr.el
index c122a19e90c..d1544764404 100644
--- a/lisp/net/shr.el
+++ b/lisp/net/shr.el
@@ -313,6 +313,11 @@ DOM should be a parse tree as generated by
                   (* (frame-char-width) 2))
                 1))))
         (max-specpdl-size max-specpdl-size)
+        ;; `bidi-display-reordering' is supposed to be only used for
+        ;; debugging purposes, but Shr's naïve filling algorithm
+        ;; cannot cope with the complexity of RTL text in an LTR
+        ;; paragraph, when a long line has been continued, so...
+        ;; this is the best we could do  :-(
         bidi-display-reordering)
     ;; Adjust for max width specification.
     (when (and shr-max-width
-- 
2.39.2