walkero
/
harfbuzz
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Docs: Move What-HarfBuzz-doesnt-do to Usermanual-what-is-HarfBuzz.

This commit is contained in:
Nathan Willis 2018-09-28 17:15:59 -05:00 committed by Khaled Hosny
parent fd270beedb
commit 0956ab4185
2 changed files with 104 additions and 95 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

96
docs/usermanual-hello-harfbuzz.xml
View File

@ -90,94 +90,10 @@
hb_buffer_destroy(buf); hb_buffer_destroy(buf);
hb_font_destroy(hb_ft_font); hb_font_destroy(hb_ft_font);
</programlisting> </programlisting>
<section id="what-harfbuzz-doesnt-do">
<title>What HarfBuzz doesn't do</title> <para>
<para> This example shows enough to get us started using HarfBuzz. Now we
The code above will take a UTF8 string, shape it, and give you the are going to use the remainder of HarfBuzz's API to refine that
information required to lay it out correctly on a single example and improve our text shaping capabilities.
horizontal (or vertical) line using the font provided. That is the </para>
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>
(&quot;bidi&quot; 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 &quot;a
<emphasis>huge</emphasis> breakfast&quot;, and you expect
&quot;huge&quot; 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> </chapter>

99
docs/usermanual-what-is-harfbuzz.xml
View File

@ -1,7 +1,7 @@
<chapter id="what-is-harfbuzz"> <chapter id="what-is-harfbuzz">
<title>What is HarfBuzz?</title> <title>What is HarfBuzz?</title>
<para> <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 give HarfBuzz a font and a string containing a sequence of Unicode
codepoints, HarfBuzz selects and positions the corresponding codepoints, HarfBuzz selects and positions the corresponding
glyphs from the font, applying all of the necessary layout rules glyphs from the font, applying all of the necessary layout rules
@ -21,7 +21,7 @@
Text shaping is the process of translating a string of character Text shaping is the process of translating a string of character
codes (such as Unicode codepoints) into a properly arranged codes (such as Unicode codepoints) into a properly arranged
sequence of glyphs that can be rendered onto a screen or into 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>
<para> <para>
The shaping process is dependent on the input string, the active The shaping process is dependent on the input string, the active
@ -66,6 +66,7 @@
tags are defined by OpenType. tags are defined by OpenType.
</para> </para>
</section> </section>
<section id="why-do-i-need-a-shaping-engine"> <section id="why-do-i-need-a-shaping-engine">
<title>Why do I need a shaping engine?</title> <title>Why do I need a shaping engine?</title>
<para> <para>
@ -212,6 +213,98 @@
implementor of a text-layout engine. implementor of a text-layout engine.
</para> </para>
</section> </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>
(&quot;bidi&quot; 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 &quot;a
<emphasis>huge</emphasis> breakfast&quot;, and you expect
&quot;huge&quot; 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&mdash;what you then do with the glyphs that your font
returns is up to you.
</para>
</section>
<section id="why-is-it-called-harfbuzz"> <section id="why-is-it-called-harfbuzz">
<title>Why is it called HarfBuzz?</title> <title>Why is it called HarfBuzz?</title>
<para> <para>
@ -220,7 +313,7 @@
within the source code copyright declarations), but was then within the source code copyright declarations), but was then
extracted out to its own project. This project is maintained by extracted out to its own project. This project is maintained by
Behdad Esfahbod, and named HarfBuzz. Originally, it was a shaping Behdad Esfahbod, and named HarfBuzz. Originally, it was a shaping
engine for OpenType fonts - &quot;HarfBuzz&quot; is the Persian engine for OpenType fonts&mdash;&quot;HarfBuzz&quot; is the Persian
for &quot;open type&quot;. for &quot;open type&quot;.
</para> </para>
</section> </section>