From fd270beedb331c4685e918f5a3ef5789a23ffaeb Mon Sep 17 00:00:00 2001
From: Nathan Willis <nwillis@glyphography.com>
Date: Fri, 28 Sep 2018 16:36:38 -0500
Subject: [PATCH] Docs: Usermanual- What is HarfBuzz; add intro to shaping
 concepts.

---
 docs/usermanual-what-is-harfbuzz.xml | 51 ++++++++++++++++++++++++++++
 1 file changed, 51 insertions(+)

diff --git a/docs/usermanual-what-is-harfbuzz.xml b/docs/usermanual-what-is-harfbuzz.xml
index 8ec7b4030..59df9e3f7 100644
--- a/docs/usermanual-what-is-harfbuzz.xml
+++ b/docs/usermanual-what-is-harfbuzz.xml
@@ -15,6 +15,57 @@
     platforms, and it supports all of the standard font formats in use
     today.
   </para>
+  <section id="what-is-text-shaping">
+    <title>What is text shaping?</title>
+    <para>
+      Text shaping is the process of translating a string of character
+      codes (such as Unicode codepoints) into a properly arranged
+      sequence of glyphs that can be rendered onto a screen or into
+      final output form for a document.
+    </para>
+    <para>
+      The shaping process is dependent on the input string, the active
+      font, the script (or writing system) that the string is in, and
+      the language that the string is in.
+    </para>
+    <para>
+      Modern software systems generally only deal with strings in the
+      Unicode encoding scheme (although legacy systems and documents may
+      involve other encodings).
+    </para>
+    <para>
+      There are several font formats that a program might
+      encounter, each of which has a set of standard text-shaping
+      rules.
+    </para>
+    <para>The dominant format is <ulink
+      url="http://www.microsoft.com/typography/otspec/">OpenType</ulink>. The
+    OpenType specification defines a series of <ulink url="https://github.com/n8willis/opentype-shaping-documents">shaping models</ulink> for
+    various scripts (including Indic, Arabic, Hangul, Hebrew, Khmer,
+    Myanmar, Thai and Lao, Tibetan, and a Universal Shaping Engine
+    designed to cover other scripts). These shaping models depend on
+    the font including certain features in its <literal>GSUB</literal>
+    and <literal>GPOS</literal> tables.
+    </para>
+    <para>
+      Alternatively, OpenType fonts can include shaping features for
+      the <ulink url="https://graphite.sil.org/">Graphite</ulink> shaping model.
+    </para>
+    <para>
+      TrueType fonts can also include OpenType shaping
+      features. Alternatively, TrueType fonts can also include <ulink url="https://developer.apple.com/fonts/TrueType-Reference-Manual/RM09/AppendixF.html">Apple
+      Advanced Typography</ulink> (AAT) tables to implement shaping
+      support. AAT fonts are generally only found on macOS systems.
+    </para>
+    <para>
+      Text strings will usually be tagged with a script and language
+      tag that provide the context for text shaping.  <ulink
+      url="https://docs.microsoft.com/en-us/typography/opentype/spec/scripttags">Script</ulink>
+      and <ulink
+      url="https://docs.microsoft.com/en-us/typography/opentype/spec/languagetags">language</ulink>
+      tags are defined by OpenType.
+    </para>
+  </section>
   <section id="why-do-i-need-a-shaping-engine">
     <title>Why do I need a shaping engine?</title>
     <para>