From 008d6d7a787481ec6fc163e889fc9a99f16f59a0 Mon Sep 17 00:00:00 2001
From: John Cupitt <jcupitt@gmail.com>
Date: Sun, 16 Nov 2014 12:57:27 +0000
Subject: [PATCH] more doc polishing

---
 doc/reference/using-C.xml      | 13 ++++++------
 doc/reference/using-cpp.xml    | 39 +++++++++++++++++-----------------
 doc/reference/using-python.xml |  3 ++-
 3 files changed, 28 insertions(+), 27 deletions(-)

diff --git a/doc/reference/using-C.xml b/doc/reference/using-C.xml
index 391de8d6..a9a067e5 100644
--- a/doc/reference/using-C.xml
+++ b/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>
diff --git a/doc/reference/using-cpp.xml b/doc/reference/using-cpp.xml
index 5400f478..a25ac104 100644
--- a/doc/reference/using-cpp.xml
+++ b/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>
diff --git a/doc/reference/using-python.xml b/doc/reference/using-python.xml
index 0be7eff5..4270fde5 100644
--- a/doc/reference/using-python.xml
+++ b/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>