Subject: General notes on testing Content.pm
Date: Tue, 2 Sep 2014 21:47:40 -0400
To: bug-PDF-API2 [...] rt.cpan.org
From: Phil M Perry
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.
#
Wed Feb 17 18:27:11 2016 steve [...] deefs.net - Correspondence added
There are too many items here for one ticket, so I'm closing it.
If spline is poorly named (I'm not knowledgeable in this area), it can be deprecated and replaced by a better-named function. Please provide documentation and a suggestion for a new name for the existing function.
Input validation is a worthwhile addition, and a massive project. Patches with tests and helpful error messages are welcome.
#
Wed Feb 17 18:27:12 2016 The RT System itself - Status changed from 'new' to 'open'
#
Wed Feb 17 18:27:12 2016 steve [...] deefs.net - Status changed from 'open' to 'rejected'
#
Subject: [rt.cpan.org #98576]
Date: Thu, 18 Feb 2016 16:03:50 -0500
To: bug-PDF-API2 [...] rt.cpan.org
From: Phil M Perry
Would you be willing to cover these items if they're broken up into single item bug reports?
I'm not a mathematician, but I think what the spline() function is doing MAY be called a B-spline (or an approximation spline). If that's the case, it could just be clarified with a note in the POD. It would be nice to get some graphics experts participating in this discussion...
Per discussion on bogen() method (98541), we could decide to simply die() upon any invalid input found, rather than trying to fix it up and soldier on. In some cases, users might find it useful to be able to fix up bad input, so we might want to think about hooks for handling these cases, or at least, provide commented-out code. E.g., for bogen with too small of radius, have code to set the radius to the minimum allowable size.
November 14, 2016, 08:50:05 PM by Phil
Some fixed in 3.001
spline() POD entry discusses the spline type in detail.
A few parameter checks have been added.
The rest of this is major work, and will have to wait for a later release. I would also like to get some feedback from the community on what they'd like to see changed.
November 18, 2016, 10:01:52 PM by Phil
We could add one or more new spline types (cubic, etc. that pass through all points), but I'd like to discuss this with the community before proceeding.
March 28, 2017, 02:26:45 PM by Phil
Regarding unnecessary restriction of data to INTEGER type, I looked around and now I can seem to find any such instances, either in the code or in the POD. Perhaps someone cleaned them up already. I'll keep an eye open, but for now it looks like this item is a dead letter.
Content.pl has been released in examples/, as has ContentText.pl.
The OO applicability, and text vs. graphics overlap, are still open issues. At the very least, they need to be better documented.
deg2rad() still needs to be looked at, to make sure 0 and 360 degree angles are different, if that is the cause of bugs when explicit conversion code was replaced with deg2rad() calls.
April 12, 2017, 08:55:21 AM by Phil
I have split out the discussion on text and graphics objects into its own topic (#59, CTS 7 - text and graphics objects), as it seems to be worth a major topic of its own. Please continue discussion on this subject over there.
April 12, 2017, 12:57:36 PM by Phil
Regarding bullet 1, I have added warnings to code (and POD) that deg2rad() wraps around at 360 degrees to 0. This is why the original concern about closed arcs (circle and ellipse: 0–360 degrees) not being able to use deg2rad(). It is unlikely that other uses of deg2rad() will encounter problems (possibly excepting some color specifications that use a color angle), but the POD update should keep people out of trouble.
Subject: General notes on testing Content.pm Date: Tue, 2 Sep 2014 21:47:40 -0400 To: bug-PDF-API2 [...] rt.cpan.org From: Phil M Perry
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:
# Wed Feb 17 18:27:11 2016 steve [...] deefs.net - Correspondence added
There are too many items here for one ticket, so I'm closing it.
If spline is poorly named (I'm not knowledgeable in this area), it can be deprecated and replaced by a better-named function. Please provide documentation and a suggestion for a new name for the existing function.
Input validation is a worthwhile addition, and a massive project. Patches with tests and helpful error messages are welcome. # Wed Feb 17 18:27:12 2016 The RT System itself - Status changed from 'new' to 'open' # Wed Feb 17 18:27:12 2016 steve [...] deefs.net - Status changed from 'open' to 'rejected' # Subject: [rt.cpan.org #98576] Date: Thu, 18 Feb 2016 16:03:50 -0500 To: bug-PDF-API2 [...] rt.cpan.org From: Phil M Perry
Would you be willing to cover these items if they're broken up into single item bug reports?
I'm not a mathematician, but I think what the spline() function is doing MAY be called a B-spline (or an approximation spline). If that's the case, it could just be clarified with a note in the POD. It would be nice to get some graphics experts participating in this discussion...
Per discussion on bogen() method (98541), we could decide to simply die() upon any invalid input found, rather than trying to fix it up and soldier on. In some cases, users might find it useful to be able to fix up bad input, so we might want to think about hooks for handling these cases, or at least, provide commented-out code. E.g., for bogen with too small of radius, have code to set the radius to the minimum allowable size.
November 14, 2016, 08:50:05 PM by Phil Some fixed in 3.001
The rest of this is major work, and will have to wait for a later release. I would also like to get some feedback from the community on what they'd like to see changed.
November 18, 2016, 10:01:52 PM by Phil
We could add one or more new spline types (cubic, etc. that pass through all points), but I'd like to discuss this with the community before proceeding.
March 28, 2017, 02:26:45 PM by Phil
Regarding unnecessary restriction of data to INTEGER type, I looked around and now I can seem to find any such instances, either in the code or in the POD. Perhaps someone cleaned them up already. I'll keep an eye open, but for now it looks like this item is a dead letter.
Content.pl has been released in examples/, as has ContentText.pl.
The OO applicability, and text vs. graphics overlap, are still open issues. At the very least, they need to be better documented.
deg2rad() still needs to be looked at, to make sure 0 and 360 degree angles are different, if that is the cause of bugs when explicit conversion code was replaced with deg2rad() calls.
April 12, 2017, 08:55:21 AM by Phil
I have split out the discussion on text and graphics objects into its own topic (#59, CTS 7 - text and graphics objects), as it seems to be worth a major topic of its own. Please continue discussion on this subject over there.
April 12, 2017, 12:57:36 PM by Phil
Regarding bullet 1, I have added warnings to code (and POD) that deg2rad() wraps around at 360 degrees to 0. This is why the original concern about closed arcs (circle and ellipse: 0–360 degrees) not being able to use deg2rad(). It is unlikely that other uses of deg2rad() will encounter problems (possibly excepting some color specifications that use a color angle), but the POD update should keep people out of trouble.