(compose-region): Improve the docstring.

diff --git a/lisp/ChangeLog b/lisp/ChangeLog
index a90a46acb36e3569fadae8586916cfc911c4ba06..8068e0d72ebf6bfc1e29ea285b88b5a8f6c9b10f 100644 (file)
--- a/lisp/ChangeLog
+++ b/lisp/ChangeLog
@@ -1,3 +1,7 @@
+2009-06-16  Kenichi Handa  <handa@m17n.org>
+
+       * composite.el (compose-region): Improve the docstring.
+
 2009-06-15  Stefan Monnier  <monnier@iro.umontreal.ca>
 
        * vc.el (vc-default-revision-granularity): Remove to let the normal

diff --git a/lisp/composite.el b/lisp/composite.el
index ce34336cedec59143bf0cd0c24762a0b8d6054bb..77eea9cb4ecd4e50f3ee705e531a32cf0fb69f7d 100644 (file)
--- a/lisp/composite.el
+++ b/lisp/composite.el
@@ -185,8 +185,17 @@ RULE is a cons of global and new reference point symbols
 (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 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 value is not positive
+  (2) below BASE if Y's ascent value is not positive
+  (3) on BASE (i.e. at the BASE position) 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.