Majestic Sea Creature
Technical Ramblings from Gregory Brown
Prawn's Second Release (0.2)
When I first released Prawn in early August, I didn’t know what to expect. I knew that at least a few people were looking forward to a gem release, but I didn’t realize that interest had expanded beyond the core group of folks who already knew about Prawn and where it was headed.
Of course, after news hit a few of the high traffic news sources, such as InfoQ and RubyInside, things immediately began to surge. A community of developers and contributors opened its doors to users, which of course, created some tension. We’ll get into the details about that later, but for now, let’s focus on what has gone on in the month of time since the first release, and what shiny new things people will find in Prawn 0.2
Getting Prawn
Prawn is installable via RubyGems:
gem install prawn
You can also clone from github and then checkout the 0.2.0 tag:
git clone git://github.com/sandal/prawn.git git checkout 0.2.0
Be warned, even after a history rewrite to prune things a bit, the Prawn repository is huge.
New Logo!
A while back we had a logo contest which ended shortly after the Prawn 0.1.0 release. Richard Mason won the contest, leaving us with this awesome logo:
Though I haven’t found out how he wants to be credited yet, this blog’s logo was the runner up for the Prawn logo contest, and was made by Michael Daines. I can’t thank these guys enough for their cool artwork.
Shiny New Features in Prawn 0.2
There are lots of new fun things to play with in Prawn 0.2, most thanks to user requests. This isn’t meant to be a comprehensive list of changes, but it should hit some of the highlights:
== Document.new now accepts a block
People really like the simplified syntax that Prawn::Document#generate offers.However, you can’t use this method when streaming PDFs rather than writing them to file. I moved the block logic from generate down into the constructor, which lets you write code like this:
== CMYK color support
Some folks who want to do high quality printing with Prawn have asked for CMYK color support, so we’ve added this feature. See the API documentation for details.
== New Font System
Since fonts tend to be a complex topic in PDF, we’ve created a Prawn::Font class and provided some accessors for it. This adds basic support for font families, among other fun things.
== Lazy Bounding Boxes
It’s useful to be able to store a bounding box and draw its contents later. You can now do this with lazy_bounding_box which will hopefully provide a foundation for building Prawn based widgets that can be reused throughout a report.
== Header / Footer Support
Lazy bounding boxes were implemented in part to make way for real header and footer support, which now has a much nicer interface than the page hooks found in Prawn 0.1.
== Per-column alignment in tables
A contributed patch now allows for column alignment to be specified per-column in tables. I made some small changes and added an example, but this new feature is great. Using it, Prawn will now default to right-aligning numeric fields so that they display properly.
== Character based wrapping
I learned quickly that Chinese doesn’t wrap well if all we look for is spaces to determine how to split up words. A more general solution that allows people to plug in locale specific text wrapping code may be in order, but for now, character based wrapping is a start.
To ease repeated use of text options, I’ve added a helper to make this easier which can be seen indirectly through a few of these examples.
== PDF::Inspector
I’ve cleaned up and off-shored our PDF::Reader based spec helpers. You can find them on github as part of PDF::Inspector now. These are included in Prawn as a git submodule, and may be useful to others who need to validate their PDF output in specs or unit tests.
Although this isn’t everything, the API documentation, specs, and examples distributed with the source have all been updated, so it should be relatively straightforward to discover the new cool stuff I’ve left out here.
Now that we’ve got the good news at of the way, here comes the bad news.
Breaking Changes
Here’s where I get to piss everyone off. The following things will likely cause you to have broken programs when migrating from Prawn 0.1 to 0.2:
== Fonts
The new font system makes it so that most font features are on the Font object rather than on Document. This means font.size instead of font_size, font.metrics instead of font_metrics, etc. For the most part, this is a major win, but is a significant API break worth knowing about.
== Bounding Box
If you are flowing text in a bounding box and it exceeds the box height, it will start again on the next page at the top-left corner of the bounding box. Stretchy boxes will flow to the bottom of the margin-box before changing to
a new page.
== Tables / Cells
- The cursor will be positioned directly below the table rather than vpad points below.
- The :border option is now :border_width
== Removed hooks:
The :on_page_start and :on_page_stop hooks have been removed from Prawn in favor of the new header / footer code.
== Other stuff
Other things have probably changed that broke things from 0.1 to 0.2. I will update this as I remember them or when people point them out.
A warning to potential users
Keep in mind that Prawn is alpha-level software suitable for project developers, contributors, and tester’s only. It may be useful enough for production work, but we are nowhere near ready to claim it is production ready.
If you’re not ready to roll up your sleeves and get your hands dirty, you may want to wait several more months before trying to work with Prawn. This is especially true because we’re not really ready to provide end user support at this point. We consider all users at this stage to be testers and contributors who are eager to lend a helping hand. If that doesn’t describe something you’re interested in doing, keep an eye out for a 1.0 release some time in the not-too-distant future.
The State of the Sea Creature
Prawn has three main goals: It aims to be fast, tiny, and nimble.
During development, each cycle may emphasize on one aspect or another, but we want to be able to claim all three of these things about Prawn.
As of Prawn 0.2, we can claim that the library is quite nimble. There is a lot of inherent flexibility in Prawn that you don’t get in other PDF solutions. You also can get a lot done without a lot of code, so that means that we’re at least part of the way there with the idea of keeping things tiny (conceptually). However, speed has started to become a major concern.
Table generation is starting to slow down as we layer in new features. Though we’re still much faster than PDF::Writer, we’re slower than we want to be. Our PNG implementation is very slow, as is some of our font management code.
For the next several weeks, we’re going to try to stop the forward motion as far as features are concerned. We’re going to dive back under the hood and clean up the core, writing more specs and adding in some benchmarks. We’ll profile the code and look for bottlenecks. We’ll remove ugly code and replace it with better code.
In the next few weeks, not much will change on the outside, but the changes on the inside will be instrumental for future growth. If we keep our sights on fast, tiny, and nimble, it’ll eventually become a reality so long as we put the work in.
How to get involved:
The easiest way to get involved with Prawn is to introduce yourself on the mailing list or to find us in #prawn on irc.freenode.net. Things are a little too fluid to put together a formal hacking guide, but if you’ve got some spare time, we’ve got a lot of different ways you can help out if you’re in need of ideas.
Until next time
Enjoy Prawn 0.2, report bugs, request features, and come chat with us!
Written by Gregory Brown on 2008.09.13 at 14:57 | Responses