1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
|
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.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 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 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).
|
