improve the using-C docs

add some stuff on giving options to operations

see https://github.com/jcupitt/libvips/issues/373

ChangeLog

@@ -10,6 +10,7 @@
 - fix double free on attach ICC profile from file in tiff write [erdmann]
 - add VIPS_FLOOR()/VIPS_CEIL(), much faster [Lovell Fuller]
 - use g_assert_not_reached();
+- better vips-from-C docs
 
 1/1/16 started 8.2.1
 - add a compat stub [Benjamin Gilbert]

doc/gtk-doc.make

@@ -25,6 +25,7 @@ TARGET_DIR=$(HTML_DIR)/$(DOC_MODULE)
 
 SETUP_FILES = \
 	$(content_files)		\
+	$(expand_content_files)		\
 	$(DOC_MAIN_SGML_FILE)		\
 	$(DOC_MODULE)-sections.txt	\
 	$(DOC_MODULE)-overrides.txt
@@ -86,7 +87,7 @@ GTK_DOC_V_SETUP_0=@echo "  DOC   Preparing build";
 
 setup-build.stamp:
 	-$(GTK_DOC_V_SETUP)if test "$(abs_srcdir)" != "$(abs_builddir)" ; then \
-	    files=`echo $(SETUP_FILES) $(expand_content_files) $(DOC_MODULE).types`; \
+	    files=`echo $(SETUP_FILES) $(DOC_MODULE).types`; \
 	    if test "x$$files" != "x" ; then \
 	        for file in $$files ; do \
 	            destdir=`dirname $(abs_builddir)/$$file`; \
@@ -118,7 +119,7 @@ scan-build.stamp: setup-build.stamp $(HFILE_GLOB) $(CFILE_GLOB)
 	$(GTK_DOC_V_INTROSPECT)if grep -l '^..*$$' $(DOC_MODULE).types > /dev/null 2>&1 ; then \
 	    scanobj_options=""; \
 	    gtkdoc-scangobj 2>&1 --help | grep  >/dev/null "\-\-verbose"; \
-	    if test "$(?)" = "0"; then \
+	    if test "$$?" = "0"; then \
 	        if test "x$(V)" = "x1"; then \
 	            scanobj_options="--verbose"; \
 	        fi; \
@@ -162,17 +163,17 @@ GTK_DOC_V_XREF=$(GTK_DOC_V_XREF_$(V))
 GTK_DOC_V_XREF_=$(GTK_DOC_V_XREF_$(AM_DEFAULT_VERBOSITY))
 GTK_DOC_V_XREF_0=@echo "  DOC   Fixing cross-references";
 
-html-build.stamp: sgml.stamp $(DOC_MAIN_SGML_FILE) $(content_files)
+html-build.stamp: sgml.stamp $(DOC_MAIN_SGML_FILE) $(content_files) $(expand_content_files)
 	$(GTK_DOC_V_HTML)rm -rf html && mkdir html && \
 	mkhtml_options=""; \
 	gtkdoc-mkhtml 2>&1 --help | grep  >/dev/null "\-\-verbose"; \
-	if test "$(?)" = "0"; then \
+	if test "$$?" = "0"; then \
 	  if test "x$(V)" = "x1"; then \
 	    mkhtml_options="$$mkhtml_options --verbose"; \
 	  fi; \
 	fi; \
 	gtkdoc-mkhtml 2>&1 --help | grep  >/dev/null "\-\-path"; \
-	if test "$(?)" = "0"; then \
+	if test "$$?" = "0"; then \
 	  mkhtml_options="$$mkhtml_options --path=\"$(abs_srcdir)\""; \
 	fi; \
 	cd html && gtkdoc-mkhtml $$mkhtml_options $(MKHTML_OPTIONS) $(DOC_MODULE) ../$(DOC_MAIN_SGML_FILE)
@@ -194,11 +195,11 @@ GTK_DOC_V_PDF=$(GTK_DOC_V_PDF_$(V))
 GTK_DOC_V_PDF_=$(GTK_DOC_V_PDF_$(AM_DEFAULT_VERBOSITY))
 GTK_DOC_V_PDF_0=@echo "  DOC   Building PDF";
 
-pdf-build.stamp: sgml.stamp $(DOC_MAIN_SGML_FILE) $(content_files)
+pdf-build.stamp: sgml.stamp $(DOC_MAIN_SGML_FILE) $(content_files) $(expand_content_files)
 	$(GTK_DOC_V_PDF)rm -f $(DOC_MODULE).pdf && \
 	mkpdf_options=""; \
 	gtkdoc-mkpdf 2>&1 --help | grep  >/dev/null "\-\-verbose"; \
-	if test "$(?)" = "0"; then \
+	if test "$$?" = "0"; then \
 	  if test "x$(V)" = "x1"; then \
 	    mkpdf_options="$$mkpdf_options --verbose"; \
 	  fi; \
@@ -223,12 +224,15 @@ clean-local:
 	@if echo $(SCAN_OPTIONS) | grep -q "\-\-rebuild-types" ; then \
 	  rm -f $(DOC_MODULE).types; \
 	fi
