merge 8.6: man timerate fix [48a7a56dda844782] clarifying -overhead

doc/timerate.n

@@ -78,10 +78,10 @@ implementation.
 .
 The \fB\-overhead\fR parameter supplies an estimate (in microseconds, which may
 be a floating point number) 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.
 .\" OPTION: -direct
 .TP
 \fB\-direct\fR
@@ -134,7 +134,7 @@ it to 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]
 
@@ -145,6 +145,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