docs/54879: man 1 jot, -r description

[David Brinegar]

>Number:         54879
>Category:       docs
>Synopsis:       man 1 jot, -r description
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    freebsd-doc
>State:          open
>Quarter:        
>Keywords:       
>Date-Required:
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Fri Jul 25 23:30:09 PDT 2003
>Closed-Date:
>Last-Modified:
>Originator:     David Brinegar
>Release:        FreeBSD 4.6-RELEASE i386
>Organization:
>Environment:
Any Freebsd machine.

	
>Description:
	
   Two inaccurate statements and missing information about defaults.



   "Random numbers are obtained through random(3)."

      is no longer true.



   "while 20 random 8-letter strings are produced with
      jot -r -c 160 a z | rs -g 0 8"

      cannot produce the letter z.



   And there is no mention of the default -w %.0f format which creates
   an unexpected distribution due to rounding.

>How-To-Repeat:
	
   man 1 jot

   To see the affect of rounding:

   > jot -r 1000 1 4 | sort -n | uniq -c
    169 1    <= top and bottom are half as likely as the others
    344 2
    319 3
    168 4    <=

   Internally, jot is assigning random floating point values like so:

      [1.0, 1.5) => 1
      [1.5, 2.5] => 2
      (2.5, 3.5) => 3
      [3.5, 4.0) => 4

   which just follows from the way printf rounds "%.0f".

   > jot -w %d -r 1000 1 4 | sort -n | uniq -c
    335 1    <= uniform distribution, but no 4
    338 2
    327 3

   Here internally jot is flooring the same floating point values
   instead of rounding them.

>Fix:

	
   "Random numbers are obtained through arc4random(3)."

   "while 20 random 8-letter strings are produced with
      jot -r -c 160 a { | rs -g 0 8

   Note: { comes after z (see man 7 ascii.)
   Note: jot -r -c 0 a z cannot produce a z character.

   And some hint about the default -w format and how "%.0f" skews the
   distribution would be useful.

>Release-Note:
>Audit-Trail:
>Unformatted: