diff --git a/docs/usermanual-clusters.xml b/docs/usermanual-clusters.xml
index 4f2825c0b..545afde89 100644
--- a/docs/usermanual-clusters.xml
+++ b/docs/usermanual-clusters.xml
@@ -182,8 +182,7 @@
- Level 0 is the default and
- reproduces the behavior of the old HarfBuzz library.
+ Level 0 is the default.
The distinguishing feature of level 0 behavior is that, at
@@ -194,7 +193,7 @@
as well as the Zero Width Joiner and
Zero Width Non-Joiner code points, are
assigned the cluster value of the closest preceding code
- point from different category.
+ point from different category.
In essence, whenever a base character is followed by a mark
@@ -206,6 +205,11 @@
url="https://www.unicode.org/reports/tr29/#Regex_Definitions">Unicode
Technical Report 29.
+
+ This cluster level is suitable for code that likes to use
+ HarfBuzz cluster values as an approximation of the Unicode
+ Grapheme Cluster Boundaries as well.
+
Client programs can specify level 0 behavior for a buffer by
setting its cluster_level to
@@ -220,13 +224,13 @@
implement backward compatibility with the old HarfBuzz.
- Level 1 differs from level 0 by not merging the
+ Level 1 differs from level 0 by not merging the
clusters of marks and other modifier code points with the
preceding "base" code point's cluster. By preserving the
separate cluster values of these marks and modifier code
points, script shapers can perform additional operations
- that might lead to improved results (for example, reordering
- a sequence of marks).
+ that might lead to improved results (for example, coloring
+ mark glyphs differently than their base).
Client programs can specify level 1 behavior for a buffer by
@@ -242,7 +246,7 @@
This difference can be seen most clearly when HarfBuzz processes
- ligature substitutions and glyph decompositions. In level 0
+ ligature substitutions and glyph decompositions. In level 0
and level 1, ligatures and glyph decomposition both involve
merging clusters; in level 2, neither of these operations
triggers a merge.
@@ -259,7 +263,7 @@
assign initial cluster values in a buffer by reusing the indices
of the code points in the input text. This gives a sequence of
cluster values that is monotonically increasing (for example,
- 0,1,2,3,4).
+ 0,1,2,3,4).
It is not required that the cluster values
@@ -314,7 +318,7 @@
-
+
A clustering example for levels 0 and 1