A list of DEPRECATED names and interfaces in PDF::Builder. These are sometimes
misspellings that have been corrected at some point in the past (in PDF::API2), 
although some are interfaces that have been removed. Rather than keeping the 
old names around forever, they will be sunset and removed in due time. Please 
periodically check this list and make sure you have plans to change or remove 
these deprecated usages before they disappear from PDF::Builder. Initially,
the deprecated items MAY only be commented out (so they can be restored by a
user in an emergency), but eventually they WILL be removed.

CAUTION for maintainer: minimum 24 months after next RELEASE, not edit date!
NOTE for maintainer: update t/deprecations.t with tests for both old 
  (deprecated) and new interfaces. when REMOVE deprecated, move to "done" 
  section here AND comment out that test in t/deprecations.t (but leave
  replacement interface's test active).

In order of scheduled removal date:

*******************************************************************************
PDF::Builder currently accepts undashed option names in all cases, e.g.,
->new('compress' => 'none'), but still accepts dashed legacy names, e.g., 
->new('-compress' => 'none') or ->new(-compress => 'none'). This is to maintain
compatibility with PDF::API2, which still has a few dashed options here and 
there. 

All cases of "dashed" option names (e.g., ->new('-compress' => 'none')) are
silently converted to "undashed" form internally (->new('compress' => 'none')).
Only the undashed forms are documented, as we encourage the use of this form.
We strongly suggest that you go through your code and change dashed option
names to undashed. PDF::API2 appears to do the same thing (except for the 
"Lite" subsystem), and has also deprecated dashed (hyphened) names. At this
point, we have no plans to disallow (or ignore) dashed names.

There are a number of option names that are different between PDF::API2 and
PDF::Builder (whether dashed or undashed), and we will attempt to honor the
PDF::API2 names as alternate names.

There are also a number of legacy method names that are still available for
back (and cross) compatibility, but we recommend that you use the listed 
(recommended) names for new code.
*******************************************************************************
The "Lite" subsystem is not maintained as is kept only for compatibility with
old code (believe it or not, some organizations may still use it!). It has had 
dashed option names changed to undashed in PDF::Builder, but not PDF::API.
*******************************************************************************

The 'text-height' CSS property was incorrectly named, and was renamed to the
correct 'line-height'. 'text-height' will be accepted as an alias to 
'line-height' through at least the 3.030 release, or one year after the 3.028 
release, whichever is later.

default()       method in Builder.pm
   May be renamed in the future, as is flagged by Perl::Critic as reserved.
   Use with caution.

width(w),height(h)  methods in Resource/XObject/Image.pm
   The ability to SET an image's width and/or height is scheduled to be removed
   after October 2025. This setting ability appears not to work, but in case
   someone IS using it in some manner, it has not been immediately removed.
 THIS ONE IS BEING REVIEWED, AS THE <img> TAG IN column() WILL REQUIRE 
 IMPLEMENTATION OF WIDTH AND HEIGHT SETTING. NEVERTHELESS, THE CURRENT IMAGE
 SUPPORT TO *SET* WIDTH AND HEIGHT DOES *NOT* WORK.

===== NOT scheduled to be removed, but take notice ===========================

PDFStr()        method in Basic/PDF/Utils.pm
   use PDFString() instead. 

PDFUtf()        method in Basic/PDF/Utils.pm
   use PDFString() instead. 

openpage()      method in Builder.pm
   use open_page() instead. 

*** If I have missed any deprecated interfaces, please let me know! ***

======= Deprecated items that already have been removed ======================

Blackls1        DecodeParms hash element in Resource/XObject/Image/TIFF.pm
   Misspelling of "BlackIs1" (EYE instead of el) PDF flag. It was reported in 
   PDF::API2 bug RT 15730, but rejected. BlackIs1 has been added, and Blackls1 
   deprecated. Blackls1 will be removed (no longer set) on or after 
   August, 2018. [Removed September, 2018]

meterlimit      method in Content.pm and Resource/ExtGState.pm
   Misspelling, corrected to miterlimit. Use "miterlimit()" instead. A warning
   message is currently given. Scheduled to be removed on or after August, 2019.
   [Removed November, 2019]

hspace          method in Content.pm
   Misnamed, as it not an amount of horizontal space, but is a horizontal
   scaling factor. Use "hscale()" instead. A warning message is currently 
   given. Scheduled to be removed on or after August, 2019.
   [Removed November, 2019]

   It is POSSIBLE that after hspace() is removed, a NEW hspace() might appear
   for the purpose of adding some amount of horizontal space to a line of text,
   but there are no firm plans at this point. If such a method is added before
   the old hspace() is cold and dead, it would have to get a different name.

linedash -full and -clear options   method in Content.pm
   The dash pattern setting hash options "-full" and "-clear" are deprecated in
   favor of the "-pattern" array. A warning message is currently given. They 
   are scheduled to be removed on or after August, 2019.
   [Removed November, 2019]

new_api         method in modules NamedDestination.pm and Resource.pm
   Also in t/deprecations.t

   This method was dropped in favor of using "new(PDF_object, options)". A
   warning message is currently given. new_api() is scheduled to be removed on
   or after August, 2019. [Removed November, 2019]

paper sizes 4a, 2a, 4b, 2b    in Resource/PaperSizes.pm
   Non-standard paper size names. Use 4a0, 2a0, 4b0, and 2b0 instead. Scheduled
   to be removed on or after August, 2019. [Removed November, 2019]

encode_3of9_string_w_chk   method in Resource/XObject/Form/BarCode/code3of9.pm
   This was rolled into encode_3of9_string() with a parameter some time ago.
   Use encode_3of9_string(*, 1) instead. A warning message is currently given.
   encode_3of9_string_w_chk is scheduled to be removed on or after August, 2019.
   [Removed November, 2019]

encode_3of9_w_chk   method in Resource/XObject/Form/BarCode/code3of9.pm
   This was rolled into encode_3of9() with a parameter some time ago.
   Use encode_3of9(*, 1, 0) instead. A warning message is currently given.
   encode_3of9_w_chk is scheduled to be removed on or after August, 2019.
   [Removed November, 2019]

encode_3of9_ext method in Resource/XObject/Form/BarCode/code3of9.pm
   This was rolled into encode_3of9() with a parameter some time ago.
   Use encode_3of9(*, 0, 1) instead. A warning message is currently given.
   encode_3of9_ext is scheduled to be removed on or after August, 2019.
   [Removed November, 2019]

encode_3of9_ext_w_chk   method in Resource/XObject/Form/BarCode/code3of9.pm
   This was rolled into encode_3of9() with a parameter some time ago.
   Use encode_3of9(*, 1, 1) instead. A warning message is currently given.
   encode_3of9_ext_w_chk is scheduled to be removed on or after August, 2019.
   [Removed November, 2019]

imask           method in Resource/XObject/Image.pm
   This functionality was rolled into mask() some time ago. Simply rename any
   call to "imask" to "mask". A warning message is currently given. imask is 
   scheduled to be removed on or after August, 2019. [Removed November, 2019]

bpc             method in Resource/XObject/Image.pm
   This functionality was renamed to bits_per_component() some time ago. Simply 
   rename any call to "bpc" to "bits_per_component". A warning message is 
   currently given. bpc is scheduled to be removed on or after August, 2019.
   [Removed November, 2019]

openScalar      method in Builder.pm
   This functionality was renamed to open_scalar() some time ago. Simply 
   rename any call to "openScalar" to "open_scalar". A warning message is 
   currently given. openScalar is scheduled to be removed on or after 
   August, 2019. [Removed November, 2019]

importpage      method in Builder.pm
   This functionality was renamed to import_page() some time ago. Simply 
   rename any call to "importpage" to "import_page". A warning message is 
   currently given. importpage is scheduled to be removed on or after 
   August, 2019. [Removed November, 2019]

pdfile          method in Annotation.pm
   This functionality was renamed to pdf_file(). Simply rename any call to
   "pdfile" to "pdf_file". pdfile is scheduled to be removed on or after
   November, 2019. [Removed November, 2019]

spline          method in Content.pm
   This functionality was renamed to qbspline() [quadratic Bezier spline].
   Simply rename any call to "spline" to "qbspline". spline is scheduled to
   be removed on or after June, 2020. [Removed November, 2020]

pdfile          method in Outline.pm, NamedDestination.pm
   This functionality was renamed to pdf_file(). Simply rename any call to
   "pdfile" to "pdf_file". pdfile is scheduled to be removed on or after
   October, 2020. [Removed November, 2020]

-slant          option in Synfont.pm
   This option was renamed to -condense, as it is the factor to condense
   (multiply width by < 1) or expand (multiply width by > 1) text characters. 
   Use "-condense" instead. -slant is scheduled to be removed on or after
   January, 2021. [Removed February, 2021]

lead()          method in Content.pm
   Use leading() instead. lead is scheduled to be removed on or after 
   March, 2023. Notice that the associated global variable 'lead' has also
   been changed to 'leading'. [Removed September, 2023]

textlead()      method in Lite.pm
   Use textleading() instead. textlead is scheduled to be removed on or after 
   March, 2023. [Removed September, 2023]

elementsof()    method in a number of Basic/PDF/ routines
   This method was renamed to elements(). elementsof() is scheduled to be
   removed on or after August, 2021. [Removed September, 2023]

removeobj()     method in Array.pm
   Not used internally and not documented. To be removed on or after August,
   2021. Replaced by remove_element(). [Removed September, 2023]

get_*box()      methods in Page.pm
   now *box() methods (both $pdf and $page) with no arguments return the 
   global and current page bounding boxes (media, crop, bleed, trim, art).
   The get routines are now obsolete, and may be removed on or after 
   August, 2021. [Removed October, 2023]

