<div dir="ltr"><div dir="ltr"><div dir="ltr"><div>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....</div><div><br></div><div>1) The opening sentence says "a cluster is a sequence of code points [...]"</div><div> ...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....</div><div><br></div><div>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)? <br></div><div><br></div><div>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."</div><div><br></div><div> ... 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?</div><div><br></div><div>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?</div><div><br></div><div>Thanks,</div><div>Nate<br>-- <br><div dir="ltr" class="gmail_signature"><div dir="ltr">nathan.p.willis<br><a href="mailto:nwillis@glyphography.com" target="_blank">nwillis@glyphography.com</a><a href="http://identi.ca/n8" target="_blank"></a></div></div></div></div></div></div>