display property as display spec vector behavior unclear

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

The documentation in the Emacs Lisp manual on the display property
states this:

  The value of the `display' property should be a display
  specification, or a list or vector containing several display
  specifications.

Unfortunately, this is the only thing it states about the case where
the display property is a list or vector of display specs.
I searched for all occurrences of the words “list” and “vector” in
that section of the manual and could not find more precise details.

I would guess from the above description that if the display property
were a vector of display specs, then all of the things specified to be
displayed would be shown from left to right.  However, it seems that
only the first one is used, which seems strange.

Reproduce by evaluating this code:

  (let ((buf (get-buffer-create "foo")))
    (with-current-buffer buf
      (display-buffer buf)
      (erase-buffer)
      (dolist (o (overlays-in (point-min) (point-max)))
        (delete-overlay o))
      (insert "ABC")
      (let ((o (make-overlay 2 3)))
        (overlay-put o 'display ["1" "2" "3"]))))

You will see the “foo” window pop up and in the window you will see
“A1C”.  I expected that instead “A123C” would be shown.

If this is a documentation bug, could the documentation please be
clarified?  If this is a code bug, could the code please be fixed?

By the way, the code in handle_display_prop in xdisp.c does explicitly
loop over all of the elements of the vector.  So the code is going to
the effort to do something with all of them, although only the work
from the first one is currently showing up.

Also by the way, it would be *extremely* useful if all of the display
specifications in a vector were shown.  I'm trying to make the
features of AUCTeX's tex-fold.el work together with latex-preview, and
if a vector of display specs were all shown this would make things
really easy.

Thanks for your time in considering this issue.

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

Major mode: Lisp Interaction

Minor modes in effect:
  TeX-source-specials-mode: t
  auto-fill-function: do-auto-fill
  shell-dirtrack-mode: t
  outline-minor-mode: t
  desktop-save-mode: t
  url-handler-mode: t
  tooltip-mode: t
  mouse-wheel-mode: t
  menu-bar-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