search

PhilterPaper / Perl-PDF-Builder

Extended version of the popular PDF::API2 Perl-based PDF library for creating, reading, and modifying PDF documents
https://www.catskilltech.com/FreeSW/product/PDF%2DBuilder/title/PDF%3A%3ABuilder/freeSW_full
Other
6 stars 7 forks source link

[CTS 32] Unnecessary depth and duplication in directory structure #126

Closed carygravel closed 3 years ago

carygravel commented 3 years ago

lib/PDF/Builder/Basic/PDF duplicates PDF, which is anyway the only thing in the Basic directory.

I suggest that the second PDFdirectory be eliminated.

PhilterPaper commented 3 years ago

What do you mean by "duplicates PDF"? The files under Basic/PDF/ are completely different from the files under lib/PDF/. What do you see it duplicating? Or are you saying that it should just be Basic/ (eliminate the unnecessary "PDF" under it)? This is the original structure inherited from PDF::API2, which in turn inherited it from an earlier predecessor. I suppose the extraneous "PDF" subdirectory level could be removed, but I'm not sure it's worth the effort (lots of code needs to be changed). I agree that it appears to be unnecessary, but at this late date, I'm more concerned that I might break something in some application's code (not that they should be calling low-level routines directly, but sometimes they do that).

Add: If I were to remove the extra "PDF" level, I would have to deprecate the current structure and give two years' warning so that developers could clean up any references to Basic/PDF. Unfortunately, it would be difficult to have a transitional period where both paths would work, unless I duplicated all the stuff in PDF into Basic (can't count on symbolic links on a Windows platform).

carygravel commented 3 years ago

I would say that deprecating the structure is only necessary when it is part of the published API, and that anything "under the hood" is fair game.

PhilterPaper commented 3 years ago

Unfortunately, even though the use of internal ("under the hood") interfaces is discouraged, they are somewhat documented in the POD. Someone could be using some of them as utilities. Therefore, giving plenty of advance warning (via deprecation) would be required.

I suspect that way back when, someone grabbed a bunch of PDF-oriented routines from some "Basic" Perl library. The library directory structure was Basic/PDF, and they didn't bother to clean it up to just Basic. Thus we still have Basic/PDF. I've always been a bit annoyed by that superfluous "PDF", but I'll have to mull over whether it's worth the bother to change it.

Add: one other thing: if I drop PDF, any code expected to run on both PDF::Builder and PDF::API2 (and uses these low-level routines) will have to be updated to work with both directory structures. Unless you can persuade Steve to do the same PDF-drop in PDF::API2 at the same time, that could be a problem. Naturally, I would hope anyone would just choose PDF::Builder and be done with it, but I know that there is code out there intended to work on either (of course you have to change the "use" instruction and anything that specifically mentions the library -- e.g., in "PDF::Table").

PhilterPaper commented 3 years ago

I discussed this with Steve Simms (PDF::API2 owner), and he had thought about doing this earlier (replacing Basic/PDF/ with Core/). What stopped him was not wanting to unnecessarily break the code of any application that was using these routines directly. Since he's not interested in changing PDF::API2, my changing PDF::Builder alone would break compatibility with PDF::API2. Therefore, I think I'll just leave well enough alone and keep the Basic/PDF/ path as it is. It's not a tremendous impact on typing, space, or execution time; certainly not enough to warrant the disruption of changing it.