@@ -575,7 +575,9 @@ Generating a Random Numeric Value: the ''random()'' function</h3>
575575 specifies a step value:
576576 the values the function can resolve to
577577 are further restricted to the form <code> min + (N * step)</code> ,
578- where N is a non-negative integer.
578+ where N is a non-negative integer
579+ chosen uniformly randomly from the possible values
580+ that result in an in-range value.
579581
580582 <div class=example>
581583 For example, ''random(100px, 300px, by 50px)''
@@ -597,7 +599,6 @@ Generating a Random Numeric Value: the ''random()'' function</h3>
597599 To be safe, you can put the maximum value
598600 <em> slightly above</em> where you expect the final step to land,
599601 like ''random(100px, 201px, by 100px / 3)'' .
600-
601602 </div>
602603
603604 <div class=example>
@@ -611,6 +612,15 @@ Generating a Random Numeric Value: the ''random()'' function</h3>
611612 is restricted to resolving only to integers;
612613 etc.
613614 </div>
615+
616+ Note: The definition of the step <em> does not</em> allow
617+ for naively generating a random value in the range
618+ and then rounding it to the nearest step value,
619+ as that can result in the values not appearing with the same weights.
620+ For example, ''random(100px, 200px, by 50px)''
621+ has to generate the three possible values each with a 1/3 chance;
622+ a naive rounding-based method will instead incorrectly generate ''150px''
623+ twice as often as the boundary values.
614624 </dl>
615625
616626 All of the [=calculation=] arguments can resolve to any <<number>> , <<dimension>> , or <<percentage>> ,
@@ -650,6 +660,10 @@ Argument Ranges</h4>
650660 If C is infinite,
651661 the result is A.
652662
663+ (If C is zero or negative,
664+ the result is A,
665+ but that falls out of the standard definition.)
666+
653667 Note: As usual for [=math functions=] ,
654668 if any argument calculation is NaN,
655669 the result is NaN.
0 commit comments