[HarfBuzz] harfbuzz: Branch 'master' - 27 commits
Behdad Esfahbod
behdad at kemper.freedesktop.org
Tue Oct 30 20:16:39 UTC 2018
docs/Makefile.am | 11
docs/harfbuzz-docs.xml | 68 -
docs/usermanual-buffers-language-script-and-direction.xml | 8
docs/usermanual-clusters.xml | 6
docs/usermanual-fonts-and-faces.xml | 8
docs/usermanual-getting-started.xml | 222 ++++
docs/usermanual-glyph-information.xml | 8
docs/usermanual-hello-harfbuzz.xml | 183 ---
docs/usermanual-install-harfbuzz.xml | 443 ++++++++-
docs/usermanual-opentype-features.xml | 8
docs/usermanual-shaping-concepts.xml | 374 +++++++
docs/usermanual-what-is-harfbuzz.xml | 474 ++++++++--
src/hb-ot-color-cbdt-table.hh | 67 -
src/hb-ot-color-sbix-table.hh | 3
test/fuzzing/fonts/clusterfuzz-testcase-minimized-hb-shape-fuzzer-5768601332613120 |binary
15 files changed, 1531 insertions(+), 352 deletions(-)
New commits:
commit dc9bd29feac6675c79343b88a06f03f356f9175b
Author: Behdad Esfahbod <behdad at behdad.org>
Date: Tue Oct 30 13:16:07 2018 -0700
[CBDT] Implement Format18 get_extens
Part of https://github.com/harfbuzz/harfbuzz/issues/1327
diff --git a/src/hb-ot-color-cbdt-table.hh b/src/hb-ot-color-cbdt-table.hh
index f1b1196b..614cc80c 100644
--- a/src/hb-ot-color-cbdt-table.hh
+++ b/src/hb-ot-color-cbdt-table.hh
@@ -437,8 +437,16 @@ struct CBDT
const GlyphBitmapDataFormat17& glyphFormat17 =
StructAtOffset<GlyphBitmapDataFormat17> (this->cbdt, image_offset);
glyphFormat17.glyphMetrics.get_extents (extents);
+ break;
+ }
+ case 18: {
+ if (unlikely (image_length < GlyphBitmapDataFormat18::min_size))
+ return false;
+ const GlyphBitmapDataFormat18& glyphFormat18 =
+ StructAtOffset<GlyphBitmapDataFormat18> (this->cbdt, image_offset);
+ glyphFormat18.glyphMetrics.get_extents (extents);
+ break;
}
- break;
default:
// TODO: Support other image formats.
return false;
commit a2a7422aaf47dd43c2c55ad48dd15513f9d5b081
Author: Behdad Esfahbod <behdad at behdad.org>
Date: Tue Oct 30 13:14:56 2018 -0700
[CBDT] Bound checks in reference_png
diff --git a/src/hb-ot-color-cbdt-table.hh b/src/hb-ot-color-cbdt-table.hh
index ae6d3b5e..f1b1196b 100644
--- a/src/hb-ot-color-cbdt-table.hh
+++ b/src/hb-ot-color-cbdt-table.hh
@@ -434,7 +434,6 @@ struct CBDT
case 17: {
if (unlikely (image_length < GlyphBitmapDataFormat17::min_size))
return false;
-
const GlyphBitmapDataFormat17& glyphFormat17 =
StructAtOffset<GlyphBitmapDataFormat17> (this->cbdt, image_offset);
glyphFormat17.glyphMetrics.get_extents (extents);
@@ -473,30 +472,42 @@ struct CBDT
if (!subtable_record->get_image_data (glyph, base, &image_offset, &image_length, &image_format))
return hb_blob_get_empty ();
- switch (image_format)
{
- case 17: {
- const GlyphBitmapDataFormat17& glyphFormat17 =
- StructAtOffset<GlyphBitmapDataFormat17> (this->cbdt, image_offset);
- return hb_blob_create_sub_blob (cbdt_blob,
- image_offset + GlyphBitmapDataFormat17::min_size,
- glyphFormat17.data.len);
- }
- case 18: {
- const GlyphBitmapDataFormat18& glyphFormat18 =
- StructAtOffset<GlyphBitmapDataFormat18> (this->cbdt, image_offset);
- return hb_blob_create_sub_blob (cbdt_blob,
- image_offset + GlyphBitmapDataFormat18::min_size,
- glyphFormat18.data.len);
- }
- case 19: {
- const GlyphBitmapDataFormat19& glyphFormat19 =
- StructAtOffset<GlyphBitmapDataFormat19> (this->cbdt, image_offset);
- return hb_blob_create_sub_blob (cbdt_blob,
- image_offset + GlyphBitmapDataFormat19::min_size,
- glyphFormat19.data.len);
- }
+ if (unlikely (image_offset > cbdt_len || cbdt_len - image_offset < image_length))
+ return hb_blob_get_empty ();
+
+ switch (image_format)
+ {
+ case 17: {
+ if (unlikely (image_length < GlyphBitmapDataFormat17::min_size))
+ return hb_blob_get_empty ();
+ const GlyphBitmapDataFormat17& glyphFormat17 =
+ StructAtOffset<GlyphBitmapDataFormat17> (this->cbdt, image_offset);
+ return hb_blob_create_sub_blob (cbdt_blob,
+ image_offset + GlyphBitmapDataFormat17::min_size,
+ glyphFormat17.data.len);
+ }
+ case 18: {
+ if (unlikely (image_length < GlyphBitmapDataFormat18::min_size))
+ return hb_blob_get_empty ();
+ const GlyphBitmapDataFormat18& glyphFormat18 =
+ StructAtOffset<GlyphBitmapDataFormat18> (this->cbdt, image_offset);
+ return hb_blob_create_sub_blob (cbdt_blob,
+ image_offset + GlyphBitmapDataFormat18::min_size,
+ glyphFormat18.data.len);
+ }
+ case 19: {
+ if (unlikely (image_length < GlyphBitmapDataFormat19::min_size))
+ return hb_blob_get_empty ();
+ const GlyphBitmapDataFormat19& glyphFormat19 =
+ StructAtOffset<GlyphBitmapDataFormat19> (this->cbdt, image_offset);
+ return hb_blob_create_sub_blob (cbdt_blob,
+ image_offset + GlyphBitmapDataFormat19::min_size,
+ glyphFormat19.data.len);
+ }
+ }
}
+
return hb_blob_get_empty ();
}
commit f236f790884d7b5c7afb73768724c360d4ea5212
Author: Nathan Willis <nwillis at glyphography.com>
Date: Tue Oct 30 11:24:56 2018 -0500
Docs Makefile: sync SGML list to harfbuzz-docs.xml include list. Hopefully fixes distcheck failure.
diff --git a/docs/Makefile.am b/docs/Makefile.am
index 595dd83e..9b54b40e 100644
--- a/docs/Makefile.am
+++ b/docs/Makefile.am
@@ -72,14 +72,15 @@ HTML_IMAGES= \
# Extra SGML files that are included by $(DOC_MAIN_SGML_FILE).
# e.g. content_files=running.sgml building.sgml changes-2.0.sgml
content_files= \
+ usermanual-what-is-harfbuzz.xml \
+ usermanual-install-harfbuzz.xml \
+ usermanual-getting-started.xml \
+ usermanual-shaping-concepts.xml \
usermanual-buffers-language-script-and-direction.xml \
- usermanual-clusters.xml \
usermanual-fonts-and-faces.xml \
- usermanual-glyph-information.xml \
- usermanual-getting-started.xml \
- usermanual-install-harfbuzz.xml \
+ usermanual-clusters.xml \
usermanual-opentype-features.xml \
- usermanual-what-is-harfbuzz.xml \
+ usermanual-glyph-information.xml \
version.xml
# SGML files where gtk-doc abbrevations (#GtkWidget) are expanded
commit 9f4b375e396fe65b30c792b9524a732da0b477d1
Author: Nathan Willis <nwillis at glyphography.com>
Date: Mon Oct 29 17:10:53 2018 -0500
Usermanual: minor wording updates, build fixes.
diff --git a/docs/usermanual-buffers-language-script-and-direction.xml b/docs/usermanual-buffers-language-script-and-direction.xml
index 9eddb71a..68ce9bd0 100644
--- a/docs/usermanual-buffers-language-script-and-direction.xml
+++ b/docs/usermanual-buffers-language-script-and-direction.xml
@@ -1,3 +1,9 @@
+<?xml version="1.0"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+ "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
+ <!ENTITY % local.common.attrib "xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'">
+ <!ENTITY version SYSTEM "version.xml">
+]>
<chapter id="buffers-language-script-and-direction">
<title>Buffers, language, script and direction</title>
<para>
@@ -74,4 +80,4 @@ void somefunc(hb_buffer_t *buffer) {
<para>
</para>
</section>
-</chapter>
\ No newline at end of file
+</chapter>
diff --git a/docs/usermanual-clusters.xml b/docs/usermanual-clusters.xml
index 608371b0..7b2c7adc 100644
--- a/docs/usermanual-clusters.xml
+++ b/docs/usermanual-clusters.xml
@@ -1,3 +1,9 @@
+<?xml version="1.0"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+ "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
+ <!ENTITY % local.common.attrib "xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'">
+ <!ENTITY version SYSTEM "version.xml">
+]>
<chapter id="clusters">
<sect1 id="clusters">
<title>Clusters</title>
diff --git a/docs/usermanual-fonts-and-faces.xml b/docs/usermanual-fonts-and-faces.xml
index 7de0f051..55360043 100644
--- a/docs/usermanual-fonts-and-faces.xml
+++ b/docs/usermanual-fonts-and-faces.xml
@@ -1,3 +1,9 @@
+<?xml version="1.0"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+ "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
+ <!ENTITY % local.common.attrib "xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'">
+ <!ENTITY version SYSTEM "version.xml">
+]>
<chapter id="fonts-and-faces">
<title>Fonts and faces</title>
<section id="using-freetype">
@@ -15,4 +21,4 @@
<para>
</para>
</section>
-</chapter>
\ No newline at end of file
+</chapter>
diff --git a/docs/usermanual-getting-started.xml b/docs/usermanual-getting-started.xml
index f8f525c6..9e16ecbf 100644
--- a/docs/usermanual-getting-started.xml
+++ b/docs/usermanual-getting-started.xml
@@ -1,3 +1,9 @@
+<?xml version="1.0"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+ "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
+ <!ENTITY % local.common.attrib "xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'">
+ <!ENTITY version SYSTEM "version.xml">
+]>
<chapter id="getting-started">
<title>Getting started with HarfBuzz</title>
<section>
diff --git a/docs/usermanual-glyph-information.xml b/docs/usermanual-glyph-information.xml
index ca674c0c..78f06c73 100644
--- a/docs/usermanual-glyph-information.xml
+++ b/docs/usermanual-glyph-information.xml
@@ -1,3 +1,9 @@
+<?xml version="1.0"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+ "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
+ <!ENTITY % local.common.attrib "xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'">
+ <!ENTITY version SYSTEM "version.xml">
+]>
<sect1 id="glyph-information">
<title>Glyph information</title>
<sect2 id="names-and-numbers">
@@ -5,4 +11,4 @@
<para>
</para>
</sect2>
-</sect1>
\ No newline at end of file
+</sect1>
diff --git a/docs/usermanual-install-harfbuzz.xml b/docs/usermanual-install-harfbuzz.xml
index 54b5fc95..a6484fc5 100644
--- a/docs/usermanual-install-harfbuzz.xml
+++ b/docs/usermanual-install-harfbuzz.xml
@@ -1,3 +1,9 @@
+<?xml version="1.0"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+ "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
+ <!ENTITY % local.common.attrib "xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'">
+ <!ENTITY version SYSTEM "version.xml">
+]>
<chapter id="install-harfbuzz">
<title>Installing HarfBuzz</title>
@@ -376,11 +382,16 @@
<term>--with-uniscribe</term>
<listitem>
<para>
- Use the <ulink url="https://docs.microsoft.com/en-us/windows/desktop/intl/uniscribe">Uniscribe</ulink> library. <emphasis>(Default = no)</emphasis>
+ Use the <ulink
+ url="https://docs.microsoft.com/en-us/windows/desktop/intl/uniscribe">Uniscribe</ulink>
+ library (experimental). <emphasis>(Default = no)</emphasis>
</para>
<para>
This option enables or disables usage of the Uniscribe
- font-rendering library. Uniscribe is available on Windows systems.
+ font-rendering library. Uniscribe is available on
+ Windows systems. Uniscribe support is used only for
+ testing purposes and does not need to be enabled for
+ HarfBuzz to run on Windows systems.
</para>
</listitem>
</varlistentry>
@@ -393,7 +404,10 @@
</para>
<para>
This option enables or disables usage of the DirectWrite
- font-rendering library. DirectWrite is available on Windows systems.
+ font-rendering library. DirectWrite is available on
+ Windows systems. DirectWrite support is used only for
+ testing purposes and does not need to be enabled for
+ HarfBuzz to run on Windows systems.
</para>
</listitem>
</varlistentry>
diff --git a/docs/usermanual-opentype-features.xml b/docs/usermanual-opentype-features.xml
index 470bab8d..51ff55a7 100644
--- a/docs/usermanual-opentype-features.xml
+++ b/docs/usermanual-opentype-features.xml
@@ -1,3 +1,9 @@
+<?xml version="1.0"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+ "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
+ <!ENTITY % local.common.attrib "xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'">
+ <!ENTITY version SYSTEM "version.xml">
+]>
<chapter id="shaping-and-shape-plans">
<title>Shaping and shape plans</title>
<section id="opentype-features">
@@ -10,4 +16,4 @@
<para>
</para>
</section>
-</chapter>
\ No newline at end of file
+</chapter>
diff --git a/docs/usermanual-shaping-concepts.xml b/docs/usermanual-shaping-concepts.xml
index 8c49ab13..bc9f1b83 100644
--- a/docs/usermanual-shaping-concepts.xml
+++ b/docs/usermanual-shaping-concepts.xml
@@ -1,3 +1,9 @@
+<?xml version="1.0"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+ "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
+ <!ENTITY % local.common.attrib "xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'">
+ <!ENTITY version SYSTEM "version.xml">
+]>
<chapter id="shaping-concepts">
<title>Shaping concepts</title>
<section id="text-shaping-concepts">
diff --git a/docs/usermanual-what-is-harfbuzz.xml b/docs/usermanual-what-is-harfbuzz.xml
index 4d9acc99..8532d7cc 100644
--- a/docs/usermanual-what-is-harfbuzz.xml
+++ b/docs/usermanual-what-is-harfbuzz.xml
@@ -91,7 +91,8 @@
engines in Firefox, LibreOffice, and Chromium. Unless you are
<emphasis>writing</emphasis> one of these layout engines
yourself, you will probably not need to use HarfBuzz: normally,
- lower-level libraries will turn text into glyphs for you.
+ a layout engine, toolkit, or other library will turn text into
+ glyphs for you.
</para>
<para>
However, if you <emphasis>are</emphasis> writing a layout engine
@@ -301,8 +302,8 @@
<para>
In addition to OpenType shaping, HarfBuzz supports the latest
- version of Graphite shaping. HarfBuzz currently supports AAT
- shaping only on macOS and iOS systems.
+ version of Graphite shaping (the "Graphite 2" model) and AAT
+ shaping.
</para>
<para>
@@ -313,8 +314,9 @@
</para>
<para>
- HarfBuzz can run on top of the FreeType, CoreText, DirectWrite,
- or Uniscribe font renderers.
+ HarfBuzz is designed and tested to run on top of the FreeType
+ font renderer. It can run on Linux, Android, Windows, macOS, and
+ iOS systems.
</para>
<para>
commit e110032b914db9f417cc152b2beb51cda0a91dd7
Author: Nathan Willis <nwillis at glyphography.com>
Date: Mon Oct 29 16:42:59 2018 -0500
Usermanual: update DTD in chapter XML to avoid HTML entity parsing errors.
diff --git a/docs/usermanual-what-is-harfbuzz.xml b/docs/usermanual-what-is-harfbuzz.xml
index 4719dd4f..4d9acc99 100644
--- a/docs/usermanual-what-is-harfbuzz.xml
+++ b/docs/usermanual-what-is-harfbuzz.xml
@@ -1,3 +1,9 @@
+<?xml version="1.0"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+ "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
+ <!ENTITY % local.common.attrib "xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'">
+ <!ENTITY version SYSTEM "version.xml">
+]>
<chapter id="what-is-harfbuzz">
<title>What is HarfBuzz?</title>
<para>
@@ -12,7 +18,7 @@
<para>
HarfBuzz can properly shape all of the world's major writing
systems. It runs on all major operating systems and software
- platforms, and it supports all of the modern font formats in use
+ platforms and it supports the modern font formats in use
today.
</para>
<section id="what-is-text-shaping">
@@ -372,7 +378,7 @@
Before sending your string to HarfBuzz, you may need to apply the
bidi algorithm to it. Libraries such as <ulink
url="http://icu-project.org/">ICU</ulink> and <ulink
- url="http://fribidi.org/">fribidi</a> can do this for you.
+ url="http://fribidi.org/">fribidi</ulink> can do this for you.
</para>
</listitem>
<listitem>
commit 01400f7425f7aec852f39ebee17aa502a74025fb
Author: Nathan Willis <nwillis at glyphography.com>
Date: Sat Oct 20 17:21:49 2018 +0100
Usermanual; minor wording changes.
diff --git a/docs/usermanual-getting-started.xml b/docs/usermanual-getting-started.xml
index 07593f56..f8f525c6 100644
--- a/docs/usermanual-getting-started.xml
+++ b/docs/usermanual-getting-started.xml
@@ -18,9 +18,7 @@
properties that affect shaping. The most important are the
text-flow direction (e.g., left-to-right, right-to-left,
top-to-bottom, or bottom-to-top), the script tag, and the
- language tag. HarfBuzz can attempt to guess the correct values
- for the buffer based on its contents if you do not set them
- explicitly.
+ language tag.
</para>
<para>
@@ -29,7 +27,8 @@
indicate whether or not to visibly render Unicode <literal>Default
Ignorable</literal> codepoints, and to modify the cluster-merging
behavior for the buffer. For shaped output buffers, the
- individual X and Y offsets and widths of each glyph are
+ individual X and Y offsets and <literal>advances</literal>
+ (the logical dimensions) of each glyph are
accessible. HarfBuzz also flags glyphs as
<literal>UNSAFE_TO_BREAK</literal> if breaking the string at
that glyph (e.g., in a line-breaking or hyphenation process)
@@ -61,9 +60,10 @@
</para>
<para>
- HarfBuzz provides glue code to integrate with FreeType, GObject,
- Uniscribe, and CoreText. Support for integrating with
- DirectWrite is experimental at present.
+ HarfBuzz provides glue code to integrate with various other
+ libraries, including FreeType, GObject, and CoreText. Support
+ for integrating with Uniscribe and DirectWrite is experimental
+ at present.
</para>
</section>
diff --git a/docs/usermanual-install-harfbuzz.xml b/docs/usermanual-install-harfbuzz.xml
index cd1e2e13..54b5fc95 100644
--- a/docs/usermanual-install-harfbuzz.xml
+++ b/docs/usermanual-install-harfbuzz.xml
@@ -279,7 +279,11 @@
graphics-rendering library. The default setting is to
check for the presence of Cairo and, if it is found,
build with Cairo support.
- </para>
+ </para>
+ <para>
+ Note: Cairo is used only by the HarfBuzz
+ command-line utilities, and not by the HarfBuzz library.
+ </para>
</listitem>
</varlistentry>
@@ -296,6 +300,10 @@
is to check for the presence of Fontconfig and, if it is
found, build with Fontconfig support.
</para>
+ <para>
+ Note: Fontconfig is used only by the HarfBuzz
+ command-line utilities, and not by the HarfBuzz library.
+ </para>
</listitem>
</varlistentry>
diff --git a/docs/usermanual-what-is-harfbuzz.xml b/docs/usermanual-what-is-harfbuzz.xml
index 0c01adae..4719dd4f 100644
--- a/docs/usermanual-what-is-harfbuzz.xml
+++ b/docs/usermanual-what-is-harfbuzz.xml
@@ -296,10 +296,7 @@
<para>
In addition to OpenType shaping, HarfBuzz supports the latest
version of Graphite shaping. HarfBuzz currently supports AAT
- shaping only on macOS and iOS systems, and in a pass-through
- fashion: HarfBuzz hands off AAT support to the system CoreText
- library. However, full, built-in AAT support within HarfBuzz is
- under development.
+ shaping only on macOS and iOS systems.
</para>
<para>
@@ -321,13 +318,9 @@
all color-font formats (<literal>CBDT</literal>,
<literal>sbix</literal>, <literal>COLR/CPAL</literal>, and
<literal>SVG-OT</literal>) and OpenType variable fonts. HarfBuzz
- also includes a font-subsetting feature.
- </para>
-
- <para>
- HarfBuzz can perform some low-level math-shaping operations,
- although it does not currently perform full shaping for
- mathematical typesetting.
+ also includes a font-subsetting feature. HarfBuzz can perform
+ some low-level math-shaping operations, although it does not
+ currently perform full shaping for mathematical typesetting.
</para>
<para>
@@ -355,9 +348,10 @@
<para>
HarfBuzz won't help you with bidirectionality. If you want to
lay out text that includes a mix of Hebrew and English, you
- will need to ensure that each buffer provided to HarfBuzz has its
- characters in the correct layout order. This will be different
- from the logical order in which the Unicode text is stored. In
+ will need to ensure that each buffer provided to HarfBuzz
+ has all of its characters in the same order and that the
+ directionality of the buffer is set correctly. This may mean
+ segmenting the text before it is placed into HarfBuzz buffers. In
other words, the user will hit the keys in the following
sequence:
</para>
@@ -374,7 +368,7 @@
This reordering is called <emphasis>bidi processing</emphasis>
("bidi" is short for bidirectional), and there's an
algorithm as an annex to the Unicode Standard which tells you how
- to reorder a string from logical order into presentation order.
+ to process a string of mixed directionality.
Before sending your string to HarfBuzz, you may need to apply the
bidi algorithm to it. Libraries such as <ulink
url="http://icu-project.org/">ICU</ulink> and <ulink
@@ -412,12 +406,7 @@
HarfBuzz can tell you how wide a shaped piece of text is, which is
useful input to a justification algorithm, but it knows nothing
about paragraphs, lines or line lengths. Nor will it adjust the
- space between words to fit them proportionally into a line. If you
- want to layout text in paragraphs, you will probably want to send
- each word of your text to HarfBuzz to determine its shaped width
- after glyph substitutions, then work out how many words will fit
- on a line, and then finally output each word of the line separated
- by a space of the correct size to fully justify the paragraph.
+ space between words to fit them proportionally into a line.
</para>
</listitem>
</itemizedlist>
commit e89f43dc0884cb4a73beff86e49b7bd8565a01f1
Author: Khaled Hosny <khaledhosny at eglug.org>
Date: Sat Oct 20 16:12:45 2018 +0100
Minor; rewording unsafe-to-break note.
Co-Authored-By: n8willis <nwillis at glyphography.com>
diff --git a/docs/usermanual-getting-started.xml b/docs/usermanual-getting-started.xml
index 69f92dbb..07593f56 100644
--- a/docs/usermanual-getting-started.xml
+++ b/docs/usermanual-getting-started.xml
@@ -33,7 +33,7 @@
accessible. HarfBuzz also flags glyphs as
<literal>UNSAFE_TO_BREAK</literal> if breaking the string at
that glyph (e.g., in a line-breaking or hyphenation process)
- would alter the shaping output for the buffer.
+ would require re-shaping the text.
</para>
<para>
commit ccdfb634382596a6114380c72f2f344b1af23f94
Author: Khaled Hosny <khaledhosny at eglug.org>
Date: Sat Oct 20 15:46:04 2018 +0100
Trivial; typo.
Co-Authored-By: n8willis <nwillis at glyphography.com>
diff --git a/docs/usermanual-what-is-harfbuzz.xml b/docs/usermanual-what-is-harfbuzz.xml
index e6fa2529..0c01adae 100644
--- a/docs/usermanual-what-is-harfbuzz.xml
+++ b/docs/usermanual-what-is-harfbuzz.xml
@@ -161,7 +161,7 @@
<listitem>
<para>
Similarly, each Arabic character has four different variants
- corresponding to the different positions in might appear in
+ corresponding to the different positions it might appear in
within a sequence. Inside a font, there will be separate
glyphs for the initial, medial, final, and isolated forms of
each letter, each at a different glyph ID.
commit 722099487be72346e7109872b6abf30696f3b7c3
Author: Khaled Hosny <khaledhosny at eglug.org>
Date: Sat Oct 20 15:45:24 2018 +0100
Minor; simplify example code
Co-Authored-By: n8willis <nwillis at glyphography.com>
diff --git a/docs/usermanual-getting-started.xml b/docs/usermanual-getting-started.xml
index 72a37462..69f92dbb 100644
--- a/docs/usermanual-getting-started.xml
+++ b/docs/usermanual-getting-started.xml
@@ -138,7 +138,9 @@
</listitem>
</orderedlist>
<programlisting language="C">
- hb_buffer_guess_segment_properties(buf);
+ hb_buffer_set_direction(buf, HB_DIRECTION_LTR);
+ hb_buffer_set_script(buf, HB_SCRIPT_LATIN);
+ hb_buffer_set_language(buf, hb_language_from_string("en", -1));
</programlisting>
<orderedlist numeration="arabic">
<listitem override="3">
commit 6e4dd58a4af003eeec93cbe90d1258d91a38b53c
Author: Khaled Hosny <khaledhosny at eglug.org>
Date: Sat Oct 20 15:44:51 2018 +0100
Minor: simplify example code
Co-Authored-By: n8willis <nwillis at glyphography.com>
diff --git a/docs/usermanual-getting-started.xml b/docs/usermanual-getting-started.xml
index 188d449d..72a37462 100644
--- a/docs/usermanual-getting-started.xml
+++ b/docs/usermanual-getting-started.xml
@@ -128,7 +128,7 @@
#include <hb.h>
hb_buffer_t *buf;
buf = hb_buffer_create();
- hb_buffer_add_utf8(buf, text, strlen(text), 0, strlen(text));
+ hb_buffer_add_utf8(buf, text, -1, 0, -1);
</programlisting>
<orderedlist numeration="arabic">
<listitem override="2">
commit f9ee0deceebd8952a8d80f3fd7b264b33e70f703
Author: Khaled Hosny <khaledhosny at eglug.org>
Date: Sat Oct 20 15:41:00 2018 +0100
Minor; drop 'OpenType' from sentence
Co-Authored-By: n8willis <nwillis at glyphography.com>
diff --git a/docs/usermanual-what-is-harfbuzz.xml b/docs/usermanual-what-is-harfbuzz.xml
index 0c961e2f..e6fa2529 100644
--- a/docs/usermanual-what-is-harfbuzz.xml
+++ b/docs/usermanual-what-is-harfbuzz.xml
@@ -221,7 +221,7 @@
<section>
<title>What does HarfBuzz do?</title>
<para>
- HarfBuzz provides OpenType text shaping through a cross-platform
+ HarfBuzz provides text shaping through a cross-platform
C API that accepts sequences of Unicode codepoints as input. Currently,
the following OpenType shaping models are supported:
</para>
commit f028da59d902c39e61021b48fc73f2821a9f3be2
Author: Nathan Willis <nwillis at glyphography.com>
Date: Sat Oct 20 15:18:29 2018 +0100
Minor.
diff --git a/docs/harfbuzz-docs.xml b/docs/harfbuzz-docs.xml
index ee04bae2..6d241190 100644
--- a/docs/harfbuzz-docs.xml
+++ b/docs/harfbuzz-docs.xml
@@ -21,11 +21,13 @@
<para>
The canonical source-code tree is available at
<ulink
- url="http://cgit.freedesktop.org/harfbuzz/">cgit.freedesktop.org/harfbuzz</ulink>
- and at
+ url="https://github.com/harfbuzz/harfbuzz">github.com/harfbuzz/harfbuzz</ulink>
+ and is also available at
<ulink
- url="https://github.com/harfbuzz/harfbuzz">github.com/harfbuzz/harfbuzz</ulink>.
- See <xref linkend="download" endterm="download.title"/> for release tarballs.
+ url="http://cgit.freedesktop.org/harfbuzz/">cgit.freedesktop.org/harfbuzz</ulink>.
+ See <xref linkend="download" endterm="download.title"/> for
+ release tarballs.
+ </para>
</abstract>
</bookinfo>
@@ -53,7 +55,7 @@
<note>
<para>
- The current HarfBuzz codebase is versioned 1.x.x and is stable
+ The current HarfBuzz codebase is versioned 2.x.x and is stable
and under active maintenance. This is what is used in latest
versions of Firefox, GNOME, ChromeOS, Chrome, LibreOffice,
XeTeX, Android, and KDE, among other places.
commit ed5547f828fe7559cc3331f05780ae9f041b1e0f
Author: Khaled Hosny <khaledhosny at eglug.org>
Date: Sat Oct 20 15:00:52 2018 +0100
Use 'glyphs' instead of 'text'
Co-Authored-By: n8willis <nwillis at glyphography.com>
diff --git a/docs/harfbuzz-docs.xml b/docs/harfbuzz-docs.xml
index 15d194cf..ee04bae2 100644
--- a/docs/harfbuzz-docs.xml
+++ b/docs/harfbuzz-docs.xml
@@ -14,7 +14,7 @@
HarfBuzz is an <ulink url="http://www.microsoft.com/typography/otspec/">OpenType</ulink>
text shaping engine. Using the HarfBuzz library allows
programs to convert a sequence of Unicode input into
- properly formatted and positioned text output—for any writing
+ properly formatted and positioned glyph output—for any writing
system and language.
</para>
commit 236285545b5da8513f2b61fc8066ba78308a555a
Author: Nathan Willis <nwillis at glyphography.com>
Date: Wed Oct 17 10:10:48 2018 -0500
Docs: minor, update Makefile w new file name.
diff --git a/docs/Makefile.am b/docs/Makefile.am
index e48b9ccd..595dd83e 100644
--- a/docs/Makefile.am
+++ b/docs/Makefile.am
@@ -76,7 +76,7 @@ content_files= \
usermanual-clusters.xml \
usermanual-fonts-and-faces.xml \
usermanual-glyph-information.xml \
- usermanual-hello-harfbuzz.xml \
+ usermanual-getting-started.xml \
usermanual-install-harfbuzz.xml \
usermanual-opentype-features.xml \
usermanual-what-is-harfbuzz.xml \
commit 163ab81ab0f4000d968cc55b418402497e605e6c
Author: Nathan Willis <nwillis at glyphography.com>
Date: Tue Oct 16 17:48:15 2018 -0500
Docs: rename Hello HarfBuzz to Getting Started.
diff --git a/docs/harfbuzz-docs.xml b/docs/harfbuzz-docs.xml
index b7d5cec7..15d194cf 100644
--- a/docs/harfbuzz-docs.xml
+++ b/docs/harfbuzz-docs.xml
@@ -33,7 +33,7 @@
<title>User's manual</title>
<xi:include href="usermanual-what-is-harfbuzz.xml"/>
<xi:include href="usermanual-install-harfbuzz.xml"/>
- <xi:include href="usermanual-hello-harfbuzz.xml"/>
+ <xi:include href="usermanual-getting-started.xml"/>
<xi:include href="usermanual-shaping-concepts.xml"/>
<xi:include href="usermanual-buffers-language-script-and-direction.xml"/>
<xi:include href="usermanual-fonts-and-faces.xml"/>
diff --git a/docs/usermanual-hello-harfbuzz.xml b/docs/usermanual-getting-started.xml
similarity index 100%
rename from docs/usermanual-hello-harfbuzz.xml
rename to docs/usermanual-getting-started.xml
commit 9e7efa3f47557a77852a15d89619787fd9933ed1
Author: Nathan Willis <nwillis at glyphography.com>
Date: Tue Oct 16 17:46:03 2018 -0500
Docs: usermanual, add API Overview to Hello HarfBuzz chapter. Start Terminology section.
diff --git a/docs/usermanual-hello-harfbuzz.xml b/docs/usermanual-hello-harfbuzz.xml
index 221692c6..188d449d 100644
--- a/docs/usermanual-hello-harfbuzz.xml
+++ b/docs/usermanual-hello-harfbuzz.xml
@@ -1,99 +1,214 @@
-<chapter id="hello-harfbuzz">
- <title>Hello, HarfBuzz</title>
- <para>
- Here's the simplest HarfBuzz that can possibly work. We will improve
- it later.
- </para>
- <orderedlist numeration="arabic">
- <listitem>
- <para>
- Create a buffer and put your text in it.
- </para>
- </listitem>
- </orderedlist>
- <programlisting language="C">
- #include <hb.h>
- hb_buffer_t *buf;
- buf = hb_buffer_create();
- hb_buffer_add_utf8(buf, text, strlen(text), 0, strlen(text));
-</programlisting>
- <orderedlist numeration="arabic">
- <listitem override="2">
- <para>
- Guess the script, language and direction of the buffer.
- </para>
- </listitem>
- </orderedlist>
- <programlisting language="C">
- hb_buffer_guess_segment_properties(buf);
-</programlisting>
- <orderedlist numeration="arabic">
- <listitem override="3">
- <para>
- Create a face and a font, using FreeType for now.
- </para>
- </listitem>
- </orderedlist>
- <programlisting language="C">
- #include <hb-ft.h>
- FT_New_Face(ft_library, font_path, index, &face)
- hb_font_t *font = hb_ft_font_create(face);
-</programlisting>
- <orderedlist numeration="arabic">
- <listitem override="4">
- <para>
- Shape!
- </para>
- </listitem>
- </orderedlist>
- <programlisting>
- hb_shape(font, buf, NULL, 0);
-</programlisting>
- <orderedlist numeration="arabic">
- <listitem override="5">
- <para>
- Get the glyph and position information.
- </para>
- </listitem>
- </orderedlist>
- <programlisting language="C">
- hb_glyph_info_t *glyph_info = hb_buffer_get_glyph_infos(buf, &glyph_count);
- hb_glyph_position_t *glyph_pos = hb_buffer_get_glyph_positions(buf, &glyph_count);
-</programlisting>
- <orderedlist numeration="arabic">
- <listitem override="6">
- <para>
- Iterate over each glyph.
- </para>
- </listitem>
- </orderedlist>
- <programlisting language="C">
- for (i = 0; i < glyph_count; ++i) {
- glyphid = glyph_info[i].codepoint;
- x_offset = glyph_pos[i].x_offset / 64.0;
- y_offset = glyph_pos[i].y_offset / 64.0;
- x_advance = glyph_pos[i].x_advance / 64.0;
- y_advance = glyph_pos[i].y_advance / 64.0;
- draw_glyph(glyphid, cursor_x + x_offset, cursor_y + y_offset);
- cursor_x += x_advance;
- cursor_y += y_advance;
- }
-</programlisting>
- <orderedlist numeration="arabic">
- <listitem override="7">
- <para>
- Tidy up.
- </para>
- </listitem>
- </orderedlist>
- <programlisting language="C">
- hb_buffer_destroy(buf);
- hb_font_destroy(hb_ft_font);
-</programlisting>
+<chapter id="getting-started">
+ <title>Getting started with HarfBuzz</title>
+ <section>
+ <title>An overview of the HarfBuzz shaping API</title>
+ <para>
+ The core of the HarfBuzz shaping API is the function
+ <function>hb_shape()</function>. This function takes a font, a
+ buffer containing a string of Unicode codepoints and
+ (optionally) a list of font features as its input. It replaces
+ the codepoints in the buffer with the corresponding glyphs from
+ the font, correctly ordered and positioned, and with any of the
+ optional font features applied.
+ </para>
+ <para>
+ In addition to holding the pre-shaping input (the Unicode
+ codepoints that comprise the input string) and the post-shaping
+ output (the glyphs and positions), a HarfBuzz buffer has several
+ properties that affect shaping. The most important are the
+ text-flow direction (e.g., left-to-right, right-to-left,
+ top-to-bottom, or bottom-to-top), the script tag, and the
+ language tag. HarfBuzz can attempt to guess the correct values
+ for the buffer based on its contents if you do not set them
+ explicitly.
+ </para>
-<para>
- This example shows enough to get us started using HarfBuzz. Now we
- are going to use the remainder of HarfBuzz's API to refine that
- example and improve our text shaping capabilities.
-</para>
+ <para>
+ For input string buffers, flags are available to denote when the
+ buffer represents the beginning or end of a paragraph, to
+ indicate whether or not to visibly render Unicode <literal>Default
+ Ignorable</literal> codepoints, and to modify the cluster-merging
+ behavior for the buffer. For shaped output buffers, the
+ individual X and Y offsets and widths of each glyph are
+ accessible. HarfBuzz also flags glyphs as
+ <literal>UNSAFE_TO_BREAK</literal> if breaking the string at
+ that glyph (e.g., in a line-breaking or hyphenation process)
+ would alter the shaping output for the buffer.
+ </para>
+
+ <para>
+ HarfBuzz also provides methods to compare the contents of
+ buffers, join buffers, normalize buffer contents, and handle
+ invalid codepoints, as well as to determine the state of a
+ buffer (e.g., input codepoints or output glyphs). Buffer
+ lifecycles are managed and all buffers are reference-counted.
+ </para>
+
+ <para>
+ Although the default <function>hb_shape()</function> function is
+ sufficient for most use cases, a variant is also provide that
+ lets you specify which of HarfBuzz's shapers to use on a buffer.
+ </para>
+
+ <para>
+ HarfBuzz can read TrueType fonts, TrueType collections, OpenType
+ fonts, and OpenType collections. Functions are provided to query
+ font objects about metrics, Unicode coverage, available tables and
+ features, and variation selectors. Individual glyphs can also be
+ queried for metrics, variations, and glyph names. OpenType
+ variable fonts are supported, and HarfBuzz allows you to set
+ variation-axis coordinates on font objects.
+ </para>
+
+ <para>
+ HarfBuzz provides glue code to integrate with FreeType, GObject,
+ Uniscribe, and CoreText. Support for integrating with
+ DirectWrite is experimental at present.
+ </para>
+ </section>
+
+ <section>
+ <title>Terminology</title>
+ <variablelist>
+ <varlistentry>
+ <term>shaper</term>
+ <listitem>
+ <para>
+ In HarfBuzz, a <emphasis>shaper</emphasis> is a
+ handler for a specific script shaping model. HarfBuzz
+ implements separate shapers for Indic, Arabic, Thai and
+ Lao, Khmer, Myanmar, Tibetan, Hangul, Hebrew, the
+ Universal Shaping Engine (USE), and a default shaper for
+ non-complex scripts.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>cluster</term>
+ <listitem>
+ <para>
+ In text shaping, a <emphasis>cluster</emphasis> is a
+ sequence of codepoints that must be handled as an
+ indivisible unit. Clusters can include codepoint
+ sequences that form a ligature or base-and-mark
+ sequences. Tracking and preserving clusters is important
+ when shaping operations might separate or reorder
+ codepoints.
+ </para>
+ <para>
+ HarfBuzz provides three cluster
+ <emphasis>levels</emphasis> that implement different
+ approaches to the problem of preserving clusters during
+ shaping operations.
+ </para>
+ </listitem>
+ </varlistentry>
+
+
+ </variablelist>
+
+ </section>
+
+
+ <section>
+ <title>A simple shaping example</title>
+
+ <para>
+ Below is the simplest HarfBuzz shaping example possible.
+ </para>
+ <orderedlist numeration="arabic">
+ <listitem>
+ <para>
+ Create a buffer and put your text in it.
+ </para>
+ </listitem>
+ </orderedlist>
+ <programlisting language="C">
+ #include <hb.h>
+ hb_buffer_t *buf;
+ buf = hb_buffer_create();
+ hb_buffer_add_utf8(buf, text, strlen(text), 0, strlen(text));
+ </programlisting>
+ <orderedlist numeration="arabic">
+ <listitem override="2">
+ <para>
+ Guess the script, language and direction of the buffer.
+ </para>
+ </listitem>
+ </orderedlist>
+ <programlisting language="C">
+ hb_buffer_guess_segment_properties(buf);
+ </programlisting>
+ <orderedlist numeration="arabic">
+ <listitem override="3">
+ <para>
+ Create a face and a font, using FreeType for now.
+ </para>
+ </listitem>
+ </orderedlist>
+ <programlisting language="C">
+ #include <hb-ft.h>
+ FT_New_Face(ft_library, font_path, index, &face)
+ hb_font_t *font = hb_ft_font_create(face);
+ </programlisting>
+ <orderedlist numeration="arabic">
+ <listitem override="4">
+ <para>
+ Shape!
+ </para>
+ </listitem>
+ </orderedlist>
+ <programlisting>
+ hb_shape(font, buf, NULL, 0);
+ </programlisting>
+ <orderedlist numeration="arabic">
+ <listitem override="5">
+ <para>
+ Get the glyph and position information.
+ </para>
+ </listitem>
+ </orderedlist>
+ <programlisting language="C">
+ hb_glyph_info_t *glyph_info = hb_buffer_get_glyph_infos(buf, &glyph_count);
+ hb_glyph_position_t *glyph_pos = hb_buffer_get_glyph_positions(buf, &glyph_count);
+ </programlisting>
+ <orderedlist numeration="arabic">
+ <listitem override="6">
+ <para>
+ Iterate over each glyph.
+ </para>
+ </listitem>
+ </orderedlist>
+ <programlisting language="C">
+ for (i = 0; i < glyph_count; ++i) {
+ glyphid = glyph_info[i].codepoint;
+ x_offset = glyph_pos[i].x_offset / 64.0;
+ y_offset = glyph_pos[i].y_offset / 64.0;
+ x_advance = glyph_pos[i].x_advance / 64.0;
+ y_advance = glyph_pos[i].y_advance / 64.0;
+ draw_glyph(glyphid, cursor_x + x_offset, cursor_y + y_offset);
+ cursor_x += x_advance;
+ cursor_y += y_advance;
+ }
+ </programlisting>
+ <orderedlist numeration="arabic">
+ <listitem override="7">
+ <para>
+ Tidy up.
+ </para>
+ </listitem>
+ </orderedlist>
+ <programlisting language="C">
+ hb_buffer_destroy(buf);
+ hb_font_destroy(hb_ft_font);
+ </programlisting>
+
+ <para>
+ This example shows enough to get us started using HarfBuzz. In
+ the sections that follow, we will use the remainder of
+ HarfBuzz's API to refine and extend the example and improve its
+ text-shaping capabilities.
+ </para>
+ </section>
</chapter>
commit 3a27e8fb97f716c17b03e3a4a634a4900bcb6045
Author: Nathan Willis <nwillis at glyphography.com>
Date: Fri Oct 12 18:23:26 2018 -0500
Docs: usermanual, add Shaping Concepts chapter.
diff --git a/docs/harfbuzz-docs.xml b/docs/harfbuzz-docs.xml
index 48ea67e6..b7d5cec7 100644
--- a/docs/harfbuzz-docs.xml
+++ b/docs/harfbuzz-docs.xml
@@ -13,8 +13,8 @@
<para>
HarfBuzz is an <ulink url="http://www.microsoft.com/typography/otspec/">OpenType</ulink>
text shaping engine. Using the HarfBuzz library allows
- programs to convert a sequence of Unicode input text into
- properly formatted and positioned output—for any writing
+ programs to convert a sequence of Unicode input into
+ properly formatted and positioned text output—for any writing
system and language.
</para>
@@ -34,6 +34,7 @@
<xi:include href="usermanual-what-is-harfbuzz.xml"/>
<xi:include href="usermanual-install-harfbuzz.xml"/>
<xi:include href="usermanual-hello-harfbuzz.xml"/>
+ <xi:include href="usermanual-shaping-concepts.xml"/>
<xi:include href="usermanual-buffers-language-script-and-direction.xml"/>
<xi:include href="usermanual-fonts-and-faces.xml"/>
<xi:include href="usermanual-clusters.xml"/>
diff --git a/docs/usermanual-shaping-concepts.xml b/docs/usermanual-shaping-concepts.xml
new file mode 100644
index 00000000..8c49ab13
--- /dev/null
+++ b/docs/usermanual-shaping-concepts.xml
@@ -0,0 +1,368 @@
+<chapter id="shaping-concepts">
+ <title>Shaping concepts</title>
+ <section id="text-shaping-concepts">
+ <title>Text shaping</title>
+ <para>
+ Text shaping is the process of transforming a sequence of Unicode
+ codepoints that represent individual characters (letters,
+ diacritics, tone marks, numbers, symbols, etc.) into the
+ orthographically and linguistically correct two-dimensional layout
+ of glyph shapes taken from a specified font.
+ </para>
+ <para>
+ For some writing systems (or <emphasis>scripts</emphasis>) and
+ languages, the process is simple, requiring the shaper to do
+ little more than advance the horizontal position forward by the
+ correct amount for each successive glyph.
+ </para>
+ <para>
+ But, for <emphasis>complex scripts</emphasis>, any combination of
+ several shaping operations may be required, and the rules for how
+ and when they are applied vary from script to script. HarfBuzz and
+ other shaping engines implement these rules.
+ </para>
+ <para>
+ The exact rules and necessary operations for a particular script
+ constitute a shaping <emphasis>model</emphasis>. OpenType
+ specifies a set of shaping models that covers all of
+ Unicode. Other shaping models are available, however, including
+ Graphite and Apple Advanced Typography (AAT).
+ </para>
+ </section>
+
+ <section id="complex-scripts">
+ <title>Complex scripts</title>
+ <para>
+ In text-shaping terminology, scripts are generally classified as
+ either <emphasis>complex</emphasis> or <emphasis>non-complex</emphasis>.
+ </para>
+ <para>
+ Complex scripts are those for which transforming the input
+ sequence into the final layout requires some combination of
+ operations—such as context-dependent substitutions,
+ context-dependent mark positioning, glyph-to-glyph joining,
+ glyph reordering, or glyph stacking.
+ </para>
+ <para>
+ In some complex scripts, the shaping rules require that a text
+ run be divided into syllables before the operations can be
+ applied. Other complex scripts may apply shaping operations over
+ entire words or over the entire text run, with no subdivision
+ required.
+ </para>
+ <para>
+ Non-complex scripts, by definition, do not require these
+ operations. However, correctly shaping a text run in a
+ non-complex script may still involve Unicode normalization,
+ ligature substitutions, mark positioning, kerning, and applying
+ other font features. The key difference is that a text run in a
+ non-complex script can be processed sequentially and in the same
+ order as the input sequence of Unicode codepoints, without
+ requiring an analysis stage.
+ </para>
+ </section>
+
+ <section id="shaping-operations">
+ <title>Shaping operations</title>
+ <para>
+ Shaping a complex-script text run involves transforming the
+ input sequence of Unicode codepoints with some combination of
+ operations that is specified in the shaping model for the
+ script.
+ </para>
+ <para>
+ The specific conditions that trigger a given operation for a
+ text run varies from script to script, as do the order that the
+ operations are performed in and which codepoints are
+ affected. However, the same general set of shaping operations is
+ common to all of the complex-script shaping models.
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ A <emphasis>reordering</emphasis> operation moves a glyph
+ from its original ("logical") position in the sequence to
+ some other ("visual") position.
+ </para>
+ <para>
+ The shaping model for a given complex script might involve
+ more than one reordering step.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ A <emphasis>joining</emphasis> operation replaces a glyph
+ with an alternate form that is designed to connect with one
+ or more of the adjacent glyphs in the sequence.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ A contextual <emphasis>substitution</emphasis> operation
+ replaces either a single glyph or a subsequence of several
+ glyphs with an alternate glyph. This substitution is
+ performed when the original glyph or subsequence of glyphs
+ occurs in a specified position with respect to the
+ surrounding sequence. For example, one substitution might be
+ performed only when the target glyph is the first glyph in
+ the sequence, while another substitution is performed only
+ when a different target glyph occurs immediately after a
+ particular string pattern.
+ </para>
+ <para>
+ The shaping model for a given complex script might involve
+ multiple contextual-substitution operations, each applying
+ to different target glyphs and patterns, and which are
+ performed in separate steps.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ A contextual <emphasis>positioning</emphasis> operation
+ moves the horizontal and/or vertical position of a
+ glyph. This positioning move is performed when the glyph
+ occurs in a specified position with respect to the
+ surrounding sequence.
+ </para>
+ <para>
+ Many contextual positioning operations are used to place
+ <emphasis>mark</emphasis> glyphs (such as diacritics, vowel
+ signs, and tone markers) with respect to
+ <emphasis>base</emphasis> glyphs. However, some complex
+ scripts may use contextual positioning operations to
+ correctly place base glyphs as well, such as
+ when the script uses <emphasis>stacking</emphasis> characters.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+ </section>
+
+ <section id="unicode-character-categories">
+ <title>Unicode character categories</title>
+ <para>
+ Shaping models are typically specified with respect to how
+ scripts are defined in the Unicode standard.
+ </para>
+ <para>
+ Every codepoint in the Unicode Character Database (UCD) is
+ assigned a <emphasis>Unicode General Category</emphasis> (UGC),
+ which provides the most fundamental information about the
+ codepoint: whether the codepoint represents a
+ <emphasis>Letter</emphasis>, a <emphasis>Mark</emphasis>, a
+ <emphasis>Number</emphasis>, <emphasis>Punctuation</emphasis>, a
+ <emphasis>Symbol</emphasis>, a <emphasis>Separator</emphasis>,
+ or something else (<emphasis>Other</emphasis>).
+ </para>
+ <para>
+ These UGC properties are "Major" categories. Each codepoint is
+ further assigned to a "minor" category within its Major
+ category, such as "Letter, uppercase" (<literal>Lu</literal>) or
+ "Letter, modifier" (<literal>Lm</literal>).
+ </para>
+ <para>
+ Shaping models are concerned primarily with Letter and Mark
+ codepoints. The minor categories of Mark codepoints are
+ particularly important for shaping. Marks can be nonspacing
+ (<literal>Mn</literal>), spacing combining
+ (<literal>Mc</literal>), or enclosing (<literal>Me</literal>).
+ </para>
+ <para>
+ In addition to the UGC property, codepoints in the Indic and
+ Southeast Asian scripts are also assigned
+ <emphasis>Unicode Indic Syllabic Category</emphasis> (UISC) and
+ <emphasis>Unicode Indic Positional Category</emphasis> (UIPC)
+ property that provides more detailed information needed for
+ shaping.
+ </para>
+ <para>
+ The UISC property sub-categorizes Letters and Marks according to
+ common script-shaping behaviors. For example, UISC distinguishes
+ between consonant letters, vowel letters, and vowel marks. The
+ UIPC property sub-categorizes Mark codepoints by the visual
+ position that they occupy (above, below, right, left, or in
+ multiple positions).
+ </para>
+ <para>
+ Some complex scripts require that the text run be split into
+ syllables, and what constitutes a valid syllable in these
+ scripts is specified in regular expressions of the Letter and
+ Mark codepoints that take the UISC and UIPC properties into account.
+ </para>
+
+ </section>
+
+ <section id="text-runs">
+ <title>Text runs</title>
+ <para>
+ Real-world text usually contains codepoints from a mixture of
+ different Unicode scripts (including punctuation, numbers, symbols,
+ white-space characters, and other codepoints that do not belong
+ to any script). Real-world text may also be marked up with
+ formatting that changes font properties (including the font,
+ font style, and font size).
+ </para>
+ <para>
+ For shaping purposes, all real-world text streams must be first
+ segmented into runs that have a uniform set of properties.
+ </para>
+ <para>
+ In particular, shaping models always assume that every codepoint
+ in a text run has the same <emphasis>direction</emphasis>,
+ <emphasis>script</emphasis> tag, and
+ <emphasis>language</emphasis> tag.
+ </para>
+ </section>
+
+ <section id="opentype-shaping-models">
+ <title>OpenType shaping models</title>
+ <para>
+ OpenType provides shaping models for the following scripts:
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ The <emphasis>default</emphasis> shaping model handles all
+ non-complex scripts, and may also be used as a fallback for
+ handling unrecognized scripts.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ The <emphasis>Indic</emphasis> shaping model handles the Indic
+ scripts Bengali, Devanagari, Gujarati, Gurmukhi, Kannada,
+ Malayalam, Oriya, Tamil, Telugu, and Sinhala.
+ </para>
+ <para>
+ The Indic shaping model was revised significantly in
+ 2005. To denote the change, a new set of <emphasis>script
+ tags</emphasis> was assigned for Bengali, Devanagari,
+ Gujarati, Gurmukhi, Kannada, Malayalam, Oriya, Tamil, and
+ Telugu. For the sake of clarity, the term "Indic2" is
+ sometimes used to refer to the current, revised shaping
+ model.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ The <emphasis>Arabic</emphasis> shaping model supports
+ Arabic, Mongolian, N'Ko, Syriac, and several other connected
+ or cursive scripts.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ The <emphasis>Thai/Lao</emphasis> shaping model supports
+ the Thai and Lao scripts.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ The <emphasis>Khmer</emphasis> shaping model supports the
+ Khmer script.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ The <emphasis>Myanmar</emphasis> shaping model supports the
+ Myanmar (or Burmese) script.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ The <emphasis>Tibetan</emphasis> shaping model supports the
+ Tibetan script.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ The <emphasis>Hangul</emphasis> shaping model supports the
+ Hangul script.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ The <emphasis>Hebrew</emphasis> shaping model supports the
+ Hebrew script.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ The <emphasis>Universal Shaping Engine</emphasis> (USE)
+ shaping model supports complex scripts not covered by one of
+ the above, script-specific shaping models, including
+ Javanese, Balinese, Buginese, Batak, Chakma, Lepcha, Modi,
+ Phags-pa, Tagalog, Siddham, Sundanese, Tai Le, Tai Tham, Tai
+ Viet, and many others.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Text runs that do not fall under one of the above shaping
+ models may still require processing by a shaping engine. Of
+ particular note is <emphasis>Emoji</emphasis> shaping, which
+ may involve variation-selector sequences and glyph
+ substitution. Emoji shaping is handled by the default
+ shaping model.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
+ </section>
+
+ <section id="graphite-shaping">
+ <title>Graphite shaping</title>
+ <para>
+ In contrast to OpenType shaping, Graphite shaping does not
+ specify a predefined set of shaping models or a set of supported
+ scripts.
+ </para>
+ <para>
+ Instead, each Graphite font contains a complete set of rules that
+ implement the required shaping model for the intended
+ script. These rules include finite-state machines to match
+ sequences of codepoints to the shaping operations to perform.
+ </para>
+ <para>
+ Graphite shaping can perform the same shaping operations used in
+ OpenType shaping, as well as other functions that have not been
+ defined for OpenType shaping.
+ </para>
+ </section>
+
+ <section id="aat-shaping">
+ <title>AAT shaping</title>
+ <para>
+ In contrast to OpenType shaping, AAT shaping does not specify a
+ predefined set of shaping models or a set of supported scripts.
+ </para>
+ <para>
+ Instead, each AAT font includes a complete set of rules that
+ implement the desired shaping model for the intended
+ script. These rules include finite-state machines to match glyph
+ sequences and the shaping operations to perform.
+ </para>
+ <para>
+ Notably, AAT shaping rules are expressed for glyphs in the font,
+ not for Unicode codepoints. AAT shaping can perform the same
+ shaping operations used in OpenType shaping, as well as other
+ functions that have not been defined for OpenType shaping.
+ </para>
+ </section>
+</chapter>
commit 9aa865dcc68ec207741e07ba3f7aacf4ac750c1c
Author: Nathan Willis <nwillis at glyphography.com>
Date: Fri Oct 12 18:22:41 2018 -0500
Docs: usermanual, minor cleanup to What Is HarfBuzz chapter.
diff --git a/docs/usermanual-what-is-harfbuzz.xml b/docs/usermanual-what-is-harfbuzz.xml
index 6a3ac102..0c961e2f 100644
--- a/docs/usermanual-what-is-harfbuzz.xml
+++ b/docs/usermanual-what-is-harfbuzz.xml
@@ -80,8 +80,8 @@
</para>
<para>
Text shaping is a fairly low-level operation. HarfBuzz is
- used directly by graphical rendering libraries like <ulink
- url="https://www.pango.org/">Pango</a>, as well as by the layout
+ used directly by text-handling libraries like <ulink
+ url="https://www.pango.org/">Pango</ulink>, as well as by the layout
engines in Firefox, LibreOffice, and Chromium. Unless you are
<emphasis>writing</emphasis> one of these layout engines
yourself, you will probably not need to use HarfBuzz: normally,
@@ -222,7 +222,7 @@
<title>What does HarfBuzz do?</title>
<para>
HarfBuzz provides OpenType text shaping through a cross-platform
- C API that accepts sequences of Unicode input text. Currently,
+ C API that accepts sequences of Unicode codepoints as input. Currently,
the following OpenType shaping models are supported:
</para>
<itemizedlist>
commit 443f87213272be5ae0579dce4749b2036dfe3815
Author: Nathan Willis <nwillis at glyphography.com>
Date: Thu Oct 11 15:40:08 2018 -0500
Docs: move harfbuzz-ng-vs-old discussion down below the TOC; put in note.
diff --git a/docs/harfbuzz-docs.xml b/docs/harfbuzz-docs.xml
index 21c251d0..48ea67e6 100644
--- a/docs/harfbuzz-docs.xml
+++ b/docs/harfbuzz-docs.xml
@@ -12,29 +12,20 @@
<graphic fileref="HarfBuzz.png" format="PNG" align="center"/>
<para>
HarfBuzz is an <ulink url="http://www.microsoft.com/typography/otspec/">OpenType</ulink>
- text shaping engine.
+ text shaping engine. Using the HarfBuzz library allows
+ programs to convert a sequence of Unicode input text into
+ properly formatted and positioned output—for any writing
+ system and language.
</para>
+
<para>
- The current HarfBuzz codebase, formerly known as harfbuzz-ng, is
- versioned 1.x.x and is stable and under active maintenance. This is
- what is used in latest versions of Firefox, GNOME, ChromeOS, Chrome,
- LibreOffice, XeTeX, Android, and KDE, among other places. The canonical
- source tree is available
- <ulink url="http://cgit.freedesktop.org/harfbuzz/">here</ulink>.
- Also available on
- <ulink url="https://github.com/harfbuzz/harfbuzz">github</ulink>.
+ The canonical source-code tree is available at
+ <ulink
+ url="http://cgit.freedesktop.org/harfbuzz/">cgit.freedesktop.org/harfbuzz</ulink>
+ and at
+ <ulink
+ url="https://github.com/harfbuzz/harfbuzz">github.com/harfbuzz/harfbuzz</ulink>.
See <xref linkend="download" endterm="download.title"/> for release tarballs.
- </para>
- <para>
- The old HarfBuzz codebase, these days known as harfbuzz-old, was
- derived from <ulink url="http://freetype.org/">FreeType</ulink>,
- <ulink url="http://pango.org/">Pango</ulink>, and
- <ulink url="http://qt-project.org/">Qt</ulink> and is available
- <ulink url="http://cgit.freedesktop.org/harfbuzz.old/">here</ulink>.
- It is not actively developed or maintained, and is extremely buggy. All
- users are encouraged to switch over to the new HarfBuzz as soon as
- possible. There are no release tarballs of old HarfBuzz whatsoever.
- </para>
</abstract>
</bookinfo>
@@ -58,6 +49,38 @@
<ulink role="online-location" url="http://[SERVER]/libharfbuzz/index.html">http://[SERVER]/libharfbuzz/</ulink>.-->
</releaseinfo>
</partinfo>
+
+ <note>
+ <para>
+ The current HarfBuzz codebase is versioned 1.x.x and is stable
+ and under active maintenance. This is what is used in latest
+ versions of Firefox, GNOME, ChromeOS, Chrome, LibreOffice,
+ XeTeX, Android, and KDE, among other places.
+ </para>
+ <para>
+ Prior to 2012, the original HarfBuzz codebase (which, these
+ days, is referred to as <emphasis>harfbuzz-old</emphasis>) was
+ derived from code in <ulink
+ url="http://freetype.org/">FreeType</ulink>, <ulink
+ url="http://pango.org/">Pango</ulink>, and
+ <ulink url="http://qt-project.org/">Qt</ulink>.
+ It is <emphasis>not</emphasis> actively developed or
+ maintained, and is extremely buggy. All users of harfbuzz-old
+ are encouraged to switch over to the new HarfBuzz as soon as possible.
+ </para>
+ <para>
+ To make this distinction clearer in discussions, the current
+ HarfBuzz codebase is sometimes referred to as
+ <emphasis>harfbuzz-ng</emphasis>.
+ </para>
+ <para>
+ For reference purposes, the harfbuzz-old source tree is archived
+ <ulink
+ url="http://cgit.freedesktop.org/harfbuzz.old/">here</ulink>. There
+ are no release tarballs of harfbuzz-old whatsoever.
+ </para>
+ </note>
+
<title>Reference manual</title>
<chapter>
<title>Core API</title>
commit 792af5d254fddcdc4292dffb76b81d65754e65a9
Author: Nathan Willis <nwillis at glyphography.com>
Date: Thu Oct 11 14:05:59 2018 -0500
Docs: flesh out config options in Usermanual:Install chapter.
diff --git a/docs/usermanual-install-harfbuzz.xml b/docs/usermanual-install-harfbuzz.xml
index f032b888..cd1e2e13 100644
--- a/docs/usermanual-install-harfbuzz.xml
+++ b/docs/usermanual-install-harfbuzz.xml
@@ -229,6 +229,10 @@
<para>
Allow linking with libstdc++. <emphasis>(Default = no)</emphasis>
</para>
+ <para>
+ This option enables or disables linking HarfBuzz to the
+ system's libstdc++ library.
+ </para>
</listitem>
</varlistentry>
@@ -236,8 +240,15 @@
<term>--with-glib</term>
<listitem>
<para>
- Use GLib. <emphasis>(Default = auto)</emphasis>
+ Use <ulink url="https://developer.gnome.org/glib/">GLib</ulink>. <emphasis>(Default = auto)</emphasis>
</para>
+ <para>
+ This option enables or disables usage of the GLib
+ library. The default setting is to check for the
+ presence of GLib and, if it is found, build with
+ GLib support. GLib is native to GNU/Linux systems but is
+ available on other operating system as well.
+ </para>
</listitem>
</varlistentry>
@@ -245,8 +256,15 @@
<term>--with-gobject</term>
<listitem>
<para>
- Use GObject. <emphasis>(Default = no)</emphasis>
- </para>
+ Use <ulink url="https://developer.gnome.org/gobject/stable/">GObject</ulink>. <emphasis>(Default = no)</emphasis>
+ </para>
+ <para>
+ This option enables or disables usage of the GObject
+ library. The default setting is to check for the
+ presence of GObject and, if it is found, build with
+ GObject support. GObject is native to GNU/Linux systems but is
+ available on other operating system as well.
+ </para>
</listitem>
</varlistentry>
@@ -254,8 +272,14 @@
<term>--with-cairo</term>
<listitem>
<para>
- Use Cairo. <emphasis>(Default = auto)</emphasis>
- </para>
+ Use <ulink url="https://cairographics.org/">Cairo</ulink>. <emphasis>(Default = auto)</emphasis>
+ </para>
+ <para>
+ This option enables or disables usage of the Cairo
+ graphics-rendering library. The default setting is to
+ check for the presence of Cairo and, if it is found,
+ build with Cairo support.
+ </para>
</listitem>
</varlistentry>
@@ -263,8 +287,15 @@
<term>--with-fontconfig</term>
<listitem>
<para>
- Use Fontconfig. <emphasis>(Default = auto)</emphasis>
+ Use <ulink url="https://www.freedesktop.org/wiki/Software/fontconfig/">Fontconfig</ulink>. <emphasis>(Default = auto)</emphasis>
</para>
+ <para>
+ This option enables or disables usage of the Fontconfig
+ library, which provides font-matching functions and
+ provides access to font properties. The default setting
+ is to check for the presence of Fontconfig and, if it is
+ found, build with Fontconfig support.
+ </para>
</listitem>
</varlistentry>
@@ -272,8 +303,17 @@
<term>--with-icu</term>
<listitem>
<para>
- Use the ICU library. <emphasis>(Default = auto)</emphasis>
+ Use the <ulink url="http://site.icu-project.org/home">ICU</ulink> library. <emphasis>(Default = auto)</emphasis>
</para>
+ <para>
+ This option enables or disables usage of the
+ <emphasis>International Components for
+ Unicode</emphasis> (ICU) library, which provides access
+ to Unicode Character Database (UCD) properties as well
+ as normalization and conversion functions. The default
+ setting is to check for the presence of ICU and, if it
+ is found, build with ICU support.
+ </para>
</listitem>
</varlistentry>
@@ -281,8 +321,17 @@
<term>--with-ucdn</term>
<listitem>
<para>
- Use the built-in UCDN library. <emphasis>(Default = auto)</emphasis>
+ Use HarfBuzz's <ulink url="https://github.com/harfbuzz/harfbuzz/tree/master/src/hb-ucdn">built-in UCDN library</ulink>. <emphasis>(Default = auto)</emphasis>
</para>
+ <para>
+ The HarfBuzz source tree includes a <emphasis>Unicode
+ Database and Normalization</emphasis> (UCDN) library
+ that provides access to basic character properties in
+ the Unicode Character Database (UCD) as well as low-level
+ normalization functions. HarfBuzz can be built without
+ this UCDN support if the usage of a different UCDN
+ library is desired.
+ </para>
</listitem>
</varlistentry>
@@ -290,8 +339,13 @@
<term>--with-graphite2</term>
<listitem>
<para>
- Use the graphite2 library. <emphasis>(Default = no)</emphasis>
+ Use the <ulink url="http://graphite.sil.org/">Graphite2</ulink> library. <emphasis>(Default = no)</emphasis>
</para>
+ <para>
+ This option enables or disables usage of the Graphite2
+ library, which provides support for the Graphite shaping
+ model.
+ </para>
</listitem>
</varlistentry>
@@ -299,8 +353,14 @@
<term>--with-freetype</term>
<listitem>
<para>
- Use the FreeType library. <emphasis>(Default = auto)</emphasis>
+ Use the <ulink url="https://www.freetype.org/">FreeType</ulink> library. <emphasis>(Default = auto)</emphasis>
</para>
+ <para>
+ This option enables or disables usage of the FreeType
+ font-rendering library. The default setting is to check for the
+ presence of FreeType and, if it is found, build with
+ FreeType support.
+ </para>
</listitem>
</varlistentry>
@@ -308,8 +368,12 @@
<term>--with-uniscribe</term>
<listitem>
<para>
- Use the Uniscribe library. <emphasis>(Default = no)</emphasis>
+ Use the <ulink url="https://docs.microsoft.com/en-us/windows/desktop/intl/uniscribe">Uniscribe</ulink> library. <emphasis>(Default = no)</emphasis>
</para>
+ <para>
+ This option enables or disables usage of the Uniscribe
+ font-rendering library. Uniscribe is available on Windows systems.
+ </para>
</listitem>
</varlistentry>
@@ -317,8 +381,12 @@
<term>--with-directwrite</term>
<listitem>
<para>
- se the DirectWrite library (experimental). <emphasis>(Default = no)</emphasis>
+ Use the <ulink url="https://docs.microsoft.com/en-us/windows/desktop/directwrite/direct-write-portal">DirectWrite</ulink> library (experimental). <emphasis>(Default = no)</emphasis>
</para>
+ <para>
+ This option enables or disables usage of the DirectWrite
+ font-rendering library. DirectWrite is available on Windows systems.
+ </para>
</listitem>
</varlistentry>
@@ -326,20 +394,14 @@
<term>--with-coretext</term>
<listitem>
<para>
- Use the CoreText library. <emphasis>(Default = no)</emphasis>
+ Use the <ulink url="https://developer.apple.com/documentation/coretext">CoreText</ulink> library. <emphasis>(Default = no)</emphasis>
</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term></term>
- <listitem>
<para>
- <emphasis>(Default = no)</emphasis>
- </para>
+ This option enables or disables usage of the CoreText
+ library. CoreText is available on macOS and iOS systems.
+ </para>
</listitem>
- </varlistentry>
-
+ </varlistentry>
</variablelist>
</section>
commit 325e2745cfa55f9ef114ee8eeaf7bd8176743822
Author: Nathan Willis <nwillis at glyphography.com>
Date: Wed Oct 10 17:01:21 2018 -0500
Docs: add basic config-options section to Usermanual Installation chapter.
diff --git a/docs/usermanual-install-harfbuzz.xml b/docs/usermanual-install-harfbuzz.xml
index 9d10e2da..f032b888 100644
--- a/docs/usermanual-install-harfbuzz.xml
+++ b/docs/usermanual-install-harfbuzz.xml
@@ -51,7 +51,8 @@
<para>
For example, on an Ubuntu or Debian system, you would run:
<programlisting>
- <command>sudo apt install</command> <package>gcc g++ libfreetype6-dev libglib2.0-dev libcairo2-dev</package>
+ <command>sudo apt install</command> <package>gcc g++
+ libfreetype6-dev libglib2.0-dev libcairo2-dev</package>
</programlisting>
On Fedora, RHEL, CentOS, or other Red-Hat–based systems, you would run:
<programlisting>
@@ -212,6 +213,135 @@
</section>
+ <section id="configuration">
+ <title>Configuration options</title>
+
+ <para>
+ The instructions in the "Building HarfBuzz" section will build
+ the source code under its default configuration. If needed,
+ the following additional configuration options are available.
+ </para>
+
+ <variablelist>
+ <varlistentry>
+ <term>--with-libstdc++</term>
+ <listitem>
+ <para>
+ Allow linking with libstdc++. <emphasis>(Default = no)</emphasis>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>--with-glib</term>
+ <listitem>
+ <para>
+ Use GLib. <emphasis>(Default = auto)</emphasis>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>--with-gobject</term>
+ <listitem>
+ <para>
+ Use GObject. <emphasis>(Default = no)</emphasis>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>--with-cairo</term>
+ <listitem>
+ <para>
+ Use Cairo. <emphasis>(Default = auto)</emphasis>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>--with-fontconfig</term>
+ <listitem>
+ <para>
+ Use Fontconfig. <emphasis>(Default = auto)</emphasis>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>--with-icu</term>
+ <listitem>
+ <para>
+ Use the ICU library. <emphasis>(Default = auto)</emphasis>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>--with-ucdn</term>
+ <listitem>
+ <para>
+ Use the built-in UCDN library. <emphasis>(Default = auto)</emphasis>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>--with-graphite2</term>
+ <listitem>
+ <para>
+ Use the graphite2 library. <emphasis>(Default = no)</emphasis>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>--with-freetype</term>
+ <listitem>
+ <para>
+ Use the FreeType library. <emphasis>(Default = auto)</emphasis>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>--with-uniscribe</term>
+ <listitem>
+ <para>
+ Use the Uniscribe library. <emphasis>(Default = no)</emphasis>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>--with-directwrite</term>
+ <listitem>
+ <para>
+ se the DirectWrite library (experimental). <emphasis>(Default = no)</emphasis>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>--with-coretext</term>
+ <listitem>
+ <para>
+ Use the CoreText library. <emphasis>(Default = no)</emphasis>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term></term>
+ <listitem>
+ <para>
+ <emphasis>(Default = no)</emphasis>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+ </section>
</section>
</chapter>
commit 97c1c46cd2241d77b531a582dd1a2432af976357
Author: Nathan Willis <nwillis at glyphography.com>
Date: Wed Oct 10 16:38:22 2018 -0500
Docs: update and linearize build instructions; add installation overview material.
diff --git a/docs/usermanual-install-harfbuzz.xml b/docs/usermanual-install-harfbuzz.xml
index 899cc5bd..9d10e2da 100644
--- a/docs/usermanual-install-harfbuzz.xml
+++ b/docs/usermanual-install-harfbuzz.xml
@@ -1,70 +1,217 @@
<chapter id="install-harfbuzz">
- <title>Install HarfBuzz</title>
+ <title>Installing HarfBuzz</title>
+
<section id="download">
- <title id="download.title">Download</title>
+ <title id="download.title">Downloading HarfBuzz</title>
<para>
- For tarball releases of HarfBuzz, look
- <ulink url="http://www.freedesktop.org/software/harfbuzz/release/">here</ulink>.
- At the same place you will
- also find Win32 binary bundles that include libharfbuzz DLL, hb-view.exe,
- hb-shape.exe, and all dependencies.
+ The HarfBuzz source code is hosted at <ulink
+ url="https://github.com/harfbuzz/harfbuzz">github.com/harfbuzz/harfbuzz</ulink>. The
+ same source tree is also available at the
+ <ulink
+ url="http://cgit.freedesktop.org/harfbuzz/">Freedesktop.org</ulink>
+ site.
</para>
<para>
- The canonical source tree is available
- <ulink url="http://cgit.freedesktop.org/harfbuzz/">here</ulink>.
- Also available on <ulink url="https://github.com/harfbuzz/harfbuzz">github</ulink>.
+ Tarball releases and Win32 binary bundles (which include the
+ libharfbuzz DLL, hb-view.exe, hb-shape.exe, and all
+ dependencies) of HarfBuzz can be downloaded from <ulink
+ url="https://github.com/harfbuzz/harfbuzz">github.com/harfbuzz/harfbuzz/releases</ulink>
+ or from
+ <ulink url="http://www.freedesktop.org/software/harfbuzz/release/">Freedesktop.org</ulink>.
</para>
<para>
- The API that comes with <filename class='headerfile'>hb.h</filename> will
- not change incompatibly. Other, peripheral, headers are more likely to go
- through minor modifications, but again, will do our best to never change
- API in an incompatible way. We will never break the ABI.
+ Release notes are posted with each new release to provide an
+ overview of the changes. The project <ulink url="https://github.com/harfbuzz/harfbuzz/issues">tracks bug
+ reports and other issues</ulink> on GitHub. Discussion and
+ questions are welcome on the <ulink
+ url="http://freedesktop.org/mailman/listinfo/harfbuzz/">HarfBuzz
+ mailing list</ulink>.
</para>
<para>
- If you are not sure whether Pango or HarfBuzz is right for you, read
- <ulink url="http://mces.blogspot.in/2009/11/pango-vs-harfbuzz.html">this</ulink>.
+ The API included in the <filename
+ class='headerfile'>hb.h</filename> file will not change in a
+ compatibility-breaking way in any release. However, other,
+ peripheral headers are more likely to go through minor
+ modifications. We will do our best to never change APIs in an
+ incompatible way. We will <emphasis>never</emphasis> break the ABI.
</para>
</section>
+
<section id="building">
- <title>Building</title>
+ <title>Building HarfBuzz</title>
+
+ <section id="building.linux">
+ <title>Building on Linux</title>
<para>
- On Linux, install the development packages for FreeType, Cairo, and GLib.
- For example, on Ubuntu / Debian, you would do:
- <programlisting>
-<command>sudo apt-get install</command> <package>gcc g++ libfreetype6-dev libglib2.0-dev libcairo2-dev</package>
- </programlisting>
- whereas on Fedora, RHEL, CentOS, and other Red Hat based systems you would do:
+ <emphasis>(1)</emphasis> To build HarfBuzz on Linux, you must first install the
+ development packages for FreeType, Cairo, and GLib. The exact
+ commands required for this step will vary depending on
+ the Linux distribution you use.
+ </para>
+ <para>
+ For example, on an Ubuntu or Debian system, you would run:
<programlisting>
-<command>sudo yum install</command> <package>gcc gcc-c++ freetype-devel glib2-devel cairo-devel</package>
+ <command>sudo apt install</command> <package>gcc g++ libfreetype6-dev libglib2.0-dev libcairo2-dev</package>
</programlisting>
- or using MacPorts:
+ On Fedora, RHEL, CentOS, or other Red-Hat–based systems, you would run:
<programlisting>
-<command>sudo port install</command> <package>freetype glib2 cairo</package>
+ <command>sudo yum install</command> <package>gcc gcc-c++ freetype-devel glib2-devel cairo-devel</package>
</programlisting>
+
+ </para>
+
+ <para>
+ <emphasis>(2)</emphasis> The next step depends on whether you
+ are building from the source in a downloaded release tarball or
+ from the source directly from the git repository.
+ </para>
+ <para>
+ <emphasis>(2)(a)</emphasis> If you downloaded the HarfBuzz
+ source code in a tarball, you can now extract the source.
+ </para>
+ <para>
+ From a shell in the top-level directory of the extracted source
+ code, you can run <command>./configure</command> followed by
+ <command>make</command> as with any other standard package.
+ </para>
+ <para>
+ This should leave you with a shared
+ library in the <filename>src/</filename> directory, and a few
+ utility programs including <command>hb-view</command> and
+ <command>hb-shape</command> under the <filename>util/</filename>
+ directory.
</para>
<para>
- If you are using a tarball, you can now proceed to running
- <command>configure</command> and <command>make</command> as with any
- other standard package. That should leave you with a shared library in
- <filename>src/</filename>, and a few utility programs including hb-view
- and hb-shape under <filename>util/</filename>.
+ <emphasis>(2)(b)</emphasis> If you are building from the source in the HarfBuzz git
+ repository, rather than installing from a downloaded tarball
+ release, then you must install two more auxiliary tools before you
+ can build for the first time: <package>pkg-config</package> and
+ <ulink url="http://www.complang.org/ragel/">ragel</ulink>.
</para>
<para>
- If you are bootstrapping from git, you need a few more tools before you
- can run <filename>autogen.sh</filename> for the first time. Namely,
- pkg-config and <ulink url="http://www.complang.org/ragel/">ragel</ulink>.
- Again, on Ubuntu / Debian:
+ On Ubuntu or Debian, run:
<programlisting>
-<command>sudo apt-get install</command> <package>autoconf automake libtool pkg-config ragel gtk-doc-tools</package>
+ <command>sudo apt-get install</command> <package>autoconf automake libtool pkg-config ragel gtk-doc-tools</package>
</programlisting>
- and on Fedora, RHEL, CentOS:
+ On Fedora, RHEL, CentOS, run:
<programlisting>
-<command>sudo yum install</command> <package>autoconf automake libtool pkgconfig ragel gtk-doc</package>
+ <command>sudo yum install</command> <package>autoconf automake libtool pkgconfig ragel gtk-doc</package>
</programlisting>
- or using MacPorts:
+
+ </para>
+ <para>
+ With <package>pkg-config</package> and <package>ragel</package>
+ installed, you can now run <command>./autogen.sh</command>,
+ followed by <command>./configure</command> and
+ <command>make</command> to build HarfBuzz.
+ </para>
+ </section>
+
+
+ <section id="building.windows">
+ <title>Building on Windows</title>
+
+ <para>
+ On Windows, consider using Microsoft's free <ulink
+ url="https://github.com/Microsoft/vcpkg">vcpkg</ulink> utility
+ to build HarfBuzz, its dependencies, and other open-source
+ libraries.
+ </para>
+ <para>
+ If you need to build HarfBuzz from source, first put the
+ <program>ragel</program> binary on your
+ <literal>PATH</literal>, then follow the appveyor CI cmake
+ <ulink
+ url="https://github.com/harfbuzz/harfbuzz/blob/master/appveyor.yml">build
+ instructions</ulink>.
+ </para>
+ </section>
+
+
+ <section id="building.macos">
+ <title>Building on macOS</title>
+
+ <para>
+ There are two ways to build HarfBuzz on Mac systems: MacPorts
+ and Homebrew. The process is similar to the process used on a
+ Linux system.
+ </para>
+ <para>
+ <emphasis>(1)</emphasis> You must first install the
+ development packages for FreeType, Cairo, and GLib. If you are
+ using MacPorts, you should run:
<programlisting>
-<command>sudo port install</command> <package>autoconf automake libtool pkgconfig ragel gtk-doc</package>
+ <command>sudo port install</command> <package>freetype glib2 cairo</package>
</programlisting>
- </para>
+ </para>
+ <para>
+ If you are using Homebrew, you should run:
+ <programlisting>
+ <command>brew install</command> <package>freetype glib cairo</package>
+ </programlisting>
+ </para>
+ <para>
+ <emphasis>(2)</emphasis> The next step depends on whether you are building from the
+ source in a downloaded release tarball or from the source directly
+ from the git repository.
+ </para>
+ <para>
+ <emphasis>(2)(a)</emphasis> If you are installing HarfBuzz
+ from a downloaded tarball release, extract the tarball and
+ open a Terminal in the extracted source-code directory. Run:
+ <programlisting>
+ <command>./configure</command>
+ </programlisting>
+ followed by:
+ <programlisting>
+ <command>make</command>
+ </programlisting>
+ to build HarfBuzz.
+ </para>
+ <para>
+ <emphasis>(2)(b)</emphasis> Alternatively, if you are building
+ HarfBuzz from the source in the HarfBuzz git repository, then
+ you must install several built-time dependencies before
+ proceeding.
+ </para>
+ <para>If you are
+ using MacPorts, you should run:
+ <programlisting>
+ <command>sudo port install</command> <package>autoconf
+ automake libtool pkgconfig ragel gtk-doc</package>
+ </programlisting>
+ to install the build dependencies.
+ </para>
+ <para>If you are using Homebrew, you should run:
+ <programlisting>
+ <command>brew install</command> <package>autoconf automake libtool pkgconfig ragel gtk-doc</package>
+ </programlisting>
+ Finally, you can run:
+ <programlisting>
+ <command>./autogen.sh</command>
+ </programlisting>
+ </para>
+ <para>
+ <emphasis>(3)</emphasis> You can now build HarfBuzz (on either
+ a MacPorts or a Homebrew system) by running:
+ <programlisting>
+ <command>./configure</command>
+ </programlisting>
+ followed by:
+ <programlisting>
+ <command>make</command>
+ </programlisting>
+ </para>
+ <para>
+ This should leave you with a shared
+ library in the <filename>src/</filename> directory, and a few
+ utility programs including <command>hb-view</command> and
+ <command>hb-shape</command> under the <filename>util/</filename>
+ directory.
+ </para>
+
+ </section>
+
+
</section>
</chapter>
commit 088755f9e654d2ec638dce0c68d523084b9eaf5a
Author: Nathan Willis <nwillis at glyphography.com>
Date: Wed Oct 10 16:37:29 2018 -0500
Docs: update usermanual What Is HarfBuzz material.
diff --git a/docs/usermanual-what-is-harfbuzz.xml b/docs/usermanual-what-is-harfbuzz.xml
index 3a98b53f..6a3ac102 100644
--- a/docs/usermanual-what-is-harfbuzz.xml
+++ b/docs/usermanual-what-is-harfbuzz.xml
@@ -11,8 +11,8 @@
</para>
<para>
HarfBuzz can properly shape all of the world's major writing
- systems. It runs on virtually all operating systems and software
- platforms, and it supports all of the standard font formats in use
+ systems. It runs on all major operating systems and software
+ platforms, and it supports all of the modern font formats in use
today.
</para>
<section id="what-is-text-shaping">
@@ -41,9 +41,7 @@
<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
+ various scripts from around the world. These shaping models depend on
the font including certain features in its <literal>GSUB</literal>
and <literal>GPOS</literal> tables.
</para>
@@ -55,12 +53,13 @@
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.
+ support. AAT fonts are generally only found on macOS and iOS 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>
+ tag that provide the context needed to perform text shaping
+ correctly. The necessary <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.
@@ -72,24 +71,25 @@
<para>
Text shaping is an integral part of preparing text for
display. Before a Unicode sequence can be rendered, the
- codepoints in the sequence must be mapped to the glyphs
- provided in the font, and the glyphs must be positioned
+ codepoints in the sequence must be mapped to the corresponding
+ glyphs provided in the font, and those glyphs must be positioned
correctly relative to each other. For many of the scripts
supported in Unicode, these steps involve script-specific layout
- rules.
+ rules, including complex joining, reordering, and positioning
+ behavior. Implementing these rules is the job of the shaping engine.
</para>
<para>
Text shaping is a fairly low-level operation. HarfBuzz is
- used directly by graphic rendering libraries such as Pango, as
- well as by the layout engines in Firefox, LibreOffice, and
- Chromium. Unless you are <emphasis>writing</emphasis> one of
- these layout engines yourself, you will probably not need to use
- HarfBuzz: normally, lower-level libraries will turn text into
- glyphs for you.
+ used directly by graphical rendering libraries like <ulink
+ url="https://www.pango.org/">Pango</a>, as well as by the layout
+ engines in Firefox, LibreOffice, and Chromium. Unless you are
+ <emphasis>writing</emphasis> one of these layout engines
+ yourself, you will probably not need to use HarfBuzz: normally,
+ lower-level libraries will turn text into glyphs for you.
</para>
<para>
However, if you <emphasis>are</emphasis> writing a layout engine
- or graphics library yourself, you will need to perform text
+ or graphics library yourself, then you will need to perform text
shaping, and this is where HarfBuzz can help you.
</para>
<para>
@@ -104,14 +104,15 @@
all other symbols), which are indexed by a <literal>glyph ID</literal>.
</para>
<para>
- The glyph ID within the font does not necessarily correlate
- to a predictable Unicode codepoint. For instance, some fonts
- have the letter "a" as glyph ID 1, but many others do
- not. To pull the right glyph out of the font in order to
- display "a", you need to consult the table inside
- the font (the <literal>cmap</literal> table) that maps Unicode
- codepoints to glyph IDs. In other words, <emphasis>text shaping turns
- codepoints into glyph IDs</emphasis>.
+ A particular glyph ID within the font does not necessarily
+ correlate to a predictable Unicode codepoint. For instance,
+ some fonts have the letter "a" as glyph ID 1, but
+ many others do not. In order to retrieve the right glyph
+ from the font to display "a", you need to consult
+ the table inside the font (the <literal>cmap</literal>
+ table) that maps Unicode codepoints to glyph IDs. In other
+ words, <emphasis>text shaping turns codepoints into glyph
+ IDs</emphasis>.
</para>
</listitem>
<listitem>
@@ -125,7 +126,7 @@
<para>
Whether you should render an "f, i" sequence
as <literal>fi</literal> or as "fi" does not
- depend on the input text. Rather, it depends on the whether
+ depend on the input text. Instead, it depends on the whether
or not the font includes an "fi" glyph and on the
level of ligature application you wish to perform. The font
and the amount of ligature application used are under your
@@ -195,26 +196,148 @@
right position, you need to consult the table inside
the font (the <literal>GPOS</literal> table) that contains
positioning information.
- In other words, <emphasis>text shaping tells you whether you have a
- precomposed glyph within your font or if you need to compose a
- glyph yourself out of combining marks—and, if so, where to
- position those marks.</emphasis>
+ In other words, <emphasis>text shaping tells you whether you
+ have a precomposed glyph within your font or if you need to
+ compose a glyph yourself out of combining marks—and,
+ if so, where to position those marks.</emphasis>
</para>
</listitem>
</itemizedlist>
<para>
- If tasks like these are something that you need to do, then you need a text
- shaping engine. You could use Uniscribe if you are writing
- Windows software; you could use CoreText on macOS; or you could
- use HarfBuzz.
+ If tasks like these are something that you need to do, then you
+ need a text shaping engine. You could use Uniscribe if you are
+ writing Windows software; you could use CoreText on macOS; or
+ you could use HarfBuzz.
+ </para>
+ <note>
+ <para>
+ In the rest of this manual, the text will assume that the reader
+ is that implementor of a text-layout engine.
+ </para>
+ </note>
+ </section>
+
+
+ <section>
+ <title>What does HarfBuzz do?</title>
+ <para>
+ HarfBuzz provides OpenType text shaping through a cross-platform
+ C API that accepts sequences of Unicode input text. Currently,
+ the following OpenType shaping models are supported:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Indic (covering Devanagari, Bengali, Gujarati,
+ Gurmukhi, Kannada, Malayalam, Oriya, Tamil, Telugu, and
+ Sinhala)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Arabic (covering Arabic, N'Ko, Syriac, and Mongolian)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Thai and Lao
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Khmer
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Myanmar
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Tibetan
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Hangul
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Hebrew
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The Universal Shaping Engine or <emphasis>USE</emphasis>
+ (covering complex scripts not covered by the above shaping
+ models)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ A default shaping model for non-complex scripts
+ (covering Latin, Cyrillic, Greek, Armenian, Georgian, Tifinagh,
+ and many others)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Emoji (including emoji modifier sequences, flag sequences,
+ and ZWJ sequences)
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ <para>
+ In addition to OpenType shaping, HarfBuzz supports the latest
+ version of Graphite shaping. HarfBuzz currently supports AAT
+ shaping only on macOS and iOS systems, and in a pass-through
+ fashion: HarfBuzz hands off AAT support to the system CoreText
+ library. However, full, built-in AAT support within HarfBuzz is
+ under development.
+ </para>
+
+ <para>
+ HarfBuzz can read and understand TrueType fonts (.ttf), TrueType
+ collections (.ttc), and OpenType fonts (.otf, including those
+ fonts that contain TrueType-style outlines and those that
+ contain PostScript CFF or CFF2 outlines).
+ </para>
+
+ <para>
+ HarfBuzz can run on top of the FreeType, CoreText, DirectWrite,
+ or Uniscribe font renderers.
</para>
+
<para>
- In the rest of this manual, we are going to assume that you are the
- implementor of a text-layout engine.
+ In addition to its core shaping functionality, HarfBuzz provides
+ functions for accessing other font features, including optional
+ GSUB and GPOS OpenType features, as well as
+ all color-font formats (<literal>CBDT</literal>,
+ <literal>sbix</literal>, <literal>COLR/CPAL</literal>, and
+ <literal>SVG-OT</literal>) and OpenType variable fonts. HarfBuzz
+ also includes a font-subsetting feature.
+ </para>
+
+ <para>
+ HarfBuzz can perform some low-level math-shaping operations,
+ although it does not currently perform full shaping for
+ mathematical typesetting.
+ </para>
+
+ <para>
+ A suite of command-line utilities is also provided in the
+ source-code tree, designed to help users test and debug
+ HarfBuzz's features on real-world fonts and input.
</para>
</section>
-
- <section id="what-harfbuzz-doesnt-do">
+
+ <section id="what-harfbuzz-doesnt-do">
<title>What HarfBuzz doesn't do</title>
<para>
HarfBuzz will take a Unicode string, shape it, and give you the
@@ -223,7 +346,7 @@
extent of HarfBuzz's responsibility.
</para>
<para>
- It is important to note that if you are implementing a
+ It is important to note that if you are implementing a complete
text-layout engine you may have other responsibilities that
HarfBuzz will <emphasis>not</emphasis> help you with. For example:
</para>
@@ -239,13 +362,13 @@
sequence:
</para>
<programlisting>
-A B C [space] ג ב א [space] D E F
+ A B C [space] ג ב א [space] D E F
</programlisting>
<para>
but will expect to see in the output:
</para>
<programlisting>
-ABC אבג DEF
+ ABC אבג DEF
</programlisting>
<para>
This reordering is called <emphasis>bidi processing</emphasis>
@@ -253,8 +376,9 @@ ABC אבג DEF
algorithm as an annex to the Unicode Standard which tells you how
to reorder a string from logical order into presentation order.
Before sending your string to HarfBuzz, you may need to apply the
- bidi algorithm to it. Libraries such as ICU and fribidi can do
- this for you.
+ bidi algorithm to it. Libraries such as <ulink
+ url="http://icu-project.org/">ICU</ulink> and <ulink
+ url="http://fribidi.org/">fribidi</a> can do this for you.
</para>
</listitem>
<listitem>
@@ -304,7 +428,7 @@ ABC אבג DEF
returns is up to you.
</para>
</section>
-
+
<section id="why-is-it-called-harfbuzz">
<title>Why is it called HarfBuzz?</title>
<para>
@@ -312,9 +436,9 @@ ABC אבג DEF
project (and you will see references to the FreeType authors
within the source code copyright declarations), but was then
extracted out to its own project. This project is maintained by
- Behdad Esfahbod, and named HarfBuzz. Originally, it was a shaping
- engine for OpenType fonts—"HarfBuzz" is the Persian
- for "open type".
+ Behdad Esfahbod, who named it HarfBuzz. Originally, it was a
+ shaping engine for OpenType fonts—"HarfBuzz" is
+ the Persian for "open type".
</para>
</section>
</chapter>
commit 0956ab41851d30f50c39c28730cf30ea0bbc5466
Author: Nathan Willis <nwillis at glyphography.com>
Date: Fri Sep 28 17:15:59 2018 -0500
Docs: Move What-HarfBuzz-doesnt-do to Usermanual-what-is-HarfBuzz.
diff --git a/docs/usermanual-hello-harfbuzz.xml b/docs/usermanual-hello-harfbuzz.xml
index 716b2f2d..221692c6 100644
--- a/docs/usermanual-hello-harfbuzz.xml
+++ b/docs/usermanual-hello-harfbuzz.xml
@@ -90,94 +90,10 @@
hb_buffer_destroy(buf);
hb_font_destroy(hb_ft_font);
</programlisting>
- <section id="what-harfbuzz-doesnt-do">
- <title>What HarfBuzz doesn't do</title>
- <para>
- The code above will take a UTF8 string, shape it, and give you the
- information required to lay it out correctly on a single
- horizontal (or vertical) line using the font provided. That is the
- extent of HarfBuzz's responsibility.
- </para>
- <para>
- If you are implementing a text layout engine you may have other
- responsibilities, that HarfBuzz will not help you with:
- </para>
- <itemizedlist>
- <listitem>
- <para>
- HarfBuzz won't help you with bidirectionality. If you want to
- lay out text with mixed Hebrew and English, you will need to
- ensure that the buffer provided to HarfBuzz has those
- characters in the correct layout order. This will be different
- from the logical order in which the Unicode text is stored. In
- other words, the user will hit the keys in the following
- sequence:
- </para>
- <programlisting>
-A B C [space] ג ב א [space] D E F
- </programlisting>
- <para>
- but will expect to see in the output:
- </para>
- <programlisting>
-ABC אבג DEF
- </programlisting>
- <para>
- This reordering is called <emphasis>bidi processing</emphasis>
- ("bidi" is short for bidirectional), and there's an
- algorithm as an annex to the Unicode Standard which tells you how
- to reorder a string from logical order into presentation order.
- Before sending your string to HarfBuzz, you may need to apply the
- bidi algorithm to it. Libraries such as ICU and fribidi can do
- this for you.
- </para>
- </listitem>
- <listitem>
- <para>
- HarfBuzz won't help you with text that contains different font
- properties. For instance, if you have the string "a
- <emphasis>huge</emphasis> breakfast", and you expect
- "huge" to be italic, you will need to send three
- strings to HarfBuzz: <literal>a</literal>, in your Roman font;
- <literal>huge</literal> using your italic font; and
- <literal>breakfast</literal> using your Roman font again.
- Similarly if you change font, font size, script, language or
- direction within your string, you will need to shape each run
- independently and then output them independently. HarfBuzz
- expects to shape a run of characters sharing the same
- properties.
- </para>
- </listitem>
- <listitem>
- <para>
- HarfBuzz won't help you with line breaking, hyphenation or
- justification. As mentioned above, it lays out the string
- along a <emphasis>single line</emphasis> of, notionally,
- infinite length. If you want to find out where the potential
- word, sentence and line break points are in your text, you
- could use the ICU library's break iterator functions.
- </para>
- <para>
- HarfBuzz can tell you how wide a shaped piece of text is, which is
- useful input to a justification algorithm, but it knows nothing
- about paragraphs, lines or line lengths. Nor will it adjust the
- space between words to fit them proportionally into a line. If you
- want to layout text in paragraphs, you will probably want to send
- each word of your text to HarfBuzz to determine its shaped width
- after glyph substitutions, then work out how many words will fit
- on a line, and then finally output each word of the line separated
- by a space of the correct size to fully justify the paragraph.
- </para>
- </listitem>
- </itemizedlist>
- <para>
- As a layout engine implementor, HarfBuzz will help you with the
- interface between your text and your font, and that's something
- that you'll need - what you then do with the glyphs that your font
- returns is up to you. The example we saw above enough to get us
- started using HarfBuzz. Now we are going to use the remainder of
- HarfBuzz's API to refine that example and improve our text shaping
- capabilities.
- </para>
- </section>
-</chapter>
\ No newline at end of file
+
+<para>
+ This example shows enough to get us started using HarfBuzz. Now we
+ are going to use the remainder of HarfBuzz's API to refine that
+ example and improve our text shaping capabilities.
+</para>
+</chapter>
diff --git a/docs/usermanual-what-is-harfbuzz.xml b/docs/usermanual-what-is-harfbuzz.xml
index 59df9e3f..3a98b53f 100644
--- a/docs/usermanual-what-is-harfbuzz.xml
+++ b/docs/usermanual-what-is-harfbuzz.xml
@@ -1,13 +1,13 @@
<chapter id="what-is-harfbuzz">
<title>What is HarfBuzz?</title>
<para>
- HarfBuzz is a <emphasis>text shaping engine</emphasis>. If you
+ HarfBuzz is a <emphasis>text-shaping engine</emphasis>. If you
give HarfBuzz a font and a string containing a sequence of Unicode
codepoints, HarfBuzz selects and positions the corresponding
glyphs from the font, applying all of the necessary layout rules
and font features. HarfBuzz then returns the string to you in the
form that is correctly arranged for the language and writing
- system.
+ system.
</para>
<para>
HarfBuzz can properly shape all of the world's major writing
@@ -21,7 +21,7 @@
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.
+ final output form for inclusion in a document.
</para>
<para>
The shaping process is dependent on the input string, the active
@@ -66,6 +66,7 @@
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>
@@ -212,6 +213,98 @@
implementor of a text-layout engine.
</para>
</section>
+
+ <section id="what-harfbuzz-doesnt-do">
+ <title>What HarfBuzz doesn't do</title>
+ <para>
+ HarfBuzz will take a Unicode string, shape it, and give you the
+ information required to lay it out correctly on a single
+ horizontal (or vertical) line using the font provided. That is the
+ extent of HarfBuzz's responsibility.
+ </para>
+ <para>
+ It is important to note that if you are implementing a
+ text-layout engine you may have other responsibilities that
+ HarfBuzz will <emphasis>not</emphasis> help you with. For example:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ HarfBuzz won't help you with bidirectionality. If you want to
+ lay out text that includes a mix of Hebrew and English, you
+ will need to ensure that each buffer provided to HarfBuzz has its
+ characters in the correct layout order. This will be different
+ from the logical order in which the Unicode text is stored. In
+ other words, the user will hit the keys in the following
+ sequence:
+ </para>
+ <programlisting>
+A B C [space] ג ב א [space] D E F
+ </programlisting>
+ <para>
+ but will expect to see in the output:
+ </para>
+ <programlisting>
+ABC אבג DEF
+ </programlisting>
+ <para>
+ This reordering is called <emphasis>bidi processing</emphasis>
+ ("bidi" is short for bidirectional), and there's an
+ algorithm as an annex to the Unicode Standard which tells you how
+ to reorder a string from logical order into presentation order.
+ Before sending your string to HarfBuzz, you may need to apply the
+ bidi algorithm to it. Libraries such as ICU and fribidi can do
+ this for you.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ HarfBuzz won't help you with text that contains different font
+ properties. For instance, if you have the string "a
+ <emphasis>huge</emphasis> breakfast", and you expect
+ "huge" to be italic, then you will need to send three
+ strings to HarfBuzz: <literal>a</literal>, in your Roman font;
+ <literal>huge</literal> using your italic font; and
+ <literal>breakfast</literal> using your Roman font again.
+ </para>
+ <para>
+ Similarly, if you change the font, font size, script,
+ language, or direction within your string, then you will
+ need to shape each run independently and output them
+ independently. HarfBuzz expects to shape a run of characters
+ that all share the same properties.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ HarfBuzz won't help you with line breaking, hyphenation, or
+ justification. As mentioned above, HarfBuzz lays out the string
+ along a <emphasis>single line</emphasis> of, notionally,
+ infinite length. If you want to find out where the potential
+ word, sentence and line break points are in your text, you
+ could use the ICU library's break iterator functions.
+ </para>
+ <para>
+ HarfBuzz can tell you how wide a shaped piece of text is, which is
+ useful input to a justification algorithm, but it knows nothing
+ about paragraphs, lines or line lengths. Nor will it adjust the
+ space between words to fit them proportionally into a line. If you
+ want to layout text in paragraphs, you will probably want to send
+ each word of your text to HarfBuzz to determine its shaped width
+ after glyph substitutions, then work out how many words will fit
+ on a line, and then finally output each word of the line separated
+ by a space of the correct size to fully justify the paragraph.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ As a layout-engine implementor, HarfBuzz will help you with the
+ interface between your text and your font, and that's something
+ that you'll need—what you then do with the glyphs that your font
+ returns is up to you.
+ </para>
+ </section>
+
<section id="why-is-it-called-harfbuzz">
<title>Why is it called HarfBuzz?</title>
<para>
@@ -220,7 +313,7 @@
within the source code copyright declarations), but was then
extracted out to its own project. This project is maintained by
Behdad Esfahbod, and named HarfBuzz. Originally, it was a shaping
- engine for OpenType fonts - "HarfBuzz" is the Persian
+ engine for OpenType fonts—"HarfBuzz" is the Persian
for "open type".
</para>
</section>
commit fd270beedb331c4685e918f5a3ef5789a23ffaeb
Author: Nathan Willis <nwillis at glyphography.com>
Date: Fri Sep 28 16:36:38 2018 -0500
Docs: Usermanual- What is HarfBuzz; add intro to shaping concepts.
diff --git a/docs/usermanual-what-is-harfbuzz.xml b/docs/usermanual-what-is-harfbuzz.xml
index 8ec7b403..59df9e3f 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>
commit d9fd92721002726c4aeaae9cc3a519a41f694e48
Author: Nathan Willis <nwillis at glyphography.com>
Date: Fri Sep 28 16:07:37 2018 -0500
Docs: update Usermanual-What Is HarfBuzz.
diff --git a/docs/usermanual-what-is-harfbuzz.xml b/docs/usermanual-what-is-harfbuzz.xml
index 38f40cf1..8ec7b403 100644
--- a/docs/usermanual-what-is-harfbuzz.xml
+++ b/docs/usermanual-what-is-harfbuzz.xml
@@ -1,115 +1,176 @@
<chapter id="what-is-harfbuzz">
<title>What is HarfBuzz?</title>
<para>
- HarfBuzz is a <emphasis>text shaping engine</emphasis>. It solves
- the problem of selecting and positioning glyphs from a font given a
- Unicode string.
+ HarfBuzz is a <emphasis>text shaping engine</emphasis>. If you
+ give HarfBuzz a font and a string containing a sequence of Unicode
+ codepoints, HarfBuzz selects and positions the corresponding
+ glyphs from the font, applying all of the necessary layout rules
+ and font features. HarfBuzz then returns the string to you in the
+ form that is correctly arranged for the language and writing
+ system.
</para>
- <section id="why-do-i-need-it">
- <title>Why do I need it?</title>
+ <para>
+ HarfBuzz can properly shape all of the world's major writing
+ systems. It runs on virtually all operating systems and software
+ platforms, and it supports all of the standard font formats in use
+ today.
+ </para>
+ <section id="why-do-i-need-a-shaping-engine">
+ <title>Why do I need a shaping engine?</title>
<para>
- Text shaping is an integral part of preparing text for display. It
- is a fairly low level operation; HarfBuzz is used directly by
- graphic rendering libraries such as Pango, and the layout engines
- in Firefox, LibreOffice and Chromium. Unless you are
- <emphasis>writing</emphasis> one of these layout engines yourself,
- you will probably not need to use HarfBuzz - normally higher level
- libraries will turn text into glyphs for you.
+ Text shaping is an integral part of preparing text for
+ display. Before a Unicode sequence can be rendered, the
+ codepoints in the sequence must be mapped to the glyphs
+ provided in the font, and the glyphs must be positioned
+ correctly relative to each other. For many of the scripts
+ supported in Unicode, these steps involve script-specific layout
+ rules.
+ </para>
+ <para>
+ Text shaping is a fairly low-level operation. HarfBuzz is
+ used directly by graphic rendering libraries such as Pango, as
+ well as by the layout engines in Firefox, LibreOffice, and
+ Chromium. Unless you are <emphasis>writing</emphasis> one of
+ these layout engines yourself, you will probably not need to use
+ HarfBuzz: normally, lower-level libraries will turn text into
+ glyphs for you.
</para>
<para>
However, if you <emphasis>are</emphasis> writing a layout engine
or graphics library yourself, you will need to perform text
- shaping, and this is where HarfBuzz can help you. Here are some
- reasons why you need it:
+ shaping, and this is where HarfBuzz can help you.
+ </para>
+ <para>
+ Here are some specific scenarios where a text-shaping engine
+ like HarfBuzz helps you:
</para>
<itemizedlist>
<listitem>
<para>
- OpenType fonts contain a set of glyphs, indexed by glyph ID.
- The glyph ID within the font does not necessarily relate to a
- Unicode codepoint. For instance, some fonts have the letter
- "a" as glyph ID 1. To pull the right glyph out of
- the font in order to display it, you need to consult a table
- within the font (the "cmap" table) which maps
- Unicode codepoints to glyph IDs. Text shaping turns codepoints
- into glyph IDs.
+ OpenType fonts contain a set of glyphs (that is, shapes
+ to represent the letters, numbers, punctuation marks, and
+ all other symbols), which are indexed by a <literal>glyph ID</literal>.
+ </para>
+ <para>
+ The glyph ID within the font does not necessarily correlate
+ to a predictable Unicode codepoint. For instance, some fonts
+ have the letter "a" as glyph ID 1, but many others do
+ not. To pull the right glyph out of the font in order to
+ display "a", you need to consult the table inside
+ the font (the <literal>cmap</literal> table) that maps Unicode
+ codepoints to glyph IDs. In other words, <emphasis>text shaping turns
+ codepoints into glyph IDs</emphasis>.
</para>
</listitem>
<listitem>
<para>
Many OpenType fonts contain ligatures: combinations of
- characters which are rendered together. For instance, it's
- common for the <literal>fi</literal> combination to appear in
- print as the single ligature "fi". Whether you should
- render text as <literal>fi</literal> or "fi" does not
- depend on the input text, but on the capabilities of the font
- and the level of ligature application you wish to perform.
- Text shaping involves querying the font's ligature tables and
- determining what substitutions should be made.
+ characters that are rendered as a single unit. For instance,
+ it is common for the <literal>fi</literal> letter
+ combination to appear in print as the single ligature glyph
+ "fi".
+ </para>
+ <para>
+ Whether you should render an "f, i" sequence
+ as <literal>fi</literal> or as "fi" does not
+ depend on the input text. Rather, it depends on the whether
+ or not the font includes an "fi" glyph and on the
+ level of ligature application you wish to perform. The font
+ and the amount of ligature application used are under your
+ control. In other words, <emphasis>text shaping involves
+ querying the font's ligature tables and determining what
+ substitutions should be made</emphasis>.
</para>
</listitem>
<listitem>
<para>
- While ligatures like "fi" are typographic
- refinements, some languages <emphasis>require</emphasis> such
+ While ligatures like "fi" are optional typographic
+ refinements, some languages <emphasis>require</emphasis> certain
substitutions to be made in order to display text correctly.
- In Tamil, when the letter "TTA" (ட) letter is
- followed by "U" (உ), the combination should appear
- as the single glyph "டு". The sequence of Unicode
- characters "டஉ" needs to be rendered as a single
- glyph from the font - text shaping chooses the correct glyph
- from the sequence of characters provided.
+ </para>
+ <para>
+ For example, in Tamil, when the letter "TTA" (ட)
+ letter is followed by "U" (உ), the pair
+ must be replaced by the single glyph "டு". The
+ sequence of Unicode characters "டஉ" needs to be
+ substituted with a single "டு" glyph from the
+ font.
+ </para>
+ <para>
+ But "டு" does not have a Unicode codepoint. To
+ find this glyph, you need to consult the table inside
+ the font (the <literal>GSUB</literal> table) that contains
+ substitution information. In other words, <emphasis>text shaping
+ chooses the correct glyph for a sequence of characters
+ provided</emphasis>.
</para>
</listitem>
<listitem>
<para>
- Similarly, each Arabic character has four different variants:
- within a font, there will be glyphs for the initial, medial,
- final, and isolated forms of each letter. Unicode only encodes
- one codepoint per character, and so a Unicode string will not
- tell you which glyph to use. Text shaping chooses the correct
- form of the letter and returns the correct glyph from the font
- that you need to render.
+ Similarly, each Arabic character has four different variants
+ corresponding to the different positions in might appear in
+ within a sequence. Inside a font, there will be separate
+ glyphs for the initial, medial, final, and isolated forms of
+ each letter, each at a different glyph ID.
+ </para>
+ <para>
+ Unicode only assigns one codepoint per character, so a
+ Unicode string will not tell you which glyph variant to use
+ for each character. To decide, you need to analyze the whole
+ string and determine the appropriate glyph for each character
+ based on its position. In other words, <emphasis>text
+ shaping chooses the correct form of the letter by its
+ position and returns the correct glyph from the font</emphasis>.
</para>
</listitem>
<listitem>
<para>
- Other languages have marks and accents which need to be
- rendered in certain positions around a base character. For
- instance, the Moldovan language has the Cyrillic letter
- "zhe" (ж) with a breve accent, like so: ӂ. Some
- fonts will contain this character as an individual glyph,
- whereas other fonts will not contain a zhe-with-breve glyph
- but expect the rendering engine to form the character by
- overlaying the two glyphs ж and ˘. Where you should draw the
- combining breve depends on the height of the preceding glyph.
- Again, for Arabic, the correct positioning of vowel marks
- depends on the height of the character on which you are
- placing the mark. Text shaping tells you whether you have a
+ Other languages involve marks and accents that need to be
+ rendered in specific positions relative a base character. For
+ instance, the Moldovan language includes the Cyrillic letter
+ "zhe" (ж) with a breve accent, like so: "ӂ".
+ </para>
+ <para>
+ Some fonts will provide this character as a single
+ zhe-with-breve glyph, but other fonts will not and, instead,
+ will expect the rendering engine to form the character by
+ superimposing the separate "ж" and "˘"
+ glyphs.
+ </para>
+ <para>
+ But exactly where you should draw the breve depends on the
+ height and width of the preceding zhe glyph. To find the
+ right position, you need to consult the table inside
+ the font (the <literal>GPOS</literal> table) that contains
+ positioning information.
+ In other words, <emphasis>text shaping tells you whether you have a
precomposed glyph within your font or if you need to compose a
- glyph yourself out of combining marks, and if so, where to
- position those marks.
+ glyph yourself out of combining marks—and, if so, where to
+ position those marks.</emphasis>
</para>
</listitem>
</itemizedlist>
<para>
- If this is something that you need to do, then you need a text
- shaping engine: you could use Uniscribe if you are using Windows;
- you could use CoreText on OS X; or you could use HarfBuzz. In the
- rest of this manual, we are going to assume that you are the
- implementor of a text layout engine.
+ If tasks like these are something that you need to do, then you need a text
+ shaping engine. You could use Uniscribe if you are writing
+ Windows software; you could use CoreText on macOS; or you could
+ use HarfBuzz.
+ </para>
+ <para>
+ In the rest of this manual, we are going to assume that you are the
+ implementor of a text-layout engine.
</para>
</section>
<section id="why-is-it-called-harfbuzz">
<title>Why is it called HarfBuzz?</title>
<para>
- HarfBuzz began its life as text shaping code within the FreeType
- project, (and you will see references to the FreeType authors
- within the source code copyright declarations) but was then
- abstracted out to its own project. This project is maintained by
+ HarfBuzz began its life as text-shaping code within the FreeType
+ project (and you will see references to the FreeType authors
+ within the source code copyright declarations), but was then
+ extracted out to its own project. This project is maintained by
Behdad Esfahbod, and named HarfBuzz. Originally, it was a shaping
engine for OpenType fonts - "HarfBuzz" is the Persian
for "open type".
</para>
</section>
-</chapter>
\ No newline at end of file
+</chapter>
commit 0af3d176a64c0a57c7acb2a64ce8b9d08f449241
Author: Khaled Hosny <khaledhosny at eglug.org>
Date: Tue Oct 30 17:05:28 2018 +0200
[sbix] Fix memory leak in early return
Fixes https://bugs.chromium.org/p/oss-fuzz/issues/detail?id=11210
diff --git a/src/hb-ot-color-sbix-table.hh b/src/hb-ot-color-sbix-table.hh
index 39f85129..4feb4e19 100644
--- a/src/hb-ot-color-sbix-table.hh
+++ b/src/hb-ot-color-sbix-table.hh
@@ -244,7 +244,10 @@ struct sbix
hb_blob_t *blob = reference_png (font, glyph, &x_offset, &y_offset, &strike_ppem);
if (unlikely (blob->length < sizeof (PNGHeader)))
+ {
+ hb_blob_destroy (blob);
return false;
+ }
const PNGHeader &png = *blob->as<PNGHeader>();
diff --git a/test/fuzzing/fonts/clusterfuzz-testcase-minimized-hb-shape-fuzzer-5768601332613120 b/test/fuzzing/fonts/clusterfuzz-testcase-minimized-hb-shape-fuzzer-5768601332613120
new file mode 100644
index 00000000..385e6707
Binary files /dev/null and b/test/fuzzing/fonts/clusterfuzz-testcase-minimized-hb-shape-fuzzer-5768601332613120 differ
More information about the HarfBuzz
mailing list