+	@if echo $(SCAN_OPTIONS) | grep -q "\-\-rebuild-sections" ; then \
+	  rm -f $(DOC_MODULE)-sections.txt; \
+	fi
 
 distclean-local:
 	@rm -rf xml html $(REPORT_FILES) $(DOC_MODULE).pdf \
 	    $(DOC_MODULE)-decl-list.txt $(DOC_MODULE)-decl.txt
 	@if test "$(abs_srcdir)" != "$(abs_builddir)" ; then \
-	    rm -f $(SETUP_FILES) $(expand_content_files) $(DOC_MODULE).types; \
+	    rm -f $(SETUP_FILES) $(DOC_MODULE).types; \
 	fi
 
 maintainer-clean-local:

doc/using-C.xml

@@ -20,8 +20,7 @@
     <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 
+      overview. 
-      summary of an operation's parameters.
     </para>
   </refsect3>
 
@@ -38,7 +37,7 @@
 
     <para>
       You can add the VIPS flags to your %GObject command-line processing
-      with vips_add_option_entries(), see below.
+      with vips_add_option_entries().
     </para>
   </refsect3>
 
@@ -85,10 +84,78 @@
   <refsect3 id="using-C-operations">
     <title>VIPS operations</title>
     <para>
-      Use things like vips_invert() to manipulate your images. See 
+      Use things like vips_embed() to manipulate your images. You use it from 
-      #VipsOperation 
+      C like this:
-      for information on
+
-      running operations on images. When you are done, you can write
+<programlisting language="C">
+const char *filename;
+VipsImage *in = vips_image_new_from_file (filename, NULL); 
+const int x = 10;
+const int y = 10;
+const int width = 1000;
+const int height = 1000;
+VipsImage *out;
+
+if (vips_embed (in, &amp;out, x, y, width, height, NULL))
+  error_handling();
+</programlisting>
+
+      Now <code>out</code> will hold a reference to a 1000 by 1000 pixel 
+      image, with <code>in</code> pasted 10 right and 10 down from the top 
+      left-hand corner. The remainder of the image will be black. If 
+      <code>in</code> is too large, it will be clipped at the image edges.
+    </para>
+
+    <para>
+      Operations can take options. You give these as a set of NULL-terminated
+      name-value pairs at the end of the call. For example, you can write:
+
+<programlisting language="C">
+if (vips_embed (in, &amp;out, x, y, width, height, 
+  "extend", VIPS_EXTEND_COPY,
+  NULL))
+  error_handling();
+</programlisting>
+
+      And now the new edge pixels, which were black, will be filled with a copy
+      of the edge pixels of <code>in</code>. Operation options are listed 
+      at the top of each operation's entry in the docs. Alternatively, 
+      the <command>vips</command> program is handy for getting a 
+      summary of an operation's parameters. For example:
+
+<programlisting language="none">
+$ vips embed
+embed an image in a larger image
+usage:
+   embed in out x y width height
+where:
+   in           - Input image, input VipsImage
+   out          - Output image, output VipsImage
+   x            - Left edge of input in output, input gint
+			                default: 0
+			                min: -1000000000, max: 1000000000
+   y            - Top edge of input in output, input gint
+			                default: 0
+			                min: -1000000000, max: 1000000000
+   width        - Image width in pixels, input gint
+			                default: 1
+			                min: 1, max: 1000000000
+   height       - Image height in pixels, input gint
+			                default: 1
+			                min: 1, max: 1000000000
+optional arguments:
+   extend       - How to generate the extra pixels, input VipsExtend
+			                default: black
+			                allowed: black, copy, repeat, mirror, white, background
+   background   - Colour for background pixels, input VipsArrayDouble
+operation flags: sequential-unbuffered 
+</programlisting>
+
+      See #VipsOperation for more information on running operations on images. 
+    </para>
+
+    <para>
+      When you are done, you can write
       the final image to a disc file, to a formatted memory buffer, or to
       C-style memory array. See vips_image_write_to_file() and friends.
     </para>
@@ -131,9 +198,6 @@
 int
 main( int argc, char **argv )
 {
-  GOptionContext *context;
-  GOptionGroup *main_group;
-  GError *error = NULL;
   VipsImage *in;
   double mean;
   VipsImage *out;
@@ -141,21 +205,6 @@ main( int argc, char **argv )
   if( VIPS_INIT( argv[0] ) )
     vips_error_exit( NULL ); 
 
-  context = g_option_context_new( "hello infile outfile - VIPS demo" );
-
-  main_group = g_option_group_new( NULL, NULL, NULL, NULL, NULL );
-  g_option_context_set_main_group( context, main_group );
-  vips_add_option_entries( main_group ); 
-
-  if( !g_option_context_parse( context, &amp;argc, &amp;argv, &amp;error ) ) {
-    if( error ) {
-      fprintf( stderr, "%s\n", error-&gt;message );
-      g_error_free( error );
-    }
-
-    vips_error_exit( NULL );
-  }
-
   if( argc != 3 )
     vips_error_exit( "usage: %s infile outfile", argv[0] );