composition text property

["Drew Adams" <drew.adams@oracle.com>]

>From the Elisp manual, node Special Properties, `composition':

     This text property is used to display a sequence of characters as a
     single glyph composed from components.  For instance, in Thai a
     base consonant is composed with the following combining vowel as a
     single glyph.  The value should be a character or a sequence
     (vector, list, or string) of integers.

        * If it is a character, it means to display that character
          instead of the text in the region.

        * If it is a string, it means to display that string's contents
          instead of the text in the region.

        * If it is a vector or list, the elements are characters
          interleaved with internal codes specifying how to compose the
          following character with the previous one.

I must be misunderstanding this - perhaps someone can explain. I try this:

(put-text-property
  (point) (1+ (point))
  'composition "Hi there!")

I expected to see "Hi there!" displayed in place of the character before
point ("display that strings contents instead of the text..."). Instead, I
see no visible change. `C-u C-x =' shows that the composition property was
applied. I also tried applying the property this way to several consecutive
characters (expecting to see "Hi there!" in place of each), but with no
visible change.

I also tried looking at Emacs source code that uses this property, but I
didn't find much, and what I found didn't enlighten me.

What am I missing? Thx.

BTW, should the text really be speaking of "the region" here? I tried with
and without an active region, with no visible change. I suspect that this
has nothing to do with the region, and I'd file a bug, but I don't yet
understand this text (obviously). Shouldn't "the region" be "the characters
with property `composition'"?

Also, the illustration of Thai doesn't help (me) much. How about a code
example, showing how `composition' can be used to compose a Thai consonant
and its following vowel, forming a single glyph?