master 7405f0340b5: Merge from origin/emacs-29

[Eli Zaretskii]

branch: master
commit 7405f0340b5ebfc8ccb903554d6d2d586611ccca
Merge: 5d9a8c3704c b9f7a2274f6
Author: Eli Zaretskii <eliz@gnu.org>
Commit: Eli Zaretskii <eliz@gnu.org>

    Merge from origin/emacs-29
    
    b9f7a2274f6 ; Improve documentation of 'minibuffer-allow-text-propert...
    5ffcca121bb ; Improve documentation of image properties
    6e801077ae8 ; * src/composite.c (composition_compute_stop_pos): Add c...
---
 doc/lispref/display.texi |  9 +++++++--
 doc/lispref/minibuf.texi | 14 ++++++++------
 lisp/image.el            | 16 ++++++++++++----
 src/composite.c          | 26 +++++++++++++++++++++-----
 4 files changed, 48 insertions(+), 17 deletions(-)

diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index 10cf5ce89e2..beca470d68a 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -6048,6 +6048,7 @@ event is composed by combining the @var{id} of the 
hot-spot with the
 mouse event; for instance, @code{[area4 mouse-1]} if the hot-spot's
 @var{id} is @code{area4}.
 
+@findex image-compute-scaling-factor
 Note that the map's coordinates should reflect the displayed image
 after all transforms have been done (rotation, scaling and so on), and
 also note that Emacs (by default) performs auto-scaling of images, so
@@ -6766,11 +6767,15 @@ from the file's name.
 The remaining arguments, @var{props}, specify additional image
 properties---for example,
 
-@c ':heuristic-mask' is not documented?
 @example
-(create-image "foo.xpm" 'xpm nil :heuristic-mask t)
+(create-image "foo.xpm" 'xpm nil :mask 'heuristic)
 @end example
 
+@noindent
+@xref{Image Descriptors}, for the list of supported properties.  Some
+properties are specific to certain image types, and are described in
+subsections specific to those types.
+
 The function returns @code{nil} if images of this type are not
 supported.  Otherwise it returns an image descriptor.
 @end defun
diff --git a/doc/lispref/minibuf.texi b/doc/lispref/minibuf.texi
index 0247c93f7b8..8f2d0d702f9 100644
--- a/doc/lispref/minibuf.texi
+++ b/doc/lispref/minibuf.texi
@@ -187,7 +187,8 @@ History}.
 If the variable @code{minibuffer-allow-text-properties} is
 non-@code{nil}, then the string that is returned includes whatever text
 properties were present in the minibuffer.  Otherwise all the text
-properties are stripped when the value is returned.
+properties are stripped when the value is returned.  (By default this
+variable is @code{nil}.)
 
 @vindex minibuffer-prompt-properties
 The text properties in @code{minibuffer-prompt-properties} are applied
@@ -350,14 +351,15 @@ See @code{read-regexp} above for details of how these 
values are used.
 @end defopt
 
 @defvar minibuffer-allow-text-properties
-If this variable is @code{nil}, then @code{read-from-minibuffer}
-and @code{read-string} strip all text properties from the minibuffer
-input before returning it.  However,
+If this variable is @code{nil}, the default, then
+@code{read-from-minibuffer} and @code{read-string} strip all text
+properties from the minibuffer input before returning it.  However,
 @code{read-no-blanks-input} (see below), as well as
 @code{read-minibuffer} and related functions (@pxref{Object from
 Minibuffer,, Reading Lisp Objects With the Minibuffer}), and all
-functions that do minibuffer input with completion, remove the @code{face}
-property unconditionally, regardless of the value of this variable.
+functions that do minibuffer input with completion, remove the
+@code{face} property unconditionally, regardless of the value of this
+variable.
 
 If this variable is non-@code{nil}, most text properties on strings
 from the completion table are preserved---but only on the part of the
diff --git a/lisp/image.el b/lisp/image.el
index 662e7eaf25d..c13fea6c45c 100644
--- a/lisp/image.el
+++ b/lisp/image.el
@@ -517,9 +517,13 @@ use its file extension as image type.
 Optional DATA-P non-nil means FILE-OR-DATA is a string containing image data.
 
 Optional PROPS are additional image attributes to assign to the image,
-like, e.g. `:mask MASK'.  If the property `:scale' is not given and the
-display has a high resolution (more exactly, when the average width of a
-character in the default font is more than 10 pixels), the image is
+like, e.g. `:mask MASK'.  See Info node `(elisp)Image Descriptors' for
+the list of supported properties; see the nodes following that node
+for properties specific to certain image types.
+
+If the property `:scale' is not given and the display has a high
+resolution (more exactly, when the average width of a character
+in the default font is more than 10 pixels), the image is
 automatically scaled up in proportion to the default font.
 
 Value is the image created, or nil if images of type TYPE are not supported.
@@ -594,7 +598,11 @@ Internal use only."
 Properties can be set with
 
   (setf (image-property IMAGE PROPERTY) VALUE)
-If VALUE is nil, PROPERTY is removed from IMAGE."
+If VALUE is nil, PROPERTY is removed from IMAGE.
+
+See Info node `(elisp)Image Descriptors' for the list of
+supported properties; see the nodes following that node for
+properties specific to certain image types."
   (declare (gv-setter image--set-property))
   (plist-get (cdr image) property))
 
diff --git a/src/composite.c b/src/composite.c
index 111b1cea88b..e89d923168a 100644
--- a/src/composite.c
+++ b/src/composite.c
@@ -1147,12 +1147,12 @@ composition_compute_stop_pos (struct composition_it 
*cmp_it, ptrdiff_t charpos,
     }
   else if (charpos > endpos)
     {
-      /* Search backward for a pattern that may be composed and the
-        position of (possibly) the last character of the match is
+      /* Search backward for a pattern that may be composed such that
+        the position of (possibly) the last character of the match is
         closest to (but not after) START.  The reason for the last
-        character is that set_iterator_to_next works in reverse order,
-        and thus we must stop at the last character for composition
-        check.  */
+        character is that set_iterator_to_next works in reverse
+        order, and thus we must stop at the last character for
+        composition check.  */
       unsigned char *p;
       int len;
       /* Limit byte position used in fast_looking_at.  This is the
@@ -1165,6 +1165,22 @@ composition_compute_stop_pos (struct composition_it 
*cmp_it, ptrdiff_t charpos,
        p = SDATA (string) + bytepos;
       c = string_char_and_length (p, &len);
       limit = bytepos + len;
+      /* The algorithmic idea behind the loop below is somewhat tricky
+         and subtle.  Keep in mind that any arbitrarily long sequence
+         of composable characters can potentially be composed to end
+         at or before START.  So the fact that we find a character C
+         before START that can be composed with several following
+         characters does not mean we can exit the loop, because some
+         character before C could also be composed, yielding a longer
+         composed sequence which ends closer to START.  And since a
+         composition can be arbitrarily long, it is very important to
+         know where to stop the search back, because the default --
+         BEGV -- could be VERY far away.  Since searching back is only
+         needed when delivering bidirectional text reordered for
+         display, and since no character composition can ever cross
+         into another embedding level, the search could end when it
+         gets to the end of the current embedding level, but this
+         limit should be imposed by the caller.   */
       while (char_composable_p (c))
        {
          val = CHAR_TABLE_REF (Vcomposition_function_table, c);