[doc] Improve syntax

doc/public/tmpl/cairo-font.sgml

@@ -8,8 +8,11 @@ Base class for font faces
 <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,
+</para>
+<para>
+Font faces are created using <firstterm>font-backend</firstterm>-specific
+constructors, typically of the form
+cairo_<emphasis>backend</emphasis>_font_face_create(),
 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().

doc/public/tmpl/cairo-matrix.sgml

@@ -5,7 +5,7 @@ cairo_matrix_t
 Generic matrix operations
 
 <!-- ##### SECTION Long_Description ##### -->
-  <para><indexterm><primary>types</primary><secondary>cairo_matrix</secondary></indexterm><indexterm><primary/></indexterm>
+  <para>
     #cairo_matrix_t is used throughout cairo to convert between different
     coordinate spaces.  A #cairo_matrix_t holds an affine transformation,
     such as a scale, rotation, shear, or a combination of these.

doc/public/tmpl/cairo-pattern.sgml

@@ -6,9 +6,15 @@ 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.
+#cairo_pattern_t is 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>
+<para>
+A cairo pattern is created by using one of the many constructors,
+of the form cairo_pattern_create_<emphasis>type</emphasis>()
+or implicitly through
+cairo_set_source_<emphasis>type</emphasis>() functions.
 </para>
 
 <!-- ##### SECTION See_Also ##### -->

doc/public/tmpl/cairo-status.sgml

@@ -9,10 +9,11 @@ Decoding cairo's status
 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.
-
+</para>
+<para>
 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
+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.

doc/public/tmpl/cairo-surface.sgml

@@ -6,9 +6,15 @@ Base class for surfaces
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
-Cairo surfaces are target of all drawing operations.  The actual drawings are
+#cairo_surface_t is the abstract type representing all different drawing
+targets that cairo can render to.  The actual drawings are
 performed using a cairo <firstterm>context</firstterm>.
 </para>
+<para>
+A cairo surface is created by using <firstterm>backend</firstterm>-specific
+constructors, typically of the form
+cairo_<emphasis>backend</emphasis>_surface_create().
+</para>
 
 <!-- ##### SECTION See_Also ##### -->
 <para>

doc/public/tmpl/cairo-xcb-xrender.sgml

@@ -8,7 +8,8 @@ X Window System rendering using the XCB library and the X Render extension
 <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.
-
+</para>
+<para>
 Note that the XCB surface automatically takes advantage of the X Render
 extension if it is available.
 </para>

doc/public/tmpl/cairo-xcb.sgml

@@ -8,7 +8,8 @@ X Window System rendering using the XCB library
 <para>
 The XCB surface is used to render cairo graphics to X Window System
 windows and pixmaps using the XCB library.
-
+</para>
+<para>
 Note that the XCB surface automatically takes advantage of the X render
 extension if it is available.
 </para>

doc/public/tmpl/cairo-xlib-xrender.sgml

@@ -8,7 +8,8 @@ X Window System rendering using XLib and the X Render extension
 <para>
 The XLib surface is used to render cairo graphics to X Window System
 windows and pixmaps using the XLib and Xrender libraries.
-
+</para>
+<para>
 Note that the XLib surface automatically takes advantage of X Render extension
 if it is available.
 </para>

doc/public/tmpl/cairo-xlib.sgml

@@ -8,7 +8,8 @@ X Window System rendering using XLib
 <para>
 The XLib surface is used to render cairo graphics to X Window System
 windows and pixmaps using the XLib library.
-
+</para>
+<para>
 Note that the XLib surface automatically takes advantage of X render extension
 if it is available.
 </para>