start python and cpp docs

TODO

@@ -1,3 +1,4 @@
+- write manual chapters for C++ (and Python?)
 
 - need a thing to test overloads 
 

doc/reference/Makefile.am

@@ -137,6 +137,8 @@ HTML_IMAGES = \
 content_files = \
 	using-command-line.xml \
 	using-C.xml \
+	using-python.xml \
+	using-cpp.xml \
 	extending.xml \
 	binding.xml
 
@@ -146,6 +148,8 @@ content_files = \
 expand_content_files = \
 	using-command-line.xml \
 	using-C.xml \
+	using-python.xml \
+	using-cpp.xml \
 	extending.xml \
 	binding.xml
 

doc/reference/libvips-docs.sgml.in

@@ -31,6 +31,8 @@
 
     <xi:include href="using-command-line.xml"/>
     <xi:include href="using-C.xml"/>
+    <xi:include href="using-python.xml"/>
+    <xi:include href="using-cpp.xml"/>
     <xi:include href="binding.xml"/>
     <xi:include href="extending.xml"/>
   </chapter>

doc/reference/using-C.xml

@@ -32,15 +32,16 @@
 
     <para>
       You can add the VIPS flags to your %GObject command-line processing
-      with vips_get_option_group(), see below.
+      with <function>vips_get_option_group()</function>, see below.
     </para>
 
     <para>
-      The basic data object is the #VipsImage, see <link
-      linkend="VipsImage">VIPS Image</link> for details on the
-      image class. You can create an image from a file on disc or from an
+      The basic data object is the <link
+      linkend="VipsImage">VipsImage</link>.
+      You can create an image from a file on disc or from an
       area of memory, either as a C-style array, or as a formatted object,
-      like JPEG. See vips_image_new_from_file() and friends.  Loading an
+      like JPEG. See <function>vips_image_new_from_file()</function> and 
+      friends.  Loading an
       image is fast. VIPS read just enough of the image to be able to get
       the various properties, such as width in pixels. It delays reading
       any pixels until they are really needed.
@@ -77,7 +78,7 @@
       Use #VipsRegion to read pixels out of images. You can use 
       VIPS_IMAGE_ADDR() as well, but this can need a large amount of 
       memory to work. See <link linkend="extending">extending</link> 
-      for an introduxction to writing your own operations. 
+      for an introduction to writing your own operations. 
     </para>
 
     <para>

doc/reference/using-cpp.xml

@@ -0,0 +1,87 @@
+<?xml version="1.0"?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+               "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
+<refentry id="using-from-cpp">
+  <refmeta>
+    <refentrytitle>VIPS from C++</refentrytitle>
+    <manvolnum>3</manvolnum>
+    <refmiscinfo>VIPS Library</refmiscinfo>
+  </refmeta>
+
+  <refnamediv>
+    <refname>Using VIPS</refname>
+    <refpurpose>How to use the VIPS library from C++</refpurpose>
+  </refnamediv>
+
+  <refsect1 id="using-cpp">
+    <title>Using VIPS from C++</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 
+      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`
+ */
+
+#include &lt;vips/vips8&gt;
+
+using namespace vips;
+
+int
+main( int argc, char **argv )
+{
+  GOptionContext *context;
+  GOptionGroup *main_group;
+  GError *error = NULL;
+
+  if( vips_init( argv[0] ) )
+    vips_error_exit( NULL ); 
+
+  context = g_option_context_new( "" ); 
+
+  main_group = g_option_group_new( NULL, NULL, NULL, NULL, NULL );
+  g_option_context_set_main_group( context, main_group );
+  g_option_context_add_group( context, vips_get_option_group() );
+
+  if( !g_option_context_parse( context, &amp;argc, &amp;argv, &amp;error ) ) {
+    if( error ) {
+      fprintf( stderr, "%s\n", error->message );
+      g_error_free( error );
+    }
+
+    vips_error_exit( NULL );
+  }
+
+  VImage in = VImage::new_from_file( argv[1], 
+    VImage::option()->
+      set( "access", VIPS_ACCESS_SEQUENTIAL_UNBUFFERED ) ); 
+
+  double avg;
+  avg = in.avg(); 
+
+  printf( "avg = %g\n", avg ); 
+
+  VImage out = in.embed( 10, 10, 1000, 1000, 
+    VImage::option()->
+      set( "extend", VIPS_EXTEND_BACKGROUND )->
+      set( "background", 128 ) );
+
+  out.write_to_file( argv[2] );
+
+  vips_shutdown();
+
+  return( 0 );
+}
+</programlisting>
+</example>
+
+  </refsect1>
+
+</refentry>

doc/reference/using-python.xml

@@ -0,0 +1,52 @@
+<?xml version="1.0"?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+               "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
+<refentry id="using-from-python">
+  <refmeta>
+    <refentrytitle>VIPS from Python</refentrytitle>
+    <manvolnum>3</manvolnum>
+    <refmiscinfo>VIPS Library</refmiscinfo>
+  </refmeta>
+
+  <refnamediv>
+    <refname>Using VIPS</refname>
+    <refpurpose>How to use the VIPS library from Python</refpurpose>
+  </refnamediv>
+
+  <refsect1 id="using-python">
+    <title>Using VIPS from Python</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 
+      overview. The <command>vips</command> program is handy for getting a 
+      summary of an operation's parameters.
+    </para>
+
+<example>
+<title>VIPS from Python example</title>
+<programlisting language="Python">
+#!/usr/bin/python
+
+import sys
+
+import logging
+#logging.basicConfig(level = logging.DEBUG)
+
+from gi.repository import Vips
+
+a = Vips.Image.black(100, 100)
+b = a.bandjoin(2)
+
+b.write_to_file("x.v")
+
+txt = Vips.Image.text("left corner", dpi = 300)
+
+c = txt.ifthenelse(2, [0, 255, 0], blend = True)
+
+c.write_to_file("x2.v")
+</programlisting>
+</example>
+
+  </refsect1>
+</refentry>