[Docs] Usermanual: integration chapter; add CoreText/Mac section.

docs/usermanual-integration.xml

@@ -303,13 +303,14 @@
   <section id="integration-uniscribe">
     <title>Uniscribe integration</title>
     <para>
-      If your client program is running on Windows, HarfBuzz can
+      If your client program is running on Windows, HarfBuzz offers
-      integrate with the Uniscribe engine.
+      an additional API that can help integrate with Microsoft's
+      Uniscribe engine and the Windows GDI.
     </para>
     <para>
       Overall, the Uniscribe API covers a broader set of typographic
       layout functions than HarfBuzz implements, but HarfBuzz's
-      shaping API can serve as a drop-in replacement for the shaping
+      shaping API can serve as a drop-in replacement for Uniscribe's shaping
       functionality. In fact, one of HarfBuzz's design goals is to
       accurately reproduce the same output for shaping a given text
       segment that Uniscribe produces &mdash; even to the point of
@@ -321,8 +322,9 @@
     <para>
       At a basic level, HarfBuzz's <function>hb_shape()</function>
       function replaces both the <ulink url=""><function>ScriptShape()</function></ulink>
-      and <ulink url="https://docs.microsoft.com/en-us/windows/desktop/api/Usp10/nf-usp10-scriptplace"><function>ScriptPlace()</function></ulink> functions from
+      and <ulink
-      Uniscribe. 
+      url="https://docs.microsoft.com/en-us/windows/desktop/api/Usp10/nf-usp10-scriptplace"><function>ScriptPlace()</function></ulink>
+      functions from Uniscribe. 
     </para>
     <para>
       However, whereas <function>ScriptShape()</function> returns the
@@ -363,10 +365,14 @@
       structure holds font-wide attributes, including metrics, size,
       and style information.
     </para>
-      
+<!--      
-SCRIPT_CACHE holds context, including LOGFONT      https://docs.microsoft.com/en-us/windows/desktop/Intl/script-cache
+     <para>
-      https://docs.microsoft.com/en-us/windows/desktop/api/wingdi/ns-wingdi-logfontw
+       In Uniscribe's model, the <type>SCRIPT_CACHE</type> holds the
-
+       device context, including the logical font that the shaping
+       functions apply.
+       https://docs.microsoft.com/en-us/windows/desktop/Intl/script-cache
+    </para>
+-->
     <para>
       The <function>hb_uniscribe_font_get_hfont()</function> function
       also takes a <type>hb_font_t</type> font object, but it returns
@@ -401,28 +407,93 @@ SCRIPT_CACHE holds context, including LOGFONT      https://docs.microsoft.com/en
   <section id="integration-coretext">
     <title>Core Text integration</title>
     <para>
-      
+      If your client program is running on macOS or iOS, HarfBuzz offers
+      an additional API that can help integrate with Apple's
+      Core Text engine and the underlying Core Graphics
+      framework. HarfBuzz does not attempt to offer the same
+      drop-in-replacement functionality for Core Text that it strives
+      for with Uniscribe on Windows, but you can still user HarfBuzz
+      to perform text shaping in native macOS and iOS applications.
     </para>
     <para>
-      
+      Note, though, that if your interest is just in using fonts that
+      contain Apple Advanced Typography (AAT) features, then you do
+      not need to add Core Text integration. HarfBuzz natively
+      supports AAT features and will shape AAT fonts (on any platform)
+      automatically, without requiring additional work on your
+      part. This includes support for AAT-specific TrueType tables
+      such as <literal>mort</literal>, <literal>morx</literal>, and
+      <literal>kerx</literal>, which AAT fonts use instead of
+      <literal>GSUB</literal> and <literal>GPOS</literal>.
     </para>
     <para>
-      
+      On a macOS or iOS system, the primary integration points offered
+      by HarfBuzz are for face objects and font objects. 
     </para>
     <para>
-      
+      The Apple APIs offer a pair of data structures that map well to
+      HarfBuzz's face and font objects. The Core Graphics API, which
+      is slightly lower-level than Core Text, provides
+      <ulink url="https://developer.apple.com/documentation/coregraphics/cgfontref"><type>CGFontRef</type></ulink>, which enables access to typeface
+      properties, but does not include size information. Core Text's
+      <ulink url="https://developer.apple.com/documentation/coretext/ctfont-q6r"><type>CTFontRef</type></ulink> is analagous to a HarfBuzz font object,
+      with all of the properties required to render text at a specific
+      size and configuration.
+      Consequently, a HarfBuzz <type>hb_font_t</type> font object can
+      be hooked up to a Core Text <type>CTFontRef</type>, and a HarfBuzz
+      <type>hb_face_t</type> face object can be hooked up to a
+      <type>CGFontRef</type>.
     </para>
     <para>
-      
+      You can create a <type>hb_face_t</type> from a
+      <type>CGFontRef</type> by using the
+      <function>hb_coretext_face_create()</function>. Subsequently,
+      you can retrieve the <type>CGFontRef</type> from a
+      <type>hb_face_t</type> with <function>hb_coretext_face_get_cg_font()</function>.
     </para>
     <para>
-      
+      Likewise, you create a <type>hb_font_t</type> from a
+      <type>CTFontRef</type> by calling
+      <function>hb_coretext_font_create()</function>, and you can
+      fetch the associated <type>CTFontRef</type> from a
+      <type>hb_font_t</type> font object with
+      <function>hb_coretext_face_get_ct_font()</function>. 
     </para>
     <para>
-      
+      HarfBuzz also offers a <function>hb_font_set_ptem()</function>
+      that you an use to set the nominal point size on any
+      <type>hb_font_t</type> font object. Core Text uses this value to
+      implement optical scaling. 
     </para>
     <para>
-      
+      When integrating your client code with Core Text, it is
+      important to recognize that Core Text <literal>points</literal>
+      are not typographic points (standardized at 72 per inch) as the
+      term is used elsewhere in OpenType. Instead, Core Text points
+      are CSS points, which are standardized at 96 per inch.
+    </para>
+    <para>
+      HarfBuzz's font functions take this distinction into account,
+      but it can be an easy detail to miss in cross-platform
+      code. 
+    </para>
+    <para>
+      As a final note, you may notice a reference to an optional
+      <literal>coretext</literal> shaper back-end in the <xref
+      linkend="configuration" /> section of the HarfBuzz manual. This
+      option is not a CoreText-integration facility.
+    </para>
+    <para>
+      Instead, it is a internal code path used in the
+      <command>hb-shape</command> command-line utility, which hands
+      shaping functionality over to CoreText entirely, when run on a
+      macOS system. That allows testing HarfBuzz's native output
+      against the CoreText engine, for tracking compatibility and debugging.
+    </para>
+    <para>
+      Because this back-end is only used when testing HarfBuzz
+      functionality, it is disabled by default when building the
+      HarfBuzz binaries.
     </para>
   </section>