[HarfBuzz] Duffer's guide

[Behdad Esfahbod]

Hi Simon,

I have had this guide of yours in my TODO list to review:

  http://www.simon-cozens.org/content/duffers-guide-fontconfig-and-harfbuzz

Of course back then when you posted it I didn't know you or Sile.  Small world
though.  Thanks for working on documentation!

Here's some feedback:

- Instead of these:

  FcPatternAddString (p, FC_FAMILY,(FcChar8*) "Times-Roman");
  FcPatternAddString (p, FC_FAMILY,(FcChar8*) "Times");
  FcPatternAddString (p, FC_FAMILY,(FcChar8*) "Helvetica");

would be enough to add "serif" or "sans" or both, etc.  If you don't specify
any of "serif", "sans", "monospace", etc, fontconfig will add "sans" for you.

- In your get_font_path() function, you just return the font file.  That's not
sufficient.  You also need to return the FC_INDEX, otherwise you can't address
faces in a collection (TTC, etc) other than the first face.

- For converting from FC_WEIGHT values to OpenType weight values and back, I
recently added FcWeightFromOpenType() and FcWeightToOpenType().

- You probably know by now, but the sentence "Except—Harfbuzz expects that
fonts come from Freetype" isn't really accurate.  That's what hb-ft requires.
 You can create a blob and create a hb_face_t from it, and these days, install
the ot-funcs and mostly be good to go...  In a few weeks we should switch to
advertising that as the preferred way to use HarfBuzz unless one explicitly
wants to use it with FreeType.

- Here:

 if (f.direction)
      hb_buffer_set_direction(buf, f.direction);

if you don't set direction, HarfBuzz will abort().  That's one property that
MUST be set on the buffer.  You can also call
hb_buffer_guess_segment_properties().  But I see you already included that in
your new user docs for HarfBuzz.  Thanks!

- Here:

    hb_buffer_add_utf8(buf, text, strlen(text), 0, strlen(text));

you can pass -1 instead of strlen(text).

- "from 0 to glyph_count." should probably say (glyph_count-1).

- "If you need height and depth information for the glyph, then you need to go
back to Freetype and ask it", might want to replace with
hb_font_glyph_extents() version for uniformity.

Cheers,
-- 
behdad
http://behdad.org/