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.