Cairo 1.12.14

Change-Id: Ibc39e63896ec42cab29fbbbf615a46f2d58319a8
Signed-off-by: hk57.kim <hk57.kim@samsung.com>

13 files changed, 1777 insertions, 0 deletions

diff --git a/doc/.gitignore b/doc/.gitignore
new file mode 100755
index 000000000..23c1897f1
--- /dev/null
+++ b/doc/.gitignore
@@ -0,0 +1,3 @@
+Makefile
+Makefile.in
+*~
diff --git a/doc/Makefile.am b/doc/Makefile.am
new file mode 100755
index 000000000..864a9f1df
--- /dev/null
+++ b/doc/Makefile.am
@@ -0,0 +1,7 @@
+include $(top_srcdir)/build/Makefile.am.common
+
+SUBDIRS=public
+
+doc:
+	cd public && $(MAKE) $(AM_MAKEFLAGS) doc
+.PHONY: doc
diff --git a/doc/cairo-evas-gl_doc.h b/doc/cairo-evas-gl_doc.h
new file mode 100755
index 000000000..fb010cb59
--- /dev/null
+++ b/doc/cairo-evas-gl_doc.h
@@ -0,0 +1,60 @@
+/* Cairo - a vector graphics library with display and print output
+ *
+ * Copyright © 2009 Eric Anholt
+ * Copyright © 2009 Chris Wilson
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it either under the terms of the GNU Lesser General Public
+ * License version 2.1 as published by the Free Software Foundation
+ * (the "LGPL") or, at your option, under the terms of the Mozilla
+ * Public License Version 1.1 (the "MPL"). If you do not alter this
+ * notice, a recipient may use your version of this file under either
+ * the MPL or the LGPL.
+ *
+ * You should have received a copy of the LGPL along with this library
+ * in the file COPYING-LGPL-2.1; if not, write to the Free Software
+ * Foundation, Inc., 51 Franklin Street, Suite 500, Boston, MA 02110-1335, USA
+ * You should have received a copy of the MPL along with this library
+ * in the file COPYING-MPL-1.1
+ *
+ * The contents of this file are subject to the Mozilla Public License
+ * Version 1.1 (the "License"); you may not use this file except in
+ * compliance with the License. You may obtain a copy of the License at
+ * http://www.mozilla.org/MPL/
+ *
+ * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY
+ * OF ANY KIND, either express or implied. See the LGPL or the MPL for
+ * the specific language governing rights and limitations.
+ *
+ * The Original Code is the cairo graphics library.
+ *
+ * The Initial Developer of the Original Code is Eric Anholt.
+ */
+
+#ifndef __TIZEN_CAIRO_EVAS_GL_DOC_H__
+#define __TIZEN_CAIRO_EVAS_GL_DOC_H__
+
+/**
+ * @defgroup CAPI_CAIRO_EVAS_GL_MODULE Cairo GL
+ * @brief  Cairo GL/Evas_GL APIs are offical APIs for Tizen.
+ * @ingroup OPENSRC_CAIRO_FRAMEWORK
+ *
+ * @section CAIRO_EVAS_GL Required Header
+ *   \#include <cairo-evas-gl.h>
+ *
+ * @section CAIRO_EVAS_GL_MODULE_OVERVIEW Overview
+ * In Tizen, Cairo provides gl backend in order to do hardware-accelerated rendering.
+ * Since the EGL is not public supported in Tizen, Cairo Evas_GL has been provided to user interfaces instead to allow indirect access to EGL layer.
+ *
+ * Features	:\n
+ *	- Support a new cairo_device structure for interface to the underlying GL or EvasGL.\n
+ *	- Support a new cairo_surface structure for representing GL or Evas_GL_Surface object that cairo can render to.\n
+ *	- Get the underlying Evas_GL object used to create cairo device object.\n
+ *	- Get the underlying Evas_GL_Context object used to create cairo device object.
+ *
+ * Remarks	:\n
+ *	- Cairo GL and Cairo Evas_GL will use an GL/Evas_GL context and API set.\n
+ *	- Therefore, Evas_GL and OpenGL-ES should be provided for normal operation of Cairo gl backend.\n
+ */
+
+#endif // __TIZEN_CAIRO_EVAS_GL_DOC_H__
diff --git a/doc/public/.gitignore b/doc/public/.gitignore
new file mode 100755
index 000000000..493a24172
--- /dev/null
+++ b/doc/public/.gitignore
@@ -0,0 +1,19 @@
+*.stamp
+Makefile
+Makefile.in
+cairo-decl-list.txt
+cairo-decl.txt
+cairo-docs.sgml
+cairo-undeclared.txt
+cairo-undocumented.txt
+cairo-unused.txt
+cairo.hierarchy
+cairo.interfaces
+cairo.prerequisites
+cairo.args
+cairo.signals
+html
+xml
+version.xml
+*~
+*.bak
diff --git a/doc/public/Makefile.am b/doc/public/Makefile.am
new file mode 100755
index 000000000..11f9e7b72
--- /dev/null
+++ b/doc/public/Makefile.am
@@ -0,0 +1,64 @@
+include $(top_srcdir)/build/Makefile.am.common
+include $(top_srcdir)/src/Makefile.am.features
+
+# The name of the module.
+DOC_MODULE=cairo
+
+# The top-level SGML file.
+DOC_MAIN_SGML_FILE=cairo-docs.xml
+
+# Extra options to supply to gtkdoc-scan
+SCAN_OPTIONS=--deprecated-guards="CAIRO_DISABLE_DEPRECATED" --ignore-decorators="cairo_public|cairo_private"
+
+# The directory containing the source code.
+DOC_SOURCE_DIR=$(top_srcdir)/src
+
+# Used for dependencies
+HFILE_GLOB=$(top_srcdir)/src/cairo*.h
+CFILE_GLOB=$(top_srcdir)/src/cairo*.c
+EXTRA_HFILES=$(top_builddir)/src/cairo-supported-features.h
+
+# Headers to ignore
+IGNORE_HFILES= \
+	drm \
+	cairo-features.h \
+	cairo-features-win32.h \
+	$(all_cairo_private) \
+	$(unsupported_cairo_headers) \
+	$(NULL)
+
+# Extra options to supply to gtkdoc-mkdb
+MKDB_OPTIONS=--sgml-mode --output-format=xml --name-space=cairo
+
+# Extra options to supply to gtkdoc-mktmpl
+MKTMPL_OPTIONS=
+
+# Non-autogenerated SGML files to be included in $(DOC_MAIN_SGML_FILE)
+content_files =	\
+	language-bindings.xml \
+	version.xml \
+	$(NULL)
+
+version.xml: $(top_srcdir)/cairo-version.h
+	echo $(CAIRO_VERSION_MAJOR).$(CAIRO_VERSION_MINOR).$(CAIRO_VERSION_MICRO) > $@
+
+# Images to copy into HTML directory
+HTML_IMAGES =
+
+# Extra options to supply to gtkdoc-fixref
+FIXXREF_OPTIONS=
+
+include $(top_srcdir)/build/Makefile.am.gtk-doc
+
+dist-hook: doc
+
+# This line really belongs in gtk-doc.mk
+$(REPORT_FILES): sgml-build.stamp
+
+if ENABLE_GTK_DOC
+TESTS += check-doc-coverage.sh
+endif
+
+TESTS += check-doc-syntax.sh
+EXTRA_DIST += check-doc-coverage.sh check-doc-syntax.sh
+TESTS_ENVIRONMENT = srcdir="$(srcdir)" top_srcdir="$(top_srcdir)" MAKE="$(MAKE) $(AM_MAKEFLAGS)" DOC_MODULE="$(DOC_MODULE)" REPORT_FILES="$(REPORT_FILES)"
diff --git a/doc/public/README b/doc/public/README
new file mode 100755
index 000000000..f3d157b1a
--- /dev/null
+++ b/doc/public/README
@@ -0,0 +1,37 @@
+Cairo Reference Documentation
+=============================
+
+The API documentation is generated using gtk-doc.
+
+
+Building
+--------
+
+The documentation is not built by default.  To build it you need to
+configure with gtk-doc enabled (--enable-gtk-doc), and run:
+
+	make doc
+
+
+Adding New API
+--------------
+
+When adding new symbols and macros to the public API, modify
+cairo-section.txt and add new symbols to the right place.
+
+When adding whole new features, you also need to modify cairo-docs.xml
+and add a new file under tmpl/.  Beware that the files are tmpl/ are
+both manually edited AND modified by gtk-doc, gathering documentation
+stub from source files.
+
+
+Tests
+-----
+
+There are some tests in this directory, ensuring proper documentation
+syntax as well as checking that all public symbols are fully documented.
+
+After adding any new API, just run:
+
+	make check
+
diff --git a/doc/public/cairo-docs.xml b/doc/public/cairo-docs.xml
new file mode 100755
index 000000000..baf844c18
--- /dev/null
+++ b/doc/public/cairo-docs.xml
@@ -0,0 +1,80 @@
+<?xml version='1.0' encoding='UTF-8'?> 
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+                "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
+<!ENTITY version SYSTEM "version.xml">
+]>
+<book lang="en" id="cairo" xmlns:xi="http://www.w3.org/2003/XInclude"> 
+<title>Cairo: A Vector Graphics Library</title>
+  <bookinfo>
+    <title>Cairo: A Vector Graphics Library</title>
+    <releaseinfo>for Cairo &version;</releaseinfo>
+  </bookinfo>
+  <chapter id="cairo-drawing">
+    <title>Drawing</title>
+    <xi:include href="xml/cairo.xml"/>
+    <xi:include href="xml/cairo-paths.xml"/>
+    <xi:include href="xml/cairo-pattern.xml"/>
+    <xi:include href="xml/cairo-region.xml"/>
+    <xi:include href="xml/cairo-transforms.xml"/>
+    <xi:include href="xml/cairo-text.xml"/>
+    <xi:include href="xml/cairo-raster-source.xml"/>
+  </chapter>
+  <chapter id="cairo-fonts">
+    <title>Fonts</title>
+    <xi:include href="xml/cairo-font-face.xml"/>
+    <xi:include href="xml/cairo-scaled-font.xml"/>
+    <xi:include href="xml/cairo-font-options.xml"/>
+    <xi:include href="xml/cairo-ft.xml"/>
+    <xi:include href="xml/cairo-win32-fonts.xml"/>
+    <xi:include href="xml/cairo-quartz-fonts.xml"/>
+    <xi:include href="xml/cairo-user-fonts.xml"/>
+  </chapter>
+  <chapter id="cairo-surfaces">
+    <title>Surfaces</title>
+    <xi:include href="xml/cairo-device.xml"/>
+    <xi:include href="xml/cairo-surface.xml"/>
+    <xi:include href="xml/cairo-image.xml"/>
+    <xi:include href="xml/cairo-pdf.xml"/>
+    <xi:include href="xml/cairo-png.xml"/>
+    <xi:include href="xml/cairo-ps.xml"/>
+    <xi:include href="xml/cairo-recording.xml"/>
+    <xi:include href="xml/cairo-win32.xml"/>
+    <!--xi:include href="xml/cairo-beos.xml"/-->
+    <xi:include href="xml/cairo-svg.xml"/>
+    <xi:include href="xml/cairo-quartz.xml" />
+    <!--xi:include href="xml/cairo-quartz-image.xml"/-->
+    <xi:include href="xml/cairo-xcb.xml"/>
+    <xi:include href="xml/cairo-xlib.xml"/>
+    <xi:include href="xml/cairo-xlib-xrender.xml"/>
+    <xi:include href="xml/cairo-script.xml"/>
+  </chapter>
+  <chapter id="cairo-support">
+    <title>Utilities</title>
+    <xi:include href="xml/cairo-matrix.xml"/>
+    <xi:include href="xml/cairo-status.xml"/>
+    <xi:include href="xml/cairo-version.xml"/>
+    <xi:include href="xml/cairo-types.xml"/>
+  </chapter>
+  <index id="index-all">
+    <title>Index</title>
+  </index>
+  <index id="index-1.2" role="1.2">
+    <title>Index of new symbols in 1.2</title>
+  </index>
+  <index id="index-1.4" role="1.4">
+    <title>Index of new symbols in 1.4</title>
+  </index>
+  <index id="index-1.6" role="1.6">
+    <title>Index of new symbols in 1.6</title>
+  </index>
+  <index id="index-1.8" role="1.8">
+    <title>Index of new symbols in 1.8</title>
+  </index>
+  <index id="index-1.10" role="1.10">
+    <title>Index of new symbols in 1.10</title>
+  </index>
+  <index id="index-1.12" role="1.12">
+    <title>Index of new symbols in 1.12</title>
+  </index>
+  <xi:include href="language-bindings.xml"/>
+</book>
diff --git a/doc/public/cairo-overrides.txt b/doc/public/cairo-overrides.txt
new file mode 100755
index 000000000..e69de29bb
--- /dev/null
+++ b/doc/public/cairo-overrides.txt
diff --git a/doc/public/cairo-sections.txt b/doc/public/cairo-sections.txt
new file mode 100755
index 000000000..c67da371c
--- /dev/null
+++ b/doc/public/cairo-sections.txt
@@ -0,0 +1,696 @@
+<SECTION>
+<FILE>cairo-ft</FILE>
+CAIRO_HAS_FT_FONT
+CAIRO_HAS_FC_FONT
+cairo_ft_font_face_create_for_ft_face
+cairo_ft_font_face_create_for_pattern
+cairo_ft_font_options_substitute
+cairo_ft_scaled_font_lock_face
+cairo_ft_scaled_font_unlock_face
+cairo_ft_synthesize_t
+cairo_ft_font_face_get_synthesize
+cairo_ft_font_face_set_synthesize
+cairo_ft_font_face_unset_synthesize
+</SECTION>
+
+<SECTION>
+<FILE>cairo-win32-fonts</FILE>
+CAIRO_HAS_WIN32_FONT
+cairo_win32_font_face_create_for_logfontw
+cairo_win32_font_face_create_for_hfont
+cairo_win32_font_face_create_for_logfontw_hfont
+cairo_win32_scaled_font_select_font
+cairo_win32_scaled_font_done_font
+cairo_win32_scaled_font_get_metrics_factor
+cairo_win32_scaled_font_get_logical_to_device
+cairo_win32_scaled_font_get_device_to_logical
+</SECTION>
+
+<SECTION>
+<FILE>cairo-quartz-fonts</FILE>
+CAIRO_HAS_QUARTZ_FONT
+cairo_quartz_font_face_create_for_cgfont
+cairo_quartz_font_face_create_for_atsu_font_id
+</SECTION>
+
+<SECTION>
+<FILE>cairo-user-fonts</FILE>
+CAIRO_HAS_USER_FONT
+cairo_user_scaled_font_init_func_t
+cairo_user_scaled_font_render_glyph_func_t
+cairo_user_scaled_font_text_to_glyphs_func_t
+cairo_user_scaled_font_unicode_to_glyph_func_t
+cairo_user_font_face_create
+cairo_user_font_face_set_init_func
+cairo_user_font_face_get_init_func
+cairo_user_font_face_set_render_glyph_func
+cairo_user_font_face_get_render_glyph_func
+cairo_user_font_face_set_unicode_to_glyph_func
+cairo_user_font_face_get_unicode_to_glyph_func
+cairo_user_font_face_set_text_to_glyphs_func
+cairo_user_font_face_get_text_to_glyphs_func
+</SECTION>
+
+<SECTION>
+<FILE>cairo-image</FILE>
+CAIRO_HAS_IMAGE_SURFACE
+cairo_format_t
+cairo_format_stride_for_width
+cairo_image_surface_create
+cairo_image_surface_create_for_data
+cairo_image_surface_get_data
+cairo_image_surface_get_format
+cairo_image_surface_get_width
+cairo_image_surface_get_height
+cairo_image_surface_get_stride
+</SECTION>
+
+<SECTION>
+<FILE>cairo-pdf</FILE>
+CAIRO_HAS_PDF_SURFACE
+cairo_pdf_surface_create
+cairo_pdf_surface_create_for_stream
+cairo_pdf_surface_restrict_to_version
+cairo_pdf_version_t
+cairo_pdf_get_versions
+cairo_pdf_version_to_string
+cairo_pdf_surface_set_size
+</SECTION>
+
+<SECTION>
+<FILE>cairo-png</FILE>
+CAIRO_HAS_PNG_FUNCTIONS
+cairo_image_surface_create_from_png
+cairo_read_func_t
+cairo_image_surface_create_from_png_stream
+cairo_surface_write_to_png
+cairo_write_func_t
+cairo_surface_write_to_png_stream
+</SECTION>
+
+<SECTION>
+<FILE>cairo-ps</FILE>
+CAIRO_HAS_PS_SURFACE
+cairo_ps_surface_create
+cairo_ps_surface_create_for_stream
+cairo_ps_surface_restrict_to_level
+cairo_ps_level_t
+cairo_ps_get_levels
+cairo_ps_level_to_string
+cairo_ps_surface_set_eps
+cairo_ps_surface_get_eps
+cairo_ps_surface_set_size
+cairo_ps_surface_dsc_begin_setup
+cairo_ps_surface_dsc_begin_page_setup
+cairo_ps_surface_dsc_comment
+</SECTION>
+
+<SECTION>
+<FILE>cairo-recording</FILE>
+CAIRO_HAS_RECORDING_SURFACE
+cairo_recording_surface_create
+cairo_recording_surface_ink_extents
+cairo_recording_surface_get_extents
+</SECTION>
+
+<SECTION>
+<FILE>cairo-win32</FILE>
+CAIRO_HAS_WIN32_SURFACE
+cairo_win32_surface_create
+cairo_win32_surface_create_with_dib
+cairo_win32_surface_create_with_ddb
+cairo_win32_printing_surface_create
+cairo_win32_surface_get_dc
+cairo_win32_surface_get_image
+<SUBSECTION Private>
+SB_NONE
+SHADEBLENDCAPS
+WIN32_FONT_LOGICAL_SCALE
+cairo_win32_device_t
+cairo_win32_display_surface_t
+cairo_win32_printing_surface_t
+cairo_win32_surface_t
+to_win32_device
+to_win32_device_from_surface
+to_win32_display_surface
+to_win32_printing_surface
+to_win32_surface
+</SECTION>
+
+<SECTION>
+<FILE>cairo-quartz</FILE>
+CAIRO_HAS_QUARTZ_SURFACE
+cairo_quartz_surface_create
+cairo_quartz_surface_create_for_cg_context
+cairo_quartz_surface_get_cg_context
+<SUBSECTION Private>
+cairo_quartz_image_surface_create
+cairo_quartz_image_surface_get_image
+</SECTION>
+
+<SECTION>
+<FILE>cairo-xlib</FILE>
+CAIRO_HAS_XLIB_SURFACE
+cairo_xlib_surface_create
+cairo_xlib_surface_create_for_bitmap
+cairo_xlib_surface_set_size
+cairo_xlib_surface_get_display
+cairo_xlib_surface_get_screen
+cairo_xlib_surface_set_drawable
+cairo_xlib_surface_get_drawable
+cairo_xlib_surface_get_visual
+cairo_xlib_surface_get_width
+cairo_xlib_surface_get_height
+cairo_xlib_surface_get_depth
+cairo_xlib_device_debug_cap_xrender_version
+cairo_xlib_device_debug_get_precision
+cairo_xlib_device_debug_set_precision
+</SECTION>
+
+<SECTION>
+<FILE>cairo-xlib-xrender</FILE>
+CAIRO_HAS_XLIB_XRENDER_SURFACE
+cairo_xlib_surface_create_with_xrender_format
+cairo_xlib_surface_get_xrender_format
+</SECTION>
+
+<SECTION>
+<FILE>cairo-xcb</FILE>
+CAIRO_HAS_XCB_SURFACE
+CAIRO_HAS_XCB_SHM_FUNCTIONS
+cairo_xcb_surface_create
+cairo_xcb_surface_create_for_bitmap
+cairo_xcb_surface_create_with_xrender_format
+cairo_xcb_surface_set_size
+cairo_xcb_surface_set_drawable
+cairo_xcb_device_get_connection
+cairo_xcb_device_debug_cap_xrender_version
+cairo_xcb_device_debug_cap_xshm_version
+cairo_xcb_device_debug_get_precision
+cairo_xcb_device_debug_set_precision
+</SECTION>
+
+<SECTION>
+<FILE>cairo-svg</FILE>
+CAIRO_HAS_SVG_SURFACE
+cairo_svg_surface_create
+cairo_svg_surface_create_for_stream
+cairo_svg_surface_restrict_to_version
+cairo_svg_version_t
+cairo_svg_get_versions
+cairo_svg_version_to_string
+</SECTION>
+
+<SECTION>
+<FILE>cairo-device</FILE>
+cairo_device_t
+cairo_device_reference
+cairo_device_destroy
+cairo_device_status
+cairo_device_finish
+cairo_device_flush
+cairo_device_type_t
+cairo_device_get_type
+cairo_device_get_reference_count
+cairo_device_set_user_data
+cairo_device_get_user_data
+cairo_device_acquire
+cairo_device_release
+</SECTION>
+
+<SECTION>
+<FILE>cairo-surface</FILE>
+CAIRO_HAS_MIME_SURFACE
+CAIRO_MIME_TYPE_JP2
+CAIRO_MIME_TYPE_JPEG
+CAIRO_MIME_TYPE_PNG
+CAIRO_MIME_TYPE_URI
+CAIRO_MIME_TYPE_UNIQUE_ID
+cairo_surface_t
+cairo_content_t
+cairo_surface_create_similar
+cairo_surface_create_similar_image
+cairo_surface_create_for_rectangle
+cairo_surface_reference
+cairo_surface_destroy
+cairo_surface_status
+cairo_surface_finish
+cairo_surface_flush
+cairo_surface_get_device
+cairo_surface_get_font_options
+cairo_surface_get_content
+cairo_surface_mark_dirty
+cairo_surface_mark_dirty_rectangle
+cairo_surface_set_device_offset
+cairo_surface_get_device_offset
+cairo_surface_set_fallback_resolution
+cairo_surface_get_fallback_resolution
+cairo_surface_type_t
+cairo_surface_get_type
+cairo_surface_get_reference_count
+cairo_surface_set_user_data
+cairo_surface_get_user_data
+cairo_surface_copy_page
+cairo_surface_show_page
+cairo_surface_has_show_text_glyphs
+cairo_surface_set_mime_data
+cairo_surface_get_mime_data
+cairo_surface_supports_mime_type
+cairo_surface_map_to_image
+cairo_surface_unmap_image
+</SECTION>
+
+<SECTION>
+<FILE>cairo-version</FILE>
+CAIRO_VERSION
+CAIRO_VERSION_MAJOR
+CAIRO_VERSION_MINOR
+CAIRO_VERSION_MICRO
+CAIRO_VERSION_STRING
+CAIRO_VERSION_ENCODE
+CAIRO_VERSION_STRINGIZE
+cairo_version
+cairo_version_string
+<SUBSECTION Private>
+CAIRO_VERSION_STRINGIZE_
+</SECTION>
+
+<SECTION>
+<FILE>cairo-region</FILE>
+cairo_region_t
+cairo_region_create
+cairo_region_create_rectangle
+cairo_region_create_rectangles
+cairo_region_copy
+cairo_region_reference
+cairo_region_destroy
+cairo_region_status
+cairo_region_get_extents
+cairo_region_num_rectangles
+cairo_region_get_rectangle
+cairo_region_is_empty
+cairo_region_contains_point
+cairo_region_overlap_t
+cairo_region_contains_rectangle
+cairo_region_equal
+cairo_region_translate
+cairo_region_intersect
+cairo_region_intersect_rectangle
+cairo_region_subtract
+cairo_region_subtract_rectangle
+cairo_region_union
+cairo_region_union_rectangle
+cairo_region_xor
+cairo_region_xor_rectangle
+</SECTION>
+
+<SECTION>
+<FILE>cairo-pattern</FILE>
+cairo_pattern_t
+cairo_pattern_add_color_stop_rgb
+cairo_pattern_add_color_stop_rgba
+cairo_pattern_get_color_stop_count
+cairo_pattern_get_color_stop_rgba
+cairo_pattern_create_rgb
+cairo_pattern_create_rgba
+cairo_pattern_get_rgba
+cairo_pattern_create_for_surface
+cairo_pattern_get_surface
+cairo_pattern_create_linear
+cairo_pattern_get_linear_points
+cairo_pattern_create_radial
+cairo_pattern_get_radial_circles
+cairo_pattern_create_mesh
+cairo_mesh_pattern_begin_patch
+cairo_mesh_pattern_end_patch
+cairo_mesh_pattern_move_to
+cairo_mesh_pattern_line_to
+cairo_mesh_pattern_curve_to
+cairo_mesh_pattern_set_control_point
+cairo_mesh_pattern_set_corner_color_rgb
+cairo_mesh_pattern_set_corner_color_rgba
+cairo_mesh_pattern_get_patch_count
+cairo_mesh_pattern_get_path
+cairo_mesh_pattern_get_control_point
+cairo_mesh_pattern_get_corner_color_rgba
+cairo_pattern_reference
+cairo_pattern_destroy
+cairo_pattern_status
+cairo_extend_t
+cairo_pattern_set_extend
+cairo_pattern_get_extend
+cairo_filter_t
+cairo_pattern_set_filter
+cairo_pattern_get_filter
+cairo_pattern_set_matrix
+cairo_pattern_get_matrix
+cairo_pattern_type_t
+cairo_pattern_get_type
+cairo_pattern_get_reference_count
+cairo_pattern_set_user_data
+cairo_pattern_get_user_data
+</SECTION>
+
+<SECTION>
+<FILE>cairo-raster-source</FILE>
+cairo_pattern_create_raster_source
+cairo_raster_source_pattern_set_callback_data
+cairo_raster_source_pattern_get_callback_data
+cairo_raster_source_pattern_set_acquire
+cairo_raster_source_pattern_get_acquire
+cairo_raster_source_pattern_set_snapshot
+cairo_raster_source_pattern_get_snapshot
+cairo_raster_source_pattern_set_copy
+cairo_raster_source_pattern_get_copy
+cairo_raster_source_pattern_set_finish
+cairo_raster_source_pattern_get_finish
+cairo_raster_source_acquire_func_t
+cairo_raster_source_release_func_t
+cairo_raster_source_snapshot_func_t
+cairo_raster_source_copy_func_t
+cairo_raster_source_finish_func_t
+</SECTION>
+
+<SECTION>
+<FILE>cairo-matrix</FILE>
+cairo_matrix_t
+cairo_matrix_init
+cairo_matrix_init_identity
+cairo_matrix_init_translate
+cairo_matrix_init_scale
+cairo_matrix_init_rotate
+cairo_matrix_translate
+cairo_matrix_scale
+cairo_matrix_rotate
+cairo_matrix_invert
+cairo_matrix_multiply
+cairo_matrix_transform_distance
+cairo_matrix_transform_point
+</SECTION>
+
+<SECTION>
+<FILE>cairo-status</FILE>
+cairo_status_t
+cairo_status_to_string
+cairo_debug_reset_static_data
+</SECTION>
+
+<SECTION>
+<FILE>cairo-font-face</FILE>
+cairo_font_face_t
+cairo_font_face_reference
+cairo_font_face_destroy
+cairo_font_face_status
+cairo_font_type_t
+cairo_font_face_get_type
+cairo_font_face_get_reference_count
+cairo_font_face_set_user_data
+cairo_font_face_get_user_data
+</SECTION>
+
+<SECTION>
+<FILE>cairo-scaled-font</FILE>
+cairo_scaled_font_t
+cairo_scaled_font_create
+cairo_scaled_font_reference
+cairo_scaled_font_destroy
+cairo_scaled_font_status
+cairo_font_extents_t
+cairo_scaled_font_extents
+cairo_text_extents_t
+cairo_scaled_font_text_extents
+cairo_scaled_font_glyph_extents
+cairo_scaled_font_text_to_glyphs
+cairo_scaled_font_get_font_face
+cairo_scaled_font_get_font_options
+cairo_scaled_font_get_font_matrix
+cairo_scaled_font_get_ctm
+cairo_scaled_font_get_scale_matrix
+cairo_scaled_font_get_type
+cairo_scaled_font_get_reference_count
+cairo_scaled_font_set_user_data
+cairo_scaled_font_get_user_data
+</SECTION>
+
+<SECTION>
+<FILE>cairo-font-options</FILE>
+cairo_font_options_t
+cairo_font_options_create
+cairo_font_options_copy
+cairo_font_options_destroy
+cairo_font_options_status
+cairo_font_options_merge
+cairo_font_options_hash
+cairo_font_options_equal
+cairo_font_options_set_antialias
+cairo_font_options_get_antialias
+cairo_subpixel_order_t
+cairo_font_options_set_subpixel_order
+cairo_font_options_get_subpixel_order
+cairo_hint_style_t
+cairo_font_options_set_hint_style
+cairo_font_options_get_hint_style
+cairo_hint_metrics_t
+cairo_font_options_set_hint_metrics
+cairo_font_options_get_hint_metrics
+</SECTION>
+
+<SECTION>
+<FILE>cairo-types</FILE>
+cairo_bool_t
+cairo_user_data_key_t
+cairo_destroy_func_t
+cairo_rectangle_int_t
+</SECTION>
+
+<SECTION>
+<FILE>cairo-transforms</FILE>
+cairo_translate
+cairo_scale
+cairo_rotate
+cairo_transform
+cairo_set_matrix
+cairo_get_matrix
+cairo_identity_matrix
+cairo_user_to_device
+cairo_user_to_device_distance
+cairo_device_to_user
+cairo_device_to_user_distance
+</SECTION>
+
+
+<SECTION>
+<FILE>cairo-paths</FILE>
+cairo_path_t
+cairo_path_data_t
+cairo_path_data_type_t
+cairo_copy_path
+cairo_copy_path_flat
+cairo_path_destroy
+cairo_append_path
+cairo_has_current_point
+cairo_get_current_point
+cairo_new_path
+cairo_new_sub_path
+cairo_close_path
+cairo_arc
+cairo_arc_negative
+cairo_curve_to
+cairo_line_to
+cairo_move_to
+cairo_rectangle
+cairo_glyph_path
+cairo_text_path
+cairo_rel_curve_to
+cairo_rel_line_to
+cairo_rel_move_to
+cairo_path_extents
+</SECTION>
+
+<SECTION>
+<FILE>cairo-text</FILE>
+cairo_glyph_t
+cairo_font_slant_t
+cairo_font_weight_t
+cairo_text_cluster_t
+cairo_text_cluster_flags_t
+cairo_select_font_face
+cairo_set_font_size
+cairo_set_font_matrix
+cairo_get_font_matrix
+cairo_set_font_options
+cairo_get_font_options
+cairo_set_font_face
+cairo_get_font_face
+cairo_set_scaled_font
+cairo_get_scaled_font
+cairo_show_text
+cairo_show_glyphs
+cairo_show_text_glyphs
+cairo_font_extents
+cairo_text_extents
+cairo_glyph_extents
+cairo_toy_font_face_create
+cairo_toy_font_face_get_family
+cairo_toy_font_face_get_slant
+cairo_toy_font_face_get_weight
+cairo_glyph_allocate
+cairo_glyph_free
+cairo_text_cluster_allocate
+cairo_text_cluster_free
+</SECTION>
+
+<SECTION>
+<FILE>cairo</FILE>
+cairo_t
+cairo_create
+cairo_reference
+cairo_destroy
+cairo_status
+cairo_save
+cairo_restore
+cairo_get_target
+cairo_push_group
+cairo_push_group_with_content
+cairo_pop_group
+cairo_pop_group_to_source
+cairo_get_group_target
+cairo_set_source_rgb
+cairo_set_source_rgba
+cairo_set_source
+cairo_set_source_surface
+cairo_get_source
+cairo_antialias_t
+cairo_set_antialias
+cairo_get_antialias
+cairo_set_dash
+cairo_get_dash_count
+cairo_get_dash
+cairo_fill_rule_t
+cairo_set_fill_rule
+cairo_get_fill_rule
+cairo_line_cap_t
+cairo_set_line_cap
+cairo_get_line_cap
+cairo_line_join_t
+cairo_set_line_join
+cairo_get_line_join
+cairo_set_line_width
+cairo_get_line_width
+cairo_set_miter_limit
+cairo_get_miter_limit
+cairo_operator_t
+cairo_set_operator
+cairo_get_operator
+cairo_set_tolerance
+cairo_get_tolerance
+cairo_clip
+cairo_clip_preserve
+cairo_clip_extents
+cairo_in_clip
+cairo_reset_clip
+cairo_rectangle_t
+cairo_rectangle_list_t
+cairo_rectangle_list_destroy
+cairo_copy_clip_rectangle_list
+cairo_fill
+cairo_fill_preserve
+cairo_fill_extents
+cairo_in_fill
+cairo_mask
+cairo_mask_surface
+cairo_paint
+cairo_paint_with_alpha
+cairo_stroke
+cairo_stroke_preserve
+cairo_stroke_extents
+cairo_in_stroke
+cairo_copy_page
+cairo_show_page
+cairo_get_reference_count
+cairo_set_user_data
+cairo_get_user_data
+<SUBSECTION Private>
+cairo_public
+CAIRO_BEGIN_DECLS
+CAIRO_END_DECLS
+cairo_current_font_extents
+cairo_get_font_extents
+cairo_current_operator
+cairo_current_tolerance
+cairo_current_point
+cairo_current_fill_rule
+cairo_current_line_width
+cairo_current_line_cap
+cairo_current_line_join
+cairo_current_miter_limit
+cairo_current_matrix
+cairo_current_target_surface
+cairo_get_status
+cairo_concat_matrix
+cairo_scale_font
+cairo_select_font
+cairo_transform_font
+cairo_transform_point
+cairo_transform_distance
+cairo_inverse_transform_point
+cairo_inverse_transform_distance
+cairo_init_clip
+cairo_surface_create_for_image
+cairo_default_matrix
+cairo_matrix_set_affine
+cairo_matrix_set_identity
+cairo_pattern_add_color_stop
+cairo_set_rgb_color
+cairo_set_pattern
+cairo_xlib_surface_create_for_pixmap_with_visual
+cairo_xlib_surface_create_for_window_with_visual
+cairo_xcb_surface_create_for_pixmap_with_visual
+cairo_xcb_surface_create_for_window_with_visual
+cairo_ps_surface_set_dpi
+cairo_pdf_surface_set_dpi
+cairo_svg_surface_set_dpi
+cairo_current_path
+cairo_current_path_flat
+cairo_get_path
+cairo_get_path_flat
+cairo_set_alpha
+cairo_show_surface
+cairo_copy
+cairo_surface_set_repeat
+cairo_surface_set_matrix
+cairo_surface_get_matrix
+cairo_surface_set_filter
+cairo_surface_get_filter
+cairo_matrix_create
+cairo_matrix_destroy
+cairo_matrix_copy
+cairo_matrix_get_affine
+cairo_set_target_surface
+cairo_set_target_image
+cairo_set_target_pdf
+cairo_set_target_png
+cairo_set_target_ps
+cairo_set_target_quartz
+cairo_set_target_win32
+cairo_set_target_xcb
+cairo_set_target_drawable
+cairo_get_status_string
+cairo_status_string
+CAIRO_FONT_TYPE_ATSUI
+cairo_atsui_font_face_create_for_atsu_font_id
+</SECTION>
+
+<SECTION>
+<FILE>cairo-script</FILE>
+CAIRO_HAS_SCRIPT_SURFACE
+cairo_script_create
+cairo_script_create_for_stream
+cairo_script_from_recording_surface
+cairo_script_get_mode
+cairo_script_mode_t
+cairo_script_set_mode
+cairo_script_surface_create
+cairo_script_surface_create_for_target
+cairo_script_write_comment
+</SECTION>
diff --git a/doc/public/cairo.types b/doc/public/cairo.types
new file mode 100755
index 000000000..e69de29bb
--- /dev/null
+++ b/doc/public/cairo.types
diff --git a/doc/public/check-doc-coverage.sh b/doc/public/check-doc-coverage.sh
new file mode 100755
index 000000000..648ca1212
--- /dev/null
+++ b/doc/public/check-doc-coverage.sh
@@ -0,0 +1,54 @@
+#!/bin/sh
+
+LC_ALL=C
+export LC_ALL
+
+if test -z "$DOC_MODULE"; then
+	# extract from Makefile
+	eval `grep '^DOC_MODULE' Makefile | sed 's/ //g'`
+	if test -z "$DOC_MODULE"; then
+		echo Failed extracting DOC_MODULE from Makefile 1>&2
+		echo Try setting DOC_MODULE env var manually 1>&2
+		exit 1
+	fi
+fi
+
+if test -n "$REPORT_FILES"; then
+	$MAKE $REPORT_FILES || exit 1
+fi
+
+test -z "$srcdir" && srcdir=.
+stat=0
+
+if test -f "$DOC_MODULE-undeclared.txt"; then
+	undeclared=`cat "$DOC_MODULE-undeclared.txt"`
+	if test -n "$undeclared"; then
+		echo "*** ERROR: Undeclared documentation symbols:" 1>&2
+		cat "$DOC_MODULE-undeclared.txt" 1>&2
+		stat=1
+	fi
+fi >&2
+if test -f "$DOC_MODULE-unused.txt"; then
+	unused=`cat "$DOC_MODULE-unused.txt"`
+	if test -n "$unused"; then
+		echo "*** ERROR: Unused documented symbols:" 1>&2
+		cat "$DOC_MODULE-unused.txt" 1>&2
+		stat=1
+	fi
+fi >&2
+if test -f "$DOC_MODULE-undocumented.txt"; then
+	if grep '^0 symbols incomplete' "$DOC_MODULE-undocumented.txt" >/dev/null &&
+	   grep '^0 not documented'     "$DOC_MODULE-undocumented.txt" >/dev/null; then
+		:
+	else
+		echo "*** ERROR: Incomplete or undocumented symbols:" 1>&2
+		cat "$DOC_MODULE-undocumented.txt" 1>&2
+		stat=1
+	fi
+fi >&2
+
+if test $stat != 0; then
+	echo "*** IGNORING ERROR ***"
+fi
+#exit $stat
+exit 0
diff --git a/doc/public/check-doc-syntax.sh b/doc/public/check-doc-syntax.sh
new file mode 100755
index 000000000..129065d2a
--- /dev/null
+++ b/doc/public/check-doc-syntax.sh
@@ -0,0 +1,12 @@
+#!/bin/sh
+
+LC_ALL=C
+export LC_ALL
+
+test -z "$srcdir" && srcdir=.
+test -z "$top_srcdir" && top_srcdir=$srcdir/../..
+
+SGML_DOCS=true
+FILES=`echo $srcdir/tmpl/*.sgml`
+
+. "$top_srcdir/src/check-doc-syntax.sh"
diff --git a/doc/public/language-bindings.xml b/doc/public/language-bindings.xml
new file mode 100755
index 000000000..ce437ef53
--- /dev/null
+++ b/doc/public/language-bindings.xml
@@ -0,0 +1,745 @@
+<appendix id="language-bindings">
+  <title>Creating a language binding for cairo</title>
+  <para>
+    While cairo is implemented and C, and has a C API, it is expected
+    that many users of cairo will be using it from languages other
+    than C. The glue that connects the core cairo library to another
+    language is known as a <firstterm>language
+    binding</firstterm>. This appendix attempts to collect together
+    issues that come up when creating a language bindings for cairo
+    and present standardized solutions to promote consistency among
+    the different language bindings.
+  </para>
+  <sect1 id="bindings-general">
+    <title>General considerations</title>
+    <para>
+      The naming of the central <link
+	linkend="cairo-t"><type>cairo_t</type></link> type is a
+      special exception. The object is “a cairo context” not “a
+      cairo”, and names such as <type>cairo_t</type> rather than
+      <type>cairo_context_t</type> and
+      <function>cairo_set_source()</function> rather than
+      <function>cairo_context_set_source()</function> are simply
+      abbreviations to make the C API more palatable. In languages
+      which have object-oriented syntax, this abbreviation is much
+      less useful. In fact, if ‘Cairo’ is used as a namespace, then
+      in many languages, you'd end up with a ridiculous type name
+      like ‘Cairo.Cairo’. For this reason, and for inter-language
+      consistency all object-oriented languages should name this
+      type as if it were <type>cairo_context_t</type>.
+    </para>
+    <para>
+      The punctuation and casing of the type names and
+      method names of cairo should be changed to match the general
+      convention of the language. In Java, where type names are written
+      in StudlyCaps and method names in javaCaps, cairo_font_extents_t
+      will become FontExtents and
+      <literal>cairo_set_source(cr,source)</literal>,
+      <literal>cr.setSource(source)</literal>.
+      As compared to changing the punctuation, and casing, much
+      more reluctance should be used in changing the method names
+      themselves. Even if get is usually omitted from getters in
+      your language, you shouldn't bind cairo_get_source() as
+      cr.source().
+    </para>
+  </sect1>
+  <sect1 id="bindings-memory">
+    <title>Memory management</title>
+    <para>
+      The objects in cairo can roughly be divided into two types:
+      reference-counted, opaque types like
+      <link
+      linkend="cairo-surface-t"><type>cairo_surface_t</type></link>
+      and plain structures like
+      <link
+	linkend="cairo-glyph-t"><type>cairo_glyph_t</type></link>.
+      <link
+	linkend="cairo-path-t"><type>cairo_path_t</type></link>
+      and 
+      <link
+	linkend="cairo-path-data-t"><type>cairo_path_data_t</type></link>
+      are special cases and are treated separately in this appendix.
+    </para>
+    <para>
+      Refcounted opaque types all have a
+      <function>..._reference()</function>
+      function to increase the refcount by one and a
+      <function>..._destroy()</function> to decrease the refcount
+      by one. These should not be exposed to the user of the language
+      binding, but rather used to implement memory management within
+      the language binding. The simplest way to do memory management
+      for a language binding is to treat the language binding object
+      as a simple handle to the cairo object. The language binding
+      object references the cairo object, and unreferences it when
+      finalized. This is the recommended method, though there are
+      a couple of caveats to be noted:
+    </para>
+    <itemizedlist>
+      <listitem>
+	<para>
+	  Equality won't work as expected. You can have two language
+	  objects for the same cairo and they won't necessarily
+	  compare equal. If the language allows customizing the
+	  equality operation, then this is fixable by comparing
+	  the underlying pointers. It also can be fixed by creating
+	  at most one language object per cairo object, and
+	  uniquifying via a <firstterm>pin table</firstterm> (a hash
+	  table that goes from cairo object to language object).
+	  For <type>cairo_surface_t</type> you can use also 
+	  <link
+	  linkend="cairo-surface-set-user-data"><function>cairo_surface_set_user_data()</function></link>
+	  instead of a separate pin table.
+	</para>
+      </listitem>
+      <listitem>
+	<para>
+	  Derivation from the language object doesn't work because
+	  you can lose the language object while keeping the Cairo
+	  object. Code like:
+	</para>
+<programlisting>
+public class MySurface (ImageSurface) {
+   public MySurface (width, height) {
+      super (Format.ARGB32, width, height);
+   }
+   public int get42 () {
+      return 42;	  
+   }
+}
+
+   cr = Cairo(MySurface(width, height));
+   surface = cr.getTarget();
+</programlisting>
+	<para>
+	  Can result in <varname>surface</varname> containing an
+	  <classname>ImageSurface</classname> not a <classname>MySurface</classname>.
+	  This is not easily fixable without creating memory leaks,
+	  and it's probably best to simply forbid deriving from the
+	  language objects.
+	</para>
+      </listitem>
+    </itemizedlist>
+    <para>
+      When a plain structure is used as a return value from cairo,
+      this is done by passing it as a “out parameter”.
+    </para>
+<programlisting>
+cairo_font_extents_t extents;      
+
+cairo_font_extents (cr, &amp;extents);</programlisting>
+    <para>
+      In a language binding, this should typically be treated
+      as a return value:
+    </para>
+<programlisting>
+FontExtents extents = cr.fontExtents ();</programlisting>
+    <para>
+      A language binding has a choice in how it implements the
+      language objects for plain structures. It can use a pure
+      language object with fields corresponding to those of the C
+      structure, and convert from and to the C structure when calling
+      cairo functions or converting cairo return values. Or it
+      can keep a pointer to the C structure internally and wrap
+      it inside a language object much like occurs for refcounted
+      objects. The choice should be invisible to the user: they should
+      be able to imagine that it is implemented as a pure language
+      object.
+    </para>
+  </sect1>
+  <sect1 id="bindings-return-values">
+    <title>Multiple return values</title>
+    <para>
+      There are a number of functions in the cairo API that have
+      multiple <firstterm>out parameters</firstterm> or
+      <firstterm>in-out parameters</firstterm>. In some languages
+      these can be translated into multiple return values. In Python,
+      what is:
+    </para>
+    <programlisting>
+cairo_user_to_device (cr, &amp;x, &amp;y);</programlisting>
+    <para>
+      can by mapped to:
+    </para>
+    <programlisting>
+(x, y) = cr.user_to_device (cr, x, y);</programlisting>
+    <para>
+      but many languages don't have provisions for multiple return
+      values, so it is necessary to introduce auxiliary types.
+      Most of the functions that require the auxiliary types
+      require a type that would, in C, look like
+    </para>
+    <programlisting>
+typedef struct _cairo_point cairo_point_t;
+struct _cairo_point {
+    double x;
+    double y;
+}</programlisting>
+    <para>
+      The same type should be used both for functions that use a pair
+      of coordinates as an absolute position, and functions that use
+      a pair of coordinates as a displacement. While an argument could
+      be made that having a separate “distance” type is more correct,
+      it is more likely just to confuse users.
+    </para>
+    <programlisting>
+void
+cairo_user_to_device (cairo_t *cr, double *x, double *y);
+
+void
+cairo_user_to_device_distance (cairo_t *cr, double *dx, double *dy);
+
+void
+cairo_device_to_user (cairo_t *cr, double *x, double *y);
+
+void
+cairo_device_to_user_distance (cairo_t *cr, double *dx, double *dy);
+
+void
+cairo_matrix_transform_distance (cairo_matrix_t *matrix, double *dx, double *dy);
+
+void
+cairo_matrix_transform_point (cairo_matrix_t *matrix, double *x, double *y);
+
+void
+cairo_get_current_point (cairo_t *cr, double *x, double *y);
+    </programlisting>
+    <para>
+      There are also a couple of functions that return four values
+      representing a rectangle. These should be mapped to a
+      “rectangle” type that looks like:
+    </para>
+    <programlisting>
+typedef struct _cairo_rectangle cairo_rectangle_t;
+struct _cairo_rectangle {
+    double x;
+    double y;
+    double width;
+    double height;
+}</programlisting>
+    <para>
+      The C function returns the rectangle as a set of two points to
+      facilitate rounding to integral extents, but this isn't worth
+      adding a “box” type to go along with the more obvious
+      “rectangle” representation.
+    </para>
+    <remark>
+      Q: Would it make sense here to define a standard
+      <function>cairo_rectangle_round()</function> method
+      that language bindings should map?
+    </remark>
+    <programlisting>
+void
+cairo_stroke_extents (cairo_t *cr,
+		      double *x1, double *y1,
+		      double *x2, double *y2);
+
+void
+cairo_fill_extents (cairo_t *cr,
+		    double *x1, double *y1,
+		    double *x2, double *y2);
+    </programlisting>
+  </sect1>
+  <sect1 id="bindings-overloading">
+    <title>Overloading and optional arguments</title>
+    <para>
+      Function overloading (having a several variants of a function
+      with the same name and different arguments) is a language
+      feature available in many languages but not in C.
+    </para>
+    <para>
+      In general, language binding authors should use restraint in
+      combining functions in the cairo API via function
+      overloading. What may seem like an obvious overload now may
+      turn out to be strange with future additions to cairo.
+      It might seem logical to make
+      <link
+      linkend="cairo-set-source-rgb"><function>cairo_set_source_rgb()</function></link>
+	an overload of <function>cairo_set_source()</function>, but future plans to add
+	<function>cairo_set_source_rgb_premultiplied()</function>,
+      which will also take three doubles make this a bad idea. For
+      this reason, only the following pairs of functions should
+      be combined via overloading
+    </para>
+    <programlisting>
+void
+cairo_set_source (cairo_t *cr, cairo_pattern_t *source);
+
+void
+cairo_set_source_surface (cairo_t          *cr,
+                          cairo_surface_t  *source,
+                          double            surface_x,
+                          double            surface_y);
+      
+void
+cairo_mask (cairo_t         *cr,
+	    cairo_pattern_t *pattern);
+
+void
+cairo_mask_surface (cairo_t         *cr,
+		    cairo_surface_t *surface,
+		    double           surface_x,
+		    double           surface_y);
+      
+cairo_surface_t *
+cairo_image_surface_create (cairo_format_t	format,
+			    int			width,
+			    int			height);
+cairo_surface_t *
+cairo_image_surface_create_for_data (unsigned char	       *data,
+				     cairo_format_t		format,
+				     int			width,
+				     int			height,
+				     int			stride);
+
+cairo_status_t
+cairo_surface_write_to_png (cairo_surface_t	*surface,
+			    const char		*filename);
+
+cairo_status_t
+cairo_surface_write_to_png_stream (cairo_surface_t	*surface,
+				   cairo_write_func_t	write_func,
+				   void			*closure);
+
+cairo_surface_t *
+cairo_image_surface_create_from_png (const char	*filename);
+
+cairo_surface_t *
+cairo_image_surface_create_from_png_stream (cairo_read_func_t	read_func,
+					    void		*closure);
+    </programlisting>
+    <para>
+      Note that there are cases where all constructors for a type
+      aren't overloaded together. For example
+      <link
+	linkend="cairo-image-surface-create-from-png"><function>cairo_image_surface_create_from_png()</function></link>
+      should <emphasis>not</emphasis> be overloaded together with
+      <link
+	linkend="cairo-image-surface-create"><function>cairo_image_surface_create()</function></link>.
+      In such cases, the remaining constructors will typically need to
+      be bound as static methods. In Java, for example, we might have:
+    </para>
+<programlisting>
+Surface surface1 = ImageSurface(Format.RGB24, 100, 100);
+Surface surface2 = ImageSurface.createFromPNG("camera.png");</programlisting>
+    <para>
+      Some other overloads that add combinations not found in C may be
+      convenient for users for language bindings that provide
+      <type>cairo_point_t</type> and <type>cairo_rectangle_t</type>
+      types, for example:
+    </para>
+    <programlisting>
+void
+cairo_move_to (cairo_t       *cr,
+               cairo_point_t *point);
+void
+cairo_rectangle (cairo_t           *cr,
+                 cairo_rectangle_t *rectangle);
+    </programlisting>
+  </sect1>
+  <sect1 id="bindings-streams">
+    <title>Streams and File I/O</title>
+    <para>
+      Various places in the cairo API deal with reading and writing
+      data, whether from and to files, or to other sources and
+      destinations. In these cases, what is typically provided in the
+      C API is a simple version that just takes a filename, and a
+      complex version that takes a callback function.
+      An example is the PNG handling functions:
+    </para>
+<programlisting>
+cairo_surface_t *
+cairo_image_surface_create_from_png (const char	*filename);
+
+cairo_surface_t *
+cairo_image_surface_create_from_png_stream (cairo_read_func_t read_func,
+					    void             *closure);
+
+cairo_status_t
+cairo_surface_write_to_png (cairo_surface_t	*surface,
+			    const char		*filename);
+
+cairo_status_t
+cairo_surface_write_to_png_stream (cairo_surface_t	*surface,
+				   cairo_write_func_t	write_func,
+				   void			*closure);</programlisting>
+    <para>
+      The expectation is that the filename version will be mapped
+      literally in the language binding, but the callback version
+      will be mapped to a version that takes a language stream
+      object. For example, in Java, the four functions above
+      might be mapped to:
+    </para>
+<programlisting>
+static public ImageSurface createFromPNG (String filename) throws IOException;
+static public ImageSurface createFromPNG (InputStream stream) throws IOException;
+public void writeToPNG (String filename) throws IOException;
+public void writeToPNG (OutputStream stream) throws IOException;
+</programlisting>
+    <para>
+      In many cases, it will be better to
+      implement the filename version internally
+      using the stream version, rather than building it on top of the
+      filename version in C. The reason for this is that will
+      naturally give a more standard handling of file errors for
+      the language, as seen in the above Java example, where
+      <methodname>createFromPNG()</methodname> is marked as raising
+      an exception. Propagating exceptions from inside the callback
+      function to the caller will pose a challenge to the language
+      binding implementor, since an exception must not propagate
+      through the Cairo code. A technique that will be useful in
+      some cases is to catch the exception in the callback,
+      store the exception object inside a structure pointed to by
+      <parameter>closure</parameter>, and then rethrow it once
+      the function returns.
+    </para>
+    <remark>
+      I'm not sure how to handle this for
+      <link
+      linkend="cairo-pdf-surface-create-for-stream"><function>cairo_pdf_surface_create_for_stream()</function></link>.
+      Other than keep a “exception to rethrow” thread-specific
+      variable
+      that is checked after <emphasis>every</emphasis> call to a Cairo
+      function.
+    </remark>
+  </sect1>
+  <sect1 id="bindings-errors">
+    <title>Error handling</title>
+    <para>
+      The error handling approach in C for Cairo has multiple
+      elements:
+    </para>
+    <itemizedlist>
+      <listitem><para>
+	  When a method on an object fails, the object is put into
+	  an error state. Subsequent operations on the object do
+	  nothing. The status of the object can be queried with
+	  a function like <link
+	    linkend="cairo-status"><function>status()</function></link>.
+      </para></listitem>
+      <listitem><para>
+	  Constructors, rather than
+	  returning <constant>NULL</constant> on out-of-memory failure,
+	  return a special singleton object on which all
+	  operations do nothing. Retrieving the status of the
+	  singleton object returns <constant>CAIRO_STATUS_NO_MEMORY</constant>
+	  </para>
+	  <remark>
+	    Is this going to apply to
+	  <type>cairo_surface_t</type> as well?
+	</remark>
+	<remark>
+	  What about cairo_copy_path_data()? It's probably going to
+	  have to return <constant>NULL</constant>.
+	</remark>
+      </listitem>
+      <listitem><para>
+	  Errors propagate from object to object. Setting a pattern
+	  in an out-of-memory state as the source of a
+	  <type>cairo_t</type> puts the type into an error state.
+      </para></listitem>
+    </itemizedlist>
+    <remark>Much of the above is not yet implemented at the time of
+      this writing</remark>
+    <para>
+      A language binding could copy the C approach, and for a 
+      language without exceptions, this is likely the right thing
+      to do. However, for a language with exceptions, exposing
+      a completely different style of error handling for cairo
+      would be strange. So, instead, status should be checked
+      after every call to cairo, and exceptions thrown as necessary.
+    </para>
+    <para>
+      One problem that can arise with this, in languages
+      where handling exceptions is mandatory (like Java), is that almost
+      every cairo function can result in a status being set,
+      usually because of an out-of-memory condition. This could make
+      cairo hard to use. To resolve this problem, let's classify then
+      cairo status codes:
+    </para>
+<programlisting>
+/* Memory */      
+CAIRO_STATUS_NO_MEMORY,
+
+/* Programmer error */      
+CAIRO_STATUS_INVALID_RESTORE
+CAIRO_STATUS_INVALID_POP_GROUP
+CAIRO_STATUS_NO_CURRENT_POINT
+CAIRO_STATUS_INVALID_MATRIX
+CAIRO_STATUS_NO_TARGET_SURFACE
+CAIRO_STATUS_INVALID_STRING
+CAIRO_STATUS_SURFACE_FINISHED
+CAIRO_STATUS_BAD_NESTING
+
+/* Language binding implementation */
+CAIRO_STATUS_NULL_POINTER
+CAIRO_STATUS_INVALID_PATH_DATA
+CAIRO_STATUS_SURFACE_TYPE_MISMATCH
+
+/* Other */      
+CAIRO_STATUS_READ_ERROR
+CAIRO_STATUS_WRITE_ERROR
+</programlisting>
+    <para>
+      If we look at these, the
+      <constant>CAIRO_STATUS_NO_MEMORY</constant>
+      should map to the native out-of-memory exception, which could
+      happen at any point in any case. Most of the others indicate
+      programmer error, and handling them in user code would be
+      silly. These should be mapped into whatever the language uses
+      for assertion failures, rather than errors that are normally
+      handled. (In Java, a subclass of Error rather than Exception,
+      perhaps.) And <constant>CAIRO_STATUS_READ_ERROR</constant>,
+      and <constant>CAIRO_STATUS_WRITE_ERROR</constant> can occur
+      only in very specific places. (In fact, as described
+      in <xref linkend="bindings-streams"/>, these errors may be
+      mapped into the language's native I/O error types.)
+      So, there really aren't exceptions that the programmer must
+      handle at most points in the Cairo API.
+    </para>
+  </sect1>
+  <sect1 id="bindings-patterns">
+    <title>Patterns</title>
+    <para>
+      The cairo C API allows for creating a number of different types
+      of patterns. All of these different types of patterns map to
+      <link
+      linkend="cairo-pattern-t"><type>cairo_pattern_t</type></link>
+      in C, but in an object oriented language, there should instead
+      be a hierarchy of types. (The functions that should map to
+      constructors or static methods for the various types are listed
+      after the type, methods on that type are listed below. Note that
+      cairo_pattern_create_rgb() and cairo_pattern_create_rgba()
+      should not be overloaded with each other as a SolidPattern()
+      constructor, but should appear as static methods instead.  This
+      is to maintain code clarity by making it clear how the arguments
+      relate to color components.)
+    </para>
+    <programlisting>
+cairo_pattern_t
+      <link linkend="cairo-pattern-set-matrix"><function>cairo_pattern_set_matrix()</function></link>
+      <link linkend="cairo-pattern-get-matrix"><function>cairo_pattern_get_matrix()</function></link>
+   cairo_solid_pattern_t (<link linkend="cairo-pattern-create-rgb"><function>cairo_pattern_create_rgb()</function></link> and <link linkend="cairo-pattern-create-rgba"><function>cairo_pattern_create_rgba()</function></link>)
+   cairo_surface_pattern_t (<link linkend="cairo-pattern-create-for-surface"><function>cairo_pattern_create_for_surface()</function></link>)
+         <link linkend="cairo-pattern-set-extend"><function>cairo_pattern_set_extend()</function></link>
+         <link linkend="cairo-pattern-get-extend"><function>cairo_pattern_get_extend()</function></link>
+         <link linkend="cairo-pattern-set-filter"><function>cairo_pattern_set_filter()</function></link>
+         <link linkend="cairo-pattern-get-filter"><function>cairo_pattern_get_filter()</function></link>
+   cairo_gradient_t
+         <link linkend="cairo-pattern-add-color-stop-rgb"><function>cairo_pattern_add_color_stop_rgb()</function></link>
+         <link linkend="cairo-pattern-add-color-stop-rgba"><function>cairo_pattern_add_color_stop_rgba()</function></link>
+      cairo_linear_gradient_t (<link linkend="cairo-pattern-create-linear"><function>cairo_pattern_create_linear()</function></link>)
+      cairo_radial_gradient_t (<link linkend="cairo-pattern-create-radial"><function>cairo_pattern_create_radial()</function></link>)
+   cairo_mesh_t (<link linkend="cairo-pattern-create-mesh"><function>cairo_pattern_create_mesh()</function></link>)
+         <link linkend="cairo-mesh-pattern-begin-patch"><function>cairo_mesh_pattern_begin_patch()</function></link>
+         <link linkend="cairo-mesh-pattern-end-patch"><function>cairo_mesh_pattern_end_patch()</function></link>
+         <link linkend="cairo-mesh-pattern-move-to"><function>cairo_mesh_pattern_move_to()</function></link>
+         <link linkend="cairo-mesh-pattern-line-to"><function>cairo_mesh_pattern_line_to()</function></link>
+         <link linkend="cairo-mesh-pattern-curve-to"><function>cairo_mesh_pattern_curve_to()</function></link>
+         <link linkend="cairo-mesh-pattern-set-control-point"><function>cairo_mesh_pattern_set_control_point()</function></link>
+         <link linkend="cairo-mesh-pattern-set-corner-color-rgb"><function>cairo_mesh_pattern_set_corner_color_rgb()</function></link>
+         <link linkend="cairo-mesh-pattern-set-corner-color-rgba"><function>cairo_mesh_pattern_set_corner_color_rgba()</function></link>
+         <link linkend="cairo-mesh-pattern-get-patch-count"><function>cairo_mesh_pattern_get_patch_count()</function></link>
+         <link linkend="cairo-mesh-pattern-get-path"><function>cairo_mesh_pattern_get_path()</function></link>
+         <link linkend="cairo-mesh-pattern-get-control-point"><function>cairo_mesh_pattern_get_control_point()</function></link>
+         <link linkend="cairo-mesh-pattern-get-corner-color-rgba"><function>cairo_mesh_pattern_get_corner_color_rgba()</function></link>
+    </programlisting>
+    <para>
+    </para>
+  </sect1>
+  <sect1 id="bindings-surfaces">
+    <title>Surfaces</title>
+    <para>
+      Like patterns, surfaces, which use only the
+      <link
+      linkend="cairo-surface-t"><type>cairo_surface_t</type></link>
+      type in the C API should be broken up into a hierarchy of types
+      in a language binding.
+    </para>
+    <programlisting>
+cairo_surface_t
+    cairo_image_surface_t
+    cairo_atsui_surface_t
+    cairo_win32_surface_t
+    cairo_xlib_surface_t
+    cairo_beos_surface_t
+    </programlisting>
+    <para>
+      Unlike patterns, the constructors and methods on these types are
+      clearly named, and can be trivially associated with the
+      appropriate subtype. Many language bindings will want to avoid
+      binding the platform-specific subtypes at all, since the
+      methods on these types are not useful without passing in native
+      C types. Unless there is a language binding for Xlib available,
+      there is no way to represent a XLib <type>Display</type> * in
+      that language.
+    </para>
+    <para>
+      This doesn't mean that platform-specific surface types can't
+      be used in a language binding that doesn't bind the constructor.
+      A very common situation is to use a cairo language binding in
+      combination with a binding for a higher level system like
+      the <ulink url="http://www.gtk.org/">GTK+</ulink> widget
+      toolkit. In such a situation, the higher level toolkit provides
+      ways to get references to platform specific surfaces.
+    </para>
+    <para>
+      The <link
+	  linkend="cairo-surface-set-user-data"><function>cairo_surface_set_user_data()</function></link>,
+      and <link
+	  linkend="cairo-surface-get-user-data"><function>cairo_surface_get_user_data()</function></link>
+      methods are provided for use in language bindings, and should
+      not be directly exposed to applications. One example of the use
+      of these functions in a language binding is creating a binding for:
+    </para>
+<programlisting>
+cairo_surface_t *
+<link linkend="cairo-image-surface-create-for-data"><function>cairo_image_surface_create_for_data</function></link> (unsigned char	       *data,
+				     cairo_format_t		format,
+				     int			width,
+				     int			height,
+				     int			stride);
+</programlisting>
+    <para>
+      The memory block passed in for <parameter>data</parameter> must be
+      kept around until the surface is destroyed, so the language
+      binding must have some way of determining when that happens. The
+      way to do this is to use the <parameter>destroy</parameter>
+      argument to <function>cairo_surface_set_user_data()</function>.
+    </para>
+    <remark>
+      Some languages may not have a suitable “pointer to a block of
+      data” type to pass in for <parameter>data</parameter>. And even
+      where a language does have such a type, the user will be
+      frequently able to cause the backing store to be reallocated
+      to a different location or truncated. Should we recommend a
+      standard type name and binding for a buffer object here?
+    </remark>
+  </sect1>
+  <sect1 id="bindings-fonts">
+    <title>Fonts</title>
+    <para>
+      Fonts are once more an area where there is a hierarchy of types:
+    </para>
+<programlisting>
+cairo_font_face_t
+   cairo_ft_font_face_t
+   cairo_win32_font_face_t
+cairo_scaled_font_t
+   cairo_ft_scaled_font_t	
+   cairo_win32_scaled_font_t	
+</programlisting>
+    <para>
+      The methods on the subtypes are, however, not useful without
+      bindings for fontconfig and FreeType or for the Win32 GDI,
+      so most language bindings will choose not to bind these
+      types.
+    </para>
+    <para>
+      The <link
+	  linkend="cairo-font-face-set-user-data"><function>cairo_font_face_set_user_data()</function></link>,
+      and <link
+	  linkend="cairo-font-face-get-user-data"><function>cairo_font_face_get_user_data()</function></link>
+      methods are provided for use in language bindings, and should
+      not be directly exposed to applications.
+    </para>
+  </sect1>
+  <sect1 id="bindings-path">
+    <title>cairo_path_t</title>
+    <para>
+      The <link linkend="cairo-path-t"><type>cairo_path_t</type></link> type is one
+      area in which most language bindings will differ significantly
+      from the C API. The C API for <type>cairo_path_t</type> is
+      designed for efficiency and to avoid auxiliary objects that
+      would be have to be manually memory managed by the
+      application. However,
+      a language binding should not present <type>cairo_path_t</type> as an
+      array, but rather as an opaque that can be iterated
+      over. Different languages have quite different conventions for
+      how iterators work, so it is impossible to give an exact
+      specification for how this API should work, but the type names
+      and methods should be similar to the language's mapping of the following:
+    </para>
+    <programlisting>
+typedef struct cairo_path_iterator cairo_path_iterator_t;
+typedef struct cairo_path_element cairo_path_element_t;
+
+cairo_path_iterator_t *
+cairo_path_get_iterator (cairo_path_t *path);
+
+cairo_bool_t
+cairo_path_iterator_has_next (cairo_path_iterator_t *iterator);
+      
+cairo_path_element_t *
+cairo_path_iterator_next (cairo_path_iterator_t *iterator);
+
+cairo_path_element_type_t
+cairo_path_element_get_type (cairo_path_element_t *element);
+      
+void
+cairo_path_element_get_point (cairo_path_element_t *element,
+                              int                   index,
+                              double                *x,
+                              double                *y);
+    </programlisting>
+    <para>
+      The above is written using the Java conventions for
+      iterators. To illustrate how the API for PathIterator might
+      depend on the native iteration conventions of the API, examine
+      three versions of the loop, first written in a hypothetical Java
+      binding:
+    </para>
+    <programlisting>
+PathIterator iter = cr.copyPath().iterator();
+while (cr.hasNext()) {
+    PathElement element = iter.next();
+    if (element.getType() == PathElementType.MOVE_TO) {
+        Point p = element.getPoint(0);
+        doMoveTo (p.x, p.y);
+    }
+}</programlisting>
+    <para>
+      And then in a hypothetical C++ binding:
+    </para>
+    <programlisting>
+Path path = cr.copyPath();
+for (PathIterator iter = path.begin(); iter != path.end(); iter++) {
+    PathElement element = *iter;
+    if (element.getType() == PathElementType.MOVE_TO) {
+        Point p = element.getPoint(0);
+        doMoveTo (p.x, p.y);
+    }
+}</programlisting>
+    <para>
+      And then finally in a Python binding:
+    </para>
+<programlisting>
+for element in cr.copy_path():
+    if element.getType == cairo.PATH_ELEMENT_MOVE_TO:
+        (x, y) = element.getPoint(0)
+        doMoveTo (x, y);</programlisting>      
+    <para>
+      While many of the API elements stay the same in the three
+      examples, the exact iteration mechanism is quite different, to
+      match how users of the language would expect to iterate over
+      a container.
+    </para>
+    <para>
+      You should not present an API for mutating or for creating new
+      <type>cairo_path_t</type> objects. In the future, these
+      guidelines may be extended to present an API for creating a
+      <type>cairo_path_t</type> from scratch for use with
+      <link
+      linkend="cairo-append-path"><function>cairo_append_path()</function></link>
+      but the current expectation is that <function>cairo_append_path()</function> will
+      mostly be used with paths from
+      <link
+      linkend="cairo-append-path"><function>cairo_copy_path()</function></link>.
+    </para>
+  </sect1>
+</appendix>
+<!--
+Local variables:
+mode: sgml
+sgml-parent-document: ("cairo-docs.xml" "book" "book" "appendix")
+End:
+-->