A list of known incompatibilities with PDF::API2. Most are very minor, as we 
have attempted to maintain as much compatibility with the older product 
(PDF::API2) as possible. This list is believed to be complete, although 
unexpected incompatibilities cannot be ruled out.

Bug fixes to PDF::API2 (in PDF::Builder) are not mentioned if they correct
an error (that produces an error message and/or incorrect output) and do not 
affect the operation or results of otherwise correct code.

==== A VERY IMPORTANT NOTE =================================================

These notes describe ONLY function known to differ from behavior found in
PDF::API2. That is, you may well see (somewhat) different behavior or output 
converting over a program that runs on PDF::API2, to PDF::Builder. It does 
NOT cover new function such as extended splines, HTML and Markdown 
formatting of columns, etc. Be aware that using such new function in 
PDF::Builder may make your code NOT portable to PDF::API2 (i.e., you are now 
locked in to PDF::Builder). The documentation may or may not mention that
this is new functionality exclusive to PDF::Builder, so be sure to test on
PDF::API2 if you have a package or library intended to run on both!

============================================================================

3.028     2025-12-31

   PDF::API2 has a number of optional arguments to various methods that are
     not the preferred name found in PDF::Builder. We will attempt to provide
     the PDF::API2 option names as an alternative. Please report as a GitHub
     bug any optional argument names you find that are valid in PDF::API2 but
     not in PDF::Builder.

   PDF::API2 from time to time changes method names. PDF::Builder has either
     adopted the new names (and kept the old ones as alternatives), or allows
     the new name as an alias (alternative) for a method. Please report as a
     GitHub bug any method names you find that are valid in PDF::API2 but are
     not recognized in PDF::Builder.

   PDF::API also appears to support a number of options with "dashed" names
     (at least, in the "Lite" subsystem, and possibly elsewhere) to the
     exclusion of "undashed" names (e.g., '-afmfile' in the "Lite"
     subsystem). PDF::Builder has changed all option names to undashed
     (unhyphened) forms, but silently accepts legacy dashed versions.

3.027     2025-04-18

   A while back, PDF::API2's Content.pm was modified to return the color just
     set for strokecolor/stroke_color and fillcolor/fill_color (as an RGB list).
     I have chosen to retain these methods returning '$self', so that they may
     be chained if desired, rather than returning the same color you just gave 
     them, which doesn't seem all that useful.

   PDF::API2 formerly (and PDF::Builder still does) define "fit" (destination)
     elements as hash elements (e.g., 'fitb'=> 1) for NamedDestination,
     Outline, selected Annotation entries, and startup preferences; while it 
     now names the destination as a location string (e.g., 'fitb') and an 
     array of data (e.g., [ 1 ]). Staying with the old system permits the 
     continued use an options hash, which PDF::API2 no longer supports.

   PDF::API2::Outline's destination() is NOT the same as PDF::Builder::Outline's
     dest(). They have different argument lists.

3.024     2022-09-12

   PDF::API2 now initializes page display to a fairly tightly zoomed-in
     (approx. 115%) scale, while PDF::Builder continues to initialize to the
     entire page being displayed (zoomed-out at less than 100% scale).

   PDF::API2 added a bar code convenience function "barcode()", which is not
     in PDF::Builder. Something like this might be added in the future.

   PDF::API2 allows a GIF version of 00 to 99, a to z, while PDF::Builder
     permits 00 to 99, a to b. I am not aware of any GIF versions other than
     GIF87a and GIF89a, so what is intended is not clear.

3.022     2021-03-03

   PDF::API2 "exposed" paragraph() and paragraphs() and documented them.
     paragraphs() is implemented in PDF::Builder as an alias for section().

     The -spillover option has been removed in PDF::API2 (behavior is the
     PDF::Builder default of "0", which is to prevent a word overflowing). 
     PDF::Builder's paragraph() still has the $continue parameter.

     text_fill_justified() in PDF::API2 adds -align-last option to 
     left/right/center/justify the last line, similar to PDF::Builder's 
     -last_align option l/r/c (PDF::Builder accepts the full names, but permits 
     shortening to the first letter). Unlike PDF::API2, PDF::Builder does not 
     support a justified last line.

