merge man timerate fix clarifying -overhead

doc/timerate.n

@@ -72,10 +72,10 @@ Note that calibration is not thread safe in the current implementation.
 \fB\-overhead \fIdouble\fR
 .
 The \fB\-overhead\fR parameter supplies an estimate (in microseconds) of the
-measurement overhead of each iteration of the tested script. This quantity
-will be subtracted from the measured time prior to reporting results. This can
-be useful for removing the cost of interpreter state reset commands from the
-script being measured.
+measurement overhead of each iteration of the tested script. The passed value
+overrides, for the current invocation of \fBtimerate\fR, the overhead
+estimated by a previous calibration. Overrides may themselves be measured
+using \fBtimerate\fR as illustrated by a later example.
 .TP
 \fB\-direct\fR
 .
@@ -126,7 +126,7 @@ calculate:
 
 \fI# estimate overhead\fR
 set tm 0
-set ovh [lindex [\fBtimerate\fR {
+set ovh [lindex [\fBtimerate -overhead 0\fR {
     incr tm [expr {24*60*60}]
 }] 0]
 
@@ -137,6 +137,14 @@ set tm 0
     incr tm [expr {24*60*60}]; # overhead for this is ignored
 } 5000
 .CE
+.PP
+In this last example, note that the overhead itself is measured using
+\fBtimerate\fR invoked with \fB-overhead 0\fR. This is necessary
+because explicit overheads are assumed to be absolute values,
+and not an increment over the default calibrated overhead. It is
+therefore important that the calibrated overhead is excluded in the
+measurement of the overhead value itself. This is accomplished by
+passing \fB-overhead 0\fR when measuring the overhead.
 .SH "SEE ALSO"
 time(n)
 .SH KEYWORDS