From 240f0f1fd2b9b8dd7476126a8b3f9ec69995a5c8 Mon Sep 17 00:00:00 2001
From: John Cupitt <jcupitt@gmail.com>
Date: Mon, 17 Nov 2014 12:25:46 +0000
Subject: [PATCH] more doc work

---
 TODO                               |  2 +-
 doc/reference/binding.xml          | 43 +++++++++++++++++++++++++++++-
 doc/reference/libvips-docs.sgml.in |  2 +-
 libvips/iofuncs/type.c             |  9 +++++++
 4 files changed, 53 insertions(+), 3 deletions(-)

diff --git a/TODO b/TODO
index 8219509f..8ccedb28 100644
--- a/TODO
+++ b/TODO
@@ -1,4 +1,4 @@
-- can we use markdown for the intro sections?
+- writing binding.xml
 
 - test other cpp arg types
 
diff --git a/doc/reference/binding.xml b/doc/reference/binding.xml
index bcddc786..5f9fe702 100644
--- a/doc/reference/binding.xml
+++ b/doc/reference/binding.xml
@@ -1,4 +1,5 @@
 <?xml version="1.0"?>
+<!-- vim: set ts=2 sw=2 expandtab: --> 
 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
                "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
 ]>
@@ -17,7 +18,47 @@
   <refsect1 id="binding-goi">
     <title>Binding and gobject-introspection</title>
     <para>
-      Write this section once the vips8 Python binding is done. 
+      The C source code 
+      to libvips has been marked up with special comments describing the 
+      interface in a standard way. These comments are read by 
+      gobject-introspection
+      when libvips is compiled and used to generate a 
+      typelib, a description of how to call the library. Many languages have 
+      gobject-introspection packages: all you need to do to call libvips
+      from your favorite language is to start g-o-i, load the libvips typelib,
+      and you should have the whole library available. For example, from 
+      Python it's as simple as:
+
+<programlisting language="Python">
+from gi.repository import Vips
+</programlisting>
+    </para>
+
+    <para>
+      libvips used in this way is likely to be rather bare-bones. For Python,
+      we wrote a set of overrides which layer a more Pythonesque interface
+      on top of the one provided for libvips by pygobject. These overrides
+      are simply a set of Python classes, there's no magic. You are likely
+      to want to do the same for your language.
+    </para>
+
+    <para>
+      A second problem is that the libvips C API makes heavy use of varargs to
+      pass optional parameters to operations. For example, in C you can write:
+
+<programlisting language="C">
+VipsImage *in = vips_image_new_from_file (filename, NULL);
+VipsImage *out; 
+
+vips_embed(in, &amp;out, 10, 10, 100, 100,
+  "extend", VIPS_EXTEND_COPY,
+  NULL);
+</programlisting>
+
+      to call <code>embed</code> with the optional parameter
+      <code>extend</code>. varargs parameter lists are not supported by 
+      gobject-introspection, so you'll need to find some other way to call 
+      <code>embed</code>.
     </para>
 
     <para>
diff --git a/doc/reference/libvips-docs.sgml.in b/doc/reference/libvips-docs.sgml.in
index 1dfbb6f9..df159327 100644
--- a/doc/reference/libvips-docs.sgml.in
+++ b/doc/reference/libvips-docs.sgml.in
@@ -40,7 +40,6 @@
 
   <chapter>
     <title>Core VIPS API</title>
-    <xi:include href="xml/basic.xml"/>
     <xi:include href="xml/vips.xml"/>
     <xi:include href="xml/image.xml"/>
     <xi:include href="xml/header.xml"/>
@@ -54,6 +53,7 @@
     <xi:include href="xml/object.xml"/>
     <xi:include href="xml/threadpool.xml"/>
     <xi:include href="xml/buf.xml"/>
+    <xi:include href="xml/basic.xml"/>
   </chapter>
 
   <chapter>
diff --git a/libvips/iofuncs/type.c b/libvips/iofuncs/type.c
index b92f5f5b..4a2a2032 100644
--- a/libvips/iofuncs/type.c
+++ b/libvips/iofuncs/type.c
@@ -55,6 +55,15 @@
 #include <vips/internal.h>
 #include <vips/debug.h>
 
+/**
+ * SECTION: basic
+ * @short_description: a few typedefs used everywhere
+ * @stability: Stable
+ * @include: vips/vips.h
+ *
+ * A few simple typedefs used by VIPS. 
+ */
+
 /**
  * SECTION: type
  * @short_description: basic types