===================================================================
RCS file: /cvsrepo/anoncvs/cvs/src/usr.bin/jot/jot.1,v
retrieving revision 1.13
retrieving revision 1.14
diff -c -r1.13 -r1.14
*** src/usr.bin/jot/jot.1	2003/12/30 19:41:48	1.13
--- src/usr.bin/jot/jot.1	2004/01/01 07:04:10	1.14
***************
*** 1,4 ****
! .\"	$OpenBSD: jot.1,v 1.13 2003/12/30 19:41:48 otto Exp $
  .\"	$NetBSD: jot.1,v 1.2 1994/11/14 20:27:36 jtc Exp $
  .\"
  .\" Copyright (c) 1993
--- 1,4 ----
! .\"	$OpenBSD: jot.1,v 1.14 2004/01/01 07:04:10 otto Exp $
  .\"	$NetBSD: jot.1,v 1.2 1994/11/14 20:27:36 jtc Exp $
  .\"
  .\" Copyright (c) 1993
***************
*** 146,151 ****
--- 146,265 ----
  derives in part from
  .Xr 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 f ,
+ .Sq e ,
+ .Sq g ,
+ .Sq E ,
+ 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 c ,
+ .Sq d ,
+ .Sq o ,
+ .Sq x ,
+ .Sq u ,
+ .Sq D ,
+ .Sq O ,
+ .Sq X ,
+ .Sq U ,
+ or
+ .Sq i
+ .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
+ For random sequences, the output format also influences the range
+ and distribution of the generated numbers:
+ .Bd -literal -offset indent
+ $ jot -r 100000 1 3 | sort -n | uniq -c
+ 24950 1
+ 50038 2
+ 25012 3
+ .Ed
+ .Pp
+ The values at the beginning and end of the interval
+ are generated less frequently than the other values.
+ There are several ways to solve this problem and generate evenly distributed
+ integers:
+ .Bd -literal -offset indent
+ $ jot -r -p 0 100000 0.5 3.5 | sort -n | uniq -c
+ 33374 1
+ 33363 2
+ 33263 3
+ 
+ $ jot -w %d -r 100000 1 4 | sort -n | uniq -c
+ 33306 1
+ 33473 2
+ 33221 3
+ .Ed
+ .Pp
+ Note that with random sequences, all numbers generated will
+ be smaller than the upper bound.
+ The largest value generated will be a tiny bit smaller than
+ the upper bound.
+ For floating point formats, the value is rounded as described
+ before being printed.
+ For integer formats, the highest value printed will be one less
+ than the requested upper bound, because the generated value will
+ be truncated.
  .Sh EXAMPLES
  Print 21 evenly spaced numbers increasing from \-1 to 1:
  .Pp
***************
*** 159,167 ****
  .Pp
  .Dl $ jot \-w xa%c 26 a
  .Pp
! Generate 20 random 8-letter strings:
  .Pp
! .Dl "$ jot \-r \-c 160 a z | rs \-g 0 8"
  .Pp
  Infinitely many
  .Xr yes 1 's
--- 273,286 ----
  .Pp
  .Dl $ jot \-w xa%c 26 a
  .Pp
! Generate 20 random 8-letter strings
! (note that the character
! .Sq {
! comes after the character
! .Sq z
! in the ASCII character set):
  .Pp
! .Dl "$ jot \-r \-c 160 a { | rs \-g 0 8"
  .Pp
  Infinitely many
  .Xr yes 1 's
***************
*** 174,184 ****
  substitution commands applying to lines 2, 7, 12, etc. is the result of:
  .Pp
  .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 precision and step size:
- .Pp
- .Dl $ jot 20 9 0 \-.475
  .Pp
  Create a file containing exactly 1024 bytes:
  .Pp
--- 293,298 ----