[cairo-commit] 2 commits - src/cairo-surface.c src/check-doc-syntax.sh

[Benjamin Otte]

 src/cairo-surface.c     |   32 ++++++++++++++++++++++++++++++++
 src/check-doc-syntax.sh |    4 +---
 2 files changed, 33 insertions(+), 3 deletions(-)

New commits:
commit dd6026b613aa5414a128727995f2a4f79284072a
Author: Benjamin Otte <otte at redhat.com>
Date:   Sun Jul 11 20:44:40 2010 +0200

    doc: Make the necessity of flush/mark_dirty more obvious

diff --git a/src/cairo-surface.c b/src/cairo-surface.c
index a0c1941..f4ada74 100644
--- a/src/cairo-surface.c
+++ b/src/cairo-surface.c
@@ -59,6 +59,38 @@
  * A cairo surface is created by using <firstterm>backend</firstterm>-specific
  * constructors, typically of the form
  * cairo_<emphasis>backend</emphasis>_surface_create().
+ *
+ * Most surface types allow accessing the surface without using Cairo
+ * functions. If you do this, keep in mind that it is mandatory that you call
+ * cairo_surface_flush() before reading from or writing to the surface and that
+ * you must use cairo_surface_mark_dirty() after modifying it.
+ * <example>
+ * <title>Directly modifying an image surface</title>
+ * <programlisting>
+ * void
+ * modify_image_surface (cairo_surface_t *surface)
+ * {
+ *   unsigned char *data;
+ *   int width, height, stride;
+ *
+ *   // flush to ensure all writing to the image was done
+ *   cairo_surface_flush (surface);
+ *
+ *   // modify the image
+ *   data = cairo_image_surface_get_data (surface);
+ *   width = cairo_image_surface_get_width (surface);
+ *   height = cairo_image_surface_get_height (surface);
+ *   stride = cairo_image_surface_get_stride (surface);
+ *   modify_image_data (data, width, height, stride);
+ *
+ *   // mark the image dirty so Cairo clears its caches.
+ *   cairo_surface_mark_dirty (surface);
+ * }
+ * </programlisting>
+ * </example>
+ * Note that for other surface types it might be necessary to acquire the
+ * surface's device first. See cairo_device_acquire() for a discussion of
+ * devices.
  */
 
 #define DEFINE_NIL_SURFACE(status, name)			\
commit 8a1944f45b9c9056088246d4f2e72d60a59fd5c4
Author: Benjamin Otte <otte at redhat.com>
Date:   Sun Jul 11 19:11:15 2010 +0200

    check: Allow unprefix type names in the title
    
    Some documentation sections use the type name as the title, and we don't
    want to use that title as a link.

diff --git a/src/check-doc-syntax.sh b/src/check-doc-syntax.sh
index 4ca82d3..8390e5e 100755
--- a/src/check-doc-syntax.sh
+++ b/src/check-doc-syntax.sh
@@ -17,8 +17,6 @@ echo Checking documentation for incorrect syntax
 
 cd "$srcdir"
 
-# Note: this test is also run from doc/public/ to check the SGML files
-
 if test "x$SGML_DOCS" = x; then
     FILES=$all_cairo_files
     if test "x$FILES" = x; then
@@ -44,7 +42,7 @@ else
 	type_regexp='\(.'$type_regexp'\)\|\('$type_regexp'.\)'
 fi
 
-if echo $FILES | xargs grep . /dev/null | sed -e '/<programlisting>/,/<\/programlisting>/d' | grep "$type_regexp" | grep -v '#####'; then
+if echo $FILES | xargs grep . /dev/null | sed -e '/<programlisting>/,/<\/programlisting>/d' | grep -v "@Title" | grep "$type_regexp" | grep -v '#####'; then
 	stat=1
 	echo Error: some type names in the docs are not prefixed by hash sign,
 	echo neither are the only token in the doc line followed by colon.