[HarfBuzz] harfbuzz: Branch 'master' - 2 commits
Behdad Esfahbod
behdad at kemper.freedesktop.org
Mon Aug 31 11:19:49 PDT 2015
configure.ac | 3
docs/Makefile.am | 117 ++++++++
docs/harfbuzz-docs.xml | 78 +++++
docs/harfbuzz-sections.txt | 498 +++++++++++++++++++++++++++++++++++
docs/reference/Makefile.am | 111 -------
docs/reference/harfbuzz-docs.xml | 78 -----
docs/reference/harfbuzz-sections.txt | 498 -----------------------------------
docs/reference/version.xml.in | 1
docs/version.xml.in | 1
9 files changed, 694 insertions(+), 691 deletions(-)
New commits:
commit 5783e05f81bbf6debf2618c8994d6852630d9847
Author: Behdad Esfahbod <behdad at behdad.org>
Date: Mon Aug 31 19:18:10 2015 +0100
[docs] Move docs/reference/ contents into docs/
diff --git a/configure.ac b/configure.ac
index a73fe62..2a0bc6a 100644
--- a/configure.ac
+++ b/configure.ac
@@ -442,8 +442,7 @@ test/Makefile
test/api/Makefile
test/shaping/Makefile
docs/Makefile
-docs/reference/Makefile
-docs/reference/version.xml
+docs/version.xml
])
AC_OUTPUT
diff --git a/docs/Makefile.am b/docs/Makefile.am
index 034926c..f605f24 100644
--- a/docs/Makefile.am
+++ b/docs/Makefile.am
@@ -1,3 +1,118 @@
-SUBDIRS = reference
+# Process this file with automake to produce Makefile.in
+
+# We require automake 1.6 at least.
+AUTOMAKE_OPTIONS = 1.6
+
+# This is a blank Makefile.am for using gtk-doc.
+# Copy this to your project's API docs directory and modify the variables to
+# suit your project. See the GTK+ Makefiles in gtk+/docs/reference for examples
+# of using the various options.
+
+# The name of the module, e.g. 'glib'.
+DOC_MODULE=harfbuzz
+
+# Uncomment for versioned docs and specify the version of the module, e.g. '2'.
+#DOC_MODULE_VERSION=$(HB_VERSION_MAJOR)
+
+# The top-level SGML file. You can change this if you want to.
+DOC_MAIN_SGML_FILE=$(DOC_MODULE)-docs.xml
+
+# Directories containing the source code.
+# gtk-doc will search all .c and .h files beneath these paths
+# for inline comments documenting functions and macros.
+# e.g. DOC_SOURCE_DIR=$(top_srcdir)/gtk $(top_srcdir)/gdk
+DOC_SOURCE_DIR=$(top_srcdir)/src $(top_builddir)/src
+
+# Extra options to pass to gtkdoc-scangobj. Not normally needed.
+SCANGOBJ_OPTIONS=
+
+# Extra options to supply to gtkdoc-scan.
+# e.g. SCAN_OPTIONS=--deprecated-guards="GTK_DISABLE_DEPRECATED"
+SCAN_OPTIONS=--rebuild-types --deprecated-guards="HB_DISABLE_DEPRECATED"
+
+# Header files or dirs to ignore when scanning. Use base file/dir names
+# e.g. IGNORE_HFILES=gtkdebug.h gtkintl.h private_code
+IGNORE_HFILES=`cd $(top_srcdir)/src; find . -path './hb-*/*.h' | sed 's@^.*/@@'`
+if HAVE_GOBJECT
+else
+IGNORE_HFILES+=hb-gobject.h hb-gobject-enums.h hb-gobject-structs.h
+endif
+
+# Extra options to supply to gtkdoc-mkdb.
+# e.g. MKDB_OPTIONS=--xml-mode --output-format=xml
+MKDB_OPTIONS=--source-suffixes=h,cc --xml-mode --output-format=xml --ignore-files="$(IGNORE_HFILES)"
+
+# Extra options to supply to gtkdoc-mktmpl
+# e.g. MKTMPL_OPTIONS=--only-section-tmpl
+MKTMPL_OPTIONS=
+
+# Extra options to supply to gtkdoc-mkhtml
+MKHTML_OPTIONS=
+
+# Extra options to supply to gtkdoc-fixref. Not normally needed.
+# e.g. FIXXREF_OPTIONS=--extra-dir=../gdk-pixbuf/html --extra-dir=../gdk/html
+FIXXREF_OPTIONS=
+
+# Used for dependencies. The docs will be rebuilt if any of these change.
+# e.g. HFILE_GLOB=$(top_srcdir)/gtk/*.h
+# e.g. CFILE_GLOB=$(top_srcdir)/gtk/*.c
+HFILE_GLOB=$(top_srcdir)/src/hb.h $(top_srcdir)/src/hb-*.h
+CFILE_GLOB=$(top_srcdir)/src/hb-*.cc
+
+# Extra header to include when scanning, which are not under DOC_SOURCE_DIR
+# e.g. EXTRA_HFILES=$(top_srcdir}/contrib/extra.h
+EXTRA_HFILES=$(top_builddir)/src/hb-version.h
+
+# Images to copy into HTML directory.
+# e.g. HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png
+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-ch01.xml \
+ usermanual-ch02.xml \
+ usermanual-ch03.xml \
+ usermanual-ch04.xml \
+ usermanual-ch05.xml \
+ usermanual-ch06.xml \
+ version.xml
+
+# SGML files where gtk-doc abbrevations (#GtkWidget) are expanded
+# These files must be listed here *and* in content_files
+# e.g. expand_content_files=running.sgml
+expand_content_files=
+
+# CFLAGS and LDFLAGS for compiling gtkdoc-scangobj with your library.
+# Only needed if you are using gtkdoc-scangobj to dynamically query widget
+# signals and properties.
+# e.g. GTKDOC_CFLAGS=-I$(top_srcdir) -I$(top_builddir) $(GTK_DEBUG_FLAGS)
+# e.g. GTKDOC_LIBS=$(top_builddir)/gtk/$(gtktargetlib)
+GTKDOC_CFLAGS=
+GTKDOC_LIBS=$(top_builddir)/src/libharfbuzz.la
+if HAVE_GOBJECT
+GTKDOC_LIBS+=$(top_builddir)/src/libharfbuzz-gobject.la
+endif
+
+# This includes the standard gtk-doc make rules, copied by gtkdocize.
+include $(top_srcdir)/gtk-doc.make
+
+# Other files to distribute
+# e.g. EXTRA_DIST += version.xml.in
+EXTRA_DIST += version.xml.in
+
+# Files not to distribute
+# for --rebuild-types in $(SCAN_OPTIONS), e.g. $(DOC_MODULE).types
+# for --rebuild-sections in $(SCAN_OPTIONS) e.g. $(DOC_MODULE)-sections.txt
+#DISTCLEANFILES +=
+
+# Comment this out if you want 'make check' to test you doc status
+# and run some sanity checks
+if ENABLE_GTK_DOC
+TESTS_ENVIRONMENT = cd $(srcdir) && \
+ DOC_MODULE=$(DOC_MODULE) DOC_MAIN_SGML_FILE=$(DOC_MAIN_SGML_FILE) \
+ SRCDIR=$(abs_srcdir) BUILDDIR=$(abs_builddir)
+#TESTS = $(GTKDOC_CHECK)
+endif
-include $(top_srcdir)/git.mk
diff --git a/docs/harfbuzz-docs.xml b/docs/harfbuzz-docs.xml
new file mode 100644
index 0000000..60ff8e2
--- /dev/null
+++ b/docs/harfbuzz-docs.xml
@@ -0,0 +1,78 @@
+<?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">
+]>
+<book id="index">
+ <bookinfo>
+ <title>HarfBuzz Manual</title>
+ <releaseinfo>
+ for HarfBuzz &version;.
+ <!--The latest version of this documentation can be found on-line at
+ <ulink role="online-location" url="http://[SERVER]/libharfbuzz/index.html">http://[SERVER]/libharfbuzz/</ulink>.-->
+ </releaseinfo>
+ </bookinfo>
+
+ <part>
+ <title>User's manual</title>
+ <xi:include href="usermanual-ch01.xml"/>
+ <xi:include href="usermanual-ch02.xml"/>
+ <xi:include href="usermanual-ch03.xml"/>
+ <xi:include href="usermanual-ch04.xml"/>
+ <xi:include href="usermanual-ch05.xml"/>
+ <xi:include href="usermanual-ch06.xml"/>
+ </part>
+
+ <part>
+ <title>Reference manual</title>
+ <chapter>
+ <title>Harfbuzz API</title>
+ <xi:include href="xml/hb.xml"/>
+ <xi:include href="xml/hb-common.xml"/>
+ <xi:include href="xml/hb-unicode.xml"/>
+ <xi:include href="xml/hb-buffer.xml"/>
+ <xi:include href="xml/hb-blob.xml"/>
+ <xi:include href="xml/hb-face.xml"/>
+ <xi:include href="xml/hb-font.xml"/>
+ <xi:include href="xml/hb-shape.xml"/>
+
+ <xi:include href="xml/hb-version.xml"/>
+ <xi:include href="xml/hb-deprecated.xml"/>
+
+ <xi:include href="xml/hb-set.xml"/>
+
+ <xi:include href="xml/hb-ot.xml"/>
+ <xi:include href="xml/hb-ot-layout.xml"/>
+ <xi:include href="xml/hb-ot-tag.xml"/>
+
+ <xi:include href="xml/hb-shape-plan.xml"/>
+
+ <xi:include href="xml/hb-glib.xml"/>
+ <xi:include href="xml/hb-icu.xml"/>
+
+ <xi:include href="xml/hb-ft.xml"/>
+
+ <xi:include href="xml/hb-graphite2.xml"/>
+ <xi:include href="xml/hb-uniscribe.xml"/>
+ <xi:include href="xml/hb-coretext.xml"/>
+
+ <xi:include href="xml/hb-gobject.xml"/>
+
+ </chapter>
+ <chapter id="object-tree">
+ <title>Object Hierarchy</title>
+ <xi:include href="xml/tree_index.sgml"/>
+ </chapter>
+ <index id="api-index-full">
+ <title>API Index</title>
+ <xi:include href="xml/api-index-full.xml"><xi:fallback /></xi:include>
+ </index>
+ <index id="deprecated-api-index" role="deprecated">
+ <title>Index of deprecated API</title>
+ <xi:include href="xml/api-index-deprecated.xml"><xi:fallback /></xi:include>
+ </index>
+
+ <xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
+ </part>
+</book>
diff --git a/docs/harfbuzz-overrides.txt b/docs/harfbuzz-overrides.txt
new file mode 100644
index 0000000..e69de29
diff --git a/docs/harfbuzz-sections.txt b/docs/harfbuzz-sections.txt
new file mode 100644
index 0000000..3612dad
--- /dev/null
+++ b/docs/harfbuzz-sections.txt
@@ -0,0 +1,498 @@
+<SECTION>
+<FILE>hb</FILE>
+<SUBSECTION Private>
+HB_H_IN
+</SECTION>
+
+<SECTION>
+<FILE>hb-blob</FILE>
+hb_blob_create
+hb_blob_create_sub_blob
+hb_blob_destroy
+hb_blob_get_data
+hb_blob_get_data_writable
+hb_blob_get_empty
+hb_blob_get_length
+hb_blob_get_user_data
+hb_blob_is_immutable
+hb_blob_make_immutable
+hb_blob_reference
+hb_blob_set_user_data
+hb_blob_t
+hb_memory_mode_t
+</SECTION>
+
+<SECTION>
+<FILE>hb-buffer</FILE>
+HB_SEGMENT_PROPERTIES_DEFAULT
+hb_buffer_add
+hb_buffer_add_utf16
+hb_buffer_add_utf32
+hb_buffer_add_utf8
+hb_buffer_allocation_successful
+hb_buffer_clear_contents
+hb_buffer_content_type_t
+hb_buffer_create
+hb_buffer_deserialize_glyphs
+hb_buffer_destroy
+hb_buffer_flags_t
+hb_buffer_get_content_type
+hb_buffer_get_direction
+hb_buffer_get_empty
+hb_buffer_get_flags
+hb_buffer_get_glyph_infos
+hb_buffer_get_glyph_positions
+hb_buffer_get_language
+hb_buffer_get_length
+hb_buffer_get_script
+hb_buffer_get_segment_properties
+hb_buffer_get_unicode_funcs
+hb_buffer_get_user_data
+hb_buffer_guess_segment_properties
+hb_buffer_normalize_glyphs
+hb_buffer_pre_allocate
+hb_buffer_reference
+hb_buffer_reset
+hb_buffer_reverse
+hb_buffer_reverse_clusters
+hb_buffer_serialize_flags_t
+hb_buffer_serialize_format_from_string
+hb_buffer_serialize_format_t
+hb_buffer_serialize_format_to_string
+hb_buffer_serialize_glyphs
+hb_buffer_serialize_list_formats
+hb_buffer_set_content_type
+hb_buffer_set_direction
+hb_buffer_set_flags
+hb_buffer_set_language
+hb_buffer_set_length
+hb_buffer_set_script
+hb_buffer_set_segment_properties
+hb_buffer_set_unicode_funcs
+hb_buffer_set_user_data
+hb_buffer_t
+hb_glyph_info_t
+hb_glyph_position_t
+hb_segment_properties_equal
+hb_segment_properties_hash
+hb_segment_properties_t
+</SECTION>
+
+<SECTION>
+<FILE>hb-common</FILE>
+HB_DIRECTION_REVERSE
+HB_LANGUAGE_INVALID
+HB_TAG
+HB_TAG_NONE
+HB_TAG_MAX
+HB_UNTAG
+hb_bool_t
+hb_codepoint_t
+hb_destroy_func_t
+hb_direction_from_string
+hb_direction_t
+hb_direction_to_string
+hb_language_from_string
+hb_language_get_default
+hb_language_t
+hb_language_to_string
+hb_mask_t
+hb_position_t
+hb_script_from_iso15924_tag
+hb_script_from_string
+hb_script_get_horizontal_direction
+hb_script_t
+hb_script_to_iso15924_tag
+hb_tag_from_string
+hb_tag_t
+hb_tag_to_string
+hb_user_data_key_t
+hb_var_int_t
+HB_DIRECTION_IS_BACKWARD
+HB_DIRECTION_IS_FORWARD
+HB_DIRECTION_IS_HORIZONTAL
+HB_DIRECTION_IS_VALID
+HB_DIRECTION_IS_VERTICAL
+<SUBSECTION Private>
+HB_BEGIN_DECLS
+HB_END_DECLS
+int16_t
+int32_t
+int64_t
+int8_t
+uint16_t
+uint32_t
+uint64_t
+uint8_t
+</SECTION>
+
+<SECTION>
+<FILE>hb-deprecated</FILE>
+HB_BUFFER_FLAGS_DEFAULT
+HB_BUFFER_SERIALIZE_FLAGS_DEFAULT
+HB_SCRIPT_CANADIAN_ABORIGINAL
+</SECTION>
+
+<SECTION>
+<FILE>hb-coretext</FILE>
+HB_CORETEXT_TAG_MORT
+HB_CORETEXT_TAG_MORX
+hb_coretext_face_create
+hb_coretext_face_get_cg_font
+hb_coretext_font_get_ct_font
+</SECTION>
+
+<SECTION>
+<FILE>hb-face</FILE>
+hb_face_create
+hb_face_create_for_tables
+hb_face_destroy
+hb_face_get_empty
+hb_face_get_glyph_count
+hb_face_get_index
+hb_face_get_upem
+hb_face_get_user_data
+hb_face_is_immutable
+hb_face_make_immutable
+hb_face_reference
+hb_face_reference_blob
+hb_face_reference_table
+hb_face_set_glyph_count
+hb_face_set_index
+hb_face_set_upem
+hb_face_set_user_data
+hb_face_t
+</SECTION>
+
+<SECTION>
+<FILE>hb-font</FILE>
+hb_font_add_glyph_origin_for_direction
+hb_font_create
+hb_font_create_sub_font
+hb_font_destroy
+hb_font_funcs_create
+hb_font_funcs_destroy
+hb_font_funcs_get_empty
+hb_font_funcs_get_user_data
+hb_font_funcs_is_immutable
+hb_font_funcs_make_immutable
+hb_font_funcs_reference
+hb_font_funcs_set_glyph_contour_point_func
+hb_font_funcs_set_glyph_extents_func
+hb_font_funcs_set_glyph_from_name_func
+hb_font_funcs_set_glyph_func
+hb_font_funcs_set_glyph_h_advance_func
+hb_font_funcs_set_glyph_h_kerning_func
+hb_font_funcs_set_glyph_h_origin_func
+hb_font_funcs_set_glyph_name_func
+hb_font_funcs_set_glyph_v_advance_func
+hb_font_funcs_set_glyph_v_kerning_func
+hb_font_funcs_set_glyph_v_origin_func
+hb_font_funcs_set_user_data
+hb_font_funcs_t
+hb_font_get_empty
+hb_font_get_face
+hb_font_get_glyph
+hb_font_get_glyph_advance_for_direction
+hb_font_get_glyph_advance_func_t
+hb_font_get_glyph_contour_point
+hb_font_get_glyph_contour_point_for_origin
+hb_font_get_glyph_contour_point_func_t
+hb_font_get_glyph_extents
+hb_font_get_glyph_extents_for_origin
+hb_font_get_glyph_extents_func_t
+hb_font_get_glyph_from_name
+hb_font_get_glyph_from_name_func_t
+hb_font_get_glyph_func_t
+hb_font_get_glyph_h_advance
+hb_font_get_glyph_h_advance_func_t
+hb_font_get_glyph_h_kerning
+hb_font_get_glyph_h_kerning_func_t
+hb_font_get_glyph_h_origin
+hb_font_get_glyph_h_origin_func_t
+hb_font_get_glyph_kerning_for_direction
+hb_font_get_glyph_kerning_func_t
+hb_font_get_glyph_name
+hb_font_get_glyph_name_func_t
+hb_font_get_glyph_origin_for_direction
+hb_font_get_glyph_origin_func_t
+hb_font_get_glyph_v_advance
+hb_font_get_glyph_v_advance_func_t
+hb_font_get_glyph_v_kerning
+hb_font_get_glyph_v_kerning_func_t
+hb_font_get_glyph_v_origin
+hb_font_get_glyph_v_origin_func_t
+hb_font_get_parent
+hb_font_get_ppem
+hb_font_get_scale
+hb_font_get_user_data
+hb_font_glyph_from_string
+hb_font_glyph_to_string
+hb_font_is_immutable
+hb_font_make_immutable
+hb_font_reference
+hb_font_set_funcs
+hb_font_set_funcs_data
+hb_font_set_ppem
+hb_font_set_scale
+hb_font_set_user_data
+hb_font_subtract_glyph_origin_for_direction
+hb_font_t
+hb_reference_table_func_t
+</SECTION>
+
+<SECTION>
+<FILE>hb-ft</FILE>
+hb_ft_face_create
+hb_ft_face_create_cached
+hb_ft_font_create
+hb_ft_font_get_face
+hb_ft_font_set_funcs
+</SECTION>
+
+<SECTION>
+<FILE>hb-glib</FILE>
+hb_glib_get_unicode_funcs
+hb_glib_script_from_script
+hb_glib_script_to_script
+</SECTION>
+
+<SECTION>
+<FILE>hb-gobject</FILE>
+HB_GOBJECT_TYPE_BLOB
+HB_GOBJECT_TYPE_BUFFER
+HB_GOBJECT_TYPE_BUFFER_CONTENT_TYPE
+HB_GOBJECT_TYPE_BUFFER_FLAGS
+HB_GOBJECT_TYPE_BUFFER_SERIALIZE_FLAGS
+HB_GOBJECT_TYPE_BUFFER_SERIALIZE_FORMAT
+HB_GOBJECT_TYPE_DIRECTION
+HB_GOBJECT_TYPE_FACE
+HB_GOBJECT_TYPE_FONT
+HB_GOBJECT_TYPE_FONT_FUNCS
+HB_GOBJECT_TYPE_MEMORY_MODE
+HB_GOBJECT_TYPE_OT_LAYOUT_GLYPH_CLASS
+HB_GOBJECT_TYPE_SCRIPT
+HB_GOBJECT_TYPE_SHAPE_PLAN
+HB_GOBJECT_TYPE_UNICODE_COMBINING_CLASS
+HB_GOBJECT_TYPE_UNICODE_FUNCS
+HB_GOBJECT_TYPE_UNICODE_GENERAL_CATEGORY
+hb_gobject_blob_get_type
+hb_gobject_buffer_content_type_get_type
+hb_gobject_buffer_flags_get_type
+hb_gobject_buffer_get_type
+hb_gobject_buffer_serialize_flags_get_type
+hb_gobject_buffer_serialize_format_get_type
+hb_gobject_direction_get_type
+hb_gobject_face_get_type
+hb_gobject_font_funcs_get_type
+hb_gobject_font_get_type
+hb_gobject_memory_mode_get_type
+hb_gobject_ot_layout_glyph_class_get_type
+hb_gobject_script_get_type
+hb_gobject_shape_plan_get_type
+hb_gobject_unicode_combining_class_get_type
+hb_gobject_unicode_funcs_get_type
+hb_gobject_unicode_general_category_get_type
+<SUBSECTION Private>
+HB_GOBJECT_H_IN
+</SECTION>
+
+<SECTION>
+<FILE>hb-gobject</FILE>
+
+</SECTION>
+
+<SECTION>
+<FILE>hb-graphite2</FILE>
+HB_GRAPHITE2_TAG_SILF
+hb_graphite2_face_get_gr_face
+hb_graphite2_font_get_gr_font
+</SECTION>
+
+<SECTION>
+<FILE>hb-icu</FILE>
+hb_icu_get_unicode_funcs
+hb_icu_script_from_script
+hb_icu_script_to_script
+</SECTION>
+
+<SECTION>
+<FILE>hb-ot</FILE>
+<SUBSECTION Private>
+HB_OT_H_IN
+</SECTION>
+
+<SECTION>
+<FILE>hb-ot-font</FILE>
+hb_ot_font_set_funcs
+</SECTION>
+
+<SECTION>
+<FILE>hb-ot-shape</FILE>
+hb_ot_shape_glyphs_closure
+</SECTION>
+
+<SECTION>
+<FILE>hb-ot-layout</FILE>
+HB_OT_LAYOUT_DEFAULT_LANGUAGE_INDEX
+HB_OT_LAYOUT_NO_FEATURE_INDEX
+HB_OT_LAYOUT_NO_SCRIPT_INDEX
+HB_OT_TAG_GDEF
+HB_OT_TAG_GPOS
+HB_OT_TAG_GSUB
+hb_ot_layout_collect_lookups
+hb_ot_layout_feature_get_lookups
+hb_ot_layout_get_attach_points
+hb_ot_layout_get_glyph_class
+hb_ot_layout_get_glyphs_in_class
+hb_ot_layout_get_ligature_carets
+hb_ot_layout_get_size_params
+hb_ot_layout_glyph_class_t
+hb_ot_layout_glyph_sequence_func_t
+hb_ot_layout_has_glyph_classes
+hb_ot_layout_has_positioning
+hb_ot_layout_has_substitution
+hb_ot_layout_language_find_feature
+hb_ot_layout_language_get_feature_indexes
+hb_ot_layout_language_get_feature_tags
+hb_ot_layout_language_get_required_feature
+hb_ot_layout_lookup_collect_glyphs
+hb_ot_layout_lookup_substitute_closure
+hb_ot_layout_lookup_would_substitute
+hb_ot_layout_script_find_language
+hb_ot_layout_script_get_language_tags
+hb_ot_layout_table_choose_script
+hb_ot_layout_table_find_script
+hb_ot_layout_table_get_feature_tags
+hb_ot_layout_table_get_script_tags
+hb_ot_layout_table_get_lookup_count
+hb_ot_shape_plan_collect_lookups
+<SUBSECTION Private>
+Xhb_ot_layout_lookup_enumerate_sequences
+Xhb_ot_layout_lookup_position
+Xhb_ot_layout_lookup_substitute
+</SECTION>
+
+<SECTION>
+<FILE>hb-ot-tag</FILE>
+HB_OT_TAG_DEFAULT_LANGUAGE
+HB_OT_TAG_DEFAULT_SCRIPT
+hb_ot_tag_from_language
+hb_ot_tag_to_language
+hb_ot_tag_to_script
+hb_ot_tags_from_script
+</SECTION>
+
+<SECTION>
+<FILE>hb-set</FILE>
+HB_SET_VALUE_INVALID
+hb_set_add
+hb_set_add_range
+hb_set_allocation_successful
+hb_set_clear
+hb_set_create
+hb_set_del
+hb_set_del_range
+hb_set_destroy
+hb_set_get_empty
+hb_set_get_max
+hb_set_get_min
+hb_set_get_population
+hb_set_get_user_data
+hb_set_has
+hb_set_intersect
+hb_set_invert
+hb_set_is_empty
+hb_set_is_equal
+hb_set_next
+hb_set_next_range
+hb_set_reference
+hb_set_set
+hb_set_set_user_data
+hb_set_subtract
+hb_set_symmetric_difference
+hb_set_t
+hb_set_union
+</SECTION>
+
+<SECTION>
+<FILE>hb-shape</FILE>
+hb_feature_from_string
+hb_feature_t
+hb_feature_to_string
+hb_shape
+hb_shape_full
+hb_shape_list_shapers
+</SECTION>
+
+<SECTION>
+<FILE>hb-shape-plan</FILE>
+hb_shape_plan_create
+hb_shape_plan_create_cached
+hb_shape_plan_destroy
+hb_shape_plan_execute
+hb_shape_plan_get_empty
+hb_shape_plan_get_shaper
+hb_shape_plan_get_user_data
+hb_shape_plan_reference
+hb_shape_plan_set_user_data
+hb_shape_plan_t
+</SECTION>
+
+<SECTION>
+<FILE>hb-unicode</FILE>
+HB_UNICODE_MAX_DECOMPOSITION_LEN
+hb_unicode_combining_class
+hb_unicode_combining_class_func_t
+hb_unicode_combining_class_t
+hb_unicode_compose
+hb_unicode_compose_func_t
+hb_unicode_decompose
+hb_unicode_decompose_compatibility
+hb_unicode_decompose_func_t
+hb_unicode_eastasian_width
+hb_unicode_funcs_create
+hb_unicode_funcs_destroy
+hb_unicode_funcs_get_default
+hb_unicode_funcs_get_empty
+hb_unicode_funcs_get_parent
+hb_unicode_funcs_get_user_data
+hb_unicode_funcs_is_immutable
+hb_unicode_funcs_make_immutable
+hb_unicode_funcs_reference
+hb_unicode_funcs_set_combining_class_func
+hb_unicode_funcs_set_compose_func
+hb_unicode_funcs_set_decompose_compatibility_func
+hb_unicode_funcs_set_decompose_func
+hb_unicode_funcs_set_eastasian_width_func
+hb_unicode_funcs_set_general_category_func
+hb_unicode_funcs_set_mirroring_func
+hb_unicode_funcs_set_script_func
+hb_unicode_funcs_set_user_data
+hb_unicode_funcs_t
+hb_unicode_general_category
+hb_unicode_general_category_func_t
+hb_unicode_general_category_t
+hb_unicode_mirroring
+hb_unicode_mirroring_func_t
+hb_unicode_script
+hb_unicode_script_func_t
+</SECTION>
+
+<SECTION>
+<FILE>hb-uniscribe</FILE>
+hb_uniscribe_font_get_hfont
+hb_uniscribe_font_get_logfontw
+</SECTION>
+
+<SECTION>
+<FILE>hb-version</FILE>
+HB_VERSION_ATLEAST
+HB_VERSION_MAJOR
+HB_VERSION_MICRO
+HB_VERSION_MINOR
+HB_VERSION_STRING
+hb_version
+hb_version_atleast
+hb_version_string
+</SECTION>
diff --git a/docs/reference/Makefile.am b/docs/reference/Makefile.am
deleted file mode 100644
index f605f24..0000000
--- a/docs/reference/Makefile.am
+++ /dev/null
@@ -1,118 +0,0 @@
-# Process this file with automake to produce Makefile.in
-
-# We require automake 1.6 at least.
-AUTOMAKE_OPTIONS = 1.6
-
-# This is a blank Makefile.am for using gtk-doc.
-# Copy this to your project's API docs directory and modify the variables to
-# suit your project. See the GTK+ Makefiles in gtk+/docs/reference for examples
-# of using the various options.
-
-# The name of the module, e.g. 'glib'.
-DOC_MODULE=harfbuzz
-
-# Uncomment for versioned docs and specify the version of the module, e.g. '2'.
-#DOC_MODULE_VERSION=$(HB_VERSION_MAJOR)
-
-# The top-level SGML file. You can change this if you want to.
-DOC_MAIN_SGML_FILE=$(DOC_MODULE)-docs.xml
-
-# Directories containing the source code.
-# gtk-doc will search all .c and .h files beneath these paths
-# for inline comments documenting functions and macros.
-# e.g. DOC_SOURCE_DIR=$(top_srcdir)/gtk $(top_srcdir)/gdk
-DOC_SOURCE_DIR=$(top_srcdir)/src $(top_builddir)/src
-
-# Extra options to pass to gtkdoc-scangobj. Not normally needed.
-SCANGOBJ_OPTIONS=
-
-# Extra options to supply to gtkdoc-scan.
-# e.g. SCAN_OPTIONS=--deprecated-guards="GTK_DISABLE_DEPRECATED"
-SCAN_OPTIONS=--rebuild-types --deprecated-guards="HB_DISABLE_DEPRECATED"
-
-# Header files or dirs to ignore when scanning. Use base file/dir names
-# e.g. IGNORE_HFILES=gtkdebug.h gtkintl.h private_code
-IGNORE_HFILES=`cd $(top_srcdir)/src; find . -path './hb-*/*.h' | sed 's@^.*/@@'`
-if HAVE_GOBJECT
-else
-IGNORE_HFILES+=hb-gobject.h hb-gobject-enums.h hb-gobject-structs.h
-endif
-
-# Extra options to supply to gtkdoc-mkdb.
-# e.g. MKDB_OPTIONS=--xml-mode --output-format=xml
-MKDB_OPTIONS=--source-suffixes=h,cc --xml-mode --output-format=xml --ignore-files="$(IGNORE_HFILES)"
-
-# Extra options to supply to gtkdoc-mktmpl
-# e.g. MKTMPL_OPTIONS=--only-section-tmpl
-MKTMPL_OPTIONS=
-
-# Extra options to supply to gtkdoc-mkhtml
-MKHTML_OPTIONS=
-
-# Extra options to supply to gtkdoc-fixref. Not normally needed.
-# e.g. FIXXREF_OPTIONS=--extra-dir=../gdk-pixbuf/html --extra-dir=../gdk/html
-FIXXREF_OPTIONS=
-
-# Used for dependencies. The docs will be rebuilt if any of these change.
-# e.g. HFILE_GLOB=$(top_srcdir)/gtk/*.h
-# e.g. CFILE_GLOB=$(top_srcdir)/gtk/*.c
-HFILE_GLOB=$(top_srcdir)/src/hb.h $(top_srcdir)/src/hb-*.h
-CFILE_GLOB=$(top_srcdir)/src/hb-*.cc
-
-# Extra header to include when scanning, which are not under DOC_SOURCE_DIR
-# e.g. EXTRA_HFILES=$(top_srcdir}/contrib/extra.h
-EXTRA_HFILES=$(top_builddir)/src/hb-version.h
-
-# Images to copy into HTML directory.
-# e.g. HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png
-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-ch01.xml \
- usermanual-ch02.xml \
- usermanual-ch03.xml \
- usermanual-ch04.xml \
- usermanual-ch05.xml \
- usermanual-ch06.xml \
- version.xml
-
-# SGML files where gtk-doc abbrevations (#GtkWidget) are expanded
-# These files must be listed here *and* in content_files
-# e.g. expand_content_files=running.sgml
-expand_content_files=
-
-# CFLAGS and LDFLAGS for compiling gtkdoc-scangobj with your library.
-# Only needed if you are using gtkdoc-scangobj to dynamically query widget
-# signals and properties.
-# e.g. GTKDOC_CFLAGS=-I$(top_srcdir) -I$(top_builddir) $(GTK_DEBUG_FLAGS)
-# e.g. GTKDOC_LIBS=$(top_builddir)/gtk/$(gtktargetlib)
-GTKDOC_CFLAGS=
-GTKDOC_LIBS=$(top_builddir)/src/libharfbuzz.la
-if HAVE_GOBJECT
-GTKDOC_LIBS+=$(top_builddir)/src/libharfbuzz-gobject.la
-endif
-
-# This includes the standard gtk-doc make rules, copied by gtkdocize.
-include $(top_srcdir)/gtk-doc.make
-
-# Other files to distribute
-# e.g. EXTRA_DIST += version.xml.in
-EXTRA_DIST += version.xml.in
-
-# Files not to distribute
-# for --rebuild-types in $(SCAN_OPTIONS), e.g. $(DOC_MODULE).types
-# for --rebuild-sections in $(SCAN_OPTIONS) e.g. $(DOC_MODULE)-sections.txt
-#DISTCLEANFILES +=
-
-# Comment this out if you want 'make check' to test you doc status
-# and run some sanity checks
-if ENABLE_GTK_DOC
-TESTS_ENVIRONMENT = cd $(srcdir) && \
- DOC_MODULE=$(DOC_MODULE) DOC_MAIN_SGML_FILE=$(DOC_MAIN_SGML_FILE) \
- SRCDIR=$(abs_srcdir) BUILDDIR=$(abs_builddir)
-#TESTS = $(GTKDOC_CHECK)
-endif
-
--include $(top_srcdir)/git.mk
diff --git a/docs/reference/harfbuzz-docs.xml b/docs/reference/harfbuzz-docs.xml
deleted file mode 100644
index 60ff8e2..0000000
--- a/docs/reference/harfbuzz-docs.xml
+++ /dev/null
@@ -1,78 +0,0 @@
-<?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">
-]>
-<book id="index">
- <bookinfo>
- <title>HarfBuzz Manual</title>
- <releaseinfo>
- for HarfBuzz &version;.
- <!--The latest version of this documentation can be found on-line at
- <ulink role="online-location" url="http://[SERVER]/libharfbuzz/index.html">http://[SERVER]/libharfbuzz/</ulink>.-->
- </releaseinfo>
- </bookinfo>
-
- <part>
- <title>User's manual</title>
- <xi:include href="usermanual-ch01.xml"/>
- <xi:include href="usermanual-ch02.xml"/>
- <xi:include href="usermanual-ch03.xml"/>
- <xi:include href="usermanual-ch04.xml"/>
- <xi:include href="usermanual-ch05.xml"/>
- <xi:include href="usermanual-ch06.xml"/>
- </part>
-
- <part>
- <title>Reference manual</title>
- <chapter>
- <title>Harfbuzz API</title>
- <xi:include href="xml/hb.xml"/>
- <xi:include href="xml/hb-common.xml"/>
- <xi:include href="xml/hb-unicode.xml"/>
- <xi:include href="xml/hb-buffer.xml"/>
- <xi:include href="xml/hb-blob.xml"/>
- <xi:include href="xml/hb-face.xml"/>
- <xi:include href="xml/hb-font.xml"/>
- <xi:include href="xml/hb-shape.xml"/>
-
- <xi:include href="xml/hb-version.xml"/>
- <xi:include href="xml/hb-deprecated.xml"/>
-
- <xi:include href="xml/hb-set.xml"/>
-
- <xi:include href="xml/hb-ot.xml"/>
- <xi:include href="xml/hb-ot-layout.xml"/>
- <xi:include href="xml/hb-ot-tag.xml"/>
-
- <xi:include href="xml/hb-shape-plan.xml"/>
-
- <xi:include href="xml/hb-glib.xml"/>
- <xi:include href="xml/hb-icu.xml"/>
-
- <xi:include href="xml/hb-ft.xml"/>
-
- <xi:include href="xml/hb-graphite2.xml"/>
- <xi:include href="xml/hb-uniscribe.xml"/>
- <xi:include href="xml/hb-coretext.xml"/>
-
- <xi:include href="xml/hb-gobject.xml"/>
-
- </chapter>
- <chapter id="object-tree">
- <title>Object Hierarchy</title>
- <xi:include href="xml/tree_index.sgml"/>
- </chapter>
- <index id="api-index-full">
- <title>API Index</title>
- <xi:include href="xml/api-index-full.xml"><xi:fallback /></xi:include>
- </index>
- <index id="deprecated-api-index" role="deprecated">
- <title>Index of deprecated API</title>
- <xi:include href="xml/api-index-deprecated.xml"><xi:fallback /></xi:include>
- </index>
-
- <xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
- </part>
-</book>
diff --git a/docs/reference/harfbuzz-overrides.txt b/docs/reference/harfbuzz-overrides.txt
deleted file mode 100644
index e69de29..0000000
diff --git a/docs/reference/harfbuzz-sections.txt b/docs/reference/harfbuzz-sections.txt
deleted file mode 100644
index 3612dad..0000000
--- a/docs/reference/harfbuzz-sections.txt
+++ /dev/null
@@ -1,498 +0,0 @@
-<SECTION>
-<FILE>hb</FILE>
-<SUBSECTION Private>
-HB_H_IN
-</SECTION>
-
-<SECTION>
-<FILE>hb-blob</FILE>
-hb_blob_create
-hb_blob_create_sub_blob
-hb_blob_destroy
-hb_blob_get_data
-hb_blob_get_data_writable
-hb_blob_get_empty
-hb_blob_get_length
-hb_blob_get_user_data
-hb_blob_is_immutable
-hb_blob_make_immutable
-hb_blob_reference
-hb_blob_set_user_data
-hb_blob_t
-hb_memory_mode_t
-</SECTION>
-
-<SECTION>
-<FILE>hb-buffer</FILE>
-HB_SEGMENT_PROPERTIES_DEFAULT
-hb_buffer_add
-hb_buffer_add_utf16
-hb_buffer_add_utf32
-hb_buffer_add_utf8
-hb_buffer_allocation_successful
-hb_buffer_clear_contents
-hb_buffer_content_type_t
-hb_buffer_create
-hb_buffer_deserialize_glyphs
-hb_buffer_destroy
-hb_buffer_flags_t
-hb_buffer_get_content_type
-hb_buffer_get_direction
-hb_buffer_get_empty
-hb_buffer_get_flags
-hb_buffer_get_glyph_infos
-hb_buffer_get_glyph_positions
-hb_buffer_get_language
-hb_buffer_get_length
-hb_buffer_get_script
-hb_buffer_get_segment_properties
-hb_buffer_get_unicode_funcs
-hb_buffer_get_user_data
-hb_buffer_guess_segment_properties
-hb_buffer_normalize_glyphs
-hb_buffer_pre_allocate
-hb_buffer_reference
-hb_buffer_reset
-hb_buffer_reverse
-hb_buffer_reverse_clusters
-hb_buffer_serialize_flags_t
-hb_buffer_serialize_format_from_string
-hb_buffer_serialize_format_t
-hb_buffer_serialize_format_to_string
-hb_buffer_serialize_glyphs
-hb_buffer_serialize_list_formats
-hb_buffer_set_content_type
-hb_buffer_set_direction
-hb_buffer_set_flags
-hb_buffer_set_language
-hb_buffer_set_length
-hb_buffer_set_script
-hb_buffer_set_segment_properties
-hb_buffer_set_unicode_funcs
-hb_buffer_set_user_data
-hb_buffer_t
-hb_glyph_info_t
-hb_glyph_position_t
-hb_segment_properties_equal
-hb_segment_properties_hash
-hb_segment_properties_t
-</SECTION>
-
-<SECTION>
-<FILE>hb-common</FILE>
-HB_DIRECTION_REVERSE
-HB_LANGUAGE_INVALID
-HB_TAG
-HB_TAG_NONE
-HB_TAG_MAX
-HB_UNTAG
-hb_bool_t
-hb_codepoint_t
-hb_destroy_func_t
-hb_direction_from_string
-hb_direction_t
-hb_direction_to_string
-hb_language_from_string
-hb_language_get_default
-hb_language_t
-hb_language_to_string
-hb_mask_t
-hb_position_t
-hb_script_from_iso15924_tag
-hb_script_from_string
-hb_script_get_horizontal_direction
-hb_script_t
-hb_script_to_iso15924_tag
-hb_tag_from_string
-hb_tag_t
-hb_tag_to_string
-hb_user_data_key_t
-hb_var_int_t
-HB_DIRECTION_IS_BACKWARD
-HB_DIRECTION_IS_FORWARD
-HB_DIRECTION_IS_HORIZONTAL
-HB_DIRECTION_IS_VALID
-HB_DIRECTION_IS_VERTICAL
-<SUBSECTION Private>
-HB_BEGIN_DECLS
-HB_END_DECLS
-int16_t
-int32_t
-int64_t
-int8_t
-uint16_t
-uint32_t
-uint64_t
-uint8_t
-</SECTION>
-
-<SECTION>
-<FILE>hb-deprecated</FILE>
-HB_BUFFER_FLAGS_DEFAULT
-HB_BUFFER_SERIALIZE_FLAGS_DEFAULT
-HB_SCRIPT_CANADIAN_ABORIGINAL
-</SECTION>
-
-<SECTION>
-<FILE>hb-coretext</FILE>
-HB_CORETEXT_TAG_MORT
-HB_CORETEXT_TAG_MORX
-hb_coretext_face_create
-hb_coretext_face_get_cg_font
-hb_coretext_font_get_ct_font
-</SECTION>
-
-<SECTION>
-<FILE>hb-face</FILE>
-hb_face_create
-hb_face_create_for_tables
-hb_face_destroy
-hb_face_get_empty
-hb_face_get_glyph_count
-hb_face_get_index
-hb_face_get_upem
-hb_face_get_user_data
-hb_face_is_immutable
-hb_face_make_immutable
-hb_face_reference
-hb_face_reference_blob
-hb_face_reference_table
-hb_face_set_glyph_count
-hb_face_set_index
-hb_face_set_upem
-hb_face_set_user_data
-hb_face_t
-</SECTION>
-
-<SECTION>
-<FILE>hb-font</FILE>
-hb_font_add_glyph_origin_for_direction
-hb_font_create
-hb_font_create_sub_font
-hb_font_destroy
-hb_font_funcs_create
-hb_font_funcs_destroy
-hb_font_funcs_get_empty
-hb_font_funcs_get_user_data
-hb_font_funcs_is_immutable
-hb_font_funcs_make_immutable
-hb_font_funcs_reference
-hb_font_funcs_set_glyph_contour_point_func
-hb_font_funcs_set_glyph_extents_func
-hb_font_funcs_set_glyph_from_name_func
-hb_font_funcs_set_glyph_func
-hb_font_funcs_set_glyph_h_advance_func
-hb_font_funcs_set_glyph_h_kerning_func
-hb_font_funcs_set_glyph_h_origin_func
-hb_font_funcs_set_glyph_name_func
-hb_font_funcs_set_glyph_v_advance_func
-hb_font_funcs_set_glyph_v_kerning_func
-hb_font_funcs_set_glyph_v_origin_func
-hb_font_funcs_set_user_data
-hb_font_funcs_t
-hb_font_get_empty
-hb_font_get_face
-hb_font_get_glyph
-hb_font_get_glyph_advance_for_direction
-hb_font_get_glyph_advance_func_t
-hb_font_get_glyph_contour_point
-hb_font_get_glyph_contour_point_for_origin
-hb_font_get_glyph_contour_point_func_t
-hb_font_get_glyph_extents
-hb_font_get_glyph_extents_for_origin
-hb_font_get_glyph_extents_func_t
-hb_font_get_glyph_from_name
-hb_font_get_glyph_from_name_func_t
-hb_font_get_glyph_func_t
-hb_font_get_glyph_h_advance
-hb_font_get_glyph_h_advance_func_t
-hb_font_get_glyph_h_kerning
-hb_font_get_glyph_h_kerning_func_t
-hb_font_get_glyph_h_origin
-hb_font_get_glyph_h_origin_func_t
-hb_font_get_glyph_kerning_for_direction
-hb_font_get_glyph_kerning_func_t
-hb_font_get_glyph_name
-hb_font_get_glyph_name_func_t
-hb_font_get_glyph_origin_for_direction
-hb_font_get_glyph_origin_func_t
-hb_font_get_glyph_v_advance
-hb_font_get_glyph_v_advance_func_t
-hb_font_get_glyph_v_kerning
-hb_font_get_glyph_v_kerning_func_t
-hb_font_get_glyph_v_origin
-hb_font_get_glyph_v_origin_func_t
-hb_font_get_parent
-hb_font_get_ppem
-hb_font_get_scale
-hb_font_get_user_data
-hb_font_glyph_from_string
-hb_font_glyph_to_string
-hb_font_is_immutable
-hb_font_make_immutable
-hb_font_reference
-hb_font_set_funcs
-hb_font_set_funcs_data
-hb_font_set_ppem
-hb_font_set_scale
-hb_font_set_user_data
-hb_font_subtract_glyph_origin_for_direction
-hb_font_t
-hb_reference_table_func_t
-</SECTION>
-
-<SECTION>
-<FILE>hb-ft</FILE>
-hb_ft_face_create
-hb_ft_face_create_cached
-hb_ft_font_create
-hb_ft_font_get_face
-hb_ft_font_set_funcs
-</SECTION>
-
-<SECTION>
-<FILE>hb-glib</FILE>
-hb_glib_get_unicode_funcs
-hb_glib_script_from_script
-hb_glib_script_to_script
-</SECTION>
-
-<SECTION>
-<FILE>hb-gobject</FILE>
-HB_GOBJECT_TYPE_BLOB
-HB_GOBJECT_TYPE_BUFFER
-HB_GOBJECT_TYPE_BUFFER_CONTENT_TYPE
-HB_GOBJECT_TYPE_BUFFER_FLAGS
-HB_GOBJECT_TYPE_BUFFER_SERIALIZE_FLAGS
-HB_GOBJECT_TYPE_BUFFER_SERIALIZE_FORMAT
-HB_GOBJECT_TYPE_DIRECTION
-HB_GOBJECT_TYPE_FACE
-HB_GOBJECT_TYPE_FONT
-HB_GOBJECT_TYPE_FONT_FUNCS
-HB_GOBJECT_TYPE_MEMORY_MODE
-HB_GOBJECT_TYPE_OT_LAYOUT_GLYPH_CLASS
-HB_GOBJECT_TYPE_SCRIPT
-HB_GOBJECT_TYPE_SHAPE_PLAN
-HB_GOBJECT_TYPE_UNICODE_COMBINING_CLASS
-HB_GOBJECT_TYPE_UNICODE_FUNCS
-HB_GOBJECT_TYPE_UNICODE_GENERAL_CATEGORY
-hb_gobject_blob_get_type
-hb_gobject_buffer_content_type_get_type
-hb_gobject_buffer_flags_get_type
-hb_gobject_buffer_get_type
-hb_gobject_buffer_serialize_flags_get_type
-hb_gobject_buffer_serialize_format_get_type
-hb_gobject_direction_get_type
-hb_gobject_face_get_type
-hb_gobject_font_funcs_get_type
-hb_gobject_font_get_type
-hb_gobject_memory_mode_get_type
-hb_gobject_ot_layout_glyph_class_get_type
-hb_gobject_script_get_type
-hb_gobject_shape_plan_get_type
-hb_gobject_unicode_combining_class_get_type
-hb_gobject_unicode_funcs_get_type
-hb_gobject_unicode_general_category_get_type
-<SUBSECTION Private>
-HB_GOBJECT_H_IN
-</SECTION>
-
-<SECTION>
-<FILE>hb-gobject</FILE>
-
-</SECTION>
-
-<SECTION>
-<FILE>hb-graphite2</FILE>
-HB_GRAPHITE2_TAG_SILF
-hb_graphite2_face_get_gr_face
-hb_graphite2_font_get_gr_font
-</SECTION>
-
-<SECTION>
-<FILE>hb-icu</FILE>
-hb_icu_get_unicode_funcs
-hb_icu_script_from_script
-hb_icu_script_to_script
-</SECTION>
-
-<SECTION>
-<FILE>hb-ot</FILE>
-<SUBSECTION Private>
-HB_OT_H_IN
-</SECTION>
-
-<SECTION>
-<FILE>hb-ot-font</FILE>
-hb_ot_font_set_funcs
-</SECTION>
-
-<SECTION>
-<FILE>hb-ot-shape</FILE>
-hb_ot_shape_glyphs_closure
-</SECTION>
-
-<SECTION>
-<FILE>hb-ot-layout</FILE>
-HB_OT_LAYOUT_DEFAULT_LANGUAGE_INDEX
-HB_OT_LAYOUT_NO_FEATURE_INDEX
-HB_OT_LAYOUT_NO_SCRIPT_INDEX
-HB_OT_TAG_GDEF
-HB_OT_TAG_GPOS
-HB_OT_TAG_GSUB
-hb_ot_layout_collect_lookups
-hb_ot_layout_feature_get_lookups
-hb_ot_layout_get_attach_points
-hb_ot_layout_get_glyph_class
-hb_ot_layout_get_glyphs_in_class
-hb_ot_layout_get_ligature_carets
-hb_ot_layout_get_size_params
-hb_ot_layout_glyph_class_t
-hb_ot_layout_glyph_sequence_func_t
-hb_ot_layout_has_glyph_classes
-hb_ot_layout_has_positioning
-hb_ot_layout_has_substitution
-hb_ot_layout_language_find_feature
-hb_ot_layout_language_get_feature_indexes
-hb_ot_layout_language_get_feature_tags
-hb_ot_layout_language_get_required_feature
-hb_ot_layout_lookup_collect_glyphs
-hb_ot_layout_lookup_substitute_closure
-hb_ot_layout_lookup_would_substitute
-hb_ot_layout_script_find_language
-hb_ot_layout_script_get_language_tags
-hb_ot_layout_table_choose_script
-hb_ot_layout_table_find_script
-hb_ot_layout_table_get_feature_tags
-hb_ot_layout_table_get_script_tags
-hb_ot_layout_table_get_lookup_count
-hb_ot_shape_plan_collect_lookups
-<SUBSECTION Private>
-Xhb_ot_layout_lookup_enumerate_sequences
-Xhb_ot_layout_lookup_position
-Xhb_ot_layout_lookup_substitute
-</SECTION>
-
-<SECTION>
-<FILE>hb-ot-tag</FILE>
-HB_OT_TAG_DEFAULT_LANGUAGE
-HB_OT_TAG_DEFAULT_SCRIPT
-hb_ot_tag_from_language
-hb_ot_tag_to_language
-hb_ot_tag_to_script
-hb_ot_tags_from_script
-</SECTION>
-
-<SECTION>
-<FILE>hb-set</FILE>
-HB_SET_VALUE_INVALID
-hb_set_add
-hb_set_add_range
-hb_set_allocation_successful
-hb_set_clear
-hb_set_create
-hb_set_del
-hb_set_del_range
-hb_set_destroy
-hb_set_get_empty
-hb_set_get_max
-hb_set_get_min
-hb_set_get_population
-hb_set_get_user_data
-hb_set_has
-hb_set_intersect
-hb_set_invert
-hb_set_is_empty
-hb_set_is_equal
-hb_set_next
-hb_set_next_range
-hb_set_reference
-hb_set_set
-hb_set_set_user_data
-hb_set_subtract
-hb_set_symmetric_difference
-hb_set_t
-hb_set_union
-</SECTION>
-
-<SECTION>
-<FILE>hb-shape</FILE>
-hb_feature_from_string
-hb_feature_t
-hb_feature_to_string
-hb_shape
-hb_shape_full
-hb_shape_list_shapers
-</SECTION>
-
-<SECTION>
-<FILE>hb-shape-plan</FILE>
-hb_shape_plan_create
-hb_shape_plan_create_cached
-hb_shape_plan_destroy
-hb_shape_plan_execute
-hb_shape_plan_get_empty
-hb_shape_plan_get_shaper
-hb_shape_plan_get_user_data
-hb_shape_plan_reference
-hb_shape_plan_set_user_data
-hb_shape_plan_t
-</SECTION>
-
-<SECTION>
-<FILE>hb-unicode</FILE>
-HB_UNICODE_MAX_DECOMPOSITION_LEN
-hb_unicode_combining_class
-hb_unicode_combining_class_func_t
-hb_unicode_combining_class_t
-hb_unicode_compose
-hb_unicode_compose_func_t
-hb_unicode_decompose
-hb_unicode_decompose_compatibility
-hb_unicode_decompose_func_t
-hb_unicode_eastasian_width
-hb_unicode_funcs_create
-hb_unicode_funcs_destroy
-hb_unicode_funcs_get_default
-hb_unicode_funcs_get_empty
-hb_unicode_funcs_get_parent
-hb_unicode_funcs_get_user_data
-hb_unicode_funcs_is_immutable
-hb_unicode_funcs_make_immutable
-hb_unicode_funcs_reference
-hb_unicode_funcs_set_combining_class_func
-hb_unicode_funcs_set_compose_func
-hb_unicode_funcs_set_decompose_compatibility_func
-hb_unicode_funcs_set_decompose_func
-hb_unicode_funcs_set_eastasian_width_func
-hb_unicode_funcs_set_general_category_func
-hb_unicode_funcs_set_mirroring_func
-hb_unicode_funcs_set_script_func
-hb_unicode_funcs_set_user_data
-hb_unicode_funcs_t
-hb_unicode_general_category
-hb_unicode_general_category_func_t
-hb_unicode_general_category_t
-hb_unicode_mirroring
-hb_unicode_mirroring_func_t
-hb_unicode_script
-hb_unicode_script_func_t
-</SECTION>
-
-<SECTION>
-<FILE>hb-uniscribe</FILE>
-hb_uniscribe_font_get_hfont
-hb_uniscribe_font_get_logfontw
-</SECTION>
-
-<SECTION>
-<FILE>hb-version</FILE>
-HB_VERSION_ATLEAST
-HB_VERSION_MAJOR
-HB_VERSION_MICRO
-HB_VERSION_MINOR
-HB_VERSION_STRING
-hb_version
-hb_version_atleast
-hb_version_string
-</SECTION>
diff --git a/docs/reference/usermanual-ch01.xml b/docs/reference/usermanual-ch01.xml
deleted file mode 100644
index 3574d75..0000000
--- a/docs/reference/usermanual-ch01.xml
+++ /dev/null
@@ -1,115 +0,0 @@
-<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.
- </para>
- <section id="why-do-i-need-it">
- <title>Why do I need it?</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.
- </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:
- </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.
- </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.
- </para>
- </listitem>
- <listitem>
- <para>
- While ligatures like "fi" are typographic
- refinements, some languages <emphasis>require</emphasis> such
- 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>
- </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.
- </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
- 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.
- </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.
- </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
- 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
diff --git a/docs/reference/usermanual-ch02.xml b/docs/reference/usermanual-ch02.xml
deleted file mode 100644
index 34db017..0000000
--- a/docs/reference/usermanual-ch02.xml
+++ /dev/null
@@ -1,183 +0,0 @@
-<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>
- <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
diff --git a/docs/reference/usermanual-ch03.xml b/docs/reference/usermanual-ch03.xml
deleted file mode 100644
index 3a26c55..0000000
--- a/docs/reference/usermanual-ch03.xml
+++ /dev/null
@@ -1,77 +0,0 @@
-<chapter id="buffers-language-script-and-direction">
- <title>Buffers, language, script and direction</title>
- <para>
- The input to Harfbuzz is a series of Unicode characters, stored in a
- buffer. In this chapter, we'll look at how to set up a buffer with
- the text that we want and then customize the properties of the
- buffer.
- </para>
- <section id="creating-and-destroying-buffers">
- <title>Creating and destroying buffers</title>
- <para>
- As we saw in our initial example, a buffer is created and
- initialized with <literal>hb_buffer_create()</literal>. This
- produces a new, empty buffer object, instantiated with some
- default values and ready to accept your Unicode strings.
- </para>
- <para>
- Harfbuzz manages the memory of objects that it creates (such as
- buffers), so you don't have to. When you have finished working on
- a buffer, you can call <literal>hb_buffer_destroy()</literal>:
- </para>
- <programlisting language="C">
- hb_buffer_t *buffer = hb_buffer_create();
- ...
- hb_buffer_destroy(buffer);
-</programlisting>
- <para>
- This will destroy the object and free its associated memory -
- unless some other part of the program holds a reference to this
- buffer. If you acquire a Harfbuzz buffer from another subsystem
- and want to ensure that it is not garbage collected by someone
- else destroying it, you should increase its reference count:
- </para>
- <programlisting language="C">
-void somefunc(hb_buffer_t *buffer) {
- buffer = hb_buffer_reference(buffer);
- ...
-</programlisting>
- <para>
- And then decrease it once you're done with it:
- </para>
- <programlisting language="C">
- hb_buffer_destroy(buffer);
-}
-</programlisting>
- <para>
- To throw away all the data in your buffer and start from scratch,
- call <literal>hb_buffer_reset(buffer)</literal>. If you want to
- throw away the string in the buffer but keep the options, you can
- instead call <literal>hb_buffer_clear_contents(buffer)</literal>.
- </para>
- </section>
- <section id="adding-text-to-the-buffer">
- <title>Adding text to the buffer</title>
- <para>
- Now we have a brand new Harfbuzz buffer. Let's start filling it
- with text! From Harfbuzz's perspective, a buffer is just a stream
- of Unicode codepoints, but your input string is probably in one of
- the standard Unicode character encodings (UTF-8, UTF-16, UTF-32)
- </para>
- </section>
- <section id="setting-buffer-properties">
- <title>Setting buffer properties</title>
- <para>
- </para>
- </section>
- <section id="what-about-the-other-scripts">
- <title>What about the other scripts?</title>
- <para>
- </para>
- </section>
- <section id="customizing-unicode-functions">
- <title>Customizing Unicode functions</title>
- <para>
- </para>
- </section>
-</chapter>
\ No newline at end of file
diff --git a/docs/reference/usermanual-ch04.xml b/docs/reference/usermanual-ch04.xml
deleted file mode 100644
index 01fcdc9..0000000
--- a/docs/reference/usermanual-ch04.xml
+++ /dev/null
@@ -1,18 +0,0 @@
-<chapter id="fonts-and-faces">
- <title>Fonts and faces</title>
- <section id="using-freetype">
- <title>Using FreeType</title>
- <para>
- </para>
- </section>
- <section id="using-harfbuzzs-native-opentype-implementation">
- <title>Using Harfbuzz's native OpenType implementation</title>
- <para>
- </para>
- </section>
- <section id="using-your-own-font-functions">
- <title>Using your own font functions</title>
- <para>
- </para>
- </section>
-</chapter>
\ No newline at end of file
diff --git a/docs/reference/usermanual-ch05.xml b/docs/reference/usermanual-ch05.xml
deleted file mode 100644
index 470bab8..0000000
--- a/docs/reference/usermanual-ch05.xml
+++ /dev/null
@@ -1,13 +0,0 @@
-<chapter id="shaping-and-shape-plans">
- <title>Shaping and shape plans</title>
- <section id="opentype-features">
- <title>OpenType features</title>
- <para>
- </para>
- </section>
- <section id="plans-and-caching">
- <title>Plans and caching</title>
- <para>
- </para>
- </section>
-</chapter>
\ No newline at end of file
diff --git a/docs/reference/usermanual-ch06.xml b/docs/reference/usermanual-ch06.xml
deleted file mode 100644
index ca674c0..0000000
--- a/docs/reference/usermanual-ch06.xml
+++ /dev/null
@@ -1,8 +0,0 @@
-<sect1 id="glyph-information">
- <title>Glyph information</title>
- <sect2 id="names-and-numbers">
- <title>Names and numbers</title>
- <para>
- </para>
- </sect2>
-</sect1>
\ No newline at end of file
diff --git a/docs/reference/version.xml.in b/docs/reference/version.xml.in
deleted file mode 100644
index de213c2..0000000
--- a/docs/reference/version.xml.in
+++ /dev/null
@@ -1 +0,0 @@
- at HB_VERSION@
diff --git a/docs/usermanual-ch01.xml b/docs/usermanual-ch01.xml
new file mode 100644
index 0000000..3574d75
--- /dev/null
+++ b/docs/usermanual-ch01.xml
@@ -0,0 +1,115 @@
+<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.
+ </para>
+ <section id="why-do-i-need-it">
+ <title>Why do I need it?</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.
+ </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:
+ </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.
+ </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.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ While ligatures like "fi" are typographic
+ refinements, some languages <emphasis>require</emphasis> such
+ 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>
+ </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.
+ </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
+ 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.
+ </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.
+ </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
+ 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
diff --git a/docs/usermanual-ch02.xml b/docs/usermanual-ch02.xml
new file mode 100644
index 0000000..34db017
--- /dev/null
+++ b/docs/usermanual-ch02.xml
@@ -0,0 +1,183 @@
+<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>
+ <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
diff --git a/docs/usermanual-ch03.xml b/docs/usermanual-ch03.xml
new file mode 100644
index 0000000..3a26c55
--- /dev/null
+++ b/docs/usermanual-ch03.xml
@@ -0,0 +1,77 @@
+<chapter id="buffers-language-script-and-direction">
+ <title>Buffers, language, script and direction</title>
+ <para>
+ The input to Harfbuzz is a series of Unicode characters, stored in a
+ buffer. In this chapter, we'll look at how to set up a buffer with
+ the text that we want and then customize the properties of the
+ buffer.
+ </para>
+ <section id="creating-and-destroying-buffers">
+ <title>Creating and destroying buffers</title>
+ <para>
+ As we saw in our initial example, a buffer is created and
+ initialized with <literal>hb_buffer_create()</literal>. This
+ produces a new, empty buffer object, instantiated with some
+ default values and ready to accept your Unicode strings.
+ </para>
+ <para>
+ Harfbuzz manages the memory of objects that it creates (such as
+ buffers), so you don't have to. When you have finished working on
+ a buffer, you can call <literal>hb_buffer_destroy()</literal>:
+ </para>
+ <programlisting language="C">
+ hb_buffer_t *buffer = hb_buffer_create();
+ ...
+ hb_buffer_destroy(buffer);
+</programlisting>
+ <para>
+ This will destroy the object and free its associated memory -
+ unless some other part of the program holds a reference to this
+ buffer. If you acquire a Harfbuzz buffer from another subsystem
+ and want to ensure that it is not garbage collected by someone
+ else destroying it, you should increase its reference count:
+ </para>
+ <programlisting language="C">
+void somefunc(hb_buffer_t *buffer) {
+ buffer = hb_buffer_reference(buffer);
+ ...
+</programlisting>
+ <para>
+ And then decrease it once you're done with it:
+ </para>
+ <programlisting language="C">
+ hb_buffer_destroy(buffer);
+}
+</programlisting>
+ <para>
+ To throw away all the data in your buffer and start from scratch,
+ call <literal>hb_buffer_reset(buffer)</literal>. If you want to
+ throw away the string in the buffer but keep the options, you can
+ instead call <literal>hb_buffer_clear_contents(buffer)</literal>.
+ </para>
+ </section>
+ <section id="adding-text-to-the-buffer">
+ <title>Adding text to the buffer</title>
+ <para>
+ Now we have a brand new Harfbuzz buffer. Let's start filling it
+ with text! From Harfbuzz's perspective, a buffer is just a stream
+ of Unicode codepoints, but your input string is probably in one of
+ the standard Unicode character encodings (UTF-8, UTF-16, UTF-32)
+ </para>
+ </section>
+ <section id="setting-buffer-properties">
+ <title>Setting buffer properties</title>
+ <para>
+ </para>
+ </section>
+ <section id="what-about-the-other-scripts">
+ <title>What about the other scripts?</title>
+ <para>
+ </para>
+ </section>
+ <section id="customizing-unicode-functions">
+ <title>Customizing Unicode functions</title>
+ <para>
+ </para>
+ </section>
+</chapter>
\ No newline at end of file
diff --git a/docs/usermanual-ch04.xml b/docs/usermanual-ch04.xml
new file mode 100644
index 0000000..01fcdc9
--- /dev/null
+++ b/docs/usermanual-ch04.xml
@@ -0,0 +1,18 @@
+<chapter id="fonts-and-faces">
+ <title>Fonts and faces</title>
+ <section id="using-freetype">
+ <title>Using FreeType</title>
+ <para>
+ </para>
+ </section>
+ <section id="using-harfbuzzs-native-opentype-implementation">
+ <title>Using Harfbuzz's native OpenType implementation</title>
+ <para>
+ </para>
+ </section>
+ <section id="using-your-own-font-functions">
+ <title>Using your own font functions</title>
+ <para>
+ </para>
+ </section>
+</chapter>
\ No newline at end of file
diff --git a/docs/usermanual-ch05.xml b/docs/usermanual-ch05.xml
new file mode 100644
index 0000000..470bab8
--- /dev/null
+++ b/docs/usermanual-ch05.xml
@@ -0,0 +1,13 @@
+<chapter id="shaping-and-shape-plans">
+ <title>Shaping and shape plans</title>
+ <section id="opentype-features">
+ <title>OpenType features</title>
+ <para>
+ </para>
+ </section>
+ <section id="plans-and-caching">
+ <title>Plans and caching</title>
+ <para>
+ </para>
+ </section>
+</chapter>
\ No newline at end of file
diff --git a/docs/usermanual-ch06.xml b/docs/usermanual-ch06.xml
new file mode 100644
index 0000000..ca674c0
--- /dev/null
+++ b/docs/usermanual-ch06.xml
@@ -0,0 +1,8 @@
+<sect1 id="glyph-information">
+ <title>Glyph information</title>
+ <sect2 id="names-and-numbers">
+ <title>Names and numbers</title>
+ <para>
+ </para>
+ </sect2>
+</sect1>
\ No newline at end of file
diff --git a/docs/version.xml.in b/docs/version.xml.in
new file mode 100644
index 0000000..de213c2
--- /dev/null
+++ b/docs/version.xml.in
@@ -0,0 +1 @@
+ at HB_VERSION@
commit cd5e3a13a6e0b6606d3a421f8cd44cdfb8314907
Author: Behdad Esfahbod <behdad at behdad.org>
Date: Mon Aug 31 19:16:41 2015 +0100
[docs] Fix out-of-tree build
diff --git a/docs/reference/Makefile.am b/docs/reference/Makefile.am
index f7a4ad6..f605f24 100644
--- a/docs/reference/Makefile.am
+++ b/docs/reference/Makefile.am
@@ -69,7 +69,14 @@ 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= version.xml
+content_files= \
+ usermanual-ch01.xml \
+ usermanual-ch02.xml \
+ usermanual-ch03.xml \
+ usermanual-ch04.xml \
+ usermanual-ch05.xml \
+ usermanual-ch06.xml \
+ version.xml
# SGML files where gtk-doc abbrevations (#GtkWidget) are expanded
# These files must be listed here *and* in content_files
diff --git a/docs/reference/harfbuzz-docs.xml b/docs/reference/harfbuzz-docs.xml
index 788372a..60ff8e2 100644
--- a/docs/reference/harfbuzz-docs.xml
+++ b/docs/reference/harfbuzz-docs.xml
@@ -16,12 +16,12 @@
<part>
<title>User's manual</title>
- <xi:include href="../usermanual-ch01.xml"/>
- <xi:include href="../usermanual-ch02.xml"/>
- <xi:include href="../usermanual-ch03.xml"/>
- <xi:include href="../usermanual-ch04.xml"/>
- <xi:include href="../usermanual-ch05.xml"/>
- <xi:include href="../usermanual-ch06.xml"/>
+ <xi:include href="usermanual-ch01.xml"/>
+ <xi:include href="usermanual-ch02.xml"/>
+ <xi:include href="usermanual-ch03.xml"/>
+ <xi:include href="usermanual-ch04.xml"/>
+ <xi:include href="usermanual-ch05.xml"/>
+ <xi:include href="usermanual-ch06.xml"/>
</part>
<part>
diff --git a/docs/reference/usermanual-ch01.xml b/docs/reference/usermanual-ch01.xml
new file mode 100644
index 0000000..3574d75
--- /dev/null
+++ b/docs/reference/usermanual-ch01.xml
@@ -0,0 +1,115 @@
+<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.
+ </para>
+ <section id="why-do-i-need-it">
+ <title>Why do I need it?</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.
+ </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:
+ </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.
+ </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.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ While ligatures like "fi" are typographic
+ refinements, some languages <emphasis>require</emphasis> such
+ 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>
+ </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.
+ </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
+ 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.
+ </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.
+ </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
+ 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
diff --git a/docs/reference/usermanual-ch02.xml b/docs/reference/usermanual-ch02.xml
new file mode 100644
index 0000000..34db017
--- /dev/null
+++ b/docs/reference/usermanual-ch02.xml
@@ -0,0 +1,183 @@
+<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>
+ <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
diff --git a/docs/reference/usermanual-ch03.xml b/docs/reference/usermanual-ch03.xml
new file mode 100644
index 0000000..3a26c55
--- /dev/null
+++ b/docs/reference/usermanual-ch03.xml
@@ -0,0 +1,77 @@
+<chapter id="buffers-language-script-and-direction">
+ <title>Buffers, language, script and direction</title>
+ <para>
+ The input to Harfbuzz is a series of Unicode characters, stored in a
+ buffer. In this chapter, we'll look at how to set up a buffer with
+ the text that we want and then customize the properties of the
+ buffer.
+ </para>
+ <section id="creating-and-destroying-buffers">
+ <title>Creating and destroying buffers</title>
+ <para>
+ As we saw in our initial example, a buffer is created and
+ initialized with <literal>hb_buffer_create()</literal>. This
+ produces a new, empty buffer object, instantiated with some
+ default values and ready to accept your Unicode strings.
+ </para>
+ <para>
+ Harfbuzz manages the memory of objects that it creates (such as
+ buffers), so you don't have to. When you have finished working on
+ a buffer, you can call <literal>hb_buffer_destroy()</literal>:
+ </para>
+ <programlisting language="C">
+ hb_buffer_t *buffer = hb_buffer_create();
+ ...
+ hb_buffer_destroy(buffer);
+</programlisting>
+ <para>
+ This will destroy the object and free its associated memory -
+ unless some other part of the program holds a reference to this
+ buffer. If you acquire a Harfbuzz buffer from another subsystem
+ and want to ensure that it is not garbage collected by someone
+ else destroying it, you should increase its reference count:
+ </para>
+ <programlisting language="C">
+void somefunc(hb_buffer_t *buffer) {
+ buffer = hb_buffer_reference(buffer);
+ ...
+</programlisting>
+ <para>
+ And then decrease it once you're done with it:
+ </para>
+ <programlisting language="C">
+ hb_buffer_destroy(buffer);
+}
+</programlisting>
+ <para>
+ To throw away all the data in your buffer and start from scratch,
+ call <literal>hb_buffer_reset(buffer)</literal>. If you want to
+ throw away the string in the buffer but keep the options, you can
+ instead call <literal>hb_buffer_clear_contents(buffer)</literal>.
+ </para>
+ </section>
+ <section id="adding-text-to-the-buffer">
+ <title>Adding text to the buffer</title>
+ <para>
+ Now we have a brand new Harfbuzz buffer. Let's start filling it
+ with text! From Harfbuzz's perspective, a buffer is just a stream
+ of Unicode codepoints, but your input string is probably in one of
+ the standard Unicode character encodings (UTF-8, UTF-16, UTF-32)
+ </para>
+ </section>
+ <section id="setting-buffer-properties">
+ <title>Setting buffer properties</title>
+ <para>
+ </para>
+ </section>
+ <section id="what-about-the-other-scripts">
+ <title>What about the other scripts?</title>
+ <para>
+ </para>
+ </section>
+ <section id="customizing-unicode-functions">
+ <title>Customizing Unicode functions</title>
+ <para>
+ </para>
+ </section>
+</chapter>
\ No newline at end of file
diff --git a/docs/reference/usermanual-ch04.xml b/docs/reference/usermanual-ch04.xml
new file mode 100644
index 0000000..01fcdc9
--- /dev/null
+++ b/docs/reference/usermanual-ch04.xml
@@ -0,0 +1,18 @@
+<chapter id="fonts-and-faces">
+ <title>Fonts and faces</title>
+ <section id="using-freetype">
+ <title>Using FreeType</title>
+ <para>
+ </para>
+ </section>
+ <section id="using-harfbuzzs-native-opentype-implementation">
+ <title>Using Harfbuzz's native OpenType implementation</title>
+ <para>
+ </para>
+ </section>
+ <section id="using-your-own-font-functions">
+ <title>Using your own font functions</title>
+ <para>
+ </para>
+ </section>
+</chapter>
\ No newline at end of file
diff --git a/docs/reference/usermanual-ch05.xml b/docs/reference/usermanual-ch05.xml
new file mode 100644
index 0000000..470bab8
--- /dev/null
+++ b/docs/reference/usermanual-ch05.xml
@@ -0,0 +1,13 @@
+<chapter id="shaping-and-shape-plans">
+ <title>Shaping and shape plans</title>
+ <section id="opentype-features">
+ <title>OpenType features</title>
+ <para>
+ </para>
+ </section>
+ <section id="plans-and-caching">
+ <title>Plans and caching</title>
+ <para>
+ </para>
+ </section>
+</chapter>
\ No newline at end of file
diff --git a/docs/reference/usermanual-ch06.xml b/docs/reference/usermanual-ch06.xml
new file mode 100644
index 0000000..ca674c0
--- /dev/null
+++ b/docs/reference/usermanual-ch06.xml
@@ -0,0 +1,8 @@
+<sect1 id="glyph-information">
+ <title>Glyph information</title>
+ <sect2 id="names-and-numbers">
+ <title>Names and numbers</title>
+ <para>
+ </para>
+ </sect2>
+</sect1>
\ No newline at end of file
diff --git a/docs/usermanual-ch01.xml b/docs/usermanual-ch01.xml
deleted file mode 100644
index 3574d75..0000000
--- a/docs/usermanual-ch01.xml
+++ /dev/null
@@ -1,115 +0,0 @@
-<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.
- </para>
- <section id="why-do-i-need-it">
- <title>Why do I need it?</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.
- </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:
- </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.
- </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.
- </para>
- </listitem>
- <listitem>
- <para>
- While ligatures like "fi" are typographic
- refinements, some languages <emphasis>require</emphasis> such
- 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>
- </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.
- </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
- 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.
- </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.
- </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
- 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
diff --git a/docs/usermanual-ch02.xml b/docs/usermanual-ch02.xml
deleted file mode 100644
index 34db017..0000000
--- a/docs/usermanual-ch02.xml
+++ /dev/null
@@ -1,183 +0,0 @@
-<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>
- <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
diff --git a/docs/usermanual-ch03.xml b/docs/usermanual-ch03.xml
deleted file mode 100644
index 3a26c55..0000000
--- a/docs/usermanual-ch03.xml
+++ /dev/null
@@ -1,77 +0,0 @@
-<chapter id="buffers-language-script-and-direction">
- <title>Buffers, language, script and direction</title>
- <para>
- The input to Harfbuzz is a series of Unicode characters, stored in a
- buffer. In this chapter, we'll look at how to set up a buffer with
- the text that we want and then customize the properties of the
- buffer.
- </para>
- <section id="creating-and-destroying-buffers">
- <title>Creating and destroying buffers</title>
- <para>
- As we saw in our initial example, a buffer is created and
- initialized with <literal>hb_buffer_create()</literal>. This
- produces a new, empty buffer object, instantiated with some
- default values and ready to accept your Unicode strings.
- </para>
- <para>
- Harfbuzz manages the memory of objects that it creates (such as
- buffers), so you don't have to. When you have finished working on
- a buffer, you can call <literal>hb_buffer_destroy()</literal>:
- </para>
- <programlisting language="C">
- hb_buffer_t *buffer = hb_buffer_create();
- ...
- hb_buffer_destroy(buffer);
-</programlisting>
- <para>
- This will destroy the object and free its associated memory -
- unless some other part of the program holds a reference to this
- buffer. If you acquire a Harfbuzz buffer from another subsystem
- and want to ensure that it is not garbage collected by someone
- else destroying it, you should increase its reference count:
- </para>
- <programlisting language="C">
-void somefunc(hb_buffer_t *buffer) {
- buffer = hb_buffer_reference(buffer);
- ...
-</programlisting>
- <para>
- And then decrease it once you're done with it:
- </para>
- <programlisting language="C">
- hb_buffer_destroy(buffer);
-}
-</programlisting>
- <para>
- To throw away all the data in your buffer and start from scratch,
- call <literal>hb_buffer_reset(buffer)</literal>. If you want to
- throw away the string in the buffer but keep the options, you can
- instead call <literal>hb_buffer_clear_contents(buffer)</literal>.
- </para>
- </section>
- <section id="adding-text-to-the-buffer">
- <title>Adding text to the buffer</title>
- <para>
- Now we have a brand new Harfbuzz buffer. Let's start filling it
- with text! From Harfbuzz's perspective, a buffer is just a stream
- of Unicode codepoints, but your input string is probably in one of
- the standard Unicode character encodings (UTF-8, UTF-16, UTF-32)
- </para>
- </section>
- <section id="setting-buffer-properties">
- <title>Setting buffer properties</title>
- <para>
- </para>
- </section>
- <section id="what-about-the-other-scripts">
- <title>What about the other scripts?</title>
- <para>
- </para>
- </section>
- <section id="customizing-unicode-functions">
- <title>Customizing Unicode functions</title>
- <para>
- </para>
- </section>
-</chapter>
\ No newline at end of file
diff --git a/docs/usermanual-ch04.xml b/docs/usermanual-ch04.xml
deleted file mode 100644
index 01fcdc9..0000000
--- a/docs/usermanual-ch04.xml
+++ /dev/null
@@ -1,18 +0,0 @@
-<chapter id="fonts-and-faces">
- <title>Fonts and faces</title>
- <section id="using-freetype">
- <title>Using FreeType</title>
- <para>
- </para>
- </section>
- <section id="using-harfbuzzs-native-opentype-implementation">
- <title>Using Harfbuzz's native OpenType implementation</title>
- <para>
- </para>
- </section>
- <section id="using-your-own-font-functions">
- <title>Using your own font functions</title>
- <para>
- </para>
- </section>
-</chapter>
\ No newline at end of file
diff --git a/docs/usermanual-ch05.xml b/docs/usermanual-ch05.xml
deleted file mode 100644
index 470bab8..0000000
--- a/docs/usermanual-ch05.xml
+++ /dev/null
@@ -1,13 +0,0 @@
-<chapter id="shaping-and-shape-plans">
- <title>Shaping and shape plans</title>
- <section id="opentype-features">
- <title>OpenType features</title>
- <para>
- </para>
- </section>
- <section id="plans-and-caching">
- <title>Plans and caching</title>
- <para>
- </para>
- </section>
-</chapter>
\ No newline at end of file
diff --git a/docs/usermanual-ch06.xml b/docs/usermanual-ch06.xml
deleted file mode 100644
index ca674c0..0000000
--- a/docs/usermanual-ch06.xml
+++ /dev/null
@@ -1,8 +0,0 @@
-<sect1 id="glyph-information">
- <title>Glyph information</title>
- <sect2 id="names-and-numbers">
- <title>Names and numbers</title>
- <para>
- </para>
- </sect2>
-</sect1>
\ No newline at end of file
More information about the HarfBuzz
mailing list