Subject: bug#40784: Clarifying the difference between fringe bitmaps and XBM images

From: Clément Pit-Claudel <[email-masked]>
Date: Wed, 22 Apr 2020 17:52:23 -0400

Hi all,

I was experimenting with XBM images today and it took me a while to realize that the bits in XBM and fringe bitmaps are not in the same order.  The attached patch attempts to highlight this.

Cheers,
Clément.
>From e6c55630b1210ce852214e84a81d59c931663506 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Cl=C3=A9ment=20Pit-Claudel?= <[email-masked]>
Date: Wed, 22 Apr 2020 17:46:07 -0400
Subject: [PATCH] Point out the difference in bit order between fringe bitmaps
 and XBM

* doc/lispref/display.texi (Customizing Bitmaps),
src/fringe.c (Fdefine_fringe_bitmap): Add a caveat about XBM.
---
 doc/lispref/display.texi | 3 ++-
 src/fringe.c             | 4 +++-
 2 files changed, 5 insertions(+), 2 deletions(-)

diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index 132a3c8535..5a5091b57b 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -4338,7 +4338,8 @@ Customizing Bitmaps
 either a string or a vector of integers, where each element (an
 integer) corresponds to one row of the bitmap.  Each bit of an integer
 corresponds to one pixel of the bitmap, where the low bit corresponds
-to the rightmost pixel of the bitmap.
+to the rightmost pixel of the bitmap (this is the opposite of XBM
+images; @pxref{XBM Images}).
 
 The height is normally the length of @var{bits}.  However, you
 can specify a different height with non-@code{nil} @var{height}.  The width
diff --git a/src/fringe.c b/src/fringe.c
index d8d80bb3fe..f33eb83bbf 100644
--- a/src/fringe.c
+++ b/src/fringe.c
@@ -1498,7 +1498,9 @@ DEFUN ("define-fringe-bitmap", Fdefine_fringe_bitmap, Sdefine_fringe_bitmap,
        2, 5, 0,
        doc: /* Define fringe bitmap BITMAP from BITS of size HEIGHT x WIDTH.
 BITMAP is a symbol identifying the new fringe bitmap.
-BITS is either a string or a vector of integers.
+BITS is either a string or a vector of integers.  Beware: the lowest
+bits of each integer is the rightmost pixel of each line, unlike in
+XBM bitmaps.
 HEIGHT is height of bitmap.  If HEIGHT is nil, use length of BITS.
 WIDTH must be an integer from 1 to 16, or nil which defaults to 8.  An
 error is signaled if WIDTH is outside this range.
-- 
2.17.1