3.017     2019-12-31

   See INFO/DEPRECATED for a list of deprecated methods and other items that
     have been removed from PDF::Builder (or will be, at some future date). 
     Everything to be removed gets at least TWO years' notice in that file. If 
     you are still using deprecated methods, you may experience errors in your 
     code (even if they still work in PDF::API2), and need to change some 
     calls. The fixes should be minor. 

     There are a large number of deprecated items removed in this release, 
     because many have been deprecated since PDF::API2's days.  A quick 
     summary: meterlimit(), hspace(), linedash() -full and -clear options, 
     new_api(), nonstandard paper sizes, encode_3of9_string_w_chk(), 
     encode_3of9_w_chk(), encode_3of9_ext(), encode_3of9_ext_w_chk(), imask(), 
     bpc(), openScalar(), importpage(), pdfile().

3.016     2019-08-03

   RT #130039 PDF::API2 returns $self on 'set' operation, while PDF::Builder
     always returns the current (possibly just-set) corners of the box. This
     permits your using a named page size, while getting back the actual 
     page bounds without having to make a separate query (get) call.

   RT #33497 and RT #117031 fixed differently in PDF::API2 2.034 (June 2019)
     than in PDF::Builder 3.013 (December 2018). In some cases with UTF-8 
     character data, PDF::API2 will now display as (text display) rather than
     in <16 bit hex Unicode values> still shown by PDF::Builder. This may lead 
     to differences in PDFs produced by the two products, but should be 
     invisible to the end user.

   lib/PDF/Builder/Basic/PDF/Pages.pm old code for the add_font() method
     documented the call as $p->add_font($pdf, $font), but implemented the code
     as $p->add_font($font, $pdf). Older user code may have swapped the order
     of arguments on an ad-hoc basis, to get it to work. The new code uses
     the same order as the documentation ($pdf, $font), which might require
     code to be swapped back. In PDF::API2 2.034, a note in the code mentions 
     the order difference, but the code was not changed.

3.013     2018-12-27

   lib/PDF/Builder/Basic/PDF/Utils.pm Instead of constantly explicitly 
     checking for UTF-8 strings, and calling PDFUtf() instead of PDFStr() as
     appropriate in many routines, PDFString() has been added to Utils to 
     accept a string and call PDFUtf() or PDFStr() internally, according to 
     the passed "usage" code. This may result in slightly different behavior 
     of PDF::Builder, compared to PDF::API2, as the code was implemented in 
     different ways in different routines.

