[HarfBuzz] Using HarfBuzz to get final glyphs

[Steve Mills]

On Mar 20, 2008, at 03:35:37, Pierre Marchand wrote:

> Because I would have been really disappointed to have missed an  
> example which
> would have saved me a lot of time, I just re-checked in a fresh  
> clone of the
> GIT repository. There is a test program for shaping and that’s it.

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. :)

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.

_________________________________________________________
Steve Mills                              Me: 952-401-6255
Senior Software Architect                         MultiAd
smills at multiad.com                       www.multi-ad.com