Comments on display.texi

Comments on display.texi

[Kim F. Storm]

Thanks for correcting my additions to display.texi.

You left some questions open in display.texi:


>   The way to display a bitmap in the left or right fringes for a given
> line in a window is by specifying the @code{display} property for one
> of the characters that appears in it.  Use a display specification of
> the form @code{(left-fringe @var{bitmap} [@var{face}])} or
> @code{(right-fringe @var{bitmap} [@var{face}])} (@pxref{Display
> Property}).  Here, @var{bitmap} is an integer identifying the bitmap
> you want, and @var{face} (which is optional) is the name of the face
> whose colors should be used for displaying the bitmap.
> @c ??? Shouldn't the symbol name be used?

The code uses the integer value (the bitmap number), so I didn't see
any reason to use a symbol here.

It is the same for e.g. images -- you specify the image, not a symbol
identifying an image.

E.g. when you use (defimage my-image ...)  to define an image, what
really happens is that the image specified by ... is loaded and
saved in the variable my-image.


> @item Value indicating that no fringe bitmap is present:
> @code{no-fringe-bitmap}.
> @c ??? I don't understand what that means.
> @c ??? Where would you find that value?

In the car or cdr of the return value from fringe-bitmaps-at-pos if
there is no bitmap in left or right fringe.

> @item Value indicating a reference to an undefined bitmap:
> @code{undef-fringe-bitmap}.
> @c ??? I don't understand what that means.
> @c ??? Where would you find that value?

If you specify an undefined fringe bitmap in a display property,
e.g. using fringe bitmap number 100 and only 50 bitmaps are defined.
Then the fringe will contain the undef-fringe-bitmap (a question-mark).


> @defun fringe-bitmaps-at-pos &optional pos window
> This function returns the fringe bitmaps of the display line
> containing position @var{pos} in window @var{window}.  The return
> value has the form @code{(@var{left} . @var{right})}, where @var{left}
> is a list of fringe bitmap numbers for left fringe, and @var{right} is
> similar for the right fringe.  These bitmap numbers are usually values
> of symbols such as the ones listed above.
>  
> @c ??? Why not return a list of symbols that identify the bitmaps?
> @c ??? This is Lisp, not C.

Internally the bitmaps are represented and managed using integers
(indexes), so there are no internal symbols defining bitmaps --- just
like there are no internal symbols defining images.

For simplicity, I chose to expose those integers as "opaque fringe
bitmap numbers".  Using symbols would be a lot of extra work for no
added functionality!

> @defun define-fringe-bitmap bits &optional height width align bitmap
> This function defines a new fringe bitmap, or replaces an existing
> bitmap.
>
> @c ??? Why not pass a symbol as the first argument
> @c ??? and define that symbol.  It would be cleaner.

There is no symbol associated with a fringe bitmap, so why invent one.
This is similar to how images are handled.

There could be a `deffringe' macro similar to `defimage' which
binds the result of define-fringe-bitmap to a variable...

