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

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

[Clément Pit-Claudel]

[-- Attachment #1: Type: text/plain, Size: 219 bytes --]

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.

[-- Attachment #2: 0001-Point-out-the-difference-in-bit-order-between-fringe.patch --]
[-- Type: text/x-patch, Size: 1970 bytes --]

From e6c55630b1210ce852214e84a81d59c931663506 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Cl=C3=A9ment=20Pit-Claudel?= <clement.pitclaudel@live.com>
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

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

[Eli Zaretskii]

> From: Clément Pit-Claudel <cpitclaudel@gmail.com>
> Date: Wed, 22 Apr 2020 17:52:23 -0400
> 
> 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.

I don't think I understand the concern, and therefore cannot make up
my mind about the proposed changes.  Can you tell more about your
difficulties?

Thanks.

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

[Clément Pit-Claudel]

On 23/04/2020 10.30, Eli Zaretskii wrote:
>> From: Clément Pit-Claudel <cpitclaudel@gmail.com>
>> Date: Wed, 22 Apr 2020 17:52:23 -0400
>>
>> 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.
> 
> I don't think I understand the concern, and therefore cannot make up
> my mind about the proposed changes.  Can you tell more about your
> difficulties?

Of course: I am currently writing a mode that displays indicators either in the margins or in the fringes, depending on the value of a defcustom.
By default, I intended to use the same bitmaps in the margins and in the fringes.  It took me a while to understand what I was doing wrong: I was seeing reversed bitmaps, but I hadn't considered the possibility that the two places where Emacs supports monochrome bitmaps would accept the same representation (unibyte strings) but use a different bit order. 
The proposed patch updates the documentation to save the next person from experiencing the same pain.

Clément.

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

[Eli Zaretskii]

> Cc: 40784@debbugs.gnu.org
> From: Clément Pit-Claudel <cpitclaudel@gmail.com>
> Date: Thu, 23 Apr 2020 10:35:54 -0400
> 
> Of course: I am currently writing a mode that displays indicators either in the margins or in the fringes, depending on the value of a defcustom.
> By default, I intended to use the same bitmaps in the margins and in the fringes.  It took me a while to understand what I was doing wrong: I was seeing reversed bitmaps, but I hadn't considered the possibility that the two places where Emacs supports monochrome bitmaps would accept the same representation (unibyte strings) but use a different bit order. 
> The proposed patch updates the documentation to save the next person from experiencing the same pain.

If so, then why do we need to mention this in the doc string?  Won't
the manual be enough?  It is strange to mention just this factoid in
the doc strings, when one can shoot themselves in the foot with
bitmapped images in many exciting ways.

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

[Clément Pit-Claudel]

On 23/04/2020 11.14, Eli Zaretskii wrote:
>> Cc: 40784@debbugs.gnu.org
>> From: Clément Pit-Claudel <cpitclaudel@gmail.com>
>> Date: Thu, 23 Apr 2020 10:35:54 -0400
>>
>> Of course: I am currently writing a mode that displays indicators either in the margins or in the fringes, depending on the value of a defcustom.
>> By default, I intended to use the same bitmaps in the margins and in the fringes.  It took me a while to understand what I was doing wrong: I was seeing reversed bitmaps, but I hadn't considered the possibility that the two places where Emacs supports monochrome bitmaps would accept the same representation (unibyte strings) but use a different bit order. 
>> The proposed patch updates the documentation to save the next person from experiencing the same pain.
> 
> If so, then why do we need to mention this in the doc string?  Won't
> the manual be enough?  It is strange to mention just this factoid in
> the doc strings, when one can shoot themselves in the foot with
> bitmapped images in many exciting ways.

The docstrings are usually good enough that I seldom read the manuals :/
Having a brief warning in the docstring is useful in that case.  But I'm happy to yield to your judgement.

Clément.

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

[Eli Zaretskii]

> Cc: 40784@debbugs.gnu.org
> From: Clément Pit-Claudel <cpitclaudel@gmail.com>
> Date: Thu, 23 Apr 2020 11:44:13 -0400
> 
> > If so, then why do we need to mention this in the doc string?  Won't
> > the manual be enough?  It is strange to mention just this factoid in
> > the doc strings, when one can shoot themselves in the foot with
> > bitmapped images in many exciting ways.
> 
> The docstrings are usually good enough that I seldom read the manuals :/
> Having a brief warning in the docstring is useful in that case.  But I'm happy to yield to your judgement.

Thanks, I've updated the manual with this caveat.