added some types and enums, documented more functions

18 files changed, 306 insertions, 32 deletions

diff --git a/doc/reference/xml/cairo_current_fill_rule.xml b/doc/reference/xml/cairo_current_fill_rule.xml
index 9ef6c4aaa..3902c7acb 100644
--- a/doc/reference/xml/cairo_current_fill_rule.xml
+++ b/doc/reference/xml/cairo_current_fill_rule.xml
@@ -10,7 +10,7 @@
   </refnamediv>
   <refsynopsisdiv>
     <programlisting>
-cairo_fill_rule_t cairo_current_fill_rule (<link linkend="cairo_t">cairo_t</link> *cr)</programlisting>
+<link linkend="cairo_fill_rule_t">cairo_fill_rule_t</link> cairo_current_fill_rule (<link linkend="cairo_t">cairo_t</link> *cr)</programlisting>
     <variablelist role="params">
       <varlistentry>
         <term><parameter>cr</parameter> :</term>
diff --git a/doc/reference/xml/cairo_current_line_cap.xml b/doc/reference/xml/cairo_current_line_cap.xml
index e395ffe02..4b01c4db7 100644
--- a/doc/reference/xml/cairo_current_line_cap.xml
+++ b/doc/reference/xml/cairo_current_line_cap.xml
@@ -10,7 +10,7 @@
   </refnamediv>
   <refsynopsisdiv>
     <programlisting>
-cairo_line_cap_t cairo_current_line_cap (<link linkend="cairo_t">cairo_t</link> *cr)</programlisting>
+<link linkend="cairo_line_cap_t">cairo_line_cap_t</link> cairo_current_line_cap (<link linkend="cairo_t">cairo_t</link> *cr)</programlisting>
     <variablelist role="params">
       <varlistentry>
         <term><parameter>cr</parameter> :</term>
diff --git a/doc/reference/xml/cairo_current_operator.xml b/doc/reference/xml/cairo_current_operator.xml
index 55d173383..166717300 100644
--- a/doc/reference/xml/cairo_current_operator.xml
+++ b/doc/reference/xml/cairo_current_operator.xml
@@ -10,7 +10,7 @@
   </refnamediv>
   <refsynopsisdiv>
     <programlisting>
-cairo_operator_t cairo_current_operator (<link linkend="cairo_t">cairo_t</link> *cr)</programlisting>
+<link linkend="cairo_operator_t">cairo_operator_t</link> cairo_current_operator (<link linkend="cairo_t">cairo_t</link> *cr)</programlisting>
     <variablelist role="params">
       <varlistentry>
         <term><parameter>cr</parameter> :</term>