3.008     2017-11-26

   lib/PDF/Builder.pm [ref RT #118047] now uses the Graphics::TIFF package
     by default for TIFF functionality. See the POD for image_tiff() for
     details, including forcing the use of the old (buggy) code. The new code
     does not permit filehandles to be passed to image_tiff() (use the old
     code via -nouseGT => 1 option).

3.003     2017-05-01

   lib/PDF/Builder/Resource/CIDFont/TrueType.pm
   lib/PDF/Builder/Resource/Font/BdFont.pm
   lib/PDF/Builder/Resource/Font/CoreFont.pm
   lib/PDF/Builder/Resource/Font/Postscript.pm [ref RT #105579 and #113084 (were
     open)] remove ~time() from font resource names. It appears to be 
     unnecessary, and made PDFs non-deterministic (two runs with the same input 
     had different output), making output comparisons difficult for developers.
     Commented out lines containing ~time(), so they can be restored easily.
     **Please report any problems which appear to be resource name collisions**
     This is a change that MAY produce incompatibilities, so heads up!

   lib/PDF/Builder/Content.pm  split out methods text_center(), text_right(), 
       text_justified(), text_fill_left(), text_fill_center(), 
       text_fill_right(), text_fill_justified(), paragraph(), section(), and 
       textlabel() into lib/PDF/Builder/Content/Text.pm.
       lib/PDF/Builder/Resource/XObject/Form/Hybrid.pm needed to add 
       Content::Text to the "use base" list, and it is possible that other
       programs may need to do so. In many cases $grfxobj->textlabel() had to
       be changed to $textobj->textlabel(), and it is possible that other
       calls to text methods may be similarly affected.

   lib/PDF/Builder/Content/Text.pm  [ref RT #98546 (was open)] text 
     justification will now attempt to use wordspace() and charspace() to fit a 
     line to its alloted space, rather than simply scaling it with hscale(). 
     This should result in much nicer looking output, though it will not be 
     identical to PDF::API2's output.

   lib/PDF/Builder/Content.pm  [ref CTS 7] $text->save() and restore() are no
     longer no-ops, if you had them in your code. They issue the same q and Q
     commands as a graphics save() and restore().
   *** Removed in release 3.26. save/restore are only for graphics context
   *** and should not be used in text context (will see a one-time warning,
   *** and the calls are now no-ops)

   lib/PDF/Builder.pm
   lib/PDF/Builder/Content.pm
   lib/PDF/Builder/Resource/ExtGState.pm
   lib/PDF/Builder/Resource/XObject/Image.pm
   lib/PDF/Builder/Resource/XObject/Form/BarCode/code3of9.pm  deprecated 
     methods (renamed or absorbed into other methods) now get get warning 
     messages output, in addition to (the PDF::API2 practice) of calling their
     replacements. If these new warnings are a problem, your code should be
     changed to no longer use the deprecated methods. It was felt to be not
     worthwhile to try to add some kind of global switch to suppress the
     warnings -- it's also too easy to forget to get around to updating your
     code!

   lib/PDF/Builder/Content.pm  
   lib/PDF/Builder/Content/Text.pm [ref RT #98543 (was rejected)] most methods
     did not have consistent return values. Some returned $self, others returned
     their old settings, and still others returned nothing. When called without
     parameters (setting routines, such as linewidth()), the current settings
     are returned. linedash(-1) may now be used to query the current dash
     pattern setting. Some methods in PDF::API2 which returned nothing, now 
     return a setting, but this is unlikely to cause problems in existing code. 
     Some methods which returned the new value on a setting call (a value was 
     given) now consistently return $self, permitting chaining of setting calls.
     It is possible, though unlikely, that existing code was depending on the 
     new value being returned; these calls will have to be updated.
    
     Read the updated POD to clarify what is returned by a method call.

3.001     2017-01-30 

   lib/PDF/Builder/Util.pm  *HexValues() calls, pad with '0' to minimum length
     (silent error). Document that if wrong number of hex digits, silently 
     ignore the extra digits. PDF::API2 could produce unexpected results if
     the wrong number of hex digits were given, or input values which should
     be in the range 0 to 1 were not (they are now clamped to that range).
     This may result in different colors being set than in PDF::API2, even
     though the original colors were erroneously specified!

   lib/PDF/Builder/Content.pm  updates:

     arctocurve() renamed to _arctocurve()
     fontset() renamed to _fontset()
     textpos2() renamed to _textpos2()
     metaStart() renamed to _metaStart()
     metaEnd() renamed to _metaEnd()  It is unlikely that anyone was using
       these internal routines, but in case they are...

     [ref RT #98538 (was open)] arc/pie couldn't cross 0 degrees. gave 
       _arctocurve() an optional direction parameter (default: 
       0=counterclockwise sweep) and split the arc at 0 degrees.

       *** NOTE *** These functions have always been ambiguous in PDF::API2 in 
         their definition. If you gave an arc or pie sweep from 60 to 30, did 
         you mean a clockwise 30 degree arc, or a counterclockwise 330 degree 
         arc? The addition of a direction parameter (pie, arc) clarifies your 
         intent, but may result in different arcs being drawn than before 
         (requiring an explicit 1 in the argument list to set a clockwise 
         sweep).

     [ref RT #98535 (was rejected)] restore nl(width) capability. PDF::API2
       cannot specify a width (amount of indent); it was treated as nl(0).
       
