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 <[email protected]> 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 "ï¬". Whether you should - render text as <literal>fi</literal> or "ï¬" 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 "ï¬" 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 @@ -@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 "ï¬". Whether you should + render text as <literal>fi</literal> or "ï¬" 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 "ï¬" 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 @@ +@HB_VERSION@ commit cd5e3a13a6e0b6606d3a421f8cd44cdfb8314907 Author: Behdad Esfahbod <[email protected]> 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 "ï¬". Whether you should + render text as <literal>fi</literal> or "ï¬" 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 "ï¬" 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 "ï¬". Whether you should - render text as <literal>fi</literal> or "ï¬" 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 "ï¬" 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
_______________________________________________ HarfBuzz mailing list [email protected] http://lists.freedesktop.org/mailman/listinfo/harfbuzz
