diff --git a/contrib/mitsub/mitsub.c b/contrib/mitsub/mitsub.c
index 436e006d..e21546d1 100644
--- a/contrib/mitsub/mitsub.c
+++ b/contrib/mitsub/mitsub.c
@@ -141,7 +141,7 @@ main( int argc, char *argv[] )
 		double factor = IM_MAX( x_factor, y_factor );
 		IMAGE *sh = im_open( "shrink", "t" );
 
-		im_diag( "mitsub", "%s", _( "shrinking by %g ..." ), factor );
+		im_diag( "mitsub", _( "shrinking by %g ..." ), factor );
 		if( !sh || im_shrink( vips, sh, factor, factor ) )
 			error_exit( "mitsub: shrink failed" );
 
diff --git a/doc/reference/libvips-docs.sgml.in b/doc/reference/libvips-docs.sgml.in
index 6e5f5190..9906a391 100644
--- a/doc/reference/libvips-docs.sgml.in
+++ b/doc/reference/libvips-docs.sgml.in
@@ -24,7 +24,6 @@
     <xi:include href="xml/colour.xml"/>
     <xi:include href="xml/region.xml"/>
     <xi:include href="xml/arithmetic.xml"/>
-    <xi:include href="xml/deprecated.xml"/>
     <xi:include href="xml/meta.xml"/>
     <xi:include href="xml/image.xml"/>
     <xi:include href="xml/transform.xml"/>
diff --git a/libvips/boolean/bool_dispatch.c b/libvips/boolean/bool_dispatch.c
index 45ec1274..9d29387d 100644
--- a/libvips/boolean/bool_dispatch.c
+++ b/libvips/boolean/bool_dispatch.c
@@ -52,12 +52,12 @@
  * These operations perform boolean operations, such as bitwise-and, on
  * every pixel in an image or pair of images. 
  * All will work with 
- * images of any type or any mixture of types, of any size and of any number 
+ * images of any type or any mixture of types of any size and of any number 
  * of bands.
  *
  * For binary operations, if the number of bands differs, one of the images 
  * must have one band. In this case, an n-band image is formed from the 
- * one-band image by joining n copies of the one-band image together, and then
+ * one-band image by joining n copies of the one-band image together and then
  * the two n-band images are operated upon.
  *
  * In the same way, for operations that take an array constant, such as 
@@ -67,7 +67,7 @@
  * The output type is the same as the input type for integer types. Float and
  * complex types are cast to signed int.
  *
- * For binary operations, the images must match in size.
+ * For binary operations on pairs of images, the images must match in size.
  *
  * You might think im_andimage() would be called "im_and", but that causes
  * problems when we try and make a C++ binding and drop the "im_" prefix.
diff --git a/libvips/boolean/boolean.c b/libvips/boolean/boolean.c
index 06337b75..a826d554 100644
--- a/libvips/boolean/boolean.c
+++ b/libvips/boolean/boolean.c
@@ -482,9 +482,9 @@ im_shiftleft_vec( IMAGE *in, IMAGE *out, int n, double *c )
  * im_shiftleft:
  * @in: input #IMAGE 
  * @out: output #IMAGE
- * @c: constant
+ * @n: constant
  *
- * This operation calculates @in1 << @c (left-shift by @c bits)
+ * This operation calculates @in1 << @n (left-shift by @n bits)
  * and writes the result to @out. 
  *
  * See also: im_andimage(), im_orimageconst().
@@ -532,9 +532,9 @@ im_shiftright_vec( IMAGE *in, IMAGE *out, int n, double *c )
  * im_shiftright:
  * @in: input #IMAGE 
  * @out: output #IMAGE
- * @c: constant
+ * @n: constant
  *
- * This operation calculates @in1 >> @c (right-shift by @c bits)
+ * This operation calculates @in1 >> @n (right-shift by @n bits)
  * and writes the result to @out. 
  *
  * See also: im_andimage(), im_orimageconst().
diff --git a/libvips/include/vips/boolean.h b/libvips/include/vips/boolean.h
index 66838c33..e90a5d6b 100644
--- a/libvips/include/vips/boolean.h
+++ b/libvips/include/vips/boolean.h
@@ -37,19 +37,23 @@
 extern "C" {
 #endif /*__cplusplus*/
 
-int im_andimage( IMAGE *, IMAGE *, IMAGE * );
-int im_andimage_vec( IMAGE *, IMAGE *, int, double * );
-int im_andimageconst( IMAGE *, IMAGE *, double );
-int im_orimage( IMAGE *, IMAGE *, IMAGE * );
-int im_orimage_vec( IMAGE *, IMAGE *, int, double * );
-int im_orimageconst( IMAGE *, IMAGE *, double );
-int im_eorimage( IMAGE *, IMAGE *, IMAGE * );
-int im_eorimage_vec( IMAGE *, IMAGE *, int, double * );
-int im_eorimageconst( IMAGE *, IMAGE *, double );
+int im_andimage( IMAGE *in1, IMAGE *in2, IMAGE *out );
+int im_orimage( IMAGE *in1, IMAGE *in2, IMAGE *out );
+int im_eorimage( IMAGE *in1, IMAGE *in2, IMAGE *out );
+
+int im_andimage_vec( IMAGE *in, IMAGE *out, int n, double *c );
+int im_andimageconst( IMAGE *in, IMAGE *out, double c );
+
+int im_orimage_vec( IMAGE *in, IMAGE *out, int n, double *c );
+int im_orimageconst( IMAGE *in, IMAGE *out, double c );
+
+int im_eorimage_vec( IMAGE *in, IMAGE *out, int n, double *c );
+int im_eorimageconst( IMAGE *in, IMAGE *out, double c );
+
 int im_shiftleft_vec( IMAGE *in, IMAGE *out, int n, double *c );
-int im_shiftleft( IMAGE *, IMAGE *, int );
+int im_shiftleft( IMAGE *in, IMAGE *out, int n );
 int im_shiftright_vec( IMAGE *in, IMAGE *out, int n, double *c );
-int im_shiftright( IMAGE *, IMAGE *, int );
+int im_shiftright( IMAGE *in, IMAGE *out, int n );
 
 #ifdef __cplusplus
 }