Emacs Lisp manual issues regarding overlays, display properties, margins, etc.

[Joe Wells <jbw@macs.hw.ac.uk>]

I have some issues with the Emacs Lisp manual's coverage of
overlays, display properties, margins, etc.  In the issues I
raise below, I'll assume this macro:

  (defmacro test-overlays (&rest body)
    `(let ((buf (get-buffer-create "xyzzy")))
      (with-current-buffer buf
        (display-buffer buf)
        (erase-buffer)
        (dolist (o (overlays-in (point-min) (point-max)))
          (delete-overlay o))
        ,@body)))

Issue 1:  The “height” display specification seems not to work at
all.  For example, in the following the B is not larger:

  (test-overlays
   (insert "ABC")
   (let ((o (make-overlay 2 3)))
     (overlay-put o 'display '(height 2))))

This seems to be a bug.  But perhaps merely the documentation is
wrong.  Can someone please check?

Issue 2:  RMS recently clarified the text in the “Display
Property” manual node (in the Emacs 22 CVS branch) to read like
this:

  The value of the @code{display} property should be a display
  specification, or a list or vector containing several display
  specifications.  Display specifications generally apply in parallel to
  the text they cover.

    Some kinds of @code{display} specifications specify something to
  display instead of the text that has the property.  If a list of
  display specifications includes more than one of this kind, the first
  is effective and the rest are ignored.

When it says that “display specifications generally apply in
parallel to the text they cover”, is that supposed to include
display properties of multiple overlays covering the same text?
For example, this works:

  (test-overlays
   (insert "A B C\nD E F")
   (let ((o1 (make-overlay 2 5)))
     (overlay-put o1 'display '((space-width 3) (raise 0.5)))))

In contrast, in the following, the display property of overlay o1
is completely ignored:

  (test-overlays
   (insert "A B C\nD E F")
   (let ((o1 (make-overlay 2 5))
         (o2 (make-overlay 2 5)))
     (overlay-put o2 'priority 1)
     (overlay-put o1 'display '(space-width 3))
     (overlay-put o2 'display '(raise 0.5))))

So “display specifications generally apply in parallel to the
text they cover” probably deserves a clarification to point out
that only the display specifications in one display property can
cover a piece of text.

Issue 3:  Does “display specifications generally apply in
parallel to the text they cover” mean that if one display spec
specifies a replacement, then the other display specs in parallel
with it cover it?  It seems not, because the Z in this is not
raised:

  (test-overlays
   (insert "ABC")
   (let ((o1 (make-overlay 2 3)))
     (overlay-put o1 'display '((raise 0.5) "Z"))))

Similarly, the space in "Y Z" in this is not wider:

  (test-overlays
   (insert "ABC")
   (let ((o1 (make-overlay 2 3)))
     (overlay-put o1 'display '((space-width 8) "Y Z"))))

So it would be helpful to clarify that a display spec never
covers replacement text in another display spec parallel to it.

Issue 4:  What does “display specifications generally apply in
parallel to the text they cover” mean in the presence of two
“slice” display specs?  I'm guessing there should be a
clarification here to specify that the leftmost one wins.  Am I
right?

Issue 5:  The “Display Margins” manual node says:

     To put text in the left or right display margin of the window, use a
  display specification of the form `(margin right-margin)' or `(margin
  left-margin)' on it.

However, this doesn't put anything in the margin:

  (test-overlays
   (insert "ABC")
   (let ((o1 (make-overlay 2 3)))
     (overlay-put o1 'display '(margin left-margin)))
   (set-window-margins (get-buffer-window (current-buffer)) 8))

As far as I can tell, (margin MARGIN) is not actually a valid
display spec, but only part of a display spec when in the
form ((margin MARGIN) SPEC) where SPEC must be a display spec
that replaces the covered text.  For example, this works:

  (test-overlays
   (insert "ABC")
   (let ((o1 (make-overlay 2 3)))
     (overlay-put o1 'display '((margin left-margin) "Z")))
   (set-window-margins (get-buffer-window (current-buffer)) 8))

But this doesn't put anything in the margin:

  (test-overlays
   (insert "ABC")
   (let ((o1 (make-overlay 2 3)))
     (overlay-put o1 'display '("Z" (margin left-margin))))
   (set-window-margins (get-buffer-window (current-buffer)) 8))

Can someone please check what the C code actually does and
clarify/correct this part of the manual accordingly?

Issue 6:  The “Overlay Properties” manual node says this on
overlay priorities:

  `priority'
       This property's value (which should be a nonnegative integer
       number) determines the priority of the overlay.  The priority
       matters when two or more overlays cover the same character and
       both specify the same property; the one whose `priority' value is
       larger takes priority over the other.  For the `face' property, ...

So what is the relative priority of an overlay which has a
nonnegative integer value of its priority property, and one which
has no priority property at all?  It seems that nil is below 0:

  (test-overlays
   (insert "ABC")
   (let ((o1 (make-overlay 2 3))
         (o2 (make-overlay 2 3)))
     (overlay-put o1 'display "123")
     (overlay-put o2 'priority 0)
     (overlay-put o2 'display "abc")))

This could beneficially be detailed in the manual.

I hope the points I made above can help in clarifying the manual (and
maybe fixing a bug in the “height” display specs).

Joe

======================================================================
In GNU Emacs 22.1.1 (i686-pc-linux-gnu, GTK+ Version 2.8.20)
 of 2007-06-27 on artemis
Windowing system distributor `The X.Org Foundation', version 11.0.70000000
configured using `configure  '--prefix=/home/jbw/local2' '--enable-debug' '--disable-nls' '--with-x-toolkit=gtk' 'CFLAGS=-O0 -g3 -ggdb''

Important settings:
  value of $LC_ALL: nil
  value of $LC_COLLATE: nil
  value of $LC_CTYPE: en_US.UTF-8
  value of $LC_MESSAGES: nil
  value of $LC_MONETARY: nil
  value of $LC_NUMERIC: nil
  value of $LC_TIME: jbw
  value of $LANG: nil
  locale-coding-system: utf-8
  default-enable-multibyte-characters: t

Minor modes in effect:
  mml-mode: t
  flyspell-mode: t
  TeX-source-specials-mode: t
  desktop-save-mode: t
  url-handler-mode: t
  tooltip-mode: t
  mouse-wheel-mode: t
  file-name-shadow-mode: t
  global-font-lock-mode: t
  font-lock-mode: t
  blink-cursor-mode: t
  unify-8859-on-encoding-mode: t
  utf-translate-cjk-mode: t
  auto-compression-mode: t
  temp-buffer-resize-mode: t
  size-indication-mode: t
  line-number-mode: t
  transient-mark-mode: t
  abbrev-mode: t