composition text property

composition text property

[Drew Adams]

>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?

RE: composition text property

[Drew Adams]

Trying again - got no reply. Anybody know about the `composition' property?
Thx.

> From: Drew Adams Sent: Wednesday, May 30, 2007 9:09 AM
> 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?

Re: composition text property

[Kenichi Handa]

In article <EIENLHALHGIMHGDOLMIMOEPADCAA.drew.adams@oracle.com>, "Drew Adams" <drew.adams@oracle.com> writes:

> Trying again - got no reply. Anybody know about the `composition' property?

Sorry for not responding.  I've thought that I already
replied, but it was in the different thread.

> > From: Drew Adams Sent: Wednesday, May 30, 2007 9:09 AM
> > 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.

In the thread of "Crash using text property 'composite on
w32", I wrote:

> Yes.  The above description is for the argument COMPONENTS
> of the function `compose-region', or for just a part of the
> property value.  The value has this form:
> 
>    The property value has this form when the composition is made:
> 	((LENGTH . COMPONENTS) . MODIFICATION-FUNC)
>    then turns to this form:
> 	(COMPOSITION-ID . (LENGTH COMPONENTS-VEC . MODIFICATION-FUNC))
>    when the composition is registered in composition_hash_table and
>    composition_table.  These rather peculiar structures were designed
>    to make it easy to distinguish them quickly (we can do that by
>    checking only the first element) and to extract LENGTH (from the
>    former form) and COMPOSITION-ID (from the latter form).
>    [...]
> 
> The detail is described in the header comment of
> src/composite.c.  How much detail, do you think, we should
> describe in Info?
> 
> Isn't it enough to say just as below?
> 
> The value should be a cons of special structure.  It should
> be manipulated only by the functions `compose-region',
> `compose-string' and `find-composition'.

So,

> > I must be misunderstanding this - perhaps someone can explain. I try this:
> >
> > (put-text-property
> >   (point) (1+ (point))
> >   'composition "Hi there!")
> >

This must be:
 (compose-region (point) (1+ (point))
 '(H? (Br . Bl) ?i (Br . Bl) ?\s (Br . Bl) ........."))

But in this case, you should simply use display property.

> > 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?

Composition is not a text property to play around by direct
manipulation.  It is more internal to Emacs, and only text
layouting program (e.g. thai-composition-function,
tibetan-composition-function) should use.

I'll improve the documentaion soon.

---
Kenichi Handa
handa@m17n.org

RE: composition text property

[Drew Adams]

Thanks for that explanation, and for offering to clean up the doc.

Perhaps, if this is meant for internal use only, it should not even be
mentioned in the doc? If it is mentioned, and if you need to use
`compose-region' to make use of it, then that should be mentioned too, and
perhaps a short example such as you provided. Again, however, this sounds
like something that we should perhaps not document at all.