Please be sure to read through these changes carefully when migrating between versions of Prawn, and let us know if you run into any problems or find something missing from these notes.

Prawn 0.8.4: 2010-02-24

(NOTE: 0.8.1-3 were gem packaging errors, please ignore these, as 0.8.4 is the first major 0.8 based release)

This is a major release that includes many new features, fixes, and overall changes. Prawn 0.7 users should look to upgrade to Prawn 0.8 as soon as possible, as Prawn <= 0.7 is no longer officially supported.

General Information

Prawn is currently under heavy flux due to our attempts to identify and lock down a suitable API and feature set for 1.0. Right now, most of the major changes are happening behind the scenes, but by 0.9, users will have a good sense of where we’re going with things and what to expect. For now, here are a few general things to note about 0.8:

• We have not yet merged James Healy’s templates branch, but this is only because we haven’t had time to rebase it against all the core changes. So if you’ve been waiting on this feature, we will hopefully get it into 0.9 for you.

• We had planned to write up the necessary steps for getting prawn-format back into the fold, but instead, we are working on a replacement that will be supported in core. More details to come soon.

• This is the last release that will use Gregory’s legacy prawn-layout API (specifically tables). Brad Ediger has been hard at work on a refactored version with a significantly different API, and we will merge that upstream within the next couple weeks. When that happens, Brad will provide some notes on how to use the new code on the Prawn mailing list.

• This is also the last release in which Prawn’s official extensions are split across gems. Since we only release versions in lockstep, we aren’t really benefiting from the split architecture. So, we plan to merge everything into the repository at http://github.com/sandal/prawn and also combine prawn-core, prawn-security, and prawn-layout into one gem.

• If you’ve written low level extensions against Prawn 0.7, they will probably break with this release. We’re working on putting together a set of low level objects to form a core developer API. See release notes for details, and expect even more of this in 0.9.

• Finally, we’ve relaxed our “no users, only contributors” policy within the Prawn community. We are asking that folks identify development discussions on the mailing list with the [dev] subject tag, but welcome general user discussion as well now. Details: http://groups.google.com/group/prawn-ruby/browse_thread/thread/01105170193b2671

Changed Since 0.7.2

In prawn-core:

