emacs-28 cf38e1c393: Clarify image file search

[Eli Zaretskii]

branch: emacs-28
commit cf38e1c3939f4799113755c762fc7b8c3093fe56
Author: Eli Zaretskii <eliz@gnu.org>
Commit: Eli Zaretskii <eliz@gnu.org>

    Clarify image file search
    
    * doc/lispref/display.texi (Defining Images, Image Descriptors):
    * lisp/image.el (create-image): Clarify that non-absolute image
    files are searched along 'image-load-path'.  (Bug#52931)
---
 doc/lispref/display.texi | 11 ++++++-----
 lisp/image.el            |  5 +++--
 2 files changed, 9 insertions(+), 7 deletions(-)

diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index b068c7d08c..3861f89036 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -5416,10 +5416,9 @@ Every image descriptor must include this property.
 
 @item :file @var{file}
 This says to load the image from file @var{file}.  If @var{file} is
-not an absolute file name, it is expanded relative to the
-@file{images} subdirectory of @code{data-directory}, and failing that,
-relative to the directories listed by @code{x-bitmap-file-path}
-(@pxref{Face Attributes}).
+not an absolute file name, it is expanded relative to each of the
+directories mentioned by @code{image-load-path} (@pxref{Defining
+Images}).
 
 @item :data @var{data}
 This specifies the raw image data.  Each image descriptor must have
@@ -6367,7 +6366,9 @@ Supports the @code{:index} property.  @xref{Multi-Frame 
Images}.
 This function creates and returns an image descriptor which uses the
 data in @var{file-or-data}.  @var{file-or-data} can be a file name or
 a string containing the image data; @var{data-p} should be @code{nil}
-for the former case, non-@code{nil} for the latter case.
+for the former case, non-@code{nil} for the latter case.  If
+@var{file-or-data} is a relative file name, the function will search
+for it in directories mentioned in @code{image-load-path}.
 
 The optional argument @var{type} is a symbol specifying the image type.
 If @var{type} is omitted or @code{nil}, @code{create-image} tries to
diff --git a/lisp/image.el b/lisp/image.el
index ea1a22698c..72b7862c95 100644
--- a/lisp/image.el
+++ b/lisp/image.el
@@ -460,8 +460,9 @@ must be available."
 
 ;;;###autoload
 (defun create-image (file-or-data &optional type data-p &rest props)
-  "Create an image.
-FILE-OR-DATA is an image file name or image data.
+  "Create an image from FILE-OR-DATA.
+FILE-OR-DATA is an image file name or image data.  If it is a relative
+file name, the function will look for it along `image-load-path'.
 
 Optional TYPE is a symbol describing the image type.  If TYPE is omitted
 or nil, try to determine the image type from its first few bytes