bug#3564: 23.0.94; compose-region doc string

bug#3564: 23.0.94; compose-region doc string

[Drew Adams]

1. Typo: "stricking" -> "striking".
 
2. Please add an explanation of what "overstriking" and "stacking"
mean.
 

In GNU Emacs 23.0.94.1 (i386-mingw-nt5.1.2600)
 of 2009-05-24 on SOFT-MJASON
Windowing system distributor `Microsoft Corp.', version 5.1.2600
configured using `configure --with-gcc (3.4)'
 

bug#3564: 23.0.94; compose-region doc string

[Kenichi Handa]

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

> 1. Typo: "stricking" -> "striking".
> 2. Please add an explanation of what "overstriking" and "stacking"
> mean.
 
How about this change?

--- composite.el.~1.47.~	2009-06-08 20:48:58.000000000 +0900
+++ composite.el	2009-06-15 15:39:21.000000000 +0900
@@ -185,8 +185,17 @@
 (defun compose-region (start end &optional components modification-func)
   "Compose characters in the current region.
 
-Characters are composed relatively, i.e. composed by overstricking or
-stacking depending on ascent, descent and other properties.
+Characters are composed relatively, i.e. composed by overstriking
+or stacking depending on ascent, descent and other metrics values
+of glyphs.
+
+For instance, if the region has three characters \"XYZ\", X is
+regarded as BASE glyph, and Y is displayed:
+  (1) above BASE if Y's descent is not positive,
+  (2) below BASE if Y's ascent is not positive,
+  (3) over BASE (at the same position of BASE) otherwise.
+and Z is displayed with the same rule while regarding the whole
+XY glyphs as BASE.
 
 When called from a program, expects these four arguments.
 
---
Kenichi Handa
handa@m17n.org

bug#3564: 23.0.94; compose-region doc string

[Drew Adams]

That helps a lot; thanks.

See inline for English suggestions. But I'm ignorant of this area, so hopefully
someone else will speak to the correct terminology to use - I don't know it.

> From: Kenichi Handa Sent: Sunday, June 14, 2009 11:43 PM
> +Characters are composed relatively, i.e. composed by overstriking
> +or stacking depending on ascent, descent and other metrics values
> +of glyphs.

"other metrics" or "other metric values"

> +For instance, if the region has three characters \"XYZ\", X is
> +regarded as BASE glyph, and Y is displayed:
> +  (1) above BASE if Y's descent is not positive,
> +  (2) below BASE if Y's ascent is not positive,

I wonder if "descent" and "ascent" shouldn't be "descender" and "ascender" or
something like that? Need to check with someone who knows typography
terminology, unless you're sure about "descent" and "ascent".

> +  (3) over BASE (at the same position of BASE) otherwise.

"on BASE" or "at BASE" or "on top of BASE" or "at the BASE position"

> +and Z is displayed with the same rule while regarding the whole
> +XY glyphs as BASE.
>  
>  When called from a program, expects these four arguments.

Sounds good. Without that, I understood nothing. Now, I understand a little.
Thx.

bug#3564: 23.0.94; compose-region doc string

[Kenichi Handa]

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

> > +For instance, if the region has three characters \"XYZ\", X is
> > +regarded as BASE glyph, and Y is displayed:
> > +  (1) above BASE if Y's descent is not positive,
> > +  (2) below BASE if Y's ascent is not positive,

> I wonder if "descent" and "ascent" shouldn't be "descender" and "ascender" or
> something like that? Need to check with someone who knows typography
> terminology, unless you're sure about "descent" and "ascent".

"descent" and "ascent" are commonly used term in glyph
metrics.  I added "value" after them for clarification.

I've just committed the change while reflecting your other
comments.

---
Kenichi Handa
handa@m17n.org