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

From: Clément Pit-Claudel <[email-masked]>
Date: Thu, 23 Apr 2020 11:44:13 -0400

On 23/04/2020 11.14, Eli Zaretskii wrote:
>> Cc: [email-masked]
>> From: Clément Pit-Claudel <[email-masked]>
>> 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.