; 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.

diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index 34f215820ed338fed39d7a0944ddf0862fa749d2..c6b29e87b3a6fb1f1dec87681000de4dca1ebb0c 100644 (file)
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -6041,6 +6041,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
@@ -6759,11 +6760,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 ef29698f647c7b3f15e23781e82056b68fd034f5..4e50f6784331dd8ae86cf3e3bca80f86c97dff9d 100644 (file)
--- a/lisp/image.el
+++ b/lisp/image.el
@@ -494,9 +494,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.
@@ -571,7 +575,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))