Bug #98541 for PDF-API2: bogen() handling edge cases

The code produces odd results for a radius $r that's too small. It takes the arcsine of the ratio of the distance between the points divided by twice the given radius. If $r is too small, this is arcsine of a number greater than 1.0, which isn't defined! So definitely, it needs to be fixed. The minimum $r, which needs to be checked for (and possibly fixed) is one-half the distance between the points, giving a semicircle centered at the midway point between the points. The current code leaves the validation of $r to the user. I think there are two possibilities for this bug. One is that it gives an error message somewhere, possibly disrupting the output, and the second is that it simply silently lengthens the radius $r to one-half the distance between the points, returning a semicircle. Does anyone have a strong opinion one way or the other? How about (in general) error conditions for other calls -- should we silently massage the parameters (where possible) to give minimally acceptable results, and/or give an error message? If an error message is given somewhere (stdout?), should we also "fix up" the call to produce minimally acceptable results (such as the semicircle rather than a funny double arc, in this case)? In this call, a minimum radius places the arc center midway between the two points, and draws a semicircle. As the radius becomes larger than the minimum, it moves off the line between the two points, and the resulting arc approaches a straight line for very large radii. To make an arc longer than the minimum case (i.e., greater than 180 degrees), you need to set one of the arc() flags ($outer) to 1, and flip ($reverse = 1) the arc. Apparently, the resulting arc is normally clockwise from point 1 to point 2, at least given the side of the line the arc center moves to. Note that my original comments said that the minimal case is a straight line between the points -- that is incorrect. It is a semicircle centered on that line.

PDF::API2's normal behavior when passed invalid input is undefined. It'll either blow up (often at a later place than where the input was provided) or accept the invalid input and produce an unusable or unexpected file. I'd be happy to review a patch that causes bogen() to die immediately if passed invalid input. That makes more sense to me than trying to guess what the radius should have been.

We should certainly move towards clearly defining what PDF::API2 does when given invalid input. I can live with an immediate die(). Would it be acceptable to also provide commented-out code to silently "fix" the invalid input and carry on (in this particular case, increase the radius to the minimum)? That way, the user can easily do it that way if they want to. It could be a run-time switch, but that might complicate/slow the code by an unacceptable amount. It would even be possible to have a "hook" for handling invalid inputs: if an invalid input (here, a too-small radius) is seen, call a function. The default behavior for the function would be simply to die, but a user could choose code to do a fixup and return the corrected radius. That way, all this stuff is isolated in a separate routine (same file). For consistency, we would want to do the same for other invalid inputs.