diff --git a/doc/gtk-doc.make b/doc/gtk-doc.make
index e7916563..19ec2648 100644
--- a/doc/gtk-doc.make
+++ b/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`; \
@@ -162,7 +163,7 @@ 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"; \
@@ -194,7 +195,7 @@ 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"; \
@@ -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:
diff --git a/libvips/conversion/embed.c b/libvips/conversion/embed.c
index 36fb5ed4..a2f8640b 100644
--- a/libvips/conversion/embed.c
+++ b/libvips/conversion/embed.c
@@ -634,7 +634,9 @@ vips_embed_init( VipsEmbed *embed )
  * @background: #VipsArrayDouble colour for edge pixels
  *
  * The opposite of vips_extract_area(): embed @in within an image of size 
- * @width by @height at position @x, @y.  @extend
+ * @width by @height at position @x, @y.  
+ *
+ * @extend
  * controls what appears in the new pels, see #VipsExtend. 
  *
  * See also: vips_extract_area(), vips_insert().
diff --git a/libvips/conversion/insert.c b/libvips/conversion/insert.c
index 6f048d28..dc1b120f 100644
--- a/libvips/conversion/insert.c
+++ b/libvips/conversion/insert.c
@@ -527,13 +527,12 @@ vips_insert_init( VipsInsert *insert )
  * @expand: expand output to hold whole of both images
  * @background: colour for new pixels
  *
- * Insert one image into another. @sub is inserted into image @main at
- * position @x, @y relative to the top LH corner of @main. 
+ * Insert @sub into @main at position @x, @y. 
  *
  * Normally @out shows the whole of @main. If @expand is #TRUE then @out is
  * made large enough to hold all of @main and @sub. 
  * Any areas of @out not coming from
- * either @main or @sub are set to @background (default 0).
+ * either @main or @sub are set to @background (default 0). 
  *
  * If @sub overlaps @main,
  * @sub will appear on top of @main.