...
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 for now. Please file bug reports if you run into any problems!
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, we'll bump our major version number.
-
Whenever we add new functionality without breaking backwards compatibility, 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, 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 is added, and also whenever we change existing features.
This should improve compatibility across viewers that do not support arbitrarily long decimal numbers, without effecting practical use 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 Reader raising errors when viewed.
(Gregory Brown, #782)
Previously, the width_of method would include the width of all soft hyphens
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.
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,
allowing calculations to work properly with TTFs.
(Ernie Miller, #827)
In earlier versions of Prawn, center alignment and bottom alignment in text boxes worked in a way that is inconsistent with common typographical conventions:
-
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 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)
In earlier versions of Prawn, accidentally calling dash(0) instead of
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.
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 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 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, 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.
_. -
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_encodingis called, rather thanASCII-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 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)
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.
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:
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
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
end
def say_hello
text "Hello, #{@name}!"
end
def say_goodbye
font("Courier") do
text "Goodbye, #{@name}!"
end
end
end
greeter = Greeter.new("Gregory")
greeter.say_hello
greeter.say_goodbye
greeter.save_as("greetings.pdf")Wherever possible, please convert your Prawn::Document subclasses to use
Prawn::View instead. It is much less invasive, and is nearly a drop-in
replacement for the existing common practice.
A defect in our text rendering system was to blame for this bad behavior. For more details, see #347.
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 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)
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 or its dependencies.
(TTFunk #21 -- Jesse Doyle)
This release includes all changes from 1.2.0, which was yanked due to a packaging error.
In addition to adding require "prawn/table" to your code, you will need to install
the prawn-table gem to make use of table and cell rendering functionality in Prawn 1.2+.
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
issues as soon as possible.
Please see the prawn-table repository for more information.
This feature is useful for preventing mid-word breaks when used in combination with the
:shink_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, bounds.top], 100, 50
font('Helvetica', size: 50) do
formatted_text_box(
[{text: 'VEGETARIAN'}],
at: [0, bounds.top],
width: 100,
height: 50,
overflow: :shrink_to_fit,
disable_wrap_by_char: true # <---- newly added in 1.2
)
end
endWithout 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
an optional behavior that is off by default.
(#752, James Coleman)
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 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
styles globally, even if fallback fonts are in use.
(#743, Pete Sharum)
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 if colors were set on text fragments. This patch resolves that issue.
(#736, Christian Hieke)
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
prawn-manual_builder gem has been released.
In addition to the notes below, please see the Prawn 1.1 blog post.
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 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 extracted into its own gem soon.
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
a path on the filesystem. For example:
io = File.open "#{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)
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 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
code is an important first step in making it more useful for everyone. Bug fixes
and improvements are welcome!
(#728, Gregory Brown)
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 for at least one row of non-header data before attempting to render headers.
(#717, Uwe Kubosch)
In previous versions of Prawn, multi-row headers with rowspan would render incorrectly in multi-page tables. This bug has now been fixed.
([#721](prawnpdf#721, "#723":prawnpdf#723), Deron Meranda + Hartwig Brandl)
This is a fix for yet another edge case in cell width calculations. See tickets for details.
In addition to the notes below, please see the Prawn 1.0 blog post.
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
bounding box spanned more than one page.
Because many of Prawn's features rely on bounding boxes internally, this problem typically would reveal itself indirectly. This example from Malte Schmitz helped us finally track down the problem:
pdf = Prawn::Document.new(:margin => 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 " * 100The 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
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.
A useless file named .. was accidentally checked into the repository,
which was causing failures with cloning Prawn on Windows. That file has been removed,
resolving the problem.
( #692, Johnny Shields)
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 )
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 Prawn::Outline and marked it as part of our stable API.
For changes before our 1.0 release, see the following wiki page: https://github.com/prawnpdf/prawn/wiki/CHANGELOG