diff --git a/doc/reference/xml/cairo_fill_rule_t.xml b/doc/reference/xml/cairo_fill_rule_t.xml
new file mode 100644
index 000000000..9f1fbe3ee
--- /dev/null
+++ b/doc/reference/xml/cairo_fill_rule_t.xml
@@ -0,0 +1,40 @@
+<refentry id="cairo_fill_rule_t">
+  <refmeta>
+    <refentrytitle>cairo_fill_rule_t</refentrytitle>
+    <manvolnum>3</manvolnum>
+  </refmeta>
+  
+  <refnamediv>
+    <refname>cairo_fill_rule_t</refname>
+    <refpurpose>enumeration for fill rules</refpurpose>
+  </refnamediv>
+
+  <refsect1>
+    <title>Description</title>
+          <indexterm><primary>enums</primary>
+    <secondary>cairo_fill_rule_t</secondary></indexterm>
+<programlisting>typedef enum cairo_fill_rule {
+    CAIRO_FILL_RULE_WINDING,
+    CAIRO_FILL_RULE_EVEN_ODD
+} cairo_fill_rule_t;
+</programlisting>
+<para>
+Select ways to fill paths.
+</para>
+<variablelist role="enum">
+<varlistentry>
+<term><literal>CAIRO_FILL_RULE_WINDING</literal></term>
+<listitem><simpara>counts all intersections with a clockwise line positive and intersections with a counter-clockwise line negative. All areas with a non-zero counts are filled.
+</simpara></listitem>
+</varlistentry>
+<varlistentry>
+<term><literal>CAIRO_FILL_RULE_EVEN_ODD</literal></term>
+<listitem><simpara>Only the area from one intersection to the next will be filled, no matter what orientation the intersected line has.
+</simpara></listitem>
+</varlistentry>
+</variablelist>      
+ </refsect1>
+</refentry>
+
+
+
diff --git a/doc/reference/xml/cairo_format_t.xml b/doc/reference/xml/cairo_format_t.xml
new file mode 100644
index 000000000..e80c18a94
--- /dev/null
+++ b/doc/reference/xml/cairo_format_t.xml
@@ -0,0 +1,52 @@
+<refentry id="cairo_format_t">
+  <refmeta>
+    <refentrytitle>cairo_format_t</refentrytitle>
+    <manvolnum>3</manvolnum>
+  </refmeta>
+  
+  <refnamediv>
+    <refname>cairo_format_t</refname>
+    <refpurpose>enumeration for image formats</refpurpose>
+  </refnamediv>
+
+  <refsect1>
+    <title>Description</title>
+          <indexterm><primary>enums</primary>
+    <secondary>cairo_format_t</secondary></indexterm>
+<programlisting>typedef enum cairo_format {
+    CAIRO_FORMAT_ARGB32 = PictStandardARGB32,
+    CAIRO_FORMAT_RGB24 = PictStandardRGB24,
+    CAIRO_FORMAT_A8 = PictStandardA8,
+    CAIRO_FORMAT_A1 = PictStandardA1
+} cairo_format_t;
+</programlisting>
+<para>
+Possible formats for in-memory images.
+</para>
+<variablelist role="enum">
+<varlistentry>
+<term><literal>CAIRO_FORMAT_ARGB32</literal></term>
+<listitem><simpara>one byte for red, green, blue and alpha. (rowstride = width * 4)
+</simpara></listitem>
+</varlistentry>
+<varlistentry>
+<term><literal>CAIRO_FORMAT_RGB24</literal></term>
+<listitem><simpara>one byte for red, green and blue (rowstride = width * 4)
+</simpara></listitem>
+</varlistentry>
+<varlistentry>
+<term><literal>CAIRO_FORMAT_A8</literal></term>
+<listitem><simpara>indexed color image 
+</simpara></listitem>
+</varlistentry>
+<varlistentry>
+<term><literal>CAIRO_FORMAT_A1</literal></term>
+<listitem><simpara>a bitmap
+</simpara></listitem>
+</varlistentry>
+</variablelist>      
+ </refsect1>
+</refentry>
+
+
+
diff --git a/doc/reference/xml/cairo_line_cap_t.xml b/doc/reference/xml/cairo_line_cap_t.xml
new file mode 100644
index 000000000..9f1ee028a
--- /dev/null
+++ b/doc/reference/xml/cairo_line_cap_t.xml
@@ -0,0 +1,43 @@
+<refentry id="cairo_line_cap_t">
+  <refmeta>
+    <refentrytitle>cairo_line_cap_t</refentrytitle>
+    <manvolnum>3</manvolnum>
+  </refmeta>
+  
+  <refnamediv>
+    <refname>cairo_line_cap_t</refname>
+    <refpurpose>enumeration for style of line-endings</refpurpose>
+  </refnamediv>
+
+  <refsect1>
+    <title>Description</title>
+          <indexterm><primary>enums</primary>
+    <secondary>cairo_line_cap_t</secondary></indexterm>
+<programlisting>typedef enum cairo_line_cap {
+    CAIRO_LINE_CAP_BUTT,
+    CAIRO_LINE_CAP_ROUND,
+    CAIRO_LINE_CAP_SQUARE
+} cairo_line_cap_t;
+</programlisting>
+<variablelist role="enum">
+<varlistentry>
+<term><literal>CAIRO_LINE_CAP_BUTT</literal></term>
+<listitem><simpara>start(stop) the line exactly at the start(end) point
+</simpara></listitem>
+</varlistentry>
+<varlistentry>
+<term><literal>CAIRO_LINE_CAP_ROUND</literal></term>
+<listitem><simpara>use a round ending, the center of the circle is the end point.
+</simpara></listitem>
+</varlistentry>
+<varlistentry>
+<term><literal>CAIRO_LINE_CAP_SQUARE</literal></term>
+<listitem><simpara>use squared ending, the center of the square is the end point.
+</simpara></listitem>
+</varlistentry>
+</variablelist>      
+ </refsect1>
+</refentry>
+
+
+
diff --git a/doc/reference/xml/cairo_matrix_t.xml b/doc/reference/xml/cairo_matrix_t.xml
new file mode 100644
index 000000000..67632ac18
--- /dev/null
+++ b/doc/reference/xml/cairo_matrix_t.xml
@@ -0,0 +1,23 @@
+
+<refentry id="cairo_matrix_t">
+  <refmeta>
+    <refentrytitle>cairo_matrix</refentrytitle>
+    <manvolnum>3</manvolnum>
+  </refmeta>
+  <refnamediv>
+    <refname>cairo_matrix</refname>
+    <refpurpose>a matrix</refpurpose>
+  </refnamediv>
+  <refsect1>
+    <title>Description</title>
+    <para><indexterm><primary>types</primary><secondary>cairo_matrix</secondary></indexterm><indexterm><primary/></indexterm>
+      A <varname>cairo_matrix</varname> contains the current state of the rendering device, 
+      including coordinates of yet to be drawn shapes.  
+      <varname>cairo_matrix</varname>'s can be pushed to a stack via 
+      <link linkend="cairo_save">cairo_save</link>. 
+      They may then savely be changed, without loosing the current state. 
+      Use <link linkend="cairo_restore">cairo_restore</link> to 
+      restore to the saved state.
+    </para>
+  </refsect1>
+</refentry>
diff --git a/doc/reference/xml/cairo_operator_t.xml b/doc/reference/xml/cairo_operator_t.xml
new file mode 100644
index 000000000..d8baf1708
--- /dev/null
+++ b/doc/reference/xml/cairo_operator_t.xml
@@ -0,0 +1,73 @@
+<refentry id="cairo_operator_t">
+  <refmeta>
+    <refentrytitle>cairo_operator_t</refentrytitle>
+    <manvolnum>3</manvolnum>
+  </refmeta>
+  
+  <refnamediv>
+    <refname>cairo_operator_t</refname>
+    <refpurpose>enumeration for image operators</refpurpose>
+  </refnamediv>
+
+  <refsect1>
+    <title>Description</title>
+          <indexterm><primary>enums</primary>
+    <secondary>cairo_operator_t</secondary></indexterm>
+<programlisting>typedef enum cairo_operator {
+    CAIRO_OPERATOR_CLEAR = PictOpClear,
+    CAIRO_OPERATOR_SRC = PictOpSrc,
+    CAIRO_OPERATOR_DST = PictOpDst,
+    CAIRO_OPERATOR_OVER = PictOpOver,
+    CAIRO_OPERATOR_OVER_REVERSE = PictOpOverReverse,
+    CAIRO_OPERATOR_IN = PictOpIn,
+    CAIRO_OPERATOR_IN_REVERSE = PictOpInReverse,
+    CAIRO_OPERATOR_OUT = PictOpOut,
+    CAIRO_OPERATOR_OUT_REVERSE = PictOpOutReverse,
+    CAIRO_OPERATOR_ATOP = PictOpAtop,
+    CAIRO_OPERATOR_ATOP_REVERSE = PictOpAtopReverse,
+    CAIRO_OPERATOR_XOR = PictOpXor,
+    CAIRO_OPERATOR_ADD = PictOpAdd,
+    CAIRO_OPERATOR_SATURATE = PictOpSaturate,
+
+    CAIRO_OPERATOR_DISJOINT_CLEAR = PictOpDisjointClear,
+    CAIRO_OPERATOR_DISJOINT_SRC = PictOpDisjointSrc,
+    CAIRO_OPERATOR_DISJOINT_DST = PictOpDisjointDst,
+    CAIRO_OPERATOR_DISJOINT_OVER = PictOpDisjointOver,
+    CAIRO_OPERATOR_DISJOINT_OVER_REVERSE = PictOpDisjointOverReverse,
+    CAIRO_OPERATOR_DISJOINT_IN = PictOpDisjointIn,
+    CAIRO_OPERATOR_DISJOINT_IN_REVERSE = PictOpDisjointInReverse,
+    CAIRO_OPERATOR_DISJOINT_OUT = PictOpDisjointOut,
+    CAIRO_OPERATOR_DISJOINT_OUT_REVERSE = PictOpDisjointOutReverse,
+    CAIRO_OPERATOR_DISJOINT_ATOP = PictOpDisjointAtop,
+    CAIRO_OPERATOR_DISJOINT_ATOP_REVERSE = PictOpDisjointAtopReverse,
+    CAIRO_OPERATOR_DISJOINT_XOR = PictOpDisjointXor,
+
+    CAIRO_OPERATOR_CONJOINT_CLEAR = PictOpConjointClear,
+    CAIRO_OPERATOR_CONJOINT_SRC = PictOpConjointSrc,
+    CAIRO_OPERATOR_CONJOINT_DST = PictOpConjointDst,
+    CAIRO_OPERATOR_CONJOINT_OVER = PictOpConjointOver,
+    CAIRO_OPERATOR_CONJOINT_OVER_REVERSE = PictOpConjointOverReverse,
+    CAIRO_OPERATOR_CONJOINT_IN = PictOpConjointIn,
+    CAIRO_OPERATOR_CONJOINT_IN_REVERSE = PictOpConjointInReverse,
+    CAIRO_OPERATOR_CONJOINT_OUT = PictOpConjointOut,
+    CAIRO_OPERATOR_CONJOINT_OUT_REVERSE = PictOpConjointOutReverse,
+    CAIRO_OPERATOR_CONJOINT_ATOP = PictOpConjointAtop,
+    CAIRO_OPERATOR_CONJOINT_ATOP_REVERSE = PictOpConjointAtopReverse,
+    CAIRO_OPERATOR_CONJOINT_XOR = PictOpConjointXor
+} cairo_operator_t;
+</programlisting>
+<para>
+Operators for surface-compositing. XXX
+</para>
+<variablelist role="enum">
+<varlistentry>
+<term><literal></literal></term>
+<listitem><simpara>
+</simpara></listitem>
+</varlistentry>
+</variablelist>      
+ </refsect1>
+</refentry>
+
+
+
diff --git a/doc/reference/xml/cairo_set_alpha.xml b/doc/reference/xml/cairo_set_alpha.xml
index f14a82952..e996c33bf 100644
--- a/doc/reference/xml/cairo_set_alpha.xml
+++ b/doc/reference/xml/cairo_set_alpha.xml
@@ -6,7 +6,7 @@
   </refmeta>
   <refnamediv>
     <refname>cairo_set_alpha</refname>
-    <refpurpose>some description</refpurpose>
+    <refpurpose>set opaqueness for painting</refpurpose>
   </refnamediv>
   <refsynopsisdiv>
     <programlisting>
@@ -15,13 +15,13 @@ void cairo_set_alpha (<link linkend="cairo_t">cairo_t</link> *cr, double alpha)<
       <varlistentry>
         <term><parameter>cr</parameter> :</term>
         <listitem>
-          <simpara>description</simpara>
+          <simpara>a cairo_r</simpara>
         </listitem>
       </varlistentry>
       <varlistentry>
         <term><parameter>alpha</parameter> :</term>
         <listitem>
-          <simpara>description</simpara>
+          <simpara>an alpha value between 0.0 and 1.0</simpara>
         </listitem>
       </varlistentry>
     </variablelist>
@@ -36,6 +36,7 @@ void cairo_set_alpha (<link linkend="cairo_t">cairo_t</link> *cr, double alpha)<
       <indexterm>
         <primary/>
       </indexterm>
+      If alpha is not between 0.0 and 1.0 it will be restricted to fit.
     </para>
   </refsect1>
 </refentry>
diff --git a/doc/reference/xml/cairo_set_fill_rule.xml b/doc/reference/xml/cairo_set_fill_rule.xml
index 346891fab..64bd9b51c 100644
--- a/doc/reference/xml/cairo_set_fill_rule.xml
+++ b/doc/reference/xml/cairo_set_fill_rule.xml
@@ -10,7 +10,7 @@
   </refnamediv>
   <refsynopsisdiv>
     <programlisting>
