[cairo-commit] 6 commits - doc/public src/cairo.c src/cairo.h src/cairo-scaled-font.c src/cairo-surface.c src/check-def.sh src/check-plt.sh
Behdad Esfahbod
behdad at kemper.freedesktop.org
Mon Jan 28 17:16:23 PST 2008
doc/public/cairo-sections.txt | 2 +
doc/public/tmpl/cairo-atsui.sgml | 6 +++--
doc/public/tmpl/cairo-beos.sgml | 7 ++++--
doc/public/tmpl/cairo-font-options.sgml | 11 +++++++---
doc/public/tmpl/cairo-font.sgml | 12 +++++++++--
doc/public/tmpl/cairo-ft.sgml | 7 ++++--
doc/public/tmpl/cairo-glitz.sgml | 7 ++++--
doc/public/tmpl/cairo-image.sgml | 25 ++++++++++++++++-------
doc/public/tmpl/cairo-matrix.sgml | 5 ++--
doc/public/tmpl/cairo-paths.sgml | 4 ++-
doc/public/tmpl/cairo-pattern.sgml | 13 ++++++++----
doc/public/tmpl/cairo-pdf.sgml | 7 ++++--
doc/public/tmpl/cairo-png.sgml | 7 ++++--
doc/public/tmpl/cairo-ps.sgml | 7 ++++--
doc/public/tmpl/cairo-quartz.sgml | 7 ++++--
doc/public/tmpl/cairo-scaled-font.sgml | 13 ++++++++----
doc/public/tmpl/cairo-status.sgml | 20 ++++++++++++++++--
doc/public/tmpl/cairo-surface.sgml | 8 +++++--
doc/public/tmpl/cairo-svg.sgml | 7 ++++--
doc/public/tmpl/cairo-text.sgml | 34 +++++++++++++++++++++++++++++---
doc/public/tmpl/cairo-transforms.sgml | 10 +++++++--
doc/public/tmpl/cairo-types.sgml | 4 +--
doc/public/tmpl/cairo-win32-fonts.sgml | 7 ++++--
doc/public/tmpl/cairo-win32.sgml | 7 ++++--
doc/public/tmpl/cairo-xcb-xrender.sgml | 10 +++++++--
doc/public/tmpl/cairo-xcb.sgml | 8 ++++++-
doc/public/tmpl/cairo-xlib-xrender.sgml | 21 ++++++++++++++++---
doc/public/tmpl/cairo-xlib.sgml | 8 ++++++-
doc/public/tmpl/cairo.sgml | 4 ++-
src/cairo-scaled-font.c | 2 -
src/cairo-surface.c | 2 -
src/cairo.c | 6 ++---
src/cairo.h | 12 ++++++-----
src/check-def.sh | 4 +--
src/check-plt.sh | 2 -
35 files changed, 239 insertions(+), 77 deletions(-)
New commits:
commit 72feed5b54e1aa725c3c5238b21946b6250503fe
Author: Behdad Esfahbod <behdad at behdad.org>
Date: Mon Jan 28 20:16:01 2008 -0500
[doc] Update templates for recently added APIs
diff --git a/doc/public/cairo-sections.txt b/doc/public/cairo-sections.txt
index 88e9c8a..5d47881 100644
--- a/doc/public/cairo-sections.txt
+++ b/doc/public/cairo-sections.txt
@@ -25,6 +25,7 @@ cairo_win32_scaled_font_get_device_to_logical
<FILE>cairo-image</FILE>
<TITLE>Image Surfaces</TITLE>
cairo_format_t
+cairo_format_stride_for_width
cairo_image_surface_create
cairo_image_surface_create_for_data
cairo_image_surface_get_data
@@ -101,6 +102,7 @@ cairo_xlib_surface_get_depth
<FILE>cairo-xlib-xrender</FILE>
<TITLE>XLib/Xrender Backend</TITLE>
cairo_xlib_surface_create_with_xrender_format
+cairo_xlib_surface_get_xrender_format
</SECTION>
<SECTION>
diff --git a/doc/public/tmpl/cairo-image.sgml b/doc/public/tmpl/cairo-image.sgml
index 1d2b833..c15cc66 100644
--- a/doc/public/tmpl/cairo-image.sgml
+++ b/doc/public/tmpl/cairo-image.sgml
@@ -31,6 +31,16 @@ image formats are those defined in #cairo_format_t.
@CAIRO_FORMAT_A8:
@CAIRO_FORMAT_A1:
+<!-- ##### FUNCTION cairo_format_stride_for_width ##### -->
+<para>
+
+</para>
+
+ at format:
+ at width:
+ at Returns:
+
+
<!-- ##### FUNCTION cairo_image_surface_create ##### -->
<para>
diff --git a/doc/public/tmpl/cairo-paths.sgml b/doc/public/tmpl/cairo-paths.sgml
index db79f26..d302cbc 100644
--- a/doc/public/tmpl/cairo-paths.sgml
+++ b/doc/public/tmpl/cairo-paths.sgml
@@ -86,7 +86,7 @@ generate simple masks.
@cr:
@x:
@y:
- at Returns:
+ at Returns:
<!-- ##### FUNCTION cairo_new_path ##### -->
diff --git a/doc/public/tmpl/cairo-status.sgml b/doc/public/tmpl/cairo-status.sgml
index 83e7167..2ee02ca 100644
--- a/doc/public/tmpl/cairo-status.sgml
+++ b/doc/public/tmpl/cairo-status.sgml
@@ -61,6 +61,7 @@ code is required before or after each individual cairo function call.
@CAIRO_STATUS_INVALID_INDEX:
@CAIRO_STATUS_CLIP_NOT_REPRESENTABLE:
@CAIRO_STATUS_TEMP_FILE_ERROR:
+ at CAIRO_STATUS_INVALID_STRIDE:
<!-- ##### FUNCTION cairo_status_to_string ##### -->
<para>
diff --git a/doc/public/tmpl/cairo-xlib-xrender.sgml b/doc/public/tmpl/cairo-xlib-xrender.sgml
index 0746dc4..3d9ebc6 100644
--- a/doc/public/tmpl/cairo-xlib-xrender.sgml
+++ b/doc/public/tmpl/cairo-xlib-xrender.sgml
@@ -37,3 +37,12 @@ if it is available.
@Returns:
+<!-- ##### FUNCTION cairo_xlib_surface_get_xrender_format ##### -->
+<para>
+
+</para>
+
+ at surface:
+ at Returns:
+
+
commit b7d43d235c01480b5a5a34db6fea8a3d86161d91
Author: Behdad Esfahbod <behdad at behdad.org>
Date: Mon Jan 28 20:14:52 2008 -0500
[src/check-*] Shut make up
diff --git a/src/check-def.sh b/src/check-def.sh
index a7aa131..3a45b32 100755
--- a/src/check-def.sh
+++ b/src/check-def.sh
@@ -11,7 +11,7 @@ test -z "$srcdir" && srcdir=.
test -z "$MAKE" && MAKE=make
status=0
-$MAKE check-has-hidden-symbols.i || exit 1
+$MAKE check-has-hidden-symbols.i > /dev/null || exit 1
if tail -1 check-has-hidden-symbols.i | grep CAIRO_HAS_HIDDEN_SYMBOLS >/dev/null; then
echo "Compiler doesn't support symbol visibility; skipping test"
exit 0
@@ -23,7 +23,7 @@ if [ "`uname -s`" = "Linux" ]; then
fi
defs="cairo.def"
-$MAKE $defs
+$MAKE $defs > /dev/null
for def in $defs; do
lib=`echo "$def" | sed 's/[.]def$//'`
lib=`echo "$lib" | sed 's at .*/@@'`
diff --git a/src/check-plt.sh b/src/check-plt.sh
index 82ea6de..c69813b 100755
--- a/src/check-plt.sh
+++ b/src/check-plt.sh
@@ -11,7 +11,7 @@ test -z "$srcdir" && srcdir=.
test -z "$MAKE" && MAKE=make
status=0
-$MAKE check-has-hidden-symbols.i || exit 1
+$MAKE check-has-hidden-symbols.i > /dev/null || exit 1
if tail -1 check-has-hidden-symbols.i | grep CAIRO_HAS_HIDDEN_SYMBOLS >/dev/null; then
echo "Compiler doesn't support symbol visibility; skipping test"
exit 0
commit dd7ce762946ec03fc115310c7e295b3327d7e805
Author: Behdad Esfahbod <behdad at behdad.org>
Date: Mon Jan 28 19:54:27 2008 -0500
[doc] Expand a couple nicks to full enum names
diff --git a/src/cairo.h b/src/cairo.h
index ba48c4f..a6a34d6 100644
--- a/src/cairo.h
+++ b/src/cairo.h
@@ -1798,9 +1798,9 @@ cairo_pattern_get_extend (cairo_pattern_t *pattern);
/**
* cairo_filter_t
* @CAIRO_FILTER_FAST: A high-performance filter, with quality similar
- * to NEAREST
+ * to %CAIRO_FILTER_NEAREST
* @CAIRO_FILTER_GOOD: A reasonable-performance filter, with quality
- * similar to BILINEAR
+ * similar to %CAIRO_FILTER_BILINEAR
* @CAIRO_FILTER_BEST: The highest-quality available, performance may
* not be suitable for interactive use.
* @CAIRO_FILTER_NEAREST: Nearest-neighbor filtering
commit c624ff46541b311c226ad7a026db3495b59dee41
Author: Behdad Esfahbod <behdad at behdad.org>
Date: Mon Jan 28 19:45:10 2008 -0500
[cairo_operator_t] Improve docs
diff --git a/src/cairo.h b/src/cairo.h
index bbc8bc6..ba48c4f 100644
--- a/src/cairo.h
+++ b/src/cairo.h
@@ -349,6 +349,7 @@ cairo_pop_group_to_source (cairo_t *cr);
* @CAIRO_OPERATOR_CLEAR: clear destination layer (bounded)
* @CAIRO_OPERATOR_SOURCE: replace destination layer (bounded)
* @CAIRO_OPERATOR_OVER: draw source layer on top of destination layer
+ * (bounded)
* @CAIRO_OPERATOR_IN: draw source where there was destination content
* (unbounded)
* @CAIRO_OPERATOR_OUT: draw source where there was no destination
@@ -362,9 +363,10 @@ cairo_pop_group_to_source (cairo_t *cr);
* @CAIRO_OPERATOR_DEST_OUT: leave destination only where there was no
* source content
* @CAIRO_OPERATOR_DEST_ATOP: leave destination on top of source content
- * an only there
- * @CAIRO_OPERATOR_XOR: pixel color xor
- * @CAIRO_OPERATOR_ADD: pixel color addition
+ * and only there
+ * @CAIRO_OPERATOR_XOR: source and destination are shown where there is only
+ * one of them
+ * @CAIRO_OPERATOR_ADD: source and destination layers are accumulated
* @CAIRO_OPERATOR_SATURATE: pixel color saturation
*
* #cairo_operator_t is used to set the compositing operator for drawing
commit f1271babcd4df1140019b258ca0af0d7da0d1328
Author: Behdad Esfahbod <behdad at behdad.org>
Date: Mon Jan 28 19:37:46 2008 -0500
[doc] Add Long_Description and some See_Also for all chapters
diff --git a/doc/public/tmpl/cairo-atsui.sgml b/doc/public/tmpl/cairo-atsui.sgml
index fb91793..434bec6 100644
--- a/doc/public/tmpl/cairo-atsui.sgml
+++ b/doc/public/tmpl/cairo-atsui.sgml
@@ -6,12 +6,14 @@ Font support for ATSUI on OS X
<!-- ##### SECTION Long_Description ##### -->
<para>
-
+The ATSUI font backend is primarily used to render text on Apple OS X systems.
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
-
+<itemizedlist>
+<listitem>#cairo_font_face_t</listitem>
+</itemizedlist>
</para>
<!-- ##### SECTION Stability_Level ##### -->
diff --git a/doc/public/tmpl/cairo-beos.sgml b/doc/public/tmpl/cairo-beos.sgml
index 707d7e1..7747e7b 100644
--- a/doc/public/tmpl/cairo-beos.sgml
+++ b/doc/public/tmpl/cairo-beos.sgml
@@ -6,12 +6,15 @@ BeOS surface support
<!-- ##### SECTION Long_Description ##### -->
<para>
-
+The BeOS surface is used to render cairo graphics natively on
+BeOS systems.
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
-
+<itemizedlist>
+<listitem>#cairo_surface_t</listitem>
+</itemizedlist>
</para>
<!-- ##### SECTION Stability_Level ##### -->
diff --git a/doc/public/tmpl/cairo-font-options.sgml b/doc/public/tmpl/cairo-font-options.sgml
index 8e15f2a..501abf4 100644
--- a/doc/public/tmpl/cairo-font-options.sgml
+++ b/doc/public/tmpl/cairo-font-options.sgml
@@ -1,17 +1,22 @@
<!-- ##### SECTION Title ##### -->
-Font Options
+cairo_font_options_t
<!-- ##### SECTION Short_Description ##### -->
How a font should be rendered
<!-- ##### SECTION Long_Description ##### -->
<para>
-
+The font options specify how fonts should be rendered. Most of the time the
+font options implied by a surface are just right and do not need any changes,
+but for pixel-based targets tweaking font options may result in superior
+output on a particular display.
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
-
+<itemizedlist>
+<listitem>#cairo_scaled_font_t</listitem>
+</itemizedlist>
</para>
<!-- ##### SECTION Stability_Level ##### -->
diff --git a/doc/public/tmpl/cairo-font.sgml b/doc/public/tmpl/cairo-font.sgml
index add99ec..079c40d 100644
--- a/doc/public/tmpl/cairo-font.sgml
+++ b/doc/public/tmpl/cairo-font.sgml
@@ -2,16 +2,24 @@
cairo_font_face_t
<!-- ##### SECTION Short_Description ##### -->
-Base class for fonts
+Base class for font faces
<!-- ##### SECTION Long_Description ##### -->
<para>
+#cairo_font_face_t represents a particular font at a particular weight,
+slant, and other characteristic but no size, transformation, or size.
+Font faces are created using font-backend specific constructors,
+or implicitly using the <firstterm>toy</firstterm> text API by way of
+cairo_select_font_face(). The resulting face can be accessed using
+cairo_get_font_face().
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
-
+<itemizedlist>
+<listitem>#cairo_scaled_font_t</listitem>
+</itemizedlist>
</para>
<!-- ##### SECTION Stability_Level ##### -->
diff --git a/doc/public/tmpl/cairo-ft.sgml b/doc/public/tmpl/cairo-ft.sgml
index db92840..8414c86 100644
--- a/doc/public/tmpl/cairo-ft.sgml
+++ b/doc/public/tmpl/cairo-ft.sgml
@@ -6,12 +6,15 @@ Font support for FreeType
<!-- ##### SECTION Long_Description ##### -->
<para>
-
+The FreeType font backend is primarily used to render text on GNU/Linux
+systems, but can be used on other platforms too.
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
-
+<itemizedlist>
+<listitem>#cairo_font_face_t</listitem>
+</itemizedlist>
</para>
<!-- ##### SECTION Stability_Level ##### -->
diff --git a/doc/public/tmpl/cairo-glitz.sgml b/doc/public/tmpl/cairo-glitz.sgml
index 437c71e..f7270c2 100644
--- a/doc/public/tmpl/cairo-glitz.sgml
+++ b/doc/public/tmpl/cairo-glitz.sgml
@@ -6,12 +6,15 @@ OpenGL accelerated rendering using the Glitz library
<!-- ##### SECTION Long_Description ##### -->
<para>
-
+The Glitz surface is used to render cairo graphics targeting the
+OpenGL hardware using the Glitz library.
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
-
+<itemizedlist>
+<listitem>#cairo_surface_t</listitem>
+</itemizedlist>
</para>
<!-- ##### SECTION Stability_Level ##### -->
diff --git a/doc/public/tmpl/cairo-image.sgml b/doc/public/tmpl/cairo-image.sgml
index b72732f..1d2b833 100644
--- a/doc/public/tmpl/cairo-image.sgml
+++ b/doc/public/tmpl/cairo-image.sgml
@@ -5,16 +5,17 @@ Image Surfaces
Rendering to memory buffers
<!-- ##### SECTION Long_Description ##### -->
-
- <para>
- Image surfaces provide the ability to render to memory buffers
- either allocated by cairo or by the calling code. The supported
- image formats are those defined in #cairo_format_t.
- </para>
+<para>
+Image surfaces provide the ability to render to memory buffers
+either allocated by cairo or by the calling code. The supported
+image formats are those defined in #cairo_format_t.
+</para>
<!-- ##### SECTION See_Also ##### -->
<para>
-
+<itemizedlist>
+<listitem>#cairo_surface_t</listitem>
+</itemizedlist>
</para>
<!-- ##### SECTION Stability_Level ##### -->
diff --git a/doc/public/tmpl/cairo-matrix.sgml b/doc/public/tmpl/cairo-matrix.sgml
index 26f7fe3..308a3ba 100644
--- a/doc/public/tmpl/cairo-matrix.sgml
+++ b/doc/public/tmpl/cairo-matrix.sgml
@@ -5,7 +5,6 @@ cairo_matrix_t
Generic matrix operations
<!-- ##### SECTION Long_Description ##### -->
-
<para><indexterm><primary>types</primary><secondary>cairo_matrix</secondary></indexterm><indexterm><primary/></indexterm>
#cairo_matrix_t is used throughout cairo to convert between different
coordinate spaces. A #cairo_matrix_t holds an affine transformation,
@@ -26,7 +25,9 @@ Generic matrix operations
<!-- ##### SECTION See_Also ##### -->
<para>
-
+<itemizedlist>
+<listitem>#cairo_t</listitem>
+</itemizedlist>
</para>
<!-- ##### SECTION Stability_Level ##### -->
diff --git a/doc/public/tmpl/cairo-paths.sgml b/doc/public/tmpl/cairo-paths.sgml
index 9eb844b..db79f26 100644
--- a/doc/public/tmpl/cairo-paths.sgml
+++ b/doc/public/tmpl/cairo-paths.sgml
@@ -6,7 +6,8 @@ Creating paths and manipulating path data
<!-- ##### SECTION Long_Description ##### -->
<para>
-
+Paths are the most basic drawing tools and are primarily used to implicitly
+generate simple masks.
</para>
<!-- ##### SECTION See_Also ##### -->
@@ -85,6 +86,7 @@ Creating paths and manipulating path data
@cr:
@x:
@y:
+ at Returns:
<!-- ##### FUNCTION cairo_new_path ##### -->
diff --git a/doc/public/tmpl/cairo-pattern.sgml b/doc/public/tmpl/cairo-pattern.sgml
index 8925b11..0deaa63 100644
--- a/doc/public/tmpl/cairo-pattern.sgml
+++ b/doc/public/tmpl/cairo-pattern.sgml
@@ -1,17 +1,22 @@
<!-- ##### SECTION Title ##### -->
-Patterns
+cairo_pattern_t
<!-- ##### SECTION Short_Description ##### -->
-Gradients and filtered sources
+Sources for drawing
<!-- ##### SECTION Long_Description ##### -->
<para>
-
+Patterns are the paint with which cairo draws. The primary use of patterns
+is as the source for all cairo drawing operations, although they can also be
+used as masks, that is, as the brush too.
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
-
+<itemizedlist>
+<listitem>#cairo_t</listitem>
+<listitem>#cairo_surface_t</listitem>
+</itemizedlist>
</para>
<!-- ##### SECTION Stability_Level ##### -->
diff --git a/doc/public/tmpl/cairo-pdf.sgml b/doc/public/tmpl/cairo-pdf.sgml
index 49f3fc1..52a2f8c 100644
--- a/doc/public/tmpl/cairo-pdf.sgml
+++ b/doc/public/tmpl/cairo-pdf.sgml
@@ -6,12 +6,15 @@ Rendering PDF documents
<!-- ##### SECTION Long_Description ##### -->
<para>
-
+The PDF surface is used to render cairo graphics to Adobe
+PDF files and is a multi-page vector surface backend.
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
-
+<itemizedlist>
+<listitem>#cairo_surface_t</listitem>
+</itemizedlist>
</para>
<!-- ##### SECTION Stability_Level ##### -->
diff --git a/doc/public/tmpl/cairo-png.sgml b/doc/public/tmpl/cairo-png.sgml
index d2e93f7..ec703ad 100644
--- a/doc/public/tmpl/cairo-png.sgml
+++ b/doc/public/tmpl/cairo-png.sgml
@@ -6,12 +6,15 @@ Reading and writing PNG images
<!-- ##### SECTION Long_Description ##### -->
<para>
-
+The PNG functions allow reading PNG images into image surfaces, and writing
+any surface to a PNG file.
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
-
+<itemizedlist>
+<listitem>#cairo_surface_t</listitem>
+</itemizedlist>
</para>
<!-- ##### SECTION Stability_Level ##### -->
diff --git a/doc/public/tmpl/cairo-ps.sgml b/doc/public/tmpl/cairo-ps.sgml
index 3cf66be..b3e80ba 100644
--- a/doc/public/tmpl/cairo-ps.sgml
+++ b/doc/public/tmpl/cairo-ps.sgml
@@ -6,12 +6,15 @@ Rendering PostScript documents
<!-- ##### SECTION Long_Description ##### -->
<para>
-
+The PostScript surface is used to render cairo graphics to Adobe
+PostScript files and is a multi-page vector surface backend.
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
-
+<itemizedlist>
+<listitem>#cairo_surface_t</listitem>
+</itemizedlist>
</para>
<!-- ##### SECTION Stability_Level ##### -->
diff --git a/doc/public/tmpl/cairo-quartz.sgml b/doc/public/tmpl/cairo-quartz.sgml
index 02a69d9..1c5e71f 100644
--- a/doc/public/tmpl/cairo-quartz.sgml
+++ b/doc/public/tmpl/cairo-quartz.sgml
@@ -6,12 +6,15 @@ Rendering to Quartz surfaces
<!-- ##### SECTION Long_Description ##### -->
<para>
-
+The Quartz surface is used to render cairo graphics targeting the
+Apple OS X Quartz rendering system.
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
-
+<itemizedlist>
+<listitem>#cairo_surface_t</listitem>
+</itemizedlist>
</para>
<!-- ##### SECTION Stability_Level ##### -->
diff --git a/doc/public/tmpl/cairo-scaled-font.sgml b/doc/public/tmpl/cairo-scaled-font.sgml
index 4175d19..4c8ee6c 100644
--- a/doc/public/tmpl/cairo-scaled-font.sgml
+++ b/doc/public/tmpl/cairo-scaled-font.sgml
@@ -1,17 +1,22 @@
<!-- ##### SECTION Title ##### -->
-Scaled Fonts
+cairo_scaled_font_t
<!-- ##### SECTION Short_Description ##### -->
-Caching metrics for a particular font size
+Font face at particular size and options
<!-- ##### SECTION Long_Description ##### -->
<para>
-
+#cairo_scaled_font_t represents a realization of a font face at a particular
+size and transformation and a certain set of font options.
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
-
+<itemizedlist>
+<listitem>#cairo_font_face_t</listitem>
+<listitem>#cairo_matrix_t</listitem>
+<listitem>#cairo_font_options_t</listitem>
+</itemizedlist>
</para>
<!-- ##### SECTION Stability_Level ##### -->
diff --git a/doc/public/tmpl/cairo-status.sgml b/doc/public/tmpl/cairo-status.sgml
index 5a1ac02..83e7167 100644
--- a/doc/public/tmpl/cairo-status.sgml
+++ b/doc/public/tmpl/cairo-status.sgml
@@ -6,12 +6,27 @@ Decoding cairo's status
<!-- ##### SECTION Long_Description ##### -->
<para>
-
+Cairo uses a single status type to represent all kinds of errors. A status
+value of %CAIRO_STATUS_SUCCESS represents no error and has an integer value
+of zero. All other status values represent an error.
+
+Cairo's error handling is designed to be easy to use and safe. All major
+cairo objects <firstterm>retain</firstterm> an error status internally which
+can be queried anytime by the users using cairo_*_status<!---->() calls. In
+the mean time, it is safe to call all cairo functions normally even if the
+underlying object is in an error status. This means that no error handling
+code is required before or after each individual cairo function call.
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
-
+<itemizedlist>
+<listitem>cairo_status()</listitem>
+<listitem>cairo_surface_status()</listitem>
+<listitem>cairo_pattern_status()</listitem>
+<listitem>cairo_font_face_status()</listitem>
+<listitem>cairo_scaled_font_status()</listitem>
+</itemizedlist>
</para>
<!-- ##### SECTION Stability_Level ##### -->
diff --git a/doc/public/tmpl/cairo-surface.sgml b/doc/public/tmpl/cairo-surface.sgml
index 3626db1..1e8b693 100644
--- a/doc/public/tmpl/cairo-surface.sgml
+++ b/doc/public/tmpl/cairo-surface.sgml
@@ -6,12 +6,16 @@ Base class for surfaces
<!-- ##### SECTION Long_Description ##### -->
<para>
-
+Cairo surfaces are target of all drawing operations. The actual drawings are
+performed using a cairo <firstterm>context</firstterm>.
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
-
+<itemizedlist>
+<listitem>#cairo_t()</listitem>
+<listitem>#cairo_pattern_t()</listitem>
+</itemizedlist>
</para>
<!-- ##### SECTION Stability_Level ##### -->
diff --git a/doc/public/tmpl/cairo-svg.sgml b/doc/public/tmpl/cairo-svg.sgml
index 4e496e1..c11b502 100644
--- a/doc/public/tmpl/cairo-svg.sgml
+++ b/doc/public/tmpl/cairo-svg.sgml
@@ -6,12 +6,15 @@ Rendering SVG documents
<!-- ##### SECTION Long_Description ##### -->
<para>
-
+The SVG surface is used to render cairo graphics to
+SVG files and is a multi-page vector surface backend.
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
-
+<itemizedlist>
+<listitem>#cairo_surface_t()</listitem>
+</itemizedlist>
</para>
<!-- ##### SECTION Stability_Level ##### -->
diff --git a/doc/public/tmpl/cairo-text.sgml b/doc/public/tmpl/cairo-text.sgml
index 00366f2..8de82ad 100644
--- a/doc/public/tmpl/cairo-text.sgml
+++ b/doc/public/tmpl/cairo-text.sgml
@@ -2,16 +2,44 @@
Text
<!-- ##### SECTION Short_Description ##### -->
-Rendering text and sets of glyphs
+Rendering text and glyphs
<!-- ##### SECTION Long_Description ##### -->
<para>
-
+Cairo has two sets of text rendering capabilities:
+<itemizedlist>
+ <listitem>
+ The functions with <emphasis>text</emphasis> in their name form cairo's
+ <firstterm>toy</firstterm> text API. The toy API takes UTF-8 encoded
+ text and is limited in its functionality to rendering simple
+ left-to-right text with no advanced features. That means for example
+ that most complex scripts like Hebrew, Arabic, and Indic scripts are
+ out of question. No kerning or correct positioning of diacritical marks
+ either. The font selection is pretty limited too and doesn't handle the
+ case that the selected font does not cover the characters in the text.
+ This set of functions are really that, a toy text API, for testing and
+ demonstration purposes. Any serious application should avoid them.
+ </listitem>
+ <listitem>
+ The functions with <emphasis>glyphs</emphasis> in their name form cairo's
+ <firstterm>low-level</firstterm> text API. The low-level API relies on
+ the user to convert text to a set of glyph indexes and positions. This
+ is a very hard problem and is best handled by external libraries, like
+ the pangocairo that is part of the Pango text layout and rendering library.
+ Pango is available from <ulink
+ url="http://www.pango.org/">http://www.pango.org/</ulink>.
+ </listitem>
+</itemizedlist>
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
-
+<itemizedlist>
+<listitem>#cairo_font_face_t</listitem>
+<listitem>#cairo_scaled_font_t</listitem>
+<listitem>cairo_text_path()</listitem>
+<listitem>cairo_glyph_path()</listitem>
+</itemizedlist>
</para>
<!-- ##### SECTION Stability_Level ##### -->
diff --git a/doc/public/tmpl/cairo-transforms.sgml b/doc/public/tmpl/cairo-transforms.sgml
index b14adcc..60c8ad9 100644
--- a/doc/public/tmpl/cairo-transforms.sgml
+++ b/doc/public/tmpl/cairo-transforms.sgml
@@ -6,12 +6,18 @@ Manipulating the current transformation matrix
<!-- ##### SECTION Long_Description ##### -->
<para>
-
+The current transformation matrix, <firstterm>ctm</firstterm>, is a
+two-dimensional affine transformation that maps all coordinates and other
+drawing instruments from the <firstterm>user space</firstterm> into the
+surface's canonical coordinate system, also known as the <firstterm>device
+space</firstterm>.
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
-
+<itemizedlist>
+<listitem>#cairo_matrix_t</listitem>
+</itemizedlist>
</para>
<!-- ##### SECTION Stability_Level ##### -->
diff --git a/doc/public/tmpl/cairo-types.sgml b/doc/public/tmpl/cairo-types.sgml
index c0c14fa..e79bc7a 100644
--- a/doc/public/tmpl/cairo-types.sgml
+++ b/doc/public/tmpl/cairo-types.sgml
@@ -2,11 +2,11 @@
Types
<!-- ##### SECTION Short_Description ##### -->
-Generic data types used in the cairo API
+Generic data types
<!-- ##### SECTION Long_Description ##### -->
<para>
-
+Generic data types used in the cairo API
</para>
<!-- ##### SECTION See_Also ##### -->
diff --git a/doc/public/tmpl/cairo-win32-fonts.sgml b/doc/public/tmpl/cairo-win32-fonts.sgml
index 5581e01..aabec96 100644
--- a/doc/public/tmpl/cairo-win32-fonts.sgml
+++ b/doc/public/tmpl/cairo-win32-fonts.sgml
@@ -6,12 +6,15 @@ Font support for Microsoft Windows
<!-- ##### SECTION Long_Description ##### -->
<para>
-
+The Microsoft Windows font backend is primarily used to render text on
+Microsoft Windows systems.
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
-
+<itemizedlist>
+<listitem>#cairo_font_face_t</listitem>
+</itemizedlist>
</para>
<!-- ##### SECTION Stability_Level ##### -->
diff --git a/doc/public/tmpl/cairo-win32.sgml b/doc/public/tmpl/cairo-win32.sgml
index fb03d83..97f1d4d 100644
--- a/doc/public/tmpl/cairo-win32.sgml
+++ b/doc/public/tmpl/cairo-win32.sgml
@@ -6,12 +6,15 @@ Microsoft Windows surface support
<!-- ##### SECTION Long_Description ##### -->
<para>
-
+The Microsoft Windows surface is used to render cairo graphics to
+Microsoft Windows windows and bitmap device contexts.
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
-
+<itemizedlist>
+<listitem>#cairo_surface_t</listitem>
+</itemizedlist>
</para>
<!-- ##### SECTION Stability_Level ##### -->
diff --git a/doc/public/tmpl/cairo-xcb-xrender.sgml b/doc/public/tmpl/cairo-xcb-xrender.sgml
index fc24323..40aa655 100644
--- a/doc/public/tmpl/cairo-xcb-xrender.sgml
+++ b/doc/public/tmpl/cairo-xcb-xrender.sgml
@@ -2,16 +2,22 @@
XCB Surfaces
<!-- ##### SECTION Short_Description ##### -->
-X Window System rendering using the XCB library
+X Window System rendering using the XCB library and the X Render extension
<!-- ##### SECTION Long_Description ##### -->
<para>
+The XCB surface is used to render cairo graphics to X Window System
+windows and pixmaps using the XCB library and its X Render extension.
+Note that the XCB surface automatically takes advantage of the X Render
+extension if it is available.
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
-
+<itemizedlist>
+<listitem>#cairo_surface_t</listitem>
+</itemizedlist>
</para>
<!-- ##### SECTION Stability_Level ##### -->
diff --git a/doc/public/tmpl/cairo-xcb.sgml b/doc/public/tmpl/cairo-xcb.sgml
index fc24323..5796542 100644
--- a/doc/public/tmpl/cairo-xcb.sgml
+++ b/doc/public/tmpl/cairo-xcb.sgml
@@ -6,12 +6,18 @@ X Window System rendering using the XCB library
<!-- ##### SECTION Long_Description ##### -->
<para>
+The XCB surface is used to render cairo graphics to X Window System
+windows and pixmaps using the XCB library.
+Note that the XCB surface automatically takes advantage of the X render
+extension if it is available.
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
-
+<itemizedlist>
+<listitem>#cairo_surface_t</listitem>
+</itemizedlist>
</para>
<!-- ##### SECTION Stability_Level ##### -->
diff --git a/doc/public/tmpl/cairo-xlib-xrender.sgml b/doc/public/tmpl/cairo-xlib-xrender.sgml
index 398900e..0746dc4 100644
--- a/doc/public/tmpl/cairo-xlib-xrender.sgml
+++ b/doc/public/tmpl/cairo-xlib-xrender.sgml
@@ -1,17 +1,23 @@
<!-- ##### SECTION Title ##### -->
-XLib/Xrender Backend
+XLib/XRender Backend
<!-- ##### SECTION Short_Description ##### -->
-
+X Window System rendering using XLib and the X Render extension
<!-- ##### SECTION Long_Description ##### -->
<para>
+The XLib surface is used to render cairo graphics to X Window System
+windows and pixmaps using the XLib and Xrender libraries.
+Note that the XLib surface automatically takes advantage of X Render extension
+if it is available.
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
-
+<itemizedlist>
+<listitem>#cairo_surface_t</listitem>
+</itemizedlist>
</para>
<!-- ##### SECTION Stability_Level ##### -->
diff --git a/doc/public/tmpl/cairo-xlib.sgml b/doc/public/tmpl/cairo-xlib.sgml
index 4abbd56..b8330a9 100644
--- a/doc/public/tmpl/cairo-xlib.sgml
+++ b/doc/public/tmpl/cairo-xlib.sgml
@@ -6,12 +6,18 @@ X Window System rendering using XLib
<!-- ##### SECTION Long_Description ##### -->
<para>
+The XLib surface is used to render cairo graphics to X Window System
+windows and pixmaps using the XLib library.
+Note that the XLib surface automatically takes advantage of X render extension
+if it is available.
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
-
+<itemizedlist>
+<listitem>#cairo_surface_t</listitem>
+</itemizedlist>
</para>
<!-- ##### SECTION Stability_Level ##### -->
diff --git a/doc/public/tmpl/cairo.sgml b/doc/public/tmpl/cairo.sgml
index 2f5c637..6faef6c 100644
--- a/doc/public/tmpl/cairo.sgml
+++ b/doc/public/tmpl/cairo.sgml
@@ -21,7 +21,9 @@ The cairo drawing context
<!-- ##### SECTION See_Also ##### -->
<para>
-
+<itemizedlist>
+<listitem>#cairo_surface_t</listitem>
+</itemizedlist>
</para>
<!-- ##### SECTION Stability_Level ##### -->
commit 73b184fb9c41f26365c99dbb5f81aa5166632722
Author: Behdad Esfahbod <behdad at behdad.org>
Date: Mon Jan 28 19:19:27 2008 -0500
[src] Fix gtk-doc warnings
diff --git a/src/cairo-scaled-font.c b/src/cairo-scaled-font.c
index fa597cb..a2271f3 100644
--- a/src/cairo-scaled-font.c
+++ b/src/cairo-scaled-font.c
@@ -1702,7 +1702,7 @@ _cairo_scaled_glyph_set_path (cairo_scaled_glyph_t *scaled_glyph,
* @scaled_glyph_ret: a #cairo_scaled_glyph_t * where the glyph
* is returned.
*
- * Returns a glyph with the requested portions filled in. Glyph
+ * Returns: a glyph with the requested portions filled in. Glyph
* lookup is cached and glyph will be automatically freed along
* with the scaled_font so no explicit free is required.
* @info can be one or more of:
diff --git a/src/cairo-surface.c b/src/cairo-surface.c
index 9716c06..38be109 100644
--- a/src/cairo-surface.c
+++ b/src/cairo-surface.c
@@ -1716,7 +1716,7 @@ slim_hidden_def (cairo_surface_show_page);
* _cairo_surface_get_current_clip_serial:
* @surface: the #cairo_surface_t to return the serial number for
*
- * Returns the serial number associated with the current
+ * Returns: the serial number associated with the current
* clip in the surface. All gstate functions must
* verify that the correct clip is set in the surface before
* invoking any surface drawing function
diff --git a/src/cairo.c b/src/cairo.c
index 6ab384e..5bbc53a 100644
--- a/src/cairo.c
+++ b/src/cairo.c
@@ -3229,7 +3229,7 @@ cairo_get_antialias (cairo_t *cr)
* Some functions unset the current path and as a result, current point:
* cairo_fill(), cairo_stroke().
*
- * Returns CAIRO_STATUS_SUCCESS if current point was successfully
+ * Returns: CAIRO_STATUS_SUCCESS if current point was successfully
* retrieved. Otherwise, if @cr has been in an error status, that status
* is returned, otherwise CAIRO_STATUS_NO_CURRENT_POINT is returned if
* no current point exists. In all error cases, both @x and @y will be
@@ -3565,7 +3565,7 @@ cairo_append_path (cairo_t *cr,
*
* Checks whether an error has previously occurred for this context.
*
- * Returns the current status of this context, see #cairo_status_t
+ * Returns: the current status of this context, see #cairo_status_t
**/
cairo_status_t
cairo_status (cairo_t *cr)
@@ -3580,7 +3580,7 @@ slim_hidden_def (cairo_status);
*
* Provides a human-readable description of a #cairo_status_t.
*
- * Returns a string representation of the status
+ * Returns: a string representation of the status
*/
const char *
cairo_status_to_string (cairo_status_t status)
More information about the cairo-commit
mailing list