[HarfBuzz] Clusters chapter

[Nathan Willis]

Hiyo. I'm revisiting the 'clusters' chapter in the User Manual, to make it
more consistent with the rest and hopefully easier to understand. Rereading
it has raised some questions....

1) The opening sentence says "a cluster is a sequence of code points [...]"
 ...which might be true for the initial buffer contents, but all the
interesting stuff happens after replacing them with glyphs. So that will
certainly need some changing. I know it's a can of worms to open, but what
if we said "characters" here? Explaining the relationship between code
points, characters, and glyphs can be tricky, but then again explaining
clusters to new readers is already difficult....

2) "Most clients will use UTF-8, UTF-16, or UTF-32 indices, but the actual
number does not matter" ... is "indices" here referring to the buffer
contents (code points)?

3) "Moreover, it is not required for the cluster values to be monotonically
increasing. Most of HarfBuzz's tests are performed on monotonically
increasing cluster numbers but, there is no such assumption in the code
itself."

... This is the big one. The examples that follow in subsequent subsections
hinge on the fact that the cluster values need to be monotonically
increasing. Keeping them monotonic & increasing is given as the reason that
clusters get merged when reordering (levels 0 and 1). So this sentence
sticks out. I'm not sure how to resolve that discrepancy; can anyone
explain how both of those pieces are supposed to fit together?

Finally, I am adding a short "why your software cares about clusters"
paragraph to the beginning. I've got cursor positioning, coloring
diacritics, and line breaking in mind; anything else worth mentioning?

Thanks,
Nate
-- 
nathan.p.willis
nwillis at glyphography.com <http://identi.ca/n8>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.freedesktop.org/archives/harfbuzz/attachments/20181102/8b22b7ce/attachment.html>