From: Lars Ingebrigtsen <larsi@gnus.org>
Date: Sun, 2 Aug 2020 17:03:07 +0000 (+0200)
Subject: Document that :width/:height in XBM images are peculiar
X-Git-Tag: emacs-28.0.90~6856
X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=94b6eb807c8991897796fd18ccd414c7d9b9ad3b;p=emacs.git

Document that :width/:height in XBM images are peculiar

* doc/lispref/display.texi (XBM Images): Note the peculiarities of
:width/:height in XBM images (bug#39735).
---

diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index 25eabd6c3fc..d3adb62c1bd 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -5572,6 +5572,15 @@ The value, @var{width}, specifies the width of the image, in pixels.
 @item :height @var{height}
 The value, @var{height}, specifies the height of the image, in pixels.
 
+Note that @code{:width} and @code{:height} can only be used if passing
+in data that doesn't specify the width and height (e.g., a string or a
+vector containing the bits of the image).  @acronym{XBM} files usually
+specify this themselves, and it's an error to use these two properties
+on these files.  Also note that @code{:width} and @code{:height} are
+used by most other image formats to specify what the displayed image
+is supposed to be, which usually means performing some sort of
+scaling.  This isn't supported for @acronym{XBM} images.
+
 @item :stride @var{stride}
 The number of bool vector entries stored for each row; the smallest
 multiple of 8 greater than or equal to @var{width}.