* lisp/net/shr.el (shr-insert-document): Explain why bidi-display-reordering

1 files changed, 5 insertions, 0 deletions

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