Or I could rename define-fringe-bitmap to make-fringe-bitmap if people
expect a function named `define-something' to have a symbol as first
arg.

> The argument @var{bits} specifies the image to use.  It should be
> 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.
> @c ??? Is the low bit the leftmost or the rightmost bit?

rightmost

For example, if you define a bitmap as

[#B00001000
 #B00001100
 #B00001110
 #B11111111
 #B11111111
 #B00001110
 #B00001100
 #B00001000]

it defines an arrow pointing to the right.


> The return value on success is an integer identifying the new bitmap.
> You should save that integer in a variable so it can be used to select
> this bitmap.  The value can also be @code{nil} of there are no more
> free bitmap slots.
> @c ??? Why not signal an error?  That would be cleaner.

Ok, I will change that.


-- 
Kim F. Storm <storm@cua.dk> http://www.cua.dk

Re: Comments on display.texi

[Richard Stallman]

    The code uses the integer value (the bitmap number), so I didn't see
    any reason to use a symbol here.

The reason is, it is more Lisp-like to use symbols than numbers.
It is easier to debug a program when you see a symbol whose name
is meaningful than when you see a number.

    It is the same for e.g. images -- you specify the image, not a symbol
    identifying an image.

Sorry, I don't understand.  When you say "you specify the image",
what data type is that?

    > @item Value indicating that no fringe bitmap is present:
    > @code{no-fringe-bitmap}.
    > @c ??? I don't understand what that means.
    > @c ??? Where would you find that value?

    In the car or cdr of the return value from fringe-bitmaps-at-pos if
    there is no bitmap in left or right fringe.

It should use nil for that.
nil is the canonical Lisp way to say such a thing.

    If you specify an undefined fringe bitmap in a display property,
    e.g. using fringe bitmap number 100 and only 50 bitmaps are defined.
    Then the fringe will contain the undef-fringe-bitmap (a question-mark).

It would be better for this function to return the value you specified
and for display to ignore undefined bitmaps.

    > @c ??? Why not return a list of symbols that identify the bitmaps?
    > @c ??? This is Lisp, not C.

    Internally the bitmaps are represented and managed using integers
    (indexes), so there are no internal symbols defining bitmaps --- just
    like there are no internal symbols defining images.

    For simplicity, I chose to expose those integers as "opaque fringe
    bitmap numbers".  Using symbols would be a lot of extra work for no
    added functionality!

Just because the internals use integers is no reason to design the
Lisp-level interface that way.

The change to use symbols would only affect two functions:
define-fringe-bitmap and fringe-bitmaps-at-pos.  The symbol could
still have an integer as its value.  define-fringe-bitmap would record
the names of the symbols in a vector, indexed by the integer, and
fringe-bitmaps-at-pos would get the symbols out of that vector.

In addition, when the text property contains a symbol instead of the
now-expected integer, use the symbol's value.



Meanwhile, why does the code only support 255 different values?
That arbitrary limit is embarrassing.  What would it cost to get
rid of that limit?

Re: Comments on display.texi

[Kim F. Storm]

Richard Stallman <rms@gnu.org> writes:

>     The code uses the integer value (the bitmap number), so I didn't see
>     any reason to use a symbol here.
>
> The reason is, it is more Lisp-like to use symbols than numbers.
> It is easier to debug a program when you see a symbol whose name
> is meaningful than when you see a number.

But when you start debugging this, you don't see the symbol name --
you will see the number.  The display property contains the number,
not the symbol.  

.. Similar to how display image properties work.

>
>     It is the same for e.g. images -- you specify the image, not a symbol
>     identifying an image.
>
> Sorry, I don't understand.  When you say "you specify the image",
> what data type is that?

An image is a list like this:
   (image :type xpm :file "splash.xpm")

To insert an image, a text property like this is used:

   (propertize "*" 'display '(image :type xpm :file "splash.xpm"))


If you define the image like this:

   (defimage splash-image ((:type xpm :file "splash.xpm")
                           (:type xbm :file "splash.xbm")))

the result is to set the value of splash-image to

    (image :type xpm :file "/home/kfs/fsf/latest/etc/splash.xpm")

To use the splash-image in a display property, you do:

   (propertize "*" 'display splash-image)

NOT

   (propertize "*" 'display 'splash-image)


So when you debug involving an image, you don't see the symbol either,
only the value.

I followed this pattern for fringe bitmaps...

>
>     > @item Value indicating that no fringe bitmap is present:
>     > @code{no-fringe-bitmap}.
>     > @c ??? I don't understand what that means.
>     > @c ??? Where would you find that value?
>
>     In the car or cdr of the return value from fringe-bitmaps-at-pos if
>     there is no bitmap in left or right fringe.
>
> It should use nil for that.
> nil is the canonical Lisp way to say such a thing.

Ok.

>
>     If you specify an undefined fringe bitmap in a display property,
>     e.g. using fringe bitmap number 100 and only 50 bitmaps are defined.
>     Then the fringe will contain the undef-fringe-bitmap (a question-mark).
>
> It would be better for this function to return the value you specified
> and for display to ignore undefined bitmaps.

Ok.

>
>     > @c ??? Why not return a list of symbols that identify the bitmaps?
>     > @c ??? This is Lisp, not C.
>
>     Internally the bitmaps are represented and managed using integers
>     (indexes), so there are no internal symbols defining bitmaps --- just
>     like there are no internal symbols defining images.
>
>     For simplicity, I chose to expose those integers as "opaque fringe
>     bitmap numbers".  Using symbols would be a lot of extra work for no
>     added functionality!
>
> Just because the internals use integers is no reason to design the
> Lisp-level interface that way.

But it is EXACTLY the same interface that is used for images.
It is just the value that is different.

>
> The change to use symbols would only affect two functions:
> define-fringe-bitmap and fringe-bitmaps-at-pos.  The symbol could
> still have an integer as its value.  define-fringe-bitmap would record
> the names of the symbols in a vector, indexed by the integer, and
> fringe-bitmaps-at-pos would get the symbols out of that vector.
>
> In addition, when the text property contains a symbol instead of the
> now-expected integer, use the symbol's value.

So if you insist on this change, should I change the image code to
do the same -- ?

>
>
>
> Meanwhile, why does the code only support 255 different values?

I don't think any code will need to use more than a few bitmaps, so I
thought a total of 255 would be sufficient.

For 21.4, I think that only gdb-ui use a few bitmaps.

> That arbitrary limit is embarrassing.  What would it cost to get
> rid of that limit?
>

The limit is controlled by FRINGE_ID_BITS (currently 8) defined in
dispextern.h, so it is extremely easy to raise the limit to e.g. 1023
or 2047 bitmaps.

There is a static array of fringe bitmap pointers; it has one pointer
element for each possible bitmap index.  Raising the limit would just
cost a few KB.  

If you want to remove the limitation completely, we could let the
table grow dynamically.

But even faces have a limit of 21^2-1, so emacs is not without
arbitrary limits.

So there must be some limit -- which ?  2^32-1 ?

-- 
Kim F. Storm <storm@cua.dk> http://www.cua.dk

Re: Comments on display.texi

[Richard Stallman]

    > The reason is, it is more Lisp-like to use symbols than numbers.
    > It is easier to debug a program when you see a symbol whose name
    > is meaningful than when you see a number.

    But when you start debugging this, you don't see the symbol name --
    you will see the number.  The display property contains the number,
    not the symbol.  

Why can't the display property contain the symbol instead?
That's easy to implement.

    .. Similar to how display image properties work.

The image specifier is a list that describes the desired result.  That
is quite Lispy.  What's not good is to use an "opaque integer".

    But it is EXACTLY the same interface that is used for images.
    It is just the value that is different.

The value is the issue here.  If the value were a list or vector that
described the bitmap, it would be quite Lispy and I'd say it was good.

Re: Comments on display.texi

[Richard Stallman]

    But even faces have a limit of 21^2-1, so emacs is not without
    arbitrary limits.

    So there must be some limit -- which ?  2^32-1 ?

A limit of 2^21 would be ok, if it is painful to overcome.

Re: Comments on display.texi

[Kim F. Storm]

Richard Stallman <rms@gnu.org> writes:

>     > The reason is, it is more Lisp-like to use symbols than numbers.
>     > It is easier to debug a program when you see a symbol whose name
>     > is meaningful than when you see a number.
>
>     But when you start debugging this, you don't see the symbol name --
>     you will see the number.  The display property contains the number,
>     not the symbol.  
>
> Why can't the display property contain the symbol instead?
> That's easy to implement.
>
>     .. Similar to how display image properties work.
>
> The image specifier is a list that describes the desired result.  That
> is quite Lispy.  What's not good is to use an "opaque integer".
>
>     But it is EXACTLY the same interface that is used for images.
>     It is just the value that is different.
>
> The value is the issue here.  If the value were a list or vector that
> described the bitmap, it would be quite Lispy and I'd say it was good.

Ok, I'll change it so that the visible representation of a bitmap is
the symbol you provide with define-fringe-bitmap as you suggested.
And modify the rest of the fringe functions to work with symbols too.

I'll update the docs as well.

-- 
Kim F. Storm <storm@cua.dk> http://www.cua.dk

Re: Comments on display.texi

[Kim F. Storm]

Richard Stallman <rms@gnu.org> writes:

>     But even faces have a limit of 21^2-1, so emacs is not without
>     arbitrary limits.
>
>     So there must be some limit -- which ?  2^32-1 ?
>
> A limit of 2^21 would be ok, if it is painful to overcome.

Actually, the 2^21 limit on faces is because we want to reduce
memory usage for glyphs.

Each glyph struct contains a face id as well as a number of 1-bit
boolean fields.  There are 11 such 1-bit fields, so to keep these
together with the face id in 32 bits, the face id is 32-11 = 21 bits
wide.

Re. number of bitmaps:

I still have problems envisioning anybody using more than a few
bitmaps in any mode (ok, a mode which shows line numbers in 
the fringe would probably use a couple of 100s).

Currently, the only package using bitmaps is gdb-ui -- and it uses
just ONE.

IMO, for 21.4 a limit of 4095 would be more than adequate.

define-fringe-bitmap should signal an error if there are no free
bitmap slots.

There are several places in the code which uses a static allocation
based on the max number of bitmaps.  Of course they can be made
dynamic, but that would be unnecessary, we could agree on a limit of
4095 for 21.4.  WDYT?

-- 
Kim F. Storm <storm@cua.dk> http://www.cua.dk

Re: Comments on display.texi

[Richard Stallman]

    I still have problems envisioning anybody using more than a few
    bitmaps in any mode (ok, a mode which shows line numbers in 
    the fringe would probably use a couple of 100s).

    Currently, the only package using bitmaps is gdb-ui -- and it uses
    just ONE.

Where are bitmap indices stored?  How many places will Emacs try to
store them?

    There are several places in the code which uses a static allocation
    based on the max number of bitmaps.  Of course they can be made
    dynamic, but that would be unnecessary, we could agree on a limit of
    4095 for 21.4.  WDYT?

One of the GNU coding standards is to avoid fixed-allocated tables.
Why not malloc them?  You can start them at length 20 and realloc them
if they are ever exceeded.

Re: Comments on display.texi

[Kim F. Storm]

Richard Stallman <rms@gnu.org> writes:

> One of the GNU coding standards is to avoid fixed-allocated tables.
> Why not malloc them?  You can start them at length 20 and realloc them
> if they are ever exceeded.

I have now changed it to allocate the tables dynamically.

There is still a limit, but it is now at 64K bitmaps -- anybody
needing more than that must be doing something wrong :-)

-- 
Kim F. Storm <storm@cua.dk> http://www.cua.dk

Re: Comments on display.texi

[David Kastrup]

storm@cua.dk (Kim F. Storm) writes:

> Richard Stallman <rms@gnu.org> writes:
>
>> One of the GNU coding standards is to avoid fixed-allocated tables.
>> Why not malloc them?  You can start them at length 20 and realloc them
>> if they are ever exceeded.
>
> I have now changed it to allocate the tables dynamically.
>
> There is still a limit, but it is now at 64K bitmaps -- anybody
> needing more than that must be doing something wrong :-)

That's what everybody said until Unicode had to be extended to more
than 16bits.

Anyway, I suppose that it will probably keep people quiet for a while.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum