First two chapters. More to follow.
diff --git a/docs/usermanual-ch02.xml b/docs/usermanual-ch02.xml
new file mode 100644
index 0000000..f0a161d
--- /dev/null
+++ b/docs/usermanual-ch02.xml
@@ -0,0 +1,182 @@
+<sect1 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>
+ <sect2 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>
+ <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>
+ </sect2>
+</sect1>
\ No newline at end of file
