Fix stuttering sequences and reverse ranges

PR:		123635
Submitted by:	Ulrich Spörlein, uqs at spoerlein dot net

1 files changed, 83 insertions, 3 deletions

diff --git a/usr.bin/jot/jot.1 b/usr.bin/jot/jot.1
index 3e198a34..b70b604 100644
--- a/usr.bin/jot/jot.1
+++ b/usr.bin/jot/jot.1
@@ -32,7 +32,7 @@
 .\"	@(#)jot.1	8.1 (Berkeley) 6/6/93
 .\" $FreeBSD$
 .\"
-.Dd February 19, 2010
+.Dd June 2, 2010
 .Dt JOT 1
 .Os
 .Sh NAME
@@ -167,6 +167,86 @@ The name
 derives in part from
 .Nm iota ,
 a function in APL.
+.Ss Rounding and truncation
+The
+.Nm
+utility uses double precision floating point arithmetic internally.
+Before printing a number, it is converted depending on the output
+format used.
+.Pp
+If no output format is specified or the output format is a
+floating point format
+.Po
+.Sq E ,
+.Sq G ,
+.Sq e ,
+.Sq f ,
+or
+.Sq g
+.Pc ,
+the value is rounded using the
+.Xr printf 3
+function, taking into account the requested precision.
+.Pp
+If the output format is an integer format
+.Po
+.Sq D ,
+.Sq O ,
+.Sq U ,
+.Sq X ,
+.Sq c ,
+.Sq d ,
+.Sq i ,
+.Sq o ,
+.Sq u ,
+or
+.Sq x
+.Pc ,
+the value is converted to an integer value by truncation.
+.Pp
+As an illustration, consider the following command:
+.Bd -literal -offset indent
+$ jot 6 1 10 0.5
+1
+2
+2
+2
+3
+4
+.Ed
+.Pp
+By requesting an explicit precision of 1, the values generated before rounding
+can be seen.
+The .5 values are rounded down if the integer part is even,
+up otherwise.
+.Bd -literal -offset indent
+$ jot -p 1 6 1 10 0.5
+1.0
+1.5
+2.0
+2.5
+3.0
+3.5
+.Ed
+.Pp
+By offsetting the values slightly, the values generated by the following
+command are always rounded down:
+.Bd -literal -offset indent
+$ jot -p 0 6 .9999999999 10 0.5
+1
+1
+2
+2
+3
+3
+.Ed
+.Pp
+Another way of achieving the same result is to force truncation by
+specifying an integer format:
+.Bd -literal -offset indent
+$ jot -w %d 6 1 10 0.5
+.Ed
+.Pp
 .Sh EXIT STATUS
 .Ex -std
 .Sh EXAMPLES
@@ -201,9 +281,9 @@ the result of
 .Dl jot -w %ds/old/new/ 30 2 - 5
 .Pp
 The stuttering sequence 9, 9, 8, 8, 7, etc.\& can be
-produced by suitable choice of step size,
+produced by truncating the output precision and a suitable choice of step size,
 as in
-.Dl jot - 9 0 -.5
+.Dl jot -w %d - 9.5 0 -.5
 .Pp
 and a file containing exactly 1024 bytes is created with
 .Dl jot -b x 512 > block