From: Eli Zaretskii <eliz@gnu.org>
Date: Thu, 7 Mar 2024 08:11:44 +0000 (+0200)
Subject: ; Improve documentation of image properties
X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=11dc4c00d02844995375c4578aa04f82e0350ee2;p=emacs.git

; Improve documentation of image properties

* lisp/image.el (create-image, image-property): Add to do strings
link to description of image properties in ELisp manual.

* doc/lispref/display.texi (Defining Images): Fix example and add
cross-reference to where image properties are described.
(Image Descriptors): Add index entry.

(cherry picked from commit 5ffcca121bb79b97c6a0f941c71a61505032d8f8)
---

diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index fc1e1a457e1..5c57bed37a2 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -6076,6 +6076,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
@@ -6794,11 +6795,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/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))