more doc polishing

doc/reference/using-C.xml

@@ -2,6 +2,7 @@
 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
                "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
 ]>
+<!-- vim: set ts=2 sw=2 expandtab: --> 
 <refentry id="using-from-c">
   <refmeta>
     <refentrytitle>VIPS from C</refentrytitle>
@@ -15,7 +16,7 @@
   </refnamediv>
 
   <refsect1 id="using-C">
-    <title>Using VIPS from C</title>
+    <title>Introduction</title>
     <para>
       VIPS comes with a convenient, high-level C API. You should read the API 
       docs for full details, but this section will try to give a brief 
@@ -24,15 +25,15 @@
     </para>
 
     <para>
-      When your program starts, use <function>VIPS_INIT()</function> to set up 
-      the VIPS library. You should pass it the name of your program, usually 
-      <literal>argv[0]</literal>. Use <function>vips_shutdown()</function> 
-      when you exit. 
+      When your program starts, use <code>VIPS_INIT()</code>
+      to start up the VIPS library. You should pass it the name
+      of your program, usually <code>argv[0]</code>. Use
+      <code>vips_shutdown()</code> when you exit.
     </para>
 
     <para>
       You can add the VIPS flags to your %GObject command-line processing
-      with <function>vips_get_option_group()</function>, see below.
+      with <code>vips_get_option_group()</code>, see below.
     </para>
 
     <para>

doc/reference/using-cpp.xml

@@ -2,6 +2,7 @@
 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
                "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
 ]>
+<!-- vim: set ts=2 sw=2 expandtab: --> 
 <refentry id="using-from-cpp">
   <refmeta>
     <refentrytitle>VIPS from C++</refentrytitle>
@@ -15,16 +16,14 @@
   </refnamediv>
 
   <refsect1 id="using-cpp">
-    <title>Using VIPS from C++</title>
+    <title>Introduction</title>
     <para>
       VIPS comes with a convenient C++ API. It is a very thin wrapper over the 
-      C API and provides automatic reference counting, exceptions, operator 
+      C API and adds automatic reference counting, exceptions, operator 
       overloads, and automatic constant expansion. You can drop down to the C 
       API at any point, so all the C API docs also work for C++. 
     </para>
 
-<example>
-<title>VIPS from C++ example</title>
 <programlisting language="C++">
 /* compile with:
  *      g++ -g -Wall try.cc `pkg-config vips-cc --cflags --libs`
@@ -84,11 +83,11 @@ main( int argc, char **argv )
   return( 0 );
 }
 </programlisting>
-</example>
 
     <para>
       Everything before <code>VImage in = VImage::..</code> is exactly as the C 
-      API. 
+      API. This boilerplate gives the example a set of standard command-line 
+      flags. 
     </para>
 
     <para>
@@ -172,13 +171,13 @@ main( int argc, char **argv )
       vips_add():
 
 <programlisting language="C++">
-  int vips_add( VipsImage *left, VipsImage *right, VipsImage **out, ... );
+int vips_add( VipsImage *left, VipsImage *right, VipsImage **out, ... );
 </programlisting>
 
       appears in C++ as:
 
 <programlisting language="C++">
-  VImage VImage::add( VImage right, VOption *options = 0 );
+VImage VImage::add( VImage right, VOption *options = 0 );
 </programlisting>
     </para>
 
@@ -193,7 +192,7 @@ main( int argc, char **argv )
       Next we reload the image. The VImage::avg() will have scanned the image 
       and reached the end of the file, we need to scan again for the next 
       operation. If we'd selected random access mode (the default) in the 
-      original VImage::new_from_file(), we would not need to load again.
+      original VImage::new_from_file(), we would not need to reload.
     </para>
 
     <para>
@@ -227,14 +226,14 @@ main( int argc, char **argv )
       bandwise join of two RGB images would be a six-band image) with:
 
 <programlisting language="C++">
-  VImage rgb = ...; 
-  VImage six_band = rgb.bandjoin( rgb );
+VImage rgb = ...; 
+VImage six_band = rgb.bandjoin( rgb );
 </programlisting>
 
       You can also bandjoin a constant, for example: 
 
 <programlisting language="C++">
-  VImage rgb_with_alpha = rgb.bandjoin( 255 );
+VImage rgb_with_alpha = rgb.bandjoin( 255 );
 </programlisting>
 
       Will add an extra band to an image, with every element in the new band 
@@ -243,7 +242,7 @@ main( int argc, char **argv )
       converted. For example:
 
 <programlisting language="C++">
-  VImage a = (a &lt; 128).ifthenelse( 128, a ); 
+VImage a = (a &lt; 128).ifthenelse( 128, a ); 
 </programlisting>
 
       Will set every band element of <code>a</code> less than 128 to 128. 
@@ -264,20 +263,20 @@ main( int argc, char **argv )
       named after the enum. For example, the C function:
 
 <programlisting language="C++">
-  int vips_math( VipsImage *in, VipsImage **out, VipsOperationMath math, ... );
+int vips_math( VipsImage *in, VipsImage **out, VipsOperationMath math, ... );
 </programlisting>
 
       where #VipsOperationMath has the member #VIPS_OPERATION_MATH_SIN, has a 
       C convenience function vips_sin():
 
 <programlisting language="C++">
-  int vips_sin( VipsImage *in, VipsImage **out, ... );
+int vips_sin( VipsImage *in, VipsImage **out, ... );
 </programlisting>
 
       and a C++ member function VImage::sin():
 
 <programlisting language="C++">
-  VImage VImage::sin( VOption *options = 0 );
+VImage VImage::sin( VOption *options = 0 );
 </programlisting>
 
     </para>
@@ -287,10 +286,10 @@ main( int argc, char **argv )
     <title>Extending the C++ interface</title>
 
     <para>
-      The C++ interface comes in two parts. First, VImage8.h defines a simple 
-      layer over #GObject for automatic reference counting, then a generic way 
-      to call any vips8 operation with VImage::call(), then a few convenience 
-      functions, then a set of overloads.
+      The C++ interface comes in two parts. First, <code>VImage8.h</code>
+      defines a simple layer over #GObject for automatic reference counting,
+      then a generic way to call any vips8 operation with VImage::call(),
+      then a few convenience functions, then a set of overloads.
     </para>
 
     <para>

doc/reference/using-python.xml

@@ -94,7 +94,8 @@ im = im.similarity(scale = 0.9, interpolate = Vips.Interpolate.new("bicubic"))
     <para>
       Finally, <code>.write_to_file()</code> sends the image back to the 
       filesystem. There's also <code>.write_to_buffer()</code> to make a 
-      string containing the formatted image. 
+      string containing the formatted image, and <code>.write()</code> to 
+      write to another image. 
     </para>
   </refsect1>