• We now omit /Encoding from font dict for AFM symbol fonts. [Fixes an issue w. ZapfDigbats font] (Brad Ediger)
• Replaced most page related methods on Prawn::Document with the Prawn::Core::Page object (Gregory Brown)
• Low level text methods moved from Prawn::Text to Prawn::Core::Text (Daniel Nelson)
• Background images for documents are now positioned absolutely, so images should be the size of the document, not the size of the margin box. [#84] (Brian Jensen)
• Line wrapping is no longer set by :wrap_block, but instead by :wrap_object. See documentation for Text::Box for details, and have a look at our DefaultLineWrap object. (Daniel Nelson)
• PDF version is raised to 1.4 when PNG images are included w. alpha channels. (Brad Ediger)
• You can no longer provide :at to the text() method. Instead, you will want to use draw_text() or text_box() if you need control over positioning. (Daniel Nelson) - This one will probably break your code, so pay attention!
• Prawn::ObjectStore is now Prawn::Core::ObjectStore (Gregory Brown)
• BoundingBox now requires :width to be set, raises an error otherwise (Gregory Brown)

No user facing changes to prawn-layout or prawn-security

Features / Fixes / Cleanup

In prawn-core:

• We now have support for PDF outlines. This produces a nested index that appears alongside the PDF in supported viewers. (Jonathan Greenberg)

    Prawn::Document.generate(outlined document) do
      text "Page 1. This is the first Chapter. "
      start_new_page
      text "Page 2. More in the first Chapter. "
      start_new_page
      define_outline do
        section 'Chapter 1', :page => 1, :closed => true do
           page 1, :title => 'Page 1'
           page 2, :title => 'Page 2'
        end
     end
  end

There are a number of ways to add sections and page indexes, so be sure to check out the rest of the examples as well as the documentation for Prawn::Outline.

• Added matrix transformations for scaling, rotation, and translation of arbitrary content. (Michaël Witrant)

• Added :origin option to scale and rotate. (Daniel Nelson)

   x      = 300
   y      = 300
   width  = 150
   height = 200
   angle  = 30

   pdf.rotate(angle, :origin => [x, y]) do
     pdf.stroke_rectangle([x, y], width, height)
   end

For those who understand matrix transformations at the PDF level, there is also a low level transformation_matrix() call that is a direct wrapper on the “cm” operator.

• It is now possible to rotate text boxes. See the :rotate and :rotate_around options. (Daniel Nelson)

• repeat() now works with dynamic content (Jonathan Greenberg)

  repeat(:all, :dynamic => true) do
    draw_text page_number, :at => [500, 0]
  end

Note that :dynamic => true should only be used when the content in the block changes from page to page. Static repeaters (the default) are far more efficient due to their use of PDF XObjects.

• Added support for rounded_rectangle() and rounded_polygon() (Jonathan Greenberg)
• Text::Box now supports a :skip_encoding option (Daniel Nelson)
• Fixed yet another encoding issue with AFM fonts (Daniel Nelson)

No significant changes to prawn-layout or prawn-security

Prawn 0.7.2: 2010-01-31

General Information

Thanks again to our vigilant users for quickly spotting bugs in the 0.7 codebase

Fixes and cleanup since 0.7.1

In prawn-core:

• Transaction rollback now properly sets page_number [#79] (Brad Ediger)
• Raise an error rather than entering an infinite loop in Text::Box :shrink_to_fit (Brad Ediger)
• Character wrapping should now work again on Ruby 1.8.6 (Daniel Nelson)
• Resolved an encoding issue with character wrapping (Daniel Nelson)
• /Encoding no longer included in font dict for AFM fonts (Brad Ediger)
• Update fill_color, stroke_color, font, and font_families documentation (Simon Hürlimann)
• Remove several prawn-format references in documentation (Gregory Brown)

In prawn-layout:

• Tables should now work in column boxes [#7] (Brad Ediger)

No changes were made to prawn-security

Prawn 0.7.1: 2010-01-03

This is a major release that includes many new features, fixes, and overall changes. Prawn 0.6 users should look to upgrade to Prawn 0.7 as soon as possible, as Prawn <= 0.6 is no longer officially supported.

General Information

We have made a lot of decisions in this cycle, in the hopes that we can see a Prawn 1.0 in the near future. Specifically, these are the issues to be aware of:

• Because we never used RubyForge for anything but gem hosting, and RubyForge’s gem index has been shut down in favor of Gemcutter, we will no longer be uploading files to RubyForge. Please see Prawn’s Gemcutter page for gem related stuff.

• The prawn/format extension has been removed from the official prawn gem, and will not be supported at all until we have an active maintainer for it. We will provide a comprehensive list of issues that need to be resolved with the library soon, hopefully before the 0.8 release. But for now, if you need inline styling, you’ll need to either hack prawn/format yourself to get it working with Prawn 0.7, or stick to Prawn <= 0.6 for those needs.

• The prawn/layout extension is currently feature frozen pending a major rewrite, to be conducted by Brad Ediger. We will be accepting patches for bugs in the old codebase, but any new featurework will need to wait until the rewrite happens. We hope to have a quick thaw on this, having the new prawn/layout codebase in place in time for the 0.8 release, but time will tell.

• We are making our version numbering a bit more consistent across our sub-projects. You’ll notice in this release that prawn-core, prawn-layout, and prawn-security all carry the same version number: 0.7.1. If we do any maintenance releases, we’ll bump the third version number on any of the codebases we touch (and of course, the prawn metagem). When Prawn 0.8 is released, all sub-projects will ship with the version 0.8.1, whether or not they’ve had any API breaking changes. We are hoping this helps people easily see what versions are compatible with each other.

• We have changed our documentation policy. All patches we merge into the master and stable branches of officially supported components of Prawn will have adequate API documentation for all public functions that aren’t explicitly marked with :nodoc:. So please help out by documenting your code before submitting a pull request. While it’s possible a core developer or someone else will do it for you, it definitely helps move things along to add any relevant docs yourself.

• After conducting a vote amongst contributors and considering the options, we plan to stick with y=0 being at the bottom of the document for the foreseeable future. I understand that many folks would prefer things to be done the other way around, but we feel like making this change will create more problems than it solves. We will however, look at creating higher level APIs to solve some of the warts that result from this convention.

• We plan to release Prawn 1.0 some time in Q2 2010. Soft feature freeze will happen no later than April 1st, 2010 with a hard freeze about 1 month before 1.0’s release. More details will come soon, but what this means is that if you have any major changes you want to introduce to Prawn, you should start that conversation as soon as possible on our mailing list.

Changed Since 0.6.3

In prawn/core:

• Document#go_to_page now treats the first page as 1, not 0. [Brad Ediger]
• start_new_page() now inserts after the current page rather than at the end of the document. [Brad Ediger]
• Text wrapping now automatically uses character based wrapping if a word is too long to fit on a single line. The :wrap option has been removed in favor of a more flexible :wrap_block. See API docs for text_box() for details. [Daniel Nelson]
• Fixed an issue where text descender could hang below the bottom of a bounding box (or margins). [Daniel Nelson]
• Document#height_of signature now matches text() and text_box() [Daniel Nelson]
• Document#transparent() now rounds negative values to 0.0, and values greater than 1 to 1.0.
• Font#descender now returns a positive value, since it is only used as a magnitude throughout Prawn’s calculations. [Daniel Nelson]
• The :kerning option for documents was previously only capable of disabling kerning. It is now possible to attempt to force kerning via :kerning => true [Daniel Nelson]

In prawn/layout:

• removed header() and footer() methods, use Prawn::Document#repeat instead.

Version bumped as per new convention.

In prawn/security:

No changes. Version bumped as per new convention.

Features / Fixes / Cleanup

In prawn/core:

• Added Document#page_number [Brad Ediger]
• Added Document#float(), which executes a block and then restores the original y position. [Gregory Brown]
• Vertical text alignment now supported via the :valign option [Daniel Nelson]
• A much more powerful text_box API. See documentation and examples for details [Daniel Nelson]
• Added a document option :optimize_objects, that reduces the amount of PDF objects in output at the expense of rendering time [Brad Ediger]
• Added on_page_create() hook to document, see examples/general/context_sensitive_headers.rb for details [Lenny Marks]
• Refactored color setting code [Wojciech Piekutowski]
• Minor fixes to transaction support [Brad Ediger]

No user facing features or fixes in prawn-layout or prawn-security.

Prawn 0.6.3: 2009-11-17

General Information

Thanks again to our vigilant users for quickly spotting bugs in the 0.6 codebase.

Bug fixes since 0.6.2

In prawn-core:

• Fixed a bug in annotations that prevented proper references from being generated [#58] (jlh)
• Prawn::Reference on_encode() method removed, this should fix marshaling issue in transactions. [#56] (Brad Ediger)
• Document extensions now work in inherited classes [#57] (Gregory Brown)

In prawn-layout:

• Cursor is now placed directly at the bottom of a table after generation, as in Prawn 0.5.x (Gregory Brown)

In prawn-format:

• Fixed internal links in basic formatting example [#11] (jlh)
• width_of() and height_of() now should work as they did in 0.5.x [#12,#13] (Gregory Brown)

As a result of fixes in core, Prawn::Format should work in classes inherited from Prawn::Document, and links should now work again.

Prawn 0.6.2 : 2009-11-13

General Information

With this release, we welcome Daniel Nelson as a core committer to Prawn. Though most of the heavy lifting on Prawn is primarily done by our casual contributors, we need a couple people upstream to keep things organized and provide us with a bus-factor greater than 1. Based on his recent work and expected things to come, we’re glad to have Daniel join us.

Updated core committer list: Gregory Brown, Brad Ediger, James Healy, Daniel Nelson (Jamis Buck has retired)

This is a bug fix release that fixes issues with some of the new features in Prawn 0.6. It should not introduce any incompatibilities with Prawn 0.6.1, so please upgrade immediately.

Bugfixes since 0.6.1

All changes were to prawn-core

• Stamped content no longer cut off when too close to document boundaries (Daniel Nelson)
• Reopening pages no longer creates an invalid content length, so page numbering should now work (Brad Ediger)
• Updated some copyright info (Brad Ediger)
• Include procedure sets on every page for PDF <= 1.3 compatibility. (Brad Ediger)
• Updated stamp example (Daniel Nelson)
• create_stamp now is able to work prior to page creation (Daniel Nelson)

NOTE: There is still one known issue that is somewhat severe that we have not resolved. Currently transactions will not work when using TTF fonts in your document. We’re aware of the fact that this means that transactions are currently not m17n-friendly, and we will absolutely fix this before Prawn 0.7. If we get this issue fixed soon, we’ll get another 0.6 maintenance release out shortly after we get it resolved.

Prawn 0.6.1 : 2009-11-10

This is a major release that includes many new features, fixes, and overall changes. Prawn 0.6 users should look to upgrade to Prawn 0.6 as soon as possible, as Prawn 0.5 is no longer officially supported.

General Information

Brad Ediger’s prawn-security extension is now an official part of Prawn, and has been added as a dependency to the prawn metagem. This adds support for encryption, password protection, and permissions to Prawn.

Example:

  require "prawn"
  require "prawn/security"  

  Prawn::Document.generate("hello_foo.pdf") do
    text "Hello, world!"
    encrypt_document :user_password => 'foo', :owner_password => 'bar',
      :permissions => { :print_document => false }
  end

Changed since 0.5.1:

In prawn-core:

• Improved low-level handling of PDF objects via ObjectStore. May break extensions that rely on certain low level features, see source for details. (Brad Ediger)
• Using text() with both :at and :align now raises an error. These two options never worked together, but may cause unexpected errors in code that was previously failing silently. (Gregory Brown)
• text_box() now returns the portion of the text that did not fit in the box. [#2] ( (Sam Livingston-Gray)
• Stretchy bounding boxes now calculate height as the largest distance the box has been stretched to, rather than the last evaluated distance from the top of the box. See the bounding box examples for clarification. (Gregory Brown)
• bounding_box() now returns the generated bounding box. This is only really useful for checking things like the final height of a stretchy box, and isn’t meant to be used as alternative API to the block form. (Gregory Brown)

No user facing API changes were made in prawn-format or prawn-layout.

Features / Fixes / Cleanup

In prawn-core:

Users will appreciate the following items:

• Added support for transactional rendering via Document#transaction and Document#rollback (Brad Ediger)
• Added Document#group() to group contents within the same column or page (Brad Ediger)
• Added for stroke dashing. See the dash(), undash() and dashed?() methods on Document (Daniel Nelson)
• Added a :margin option for Document#new and Document#start_new_page, can be specified as a single value or CSS shorthand. [#18] (Henrik Nyh)
• Added transparency support for PDF Vector graphics, see Prawn::Graphics::Transparency. (Daniel Nelson)
• Added “stamps” which allow for repeatable elements via XObjects. See Prawn::Stamp. (Daniel Nelson)
• Added stroke cap and join styles, see Graphics::CapStyle and Graphics::JoinStyle (Daniel Nelson)
• Added Document#move_cursor_to() to allow for moving the y position relative to the bottom boundary. (Gregory Brown)
• Added Document#number_pages() for “Page k of n” style page numbering templates. (Gregory Brown)
• Updated some outdated documentation

Those extending Prawn will want to know about these changes as well:

• Fixed PDF format identifier to conform to spec (Brad Ediger)
• Added a simple system for defining extensions to Prawn::Document via Document.extensions (James Edward Gray II)
• Fixed a bug in NameTree insertion when nodes are already in insertion order [#48] (JeanLuc)
• Added ByteString to denote literal byte streams (Brad Ediger)

In prawn-layout:

• Cells should no longer have a gap between their border and background color (corny)
• Added AndrewO’s prawn-grid examples to prawn-layout. (Brad Ediger)
• Added :row_gutter and :column_gutter options to Grid. (Jordan Byron)

In prawn-format

• Fixed an encoding bug (Jose Espinal)
• Refactored to use new extension system in prawn-core (James Edward Gray II)

In prawn-security

• Birthday!

Prawn 0.5.1 : 2009-09-22

This is a major release that includes many new features, fixes, and overall changes. Prawn 0.4 users should look to upgrade to Prawn 0.5 as soon as possible, as Prawn 0.4 is no longer officially supported. This also goes for Prawn 0.5.0.1, which was mainly released as an unstable developer preview.

General Information

Note that our bug trackers have moved from lighthouse, and are now on Github:
core: http://github.com/sandal/prawn/issues
layout: http://github.com/sandal/prawn-layout/issues
format: http://github.com/sandal/prawn-format/issues

Also note that Jamis Buck has retired as a Prawn core developer, so the new home for prawn-format is:
http://github.com/sandal/prawn-format

Prawn has been restructured so that the prawn gem is just a meta-gem that pulls in prawn-core, prawn-layout, and prawn-format. This change is backwards compatible, so unless you plan to mix and match gem versions for the various packages in a way other than what we recommend, you don’t need to make any changes to the way you load Prawn.

Changed since 0.4.1:

In prawn-core:

• Document::Font#width_of becomes Document#width_of (Jamis Buck)
• padded_box, lazy_bounding_box, header, and footer moved to prawn/layout
• Raise Errors::NotOnPage if font is called without a current page (Brad Ediger)
• Prawn::Document.text_options removed.
• :spacing is now :leading for Document#text()
• Font#normalize_encoding now non-destructive, use Font#normalize_encoding!() to modify in place.

In prawn-layout:

Note that this version is not compatible with Prawn 0.4.×. To use the new prawn-layout code you must upgrade to Prawn 0.5.1. However, the API should be mostly backwards compatible.

No user facing API changes were made in prawn-format

Features / Fixes / Cleanup

In prawn-core:

• Unsupported image types now throw a better error [James Healy]
• Added Document#min_version to internals, to allow extensions to set a minimum PDF version other than the one Prawn provides. (James Healy)
• Added Document#column_box to allow flowing text from column to column (Paul Ostazeski)
• Added Document#indent to allow temporary resetting x position to allow for indentation. (Jeremy Friesen)
• Added support for document metadata properties (John Weathers)
• Many improvements to documentation (Mikel Lindsaar)
• Output a newline after %EOF to make Ghostscript and ImageMagick happy (Brad Ediger)
• A whole bunch of refactorings and cleanup (Petrik de Heus)
• Minor documentation fix (Brandon Hauff)

In prawn-layout:

• As previously mentioned, prawn-layout now includes padded_box, lazy_bounding_box, header, and footer
• Hash syntax for cells now supports any key that Cell.new supports.
• Merged prawn-grid, a tool for doing grid based layouts. (Andrew O’Brien)
• Fix a bug involving colspan width calculations (Jesús GS)
• Allow font_style to be set on individual cells, and properly handle font size changes: (Sean Kirby)
• Add License files to repository
• Other minor cleanups (Łukasz Piestrzeniewicz)

In prawn-format

• External links now supported (Phil Morris)