diff --git a/libvips/histograms_lut/im_histplot.c b/libvips/histograms_lut/im_histplot.c
index d30c07e1..cb9c108c 100644
--- a/libvips/histograms_lut/im_histplot.c
+++ b/libvips/histograms_lut/im_histplot.c
@@ -1,22 +1,4 @@
-/* @(#) im_histplot: plot a 1xany or anyx1 image file as a max x any or 
- * @(#) any x max graph using these rules:
- * @(#)
- * @(#) - unsigned char
- * @(#) 	always output 256 
- * @(#) - other unsigned integer types
- * @(#) 	output 0 - max
- * @(#) - signed int types
- * @(#) 	min moved to 0, max moved to max + min.
- * @(#) - float types
- * @(#) 	min moved to 0, max moved to any (square output)
- * @(#)
- * @(#) usage:
- * @(#)
- * @(#)  	int 
- * @(#)  	im_histplot( hist, histplot )
- * @(#)  	IMAGE *hist, *histplot;
- * @(#) 
- * @(#) Returns non-zero on error
+/* draw a histogram
  *
  * Copyright: 1990, N. Dessipris.
  *
diff --git a/libvips/histograms_lut/im_histspec.c b/libvips/histograms_lut/im_histspec.c
index d87a2b87..d8b98835 100644
--- a/libvips/histograms_lut/im_histspec.c
+++ b/libvips/histograms_lut/im_histspec.c
@@ -1,22 +1,17 @@
-/* @(#) Creates a lut for transforming imagein (with histin) according to 
- * @(#) the pdf of imageref (with histref).  The lut should have been set
- * @(#) by a call to im_setbuf() or im_openout(). histin and histref
- * @(#) should have been set by a call to im_mmapin() or they are buffer images
- * @(#)
- * @(#) Usage: int im_histspec(in, ref, out)
- * @(#) IMAGE *histin, *histref, *out;
- * @(#)
- * @(#) Returns 0 on success and -1 on error
- * @(#)
+/* match PDFs
  *
  * Copyright: 1991, N. Dessipris.
  *
  * Author: Nicos Dessipris
  * Written on: 19/07/1990
  * Modified on: 26/03/1991
+ *
  * 1/3/01 JC
- * - bleurg! rewritten, now does 16 bits as well, bugs removed, faster,
- *   smaller
+ * 	- bleurg! rewritten, now does 16 bits as well, bugs removed, faster,
+ *     	  smaller
+ * 24/3/10
+ * 	- gtkdoc
+ * 	- small cleanups
  */
 
 /*
@@ -86,22 +81,16 @@ match( IMAGE *in, IMAGE *ref, IMAGE *out )
 
 	int i, j;
 
-	if( im_iocheck( in, out ) || im_iocheck( ref, out ) )
-		return( -1 );
-	if( in->Coding != IM_CODING_NONE || ref->Coding != IM_CODING_NONE ) {
-                im_error( "im_histspec", "%s", _( "not uncoded" ) );
+	if( im_iocheck( in, out ) || 
+		im_iocheck( ref, out ) ||
+		im_check_uncoded( "im_histspec", in ) ||
+		im_check_format( "im_histspec", in, IM_BANDFMT_UINT ) ||
+		im_check_coding_same( "im_histspec", in, ref ) ||
+		im_check_format_same( "im_histspec", in, ref ) ||
+		im_check_bands_same( "im_histspec", in, ref ) ||
+		im_check_hist( "im_histspec", in ) ||
+		im_check_hist( "im_histspec", ref ) )
                 return( -1 );
-	}
-	if( in->BandFmt != IM_BANDFMT_UINT || 
-		ref->BandFmt != IM_BANDFMT_UINT ) {
-                im_error( "im_histspec", "%s", _( "bad band format" ) );
-                return( -1 );
-	}
-	if( in->Bands != ref->Bands ) {
-                im_error( "im_histspec", "%s", 
-			_( "input histograms differ in number of bands" ) );
-                return( -1 );
-	}
 
 	/* How big?
 	 */
@@ -109,13 +98,9 @@ match( IMAGE *in, IMAGE *ref, IMAGE *out )
 		px = 256;
 	else if( inpx <= 65536 && refpx <= 65536 )
 		px = 65536;
-	else {
-		im_error( "im_histspec", "%s", _( "luts too large" ) );
-		return( -1 );
-	}
 	max = px * bands;
 
-	/* Unpack to equal sized buffers.
+	/* Unpack to equal-sized buffers.
 	 */
 	inbuf = IM_ARRAY( out, max, unsigned int );
 	refbuf = IM_ARRAY( out, max, unsigned int );
@@ -165,13 +150,29 @@ match( IMAGE *in, IMAGE *ref, IMAGE *out )
 	out->Xsize = px;
 	out->Ysize = 1;
 	out->Type = IM_TYPE_HISTOGRAM;
+        if( im_setupout( out ) )
+		return( -1 );
 
-        if( im_setupout( out ) || im_writeline( 0, out, (PEL *) outbuf ) )
+        if( im_writeline( 0, out, (PEL *) outbuf ) )
 		return( -1 );
 
 	return( 0 );
 }
 
+/**
+ * im_histspec:
+ * @in: input image
+ * @ref: reference histogram 
+ * @out: output image
+ *
+ * Creates a lut which, when applied to the image from which histogram @in was
+ * formed, will produce an image whose PDF matches that of the image from 
+ * which @ref was formed.
+ *
+ * See also: im_histgr(), im_maplut().
+ *
+ * Returns: 0 on success, -1 on error
+ */
 int 
 im_histspec( IMAGE *in, IMAGE *ref, IMAGE *out )
 {
@@ -179,18 +180,14 @@ im_histspec( IMAGE *in, IMAGE *ref, IMAGE *out )
 	int px;
 	int fmt;
 
-	if( im_open_local_array( out, t, 5, "im_histspec", "p" ) )
+	if( im_check_uint( "im_histspec", in ) ||
+		im_check_uint( "im_histspec", ref ) )
 		return( -1 );
-	if( !vips_bandfmt_isuint( in->BandFmt ) || 
-		!vips_bandfmt_isuint( ref->BandFmt ) ) {
-                im_error( "im_histspec", "%s", 
-			_( "input luts are not some unsigned integer type" ) );
-                return( -1 );
-	}
 
 	/* Match hists.
 	 */
-	if( im_histeq( in, t[0] ) || 
+	if( im_open_local_array( out, t, 5, "im_histspec", "p" ) ||
+		im_histeq( in, t[0] ) || 
 		im_clip2fmt( t[0], t[1], IM_BANDFMT_UINT ) ||
 		im_histeq( ref, t[2] ) || 
 		im_clip2fmt( t[2], t[3], IM_BANDFMT_UINT ) ||