Thanks for reviving this topic.
It seems to me that the documentation should:
a) steer users to a new mapping function which handles the +/-1 adjustment to the endpoints and considers using rounding.
b) warn that the function is based on hybrid math concepts which eventually break down for smaller ranges. It should probably warn that its 10-bit to 8-bit mapping example is not optimal, and could drive the message home by showing the problem of mapping to a single bit.
c) warn that the function does not continue the regular stair-step pattern when crossing the in_min boundary.
d) clean up official arduino sample code to use proper mapping techniques
The problem with uneven partitioning stems from miscalculation of the slope of the mapping, not so much truncation. The mapping formula can roughly be described as being like y=trunc(mx)+b where the slope m = (out_max - out_min) / (in_max – in_min). Attempts to map 8 points {0,1,2,3,4,5,6,7} onto 4 points {0,1,2,3} using map(value,0,7,0,3) are screwy because the function roughly parallels a line of slope m=3/7 instead of a slope m=4/8. 3/7 is the wrong compression for this mapping regardless of rounding or truncating. By adjusting the out_max & in_max values, the user is adjusting the slope, not the truncation. Extrapolating outside the range may be even more reliant on the correct slope. In this example, the slope 4/8 extrapolates to include the points (8,4), (64,16) as may be expected. Introducing rounding to the formula can offer some smoothness to the partitioning, but would not generally correct for the miscalculated slope. Maybe wrong and miscalculated are strong words--there may be applications where the slope of 3/7 is actually desirable.
Speaking of extrapolating outside of the range, truncation does cause a break in the staircase pattern when crossing the in_min boundary. That tread is nearly twice as wide as the other treads in the pattern. That is, the out_min value is generally represented more than other step values. Rounding instead of truncation might offer a niceness to that situation, so long as it is not done at the expense of even tread width within the range.