[HarfBuzz] Using HarfBuzz to get final glyphs

[Ed Trager]

Hi, Steve,

On Thu, Mar 20, 2008 at 10:26 AM, Steve Mills <smills at multi-ad.com> wrote:
>
> Can someone explain what "shaping" means in HarfBuzz nomenclature?
> It's not obvious to me by looking at shaper.h, which has a bunch of
> script constants, some word/sentence boundary routines, a bunch of
> structs, and one function for shaping something. :)
>

Take for example the image that appears at the top of the HarfBuzz wiki page:

http://freedesktop.org/wiki/Software/HarfBuzz?action=AttachFile&do=get&target=HarfBuzz.png

This image shows the rendering of the word "HarfBuzz" in Arabic
script.  Starting from the right side, note that the HEH and REH are
connected together.  This requires using the initial form of HEH
followed by the final form of REH.  Then the 3rd letter, FEH, is not
connected but is instead shown in isolated form because the REH in
Arabic script does not join to letters on its left.  So we have
HEH--REH--FEH which is pronounced "harf".  Then after this we see the
initial form of BEH followed by ALIF and finally by ZAIN, giving the
pronounciation "baaz".  Carrying out all of the rules for joining or
non-joining of letters, the replacement of certain letters with
ligated forms, the rendering of a script in the correct direction
(right-to-left for Arabic) and similar functionality all fall under
the umbrella of "shaping".

> As for Ed's nice comment about usage and documentation, even putting
> an explanation at the top of each file helps people understand the
> structure of a library such as this. Pango has a simple 1-line
> description at the top of most files, and that helps. But what
> developers like myself really want is documentation that explains how
> to use the library from a very high level, but then goes deeper if
> lower-level access is needed. Ideally, it would be a mix of
> explanations and code samples. Something like:
>
> Using HarfBuzz is easy. If you want to render some text, here's how:
>
>        HBRenderMeSomeText(text, something);
>
>        This function does stuff by doing stuff.
>
> If you only need to generate glyphs for some text with OpenType glyph
> substitution, it's a piece of pie [sic]:
>
>        HBGenerateGlyphsFromTextWithFeatures(text, font, kHBSwashes |
> kHBLigatures, returnGlyphsHere);
>
>        This function generates glyphs for the given text based on the
> features allowed by the user. The features are only available for
> OpenType fonts. Blah blah blah…
>
> At one point we realized that the C++ classes we'd created for sending
> and receiving Apple Events could be very useful to other developers
> who don't have time to learn everything about Apple Events. So we
> packaged them up into a library for sale. I went through wrote up some
> docs, then passed the entire package to another developer who'd never
> done any AE work to see if he could successfully use our library
> without confusion. If he had any question, I enhanced the docs in that
> area. Repeat until he could do an assigned task with our lib without
> asking any questions. Then we knew it was well documented and would be
> *easily* and *happily* used by many developers.
>
> But like Ed said, maybe HarfBuzz's use by a wider audience was not
> expected, or even wanted. If so, it should be stated on the site so
> developers such as I don't waste time trying to figure it out, only to
> find that it won't do what we want.
>

Even if one is very lazy about writing documentation, running the code
through DOxygen and putting the resulting HTML output on the web makes
it much faster for users to drill down to what they want.

I was very lazy about writing DOxygen comments in our Madeline
project, but no worries because the DOxygen-generated documentation
speaks for itself (http://eyegene.ophthy.med.umich.edu/madeline/api/).
 So at the very least HarfBuzz should get some DOxygen documentation
up there.

Its a bit ironic for me : our Madeline project caters to only a small
audience of researchers in genetics, and yet we spent a large amount
of time preparing all kinds of documentation: build documentation, API
documentation, comparison of our software to competing software, test
cases and sample data files, and even an online web-based demo
application that calls the command-line C++ program running on the
server (see http://eyegene.ophthy.med.umich.edu/madeline/).  HarfBuzz
appeals to a much, much larger audience, and is already used
indirectly by many many times more people.  But there is essentially
no documentation.  Well, maybe our little Madeline project can serve
as an example of how it should be done?

Best - Ed