-void cairo_set_fill_rule (<link linkend="cairo_t">cairo_t</link> *cr, cairo_fill_rule_t fill_rule)</programlisting>
+void cairo_set_fill_rule (<link linkend="cairo_t">cairo_t</link> *cr, <link linkend="cairo_fill_rule_t">cairo_fill_rule_t</link> fill_rule)</programlisting>
     <variablelist role="params">
       <varlistentry>
         <term><parameter>cr</parameter> :</term>
diff --git a/doc/reference/xml/cairo_set_line_cap.xml b/doc/reference/xml/cairo_set_line_cap.xml
index 4deee3693..9b346b782 100644
--- a/doc/reference/xml/cairo_set_line_cap.xml
+++ b/doc/reference/xml/cairo_set_line_cap.xml
@@ -1,4 +1,3 @@
-
 <refentry id="cairo_set_line_cap">
   <refmeta>
     <refentrytitle>cairo_set_line_cap</refentrytitle>
@@ -6,22 +5,22 @@
   </refmeta>
   <refnamediv>
     <refname>cairo_set_line_cap</refname>
-    <refpurpose>some description</refpurpose>
+    <refpurpose>determine shape of line endings</refpurpose>
   </refnamediv>
   <refsynopsisdiv>
     <programlisting>
-void cairo_set_line_cap (<link linkend="cairo_t">cairo_t</link> *cr, cairo_line_cap_t line_cap)</programlisting>
+void cairo_set_line_cap (<link linkend="cairo_t">cairo_t</link> *cr, <link linkend="cairo_line_cap_t">cairo_line_cap_t</link> line_cap)</programlisting>
     <variablelist role="params">
       <varlistentry>
         <term><parameter>cr</parameter> :</term>
         <listitem>
