22.6 KB
Newer Older
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
## PrawnPDF master branch

## PrawnPDF 2.1.0 -- 2016-02-29

### Added support for PNG images with indexed transparency

Prawn now properly hadles transparency in PNG images with indexed color.

(Maciej Mucha, [#783](; Alexander Mankuta, [#920](

### Prawn no longer generates IRB warnings

Fix a few issues with code style that were triggering warnings in IRB when run in verbose mode (`irb -w`).

(Jesse Doyle, [#914](

### Gradients applied inside transformations are now correctly positioned

PDF gradients/patterns take coordinates in the coordinate space of the
document, not the "user space", so if you performed a scale/rotate/translate
and then painted a gradient inside, it wasn't correctly positioned.

This change tracks transformations applied to the document, and multiplies
the gradient matrix with this tracked transformation matrix so that the
gradient appears in the correct place in the document.

Because this changes how the x and y coordinates are interpreted, you must
manually add `apply_transformations: true` to your `stroke_gradient` and
`fill_gradient` calls to use the fixed behaviour in Prawn 2.  It is expected
that this will be the default in Prawn 3.

Please [refer to the wiki page on this change](
for more information.

(Roger Nesbitt, [#891](, [#894](

### Prawn::Graphics::BlendMode#blend_mode added
Blend modes can be used to change the way two layers are blended together. The
BM key is added to the External Graphics State based on the v1.4 PDF spec. `blend_mode`
accepts a single blend mode or array of blend modes. If an array is passed, the
PDF viewer blends layers based on the first valid blend mode.

43 44 45 46 47 48 49 50 51 52 53 54 55
## PrawnPDF 2.0.2 -- 2015-07-15

### Links in repeaters/stamps are now clickable

Previously, url links were not clickable when rendered within a stamp. The
proper annotation references are now added to the page object that the
stamp is called, thereby generating a clickable link in the pdf.

Because repeaters are built upon stamps, this fix should also solve
issues with links inside of repeaters.

(Jesse Doyle, [#801](, [#498](

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
## PrawnPDF 2.0.1 -- 2015-03-23

### Fix regression in draw_text() with rotation

Due to missing tests, a typo snuck into the `draw_text()` method in PDF::Core,
preventing it from working properly when called with the `:rotate` option.

This issue has been resolved, and a test has been added to Prawn's test suite.
Speaking more generally, we need to improve the condition of the tests for
`PDF::Core`, and make a clear separation between Prawn's test suite and
PDF::Core's tests. Currently there are lots of little gaps that can lead
to this sort of problem.

[Robert S. Gerus, [pdf-core#15](]

## PrawnPDF 2.0.0 -- 2015-02-26

### Changes to supported Ruby versions

Now that Ruby 1.9.3 is no longer supported by the Ruby core team, Prawn will no
longer attempt to maintain 1.9.x compatibility.

We will continue to support Ruby 2.0.0 and 2.1.x, and have added support for Ruby
2.2.x as well.

If you're using JRuby, we recommend using JRuby 1.7.x (>= 1.7.18) in 2.0 mode
82 83 84 85 86 87
for now. Please file bug reports if you run into any problems!

### Changes to PrawnPDF's versioning policies

Starting with this release, we will set version numbers based on the following policy:

* Whenever a documented feature is modified in a backwards-incompatible way,
89 90
we'll bump our major version number.

* Whenever we add new functionality without breaking backwards compatibility,
92 93 94 95 96
we'll bump our minor version number.

* Whenever we cut maintenance releases (which cover only bug fixes,
documentation, and internal improvements), we'll bump our tiny version number.

This policy is similar in spirit to [Semantic Versioning](,
98 99 100 101 102 103 104 105 106
and we may end up formally adopting SemVer in the future.

The main caveat is that if a feature is not documented (either in our API
documentation or in Prawn's manual), you cannot assume anything about its
intended behavior. Prawn has a lot of cruft left in it due to piecewise
development over nearly a decade, so the APIs have not been designed as
much as they have been organically grown.

To make sure that the amount of undefined behavior in Prawn shrinks over time,
we'll make sure to review and revise documentation whenever new functionality
108 109
is added, and also whenever we change existing features.

### All decimals in PDF output are now rounded to a fixed precision of 4 decimal places

112 113
This should improve compatibility across viewers that do not support
arbitrarily long decimal numbers, without effecting practical use
114 115
at all. (A PDF point is 1/72 inch, so 0.0001 PDF point is a very, very small number).

This patch was added in response to certain PDFs on certain versions of Adobe
117 118 119 120 121 122
Reader raising errors when viewed.

(Gregory Brown, [#782](

### Fixed text width calculation to prevent unnecessary soft hyphen

Previously, the `width_of` method would include the width of all soft hyphens
124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142
in a string, regardless of whether they would be rendered or not. This caused
lines of text to appear longer than they actually were, causing unnecessary
wrapping and hyphenation at times.

We've changed this calculation to only include the width of a soft hyphen when
it will actually be rendered (i.e. when a line needs to be wrapped), which
should prevent unnecessary hyphenation and text wrapping in strings containing
soft hyphens.

(Mario Albert, [#775](, [#786](

### Fixed styled text width calculations when using TTF files

Previously, `width_of` calculations on styled text were relying on the
document font's name attribute in order to look up the appropriate
font style. This doesn't work for TTF fonts, since the name is a full
path to a single style of font, and the Prawn must know about the font
family in order to find another style.

The `width_of` method has been updated to use the font family instead,
144 145 146 147 148 149 150
allowing calculations to work properly with TTFs.

(Ernie Miller, [#827](

### Fixed broken vertical alignment for center and bottom

In earlier versions of Prawn, center alignment and bottom alignment in text
151 152
boxes worked in a way that is inconsistent with common typographical

154 155
* Vertically centered text was padded so that the distance between the
top of the box and the ascender of the first line of text was made equal to the
156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174
distance between the descender of the bottom line to the descender of the last line of text.

* Bottom aligned text included the line gap specified by a font, leaving a bit of
extra in the box space below the descender of the last line of text.

Other commonly used software typically uses the baseline rather than the descender
when centering text, and does not include the line gap when bottom aligning text.
We've changed Prawn's behavior to be consistent with those conventions, which
should result in less surprising output.

That said, this problem has existed in Prawn for a very, very long time. Check your code to
see if you've been working around this issue, because if so it may cause breakage.

For a very detailed discussion (with pictures), see issue [#169](

(Jesse Doyle, [#788](

### Calling dash(0) now raises an error instead of generating a corrupt PDF

In earlier versions of Prawn, accidentally calling `dash(0)` instead of
176 177 178 179 180 181 182 183 184
`undash` in an attempt to clear dash settings would generate a corrupted
document instead of raising an error, making debugging difficult.

Because `dash(0)` is not a valid API call, we now raise an error that says
"Zero length dashes are invalid. Call #undash to disable dashes.", making
the source of the problem much clearer.

### Vastly improved handling of encodings for PDF built in (AFM) fonts

Prawn has always had comprehensive UTF-8 support for TTF font files, but many
users still rely on the "built in" AFM fonts that are provided by PDF viewers.
These fonts only support the very limited set of internationalized characters
188 189 190
specified by the Windows-1252 character encoding, and that has been a long
standing source of confusion and awkward behaviors.

Earlier versions of Prawn attempted to transcode UTF-8 to Windows-1252
192 193 194 195 196 197 198 199 200 201
automatically, but some of our low level features either assumed that
text was already encoded properly, or returned text in a different
encoding than what was provided because of the internal transcoding
operations. We also handled Windows-1252 encoding manually, so strings
would come back tagged as ASCII-8BIT instead of Windows-1252, making
things even more confusing.

In this release, we've made some major behavior changes to the way AFM
fonts work so that users need to think less about Prawn's internals:

* Text handling for all public Prawn methods is now UTF-8-in, UTF-8-out,
203 204 205
making Windows-1252 transcoding purely an implementation detail of Prawn
that isn't visible from the outside.

* When using AFM fonts + non-ASCII characters that are NOT supported in
Windows-1252, an exception will be raised rather than replacing w.
209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225

* When using AFM fonts + non-ASCII characters that are supported in
 Windows-1252, users will see a warning about the limited
internationalization support, along with a recommendation to use a TTF
 font instead.

* The warning includes instructions on how to disable it (just set
`Prawn::Font::AFM.hide_m17_warning = true`)

* When using AFM fonts + ASCII only text, no warning will be seen.

* Internally, we're now using Ruby's M17n system to handle the encoding
into Windows-1252, so text.encoding will come back as Windows-1252
when `AFM#normalize_encoding` is called, rather than `ASCII-8Bit`

None of the above issues apply when using TTF fonts with Prawn, because
those have always been UTF-8 in, UTF-8 out, and no transcoding was
done internally. It is still our recommendation for those using internationalized
227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250
text to use TTF fonts because they do not have the same limitations
as AFM fonts, but those who need to use AFM for whatever reason
should benefit greatly from these changes.

(Gregory Brown, [#793](

### Temporarily restored the Document#on_page_create method

This method was moved into PDF::Core in the Prawn 1.3.0 release, removing
it from the `Prawn::Document` API. Although it is a low-level method not
meant for general use, it is necessary for certain tasks that we do not
have proper support for elsewhere.

This method should still be considered part of Prawn's internals and is subject
to change at any time, but we have restored it temporarily until we have
a suitable replacement for it. See the discussion on [#797](
for more details.

(Jesse Doyle, [#797](, [#825](

## PrawnPDF 1.3.0 -- 2014-09-28

### Added the Prawn::View mixin for using Prawn's DSL in your own classes.

251 252 253 254
In complex Prawn-based documents, it is a common pattern to create subclasses
of `Prawn::Document` to isolate different components from one another,
or to provide some customized rendering methods. However, the sprawling
nature of the `Prawn::Document` object makes this an unsafe practice:
255 256 257
it implements hundreds of methods and contains dozens of instance variables,
all of which can conflict with any subclass functionality.

`Prawn::View` provides a safer alternative by using object
259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291
composition instead of inheritance. This will keep your state and
methods separate from Prawn's internals, while still allowing you to
directly call any methods provided by the `Prawn::Document` object.

Here's an example of `Prawn::View` in use:

class Greeter
  include Prawn::View

  def initialize(name)
    @name = name

  def say_hello
    text "Hello, #{@name}!"

  def say_goodbye
    font("Courier") do
      text "Goodbye, #{@name}!"

greeter ="Gregory")



292 293
Wherever possible, please convert your `Prawn::Document` subclasses to use
`Prawn::View` instead. It is much less invasive, and is nearly a drop-in
294 295 296 297
replacement for the existing common practice.

### Soft hyphenation no longer renders unnecessary hyphens in the last word of paragraphs.

A defect in our text rendering system was to blame for this bad behavior.
299 300 301 302 303 304
For more details, see [#347](

([#773](, [#774]( -- Mario Albert)

### Fonts with unsupported character mappings will now only fail if you use unsupported glyphs.

A bug in TTFunk prevented certain fonts from being used because they contained
unsupported character map information. In most cases, this information would
only be needed to render a handful of obscure glyphs, and so most users
308 309 310 311 312 313 314 315 316
would never run into issues by using them.

This issue has been resolved, and should help improve compatibility
for CJK-based fonts in particular.

([TTFunk #20]( -- Dan Allen)

### Prawn no longer triggers Ruby warnings when loaded

317 318 319
Some minor issues in our TTFunk dependency was causing many warnings to be
generated upon loading Prawn. As of this release, you should now be able to
run Ruby with warnings on and see no warnings generated from Prawn
320 321 322 323 324 325 326 327 328 329
or its dependencies.

([TTFunk #21]( -- Jesse Doyle)

## PrawnPDF 1.2.1 -- 2014-07-27

This release includes all changes from 1.2.0, which was yanked due to a packaging error.

### Prawn::Table has been moved into an optional gem extension.

In addition to adding `require "prawn/table"` to your code, you will need to install
331 332
the `prawn-table` gem to make use of table and cell rendering functionality in Prawn 1.2+.

333 334 335
The `prawn-table` gem will be maintained by Hartwig Brandl, and is semi-officially
supported by the Prawn maintenance team. That means that we'll continue to watch its
CI builds against each Prawn release, and help to resolve any compatibility
336 337
issues as soon as possible.

Please see the [prawn-table repository](
339 340 341 342
for more information.

### Text box now has an option to disable wrapping by character.

This feature is useful for preventing mid-word breaks when used in combination with the
344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363
`:shrink_to_fit` overflow option. See the following example practical use case:

# An example shared by Simon Mansfield
Prawn::Document.generate("x.pdf") do
  stroke_rectangle [0,], 100, 50

  font('Helvetica', size: 50) do
      [{text: 'VEGETARIAN'}],
      at: [0,],
      width: 100,
      height: 50,
      overflow: :shrink_to_fit,
      disable_wrap_by_char: true  # <---- newly added in 1.2

364 365
Without setting `:disable_wrap_by_char`, the code above will break the word "VEGETARIAN"
into two lines rather than shrinking it all the way down to fit on a single unbroken line.

To maintain backwards compatibility, `:disable_wrap_by_char` is implemented as
368 369 370 371 372 373
an optional behavior that is off by default.

([#752](, James Coleman)

### Fallback fonts no longer break global font styling.

374 375
In earlier versions of Prawn, using the fallback font system caused styling information
(i.e. bold, italic) for all fonts to be lost, and the only workaround to this
376 377
problem was to specify style explicitly for each individual text fragment.

Now that this issue has been resolved, it is safe to use the `font` method to set
379 380 381 382 383 384
styles globally, even if fallback fonts are in use.

([#743](, Pete Sharum)

### Formatted text box dry runs no longer modify graphics state

385 386
Dry runs are supposed to be a side-effect-free way of simulating text rendering,
but a bug in earlier versions of Prawn caused the graphics state to be modified
387 388 389 390 391 392
if colors were set on text fragments. This patch resolves that issue.

([#736](, Christian Hieke)

### Fixed manual build failure on Ruby 1.9.3

393 394
When we extracted Prawn::ManualBuilder, we accidentally broke its support for
Ruby 1.9.3. That issue has been resolved, and a new version of the
395 396 397 398
`prawn-manual_builder` gem has been released.

## PrawnPDF 1.1.0 -- 2014-06-27

In addition to the notes below, please see the
400 401 402 403
[Prawn 1.1 blog post](").

### Table support now disabled by default, moving to its own gem soon.

404 405
We're planning to extract table generation into its own semi-officially
supported gem in a future release. Until then, you can use the following line
406 407 408 409 410 411 412
to enable table support in your projects:

require "prawn/table"

As of right now tables are still supported as an experimental public feature --
we only disabled it by default to make sure people are aware that it will be
414 415 416 417 418 419
extracted into its own gem soon.

### I/O objects are now supported in the font system.

You can now pass a fully formed Prawn::Font object in addition to a
file path when adding a font family to your document. `Prawn::Font.load`
now also accepts IO object as an alternative to explicitly specifying
421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436
a path on the filesystem. For example:

io = "#{Prawn::DATADIR}/fonts/DejaVuSans.ttf"
@pdf.font_families["DejaVu Sans"] = {
  normal: Prawn::Font.load(@pdf, io)

@pdf.font "DejaVu Sans"
@pdf.text "In DejaVu Sans"

([#730](, Evan Sharp)

### We now use the Prawn::ManualBuilder gem to generate our documentation.

437 438 439 440
In previous releases, the system that generated Prawn's manual
was bundled directly with Prawn and not usable by third party extensions.
We've now extracted that system into
[its own project]( so that it can be
441 442 443
used by anyone who wants to ship PDF-based documentation for their Prawn code.

`Prawn::ManualBuilder` is still a bit rough around the edges because it
wasn't originally meant for general purpose use, but extracting out the
445 446 447 448 449 450 451
code is an important first step in making it more useful for everyone. Bug fixes
and improvements are welcome!

([#728](, Gregory Brown)

### Table headers are now rendered only if there is also room for non-header rows.

452 453
Orphaned header rows look bad and could be considered a rendering bug,
and so this change fixes that problem by making sure there is enough room
454 455 456 457 458 459
for at least one row of non-header data before attempting to render headers.

([#717](, Uwe Kubosch)

### Row-spans in multi-row headers are no longer lost after pagebreak

In previous versions of Prawn, multi-row headers with rowspan would render
461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478
incorrectly in multi-page tables. This bug has now been fixed.

([#721](, "#723":, Deron Meranda + Hartwig Brandl)

### Fixed a table bug when using an array of column widths

This is a fix for yet another edge case in cell width calculations. See tickets for details.

([#710](, [#712]( Hartwig Brandl)

## PrawnPDF 1.0.0 -- 2014-03-16

In addition to the notes below, please see the [Prawn 1.0 blog post.][1-0-blog-post]


### Margins are now properly restored after a multi-page bounding box is rendered.

479 480 481
In a Prawn document, it's possible to reset the page margins on each
newly created page: i.e. `@doc.start_new_page(:margin => 64)`. But due to a
very old bug, this feature did not work correctly any time that a
482 483
bounding box spanned more than one page.

484 485
Because many of Prawn's features rely on bounding boxes internally, this problem
typically would reveal itself indirectly. This example from Malte Schmitz helped
486 487 488 489 490 491 492 493 494 495 496 497 498 499
us finally track down the problem:

pdf = => 200)
pdf.table [["Foo"]] * 20, position: :center # spans multiple pages
pdf.start_new_page(:margin => 0) # should have updated margins but didn't
pdf.text "Foo " * 100

The root cause of this problem has been found and fixed, and there should no longer be
unexpected issues when using the `:margin` parameter to `start_new_page`.

### Transaction support has been removed from Prawn, and the Document#group feature has been temporarily disabled.

We've discovered some very serious flaws in Prawn's transaction support which can
501 502 503 504 505 506 507 508 509 510 511 512 513 514 515
easily cause documents to become corrupted. The only thing transactions were used internally
for in Prawn was to support the `Document#group` feature, but the underlying defects were
severe enough to make `Document#group` unsafe for use whenever a page boundary is crossed.

We'd like to bring back both transactions and grouping functionality, but it's going to
involve some major work to do so cleanly. Until that happens, we've decided its better
not to provide the feature at all than it is to have folks try to use something that
will likely result in hard to hunt down bugs.

An experiment to restore grouping functionality without relying on transactions
has already been released by Daniel Dengler in the [prawn-grouping](
extension, so you may want to give that a try if you need grouping functionality.

### Fixed broken git clone of Prawn repository for Windows

516 517
A useless file named `..` was accidentally checked into the repository,
which was causing failures with cloning Prawn on Windows. That file has been removed,
518 519
resolving the problem.

( [#692](, Johnny Shields)
521 522 523 524 525 526 527 528 529 530

### Deprecated gradient method signatures have been removed.

The  `fill_gradient(point, width, height,...)` and `stroke_gradient(point, width, height,...)`
calls are no longer supported. Use `fill_gradient(from, to, ...)`  and `stroke_gradient(from, to, ...)` instead.

( [#674](, Alexander Mankuta )

### PDF::Core::Outline has been moved back to Prawn::Outline

531 532
When we first broke out the PDF::Core namespace from Prawn's internals, our outline
support ended going along with it. That was accidental, and so we've now restored
533 534 535 536 537 538
Prawn::Outline and marked it as part of our stable API.

## Pre-1.0 Release Notes

For changes before our 1.0 release, see the following wiki page: