| Subject: | General notes on testing Content.pm |
| Date: | Tue, 2 Sep 2014 21:47:40 -0400 |
| To: | bug-PDF-API2 [...] rt.cpan.org |
| From: | <philperry [...] hvc.rr.com> |
PDF::API2 v2.022 Perl 5.16.3 Windows 7 Severity: Normal
While testing, updating, and documenting Content.pm and some related components,
I encountered some issues that should be thought about:
* I initially changed the circle() and ellipse() methods to call deg2rad()
for the 0-to-360 degree sweeps, but they broke. I think we need more
testing for any place that uses deg2rad() and might get angles that are
360 degrees apart. At the least, the documentation for those methods
should warn about this.
* In most graphics packages I've encountered, a "spline" is a curve that
passes THROUGH all the points given. It's not a Bezier cubic curve with
synthesized control points (as far as I can tell, although it IS often
cubic). If what PDF::API2 is doing is not normally considered a spline,
perhaps this particular construct should be renamed.
* The code does very little testing and validation of input parameters. It
would be easy to send an application into outer space by feeding it incorrect
inputs. Of course, the downside is that more robust code runs more slowly.
* In many places in the POD, dimensions (lengths) were specified as INTEGER
points. I believe this is incorrect, and REAL values are just as acceptable.
If this is so, we need to check where REAL inputs for dimensions are coerced
into INTEGERs (unexpected loss of precision).
* It would be nice to find official word on how much graphics and text states
overlap in functionality (and how they affect each other, if at all), and
add this to the POD. save() and restore() are of special interest -- do they
cover everything, or are they separate for graphics and text?
* The OO architecture is somewhat misleading, as it appears that there can be
only one graphics object and one text object. I'm not sure what happens when
you have multiple of each -- at the PDF level, I think they resolve down to
affecting the same global graphic or text state, and different PDF::API2
global settings (e.g., miterlimit settings in two different graphics objects)
could apply at different times. At the least, this needs to be clearly stated
in the POD.
* I have written a Content.pl program that exercises and demonstrates many of the
methods (including those not in content.t), and provided it to the maintainer.
My hope is that eventually it could be the core for a full-fledged PDF
document or book explaining and documenting PDF::API2.