-          <simpara>description</simpara>
+          <simpara>a <link linkend="cairo_t">cairo_t</link></simpara>
         </listitem>
       </varlistentry>
       <varlistentry>
         <term><parameter>line_cap</parameter> :</term>
         <listitem>
-          <simpara>description</simpara>
+          <simpara>see <link linkend="cairo_line_cap_t">cairo_line_cap_t</link> for styles</simpara>
         </listitem>
       </varlistentry>
     </variablelist>
@@ -36,6 +35,7 @@ void cairo_set_line_cap (<link linkend="cairo_t">cairo_t</link> *cr, cairo_line_
       <indexterm>
         <primary/>
       </indexterm>
+      When the line width is larger than one device unit, it matters which way the ending of a line is drawn. Use this function to set the line-ending-style.
     </para>
   </refsect1>
 </refentry>
diff --git a/doc/reference/xml/cairo_set_line_width.xml b/doc/reference/xml/cairo_set_line_width.xml
index 1a718cf00..033a426c1 100644
--- a/doc/reference/xml/cairo_set_line_width.xml
+++ b/doc/reference/xml/cairo_set_line_width.xml
@@ -6,7 +6,7 @@
   </refmeta>
   <refnamediv>
     <refname>cairo_set_line_width</refname>
-    <refpurpose>some description</refpurpose>
+    <refpurpose>set line width in device units</refpurpose>
   </refnamediv>
   <refsynopsisdiv>
     <programlisting>
@@ -15,13 +15,13 @@ void cairo_set_line_width (<link linkend="cairo_t">cairo_t</link> *cr, double wi
       <varlistentry>
         <term><parameter>cr</parameter> :</term>
         <listitem>
-          <simpara>description</simpara>
+          <simpara>a <link linkend="cairo_t">cairo_t</link></simpara>
         </listitem>
       </varlistentry>
       <varlistentry>
         <term><parameter>width</parameter> :</term>
         <listitem>
-          <simpara>description</simpara>
+          <simpara>width in device units</simpara>
         </listitem>
       </varlistentry>
     </variablelist>
diff --git a/doc/reference/xml/cairo_set_operator.xml b/doc/reference/xml/cairo_set_operator.xml
index 5105d8fe6..0bde0b1b5 100644
--- a/doc/reference/xml/cairo_set_operator.xml
+++ b/doc/reference/xml/cairo_set_operator.xml
@@ -6,22 +6,22 @@
   </refmeta>
   <refnamediv>
     <refname>cairo_set_operator</refname>
-    <refpurpose>some description</refpurpose>
+    <refpurpose>select operator for surface compositing</refpurpose>
   </refnamediv>
   <refsynopsisdiv>
     <programlisting>
-void cairo_set_operator (<link linkend="cairo_t">cairo_t</link> *cr, cairo_operator_t op)</programlisting>
+void cairo_set_operator (<link linkend="cairo_t">cairo_t</link> *cr, <link linkend="cairo_operator_t">cairo_operator_t</link> op)</programlisting>
     <variablelist role="params">
       <varlistentry>
         <term><parameter>cr</parameter> :</term>
         <listitem>
-          <simpara>description</simpara>
+          <simpara>a <link linkend="cairo_t">cairo_t</link></simpara>
         </listitem>
       </varlistentry>
       <varlistentry>
         <term><parameter>op</parameter> :</term>
         <listitem>
-          <simpara>description</simpara>
+          <simpara>the operator for subsequent compositing operations</simpara>
         </listitem>
       </varlistentry>
     </variablelist>
@@ -36,6 +36,7 @@ void cairo_set_operator (<link linkend="cairo_t">cairo_t</link> *cr, cairo_opera
       <indexterm>
         <primary/>
       </indexterm>
+       
     </para>
   </refsect1>
 </refentry>
diff --git a/doc/reference/xml/cairo_set_pattern.xml b/doc/reference/xml/cairo_set_pattern.xml
index a82ee7c01..14d0678df 100644
--- a/doc/reference/xml/cairo_set_pattern.xml
+++ b/doc/reference/xml/cairo_set_pattern.xml
@@ -1,4 +1,3 @@
-
 <refentry id="cairo_set_pattern">
   <refmeta>
     <refentrytitle>cairo_set_pattern</refentrytitle>
@@ -6,7 +5,7 @@
   </refmeta>
   <refnamediv>
     <refname>cairo_set_pattern</refname>
-    <refpurpose>some description</refpurpose>
+    <refpurpose>select a surface as fill pattern</refpurpose>
   </refnamediv>
   <refsynopsisdiv>
     <programlisting>
@@ -15,13 +14,13 @@ void cairo_set_pattern (<link linkend="cairo_t">cairo_t</link> *cr, <link linken
       <varlistentry>
         <term><parameter>cr</parameter> :</term>
         <listitem>
-          <simpara>description</simpara>
+          <simpara>a <link linkend="cairo_t">cairo_t</link></simpara>
         </listitem>
       </varlistentry>
       <varlistentry>
         <term><parameter>pattern</parameter> :</term>
         <listitem>
-          <simpara>description</simpara>
+          <simpara>a surface</simpara>
         </listitem>
       </varlistentry>
     </variablelist>
@@ -36,6 +35,7 @@ void cairo_set_pattern (<link linkend="cairo_t">cairo_t</link> *cr, <link linken
       <indexterm>
         <primary/>
       </indexterm>
+      This function selects <varname>pattern</varname> as pattern for fill operations. If the repeat flag is set via <link linkend="cairo_surface_set_repeat">cairo_surface_set_repeat</link>, the pattern will be tiled, otherwise just drawn once.
     </para>
   </refsect1>
 </refentry>
diff --git a/doc/reference/xml/cairo_set_rgb_color.xml b/doc/reference/xml/cairo_set_rgb_color.xml
index 299e55ea4..24db26a63 100644
--- a/doc/reference/xml/cairo_set_rgb_color.xml
+++ b/doc/reference/xml/cairo_set_rgb_color.xml
@@ -6,7 +6,7 @@
   </refmeta>
   <refnamediv>
     <refname>cairo_set_rgb_color</refname>
-    <refpurpose>some description</refpurpose>
+    <refpurpose>select color for painting operations</refpurpose>
   </refnamediv>
   <refsynopsisdiv>
     <programlisting>
@@ -15,25 +15,25 @@ void cairo_set_rgb_color (<link linkend="cairo_t">cairo_t</link> *cr, double red
       <varlistentry>
         <term><parameter>cr</parameter> :</term>
         <listitem>
-          <simpara>description</simpara>
+          <simpara>a <link linkend="cairo_t">cairo_t</link></simpara>
         </listitem>
       </varlistentry>
       <varlistentry>
         <term><parameter>red</parameter> :</term>
         <listitem>
-          <simpara>description</simpara>
+          <simpara>red component</simpara>
         </listitem>
       </varlistentry>
       <varlistentry>
         <term><parameter>green</parameter> :</term>
         <listitem>
-          <simpara>description</simpara>
+          <simpara>green component</simpara>
         </listitem>
       </varlistentry>
       <varlistentry>
         <term><parameter>blue</parameter> :</term>
         <listitem>
-          <simpara>description</simpara>
+          <simpara>blue component</simpara>
         </listitem>
       </varlistentry>
     </variablelist>
@@ -48,6 +48,7 @@ void cairo_set_rgb_color (<link linkend="cairo_t">cairo_t</link> *cr, double red
       <indexterm>
         <primary/>
       </indexterm>
+      Set the color for subsequent drawing operations. Values which are not between 0.0 and 1.0 will be changed (e.g. red=2.0 => red=1.0).
     </para>
   </refsect1>
 </refentry>
diff --git a/doc/reference/xml/cairo_set_tolerance.xml b/doc/reference/xml/cairo_set_tolerance.xml
index aa483f409..2ab257c0a 100644
--- a/doc/reference/xml/cairo_set_tolerance.xml
+++ b/doc/reference/xml/cairo_set_tolerance.xml
@@ -1,4 +1,3 @@
-
 <refentry id="cairo_set_tolerance">
   <refmeta>
     <refentrytitle>cairo_set_tolerance</refentrytitle>
@@ -6,7 +5,7 @@
   </refmeta>
   <refnamediv>
     <refname>cairo_set_tolerance</refname>
-    <refpurpose>some description</refpurpose>
+    <refpurpose>set accuracy of painting operations</refpurpose>
   </refnamediv>
   <refsynopsisdiv>
     <programlisting>
@@ -15,13 +14,13 @@ void cairo_set_tolerance (<link linkend="cairo_t">cairo_t</link> *cr, double tol
       <varlistentry>
         <term><parameter>cr</parameter> :</term>
         <listitem>
-          <simpara>description</simpara>
+          <simpara>a <link linkend="cairo_t">cairo_t</link></simpara>
         </listitem>
       </varlistentry>
       <varlistentry>
         <term><parameter>tolerance</parameter> :</term>
         <listitem>
-          <simpara>description</simpara>
+          <simpara>the accuracy in device pixels</simpara>
         </listitem>
       </varlistentry>
     </variablelist>
@@ -36,6 +35,7 @@ void cairo_set_tolerance (<link linkend="cairo_t">cairo_t</link> *cr, double tol
       <indexterm>
         <primary/>
       </indexterm>
+      This function adjusts the error tolerance for tesselating curved objects. The default value is 0.1 (device pixels). This function can be used to trade speed against accuracy.
     </para>
   </refsect1>
 </refentry>
diff --git a/doc/reference/xml/cairo_surface_t.xml b/doc/reference/xml/cairo_surface_t.xml
new file mode 100644
index 000000000..aa5b9d80e
--- /dev/null
+++ b/doc/reference/xml/cairo_surface_t.xml
@@ -0,0 +1,17 @@
+
+<refentry id="cairo_surface_t">
+  <refmeta>
+    <refentrytitle>cairo_surface_t</refentrytitle>
+    <manvolnum>3</manvolnum>
+  </refmeta>
+  <refnamediv>
+    <refname>cairo_surface_t</refname>
+    <refpurpose>surface to draw on</refpurpose>
+  </refnamediv>
+  <refsect1>
+    <title>Description</title>
+    <para><indexterm><primary>types</primary><secondary>cairo_surface_t</secondary></indexterm><indexterm><primary/></indexterm>
+      A <varname>cairo_surface_t</varname> is a high level wrapper for varoius surface. So far the surface can be a bitmap or a memory image. It also contains information about the width and height, repeating information (in case it is used as a pattern: <link linkend="cairo_surface_set_repeat">cairo_surface_set_repeat</link>), the quality for rescaling (<link linkend="cairo_surface_set_filter">cairo_surface_set_filter</link>), and transformations. Surfaces support reference counting via <link linkend="cairo_surface_reference">cairo_surface_reference</link> and <link linkend="cairo_surface_destroy">cairo_surface_destroy</link>.
+    </para>
+  </refsect1>
+</refentry>
diff --git a/doc/reference/xml/cairo_t.xml b/doc/reference/xml/cairo_t.xml
new file mode 100644
index 000000000..5adb628a5
--- /dev/null
+++ b/doc/reference/xml/cairo_t.xml
@@ -0,0 +1,23 @@
+
+<refentry id="cairo_t">
+  <refmeta>
+    <refentrytitle>cairo_t</refentrytitle>
+    <manvolnum>3</manvolnum>
+  </refmeta>
+  <refnamediv>
+    <refname>cairo_t</refname>
+    <refpurpose>holds the current state</refpurpose>
+  </refnamediv>
+  <refsect1>
+    <title>Description</title>
+    <para><indexterm><primary>types</primary><secondary>cairo_t</secondary></indexterm><indexterm><primary/></indexterm>
+      A <varname>cairo_t</varname> contains the current state of the rendering device, 
+      including coordinates of yet to be drawn shapes.  
+      <varname>cairo_t</varname>'s can be pushed to a stack via 
+      <link linkend="cairo_save">cairo_save</link>. 
+      They may then savely be changed, without loosing the current state. 
+      Use <link linkend="cairo_restore">cairo_restore</link> to 
+      restore to the saved state.
+    </para>
+  </refsect1>
+</refentry>