If you use PDF::Writer, read this post!

Ruby
1

I’m getting very few requests for features to add to Prawn that exist
in PDF::Writer but not in Prawn.
Because it directly effects each and every user, I need to know what
this means. Please remember that I intend to END ALL SUPPORT FOR
PDF::WRITER after Prawn becomes PDF::Document, so long as there is a
sufficient mandate from the community.

= Are you happy with Prawn as it is and have already migrated your new
projects to it?

If so, you have your right to remain silent. But it’d be re-assuring
to hear from you to know that you’re satisfied.

= Are there features you need that have not yet been implemented in
Prawn?

Please let me know know ASAP, within the next few weeks or so if
possible. Other uses should feel welcome to +1 these requests, so I
know how much of a demand there is. If you do this, there is a good
chance you’ll see these in Prawn / PDF::Document 1.0

= Do you plan to keep on using PDF::Writer even though it’s slated for
deprecation?

Don’t. We won’t even be handling bug fixes after this summer.

Or if there are enough people with this plan, please start talking to
me now. I’ll get in touch with Austin and see what he thinks about
bringing in a new maintainer. But you should have a really good
reason for this. :slight_smile:

With luck, we’ll have a broad adoption of Prawn and there will be
group hugs all around. But I’m trying to make this transition as
smooth as possible by planning ahead, so please help me by stating
your intentions.

-greg

PS: The urgency and intensity of this post is meant to be a bit
humorous, but also to emphasize the point that a change is in the
wind.

2

2009/1/18 Gregory B. [email protected]:

I’m getting very few requests for features to add to Prawn that exist
in PDF::Writer but not in Prawn.
Because it directly effects each and every user, I need to know what
this means. Please remember that I intend to END ALL SUPPORT FOR
PDF::WRITER after Prawn becomes PDF::Document, so long as there is a
sufficient mandate from the community.

Why rename it? Prawn is a nice name, while PDF::Document seems to
imply that there are other closely related PDF::* modules.

= Are you happy with Prawn as it is and have already migrated your new
projects to it?

If so, you have your right to remain silent. But it’d be re-assuring
to hear from you to know that you’re satisfied.

I’ve written a prototype with Prawn and it was a pleasurable
experience. Nice API!

= Are there features you need that have not yet been implemented in
Prawn?

Being able to put more complex objects than just text into table
cells would be cool, as well as more options for table borders.
(I’ve used 0.3.0 so maybe this request is already obsolete.)

Please let me know know ASAP, within the next few weeks or so if
possible. Other uses should feel welcome to +1 these requests, so I
know how much of a demand there is. If you do this, there is a good
chance you’ll see these in Prawn / PDF::Document 1.0

-greg

Stefan

3

On Sat, Jan 17, 2009 at 9:00 PM, Stefan L.
[email protected] wrote:

2009/1/18 Gregory B. [email protected]:

I’m getting very few requests for features to add to Prawn that exist
in PDF::Writer but not in Prawn.
Because it directly effects each and every user, I need to know what
this means. Please remember that I intend to END ALL SUPPORT FOR
PDF::WRITER after Prawn becomes PDF::Document, so long as there is a
sufficient mandate from the community.

Why rename it? Prawn is a nice name, while PDF::Document seems to
imply that there are other closely related PDF::* modules.

There are :slight_smile:

We’ve got PDF::Inspector and PDF::Reader. Both which are tentatively
planned to become part of the ‘pdf’ project.

http://rubyforge.org/projects/pdf

gem install pdf would get you all of them.
Note that I’ll likely turn Prawn into PDF::Document by something
simple like this in the pdf gem:

module PDF; end
Prawn = PDF;
require “prawn”

Or something silly like that, at first. (Just off the top of my head,
I’m not sure the above actually works)

It may be possible to just keep Prawn as Prawn, but we’ll see how it
goes.

= Are you happy with Prawn as it is and have already migrated your new
projects to it?

If so, you have your right to remain silent. But it’d be re-assuring
to hear from you to know that you’re satisfied.

I’ve written a prototype with Prawn and it was a pleasurable
experience. Nice API!

Awesome.

= Are there features you need that have not yet been implemented in
Prawn?

Being able to put more complex objects than just text into table
cells would be cool, as well as more options for table borders.
(I’ve used 0.3.0 so maybe this request is already obsolete.)

The former request is in high demand. I’ve been hoping for someone
else to nail it because I’ve suggested on the Prawn list how I’d like
to see it implemented and I feel it’s a straightforward patch. So
far, no one has bit. I will implement this if no one does before
1.0, most likely.

The latter, we’ve got some things that are new, others not advertised.
Before I do more with the table stuff, I need to re-organize it a
bit, but it’s coming. I usually ask for folks to file tickets for
stuff like this, but those two issues are burned into my brain well
enough and rest on me getting some stuff done before I can tackle them
anyway, so don’t worry about it.

Of course, patches are welcome for both. :slight_smile:

-greg

4

On Jan 17, 9:13 pm, Gregory B. [email protected] wrote:

gem install pdf would get you all of them.
It may be possible to just keep Prawn as Prawn, but we’ll see how it goes.
module Prawn
module PDF
class Document

The extra namespace ensures it can still be used without conflict
should another lib use the PDF namespace too. And one can do:

include Prawn

to still use just

PDF::Document

A ‘shortcut’ require can also be provided to automatically do the
including.

T.

5

On Sat, Jan 17, 2009 at 10:12 PM, Trans [email protected] wrote:

PDF::Document

A ‘shortcut’ require can also be provided to automatically do the
including.

Nah, it’d be mighty annoying to nest all my classes that way. I’m fine
with claiming the PDF namespace since I’m the current maintainer of
the Ruby PDF project (PDF::Writer), and one of the principle
developers on Prawn maintains PDF::Reader.

It will be up to other developers to avoid namespace collisions with
us, or alternatively, join forces and become part of the ‘pdf’ project
for Ruby.

-greg

6

Does anybody use this stuff as an alternative to LaTeX?

7

On Sun, Jan 18, 2009 at 3:32 PM, Redd V. [email protected]
wrote:

Does anybody use this stuff as an alternative to LaTeX?

I have a project that generates lout from ruby and then pdf from lout

  • I’ve been meaning to port it over to prawn and drop the external
    dependency. In general, I’d say that if you are machine-generating a
    PDF, a ruby library would be a lot more convenient to use than
    generating latex or lout or whatever.

martin

8

Too true, too true. LaTeX gives me a headache.

9

Redd V. wrote:

PDF, a ruby library would be a lot more convenient to use than
generating latex or lout or whatever.

martin

While we’re on the subject of PDFs, LaTeX, etc.

  1. I use an open-source document writing tool called LyX
    (http://www.lyx.org) to do nearly all of my documentation. It can
    convert to and from almost any format that has an open-source library,
    but its “core” is LaTeX and “pdflatex”. Its internal format looks a lot
    like LaTeX.

The primary scripting language in LyX is Python. Sorry, guys, the snakes
just got there first. :slight_smile: There is also an excellent package for doing
“literate programming” with LyX in the R programming language at

http://cran.fhcrc.org/contrib/extra/lyx/

I would like to be able to do literate programming with LyX as easily in
Ruby as I can in R or Python.

  1. New features for Prawn aka PDF::Document? The PDF format includes the
    ability to incorporate multimedia files “seamlessly” into a document.
    One extremely impressive example of this is a format called “U3D”. This
    allows you to incorporate a 3D object in a PDF with very little space
    cost, and you can rotate the object, change the lighting on it, etc.
    There’s a stunning example of the capabilities of this at

And the code to make it is at

http://www.tug.org/texshowcase/Laurana_tex.zip

I’m sure the tools in PDF::Document can easily get a U3D into a PDF, or
if not, could be extended to do so easily. But what I’d really like is a
set of Ruby libraries / classes for making the U3Ds from data! Right
now, it looks like the main open source package for making U3Ds is
Meshlab, which is at

http://meshlab.sourceforge.net/

See also

http://vcg.sourceforge.net/

–
M. Edward (Ed) Borasky

I’ve never met a happy clam. In fact, most of them were pretty steamed.

10

On Sun, Jan 18, 2009 at 5:02 AM, Redd V. [email protected]
wrote:

Does anybody use this stuff as an alternative to LaTeX?

That’s certainly not the goal, but actually Jamis B.'s
prawn-format[0] extension might get people close to some of the
complex needs you’d use LaTeX for. But of course, YMMV.

-greg

[0] http://github.com/jamis/prawn-format

11

On Sun, Jan 18, 2009 at 7:11 AM, Martin DeMello
[email protected] wrote:

On Sun, Jan 18, 2009 at 3:32 PM, Redd V. [email protected] wrote:

Does anybody use this stuff as an alternative to LaTeX?

I have a project that generates lout from ruby and then pdf from lout

  • I’ve been meaning to port it over to prawn and drop the external
    dependency. In general, I’d say that if you are machine-generating a
    PDF, a ruby library would be a lot more convenient to use than
    generating latex or lout or whatever.

Yes, the benefit of a pure-Ruby to PDF library is that there aren’t
intermediate dependencies. Of course, thinks like LaTeX or lout, or
Postscript (via the very cool RGhost library) might have their
benefits in certain situations, and might kick our butts performance
wise.

But when you use Prawn (or PDF::Writer), you’ve got vanilla Ruby that
generates a complete PDF. The purists among us are sure to find that
appealing.

-greg

12

On Sun, Jan 18, 2009 at 11:52 AM, M. Edward (Ed) Borasky
[email protected] wrote:

  1. New features for Prawn aka PDF::Document? The PDF format includes the
    ability to incorporate multimedia files “seamlessly” into a document.
    One extremely impressive example of this is a format called “U3D”. This
    allows you to incorporate a 3D object in a PDF with very little space
    cost, and you can rotate the object, change the lighting on it, etc.
    There’s a stunning example of the capabilities of this at

http://www.tug.org/texshowcase/Laurana.pdf

This wouldn’t load in OS X Preview. Interesting to see this stuff
used, I saw brief mentions of this in the PDF specs, but I was sort of
expecting it was unused and unsupported across many viewers. The
former I’ve apparently been proven wrong on, the latter, I think might
be right. What viewers support this?

http://meshlab.sourceforge.net/

See also

http://vcg.sourceforge.net/

You’d need to write an extension, but it might not be too hard. I
haven’t researched it at all, honestly. You might look at the PDF
spec[0]. It’d be neat to see an extension that did this, and I’d
expose the necessary bits to make sure it was possible to do
externally, but I’m sure this wouldn’t be part of core Prawn, and I
hesitate to say whether it’d be part of the ‘official’ project. It
seems like a better home for it might be SciRuby or something like
that. We’d of course help promote the use of the tool and help with
the Prawn specific details, but beyond that, this seems a bit
specialized for what we’re trying to keep a small and simple library.
Please do look into this though, and feel free to discuss it on the
Prawn list in hopes of finding other interested parties.

-greg

[0] http://www.adobe.com/devnet/pdf/pdf_reference.html

13

Gregory B. wrote:

http://www.tug.org/texshowcase/Laurana.pdf

This wouldn’t load in OS X Preview. Interesting to see this stuff
used, I saw brief mentions of this in the PDF specs, but I was sort of
expecting it was unused and unsupported across many viewers. The
former I’ve apparently been proven wrong on, the latter, I think might
be right. What viewers support this?

As far as I can tell, only Acrobat Reader on Linux. There may be others
on Windows and Macs, but I have only played with it on Linux.

http://meshlab.sourceforge.net/
hesitate to say whether it’d be part of the ‘official’ project. It
seems like a better home for it might be SciRuby or something like
that. We’d of course help promote the use of the tool and help with
the Prawn specific details, but beyond that, this seems a bit
specialized for what we’re trying to keep a small and simple library.
Please do look into this though, and feel free to discuss it on the
Prawn list in hopes of finding other interested parties.

Actually, I do think “data → U3D” needs a separate project. I haven’t
been following the “scientific computing in Ruby” projects much in the
past two years, so I don’t know what’s “new”. But I would think Prawn
should definitely be able to take a U3D into a PDF. The fact that my
search for “open source U3D creators” essentially dead-ends at Meshlab
leads me to believe that it (or its core, VCG) is the only game in town.

But it might be relatively easy to get a Ruby interface to VCG using
SWIG.

-greg

[0] http://www.adobe.com/devnet/pdf/pdf_reference.html

–
M. Edward (Ed) Borasky

I’ve never met a happy clam. In fact, most of them were pretty steamed.

14

On Sun, Jan 18, 2009 at 10:16 PM, M. Edward (Ed) Borasky
[email protected] wrote:

Gregory B. wrote:

We’d of course help promote the use of the tool and help with
the Prawn specific details, but beyond that, this seems a bit
specialized for what we’re trying to keep a small and simple library.
Please do look into this though, and feel free to discuss it on the
Prawn list in hopes of finding other interested parties.

But I would think Prawn should definitely be able to take a U3D into a > PDF.

If you’re talking about the technical possibility, yes, since it’s
specified by Adobe, it can be done, I imagine. And a third-party gem
to do this (prawn-u3d), would be welcome.

But if you’re talking about how we should include this feature because
it’s an important feature for a PDF generator, well… I disagree
there. I have no plans to fully support the PDF specification (it’s
massive), and the fact that there are no open-source (or even
commercial) applications that seem to support this feature other than
Adobe’s own acrobat reader makes me very uninterested in supporting it
directly in Prawn.

-greg

15

On Jan 18, 2009, at 11:59 AM, Gregory B. wrote:

http://www.tug.org/texshowcase/Laurana.pdf

This wouldn’t load in OS X Preview. Interesting to see this stuff
used, I saw brief mentions of this in the PDF specs, but I was sort of
expecting it was unused and unsupported across many viewers. The
former I’ve apparently been proven wrong on, the latter, I think might
be right. What viewers support this?

Acrobat is the only one I know, which sucks. I’ve been wanting to
embed multimedia in our books for a while, but the fact that most
readers won’t display the stuff correctly has held us back.

Dave

16

On Mon, Jan 19, 2009 at 3:54 AM, Jocke S. [email protected]
wrote:

I haven’t even tried Prawn. Why? Because PDF::Write works and I frankly
the time, it’d be crazy for me to use it for new projects because
product is ready, the other product will be out of Beta too. :slight_smile:
Ah, that’s completely understandable. Glad we cleared this up.

Just for the record, I think this is an interesting feature. It’s not
present in PDF::Writer, so it’s not at the top of the queue in terms
of my personal goals, but I like the idea a lot and would welcome a
prawn-paper extension, possibly even as part of the ‘official’
project. Those interested in working on such a thing should contact
me on the Prawn mailing list[0].

Excellent. I will do my best to provide “specifications” if required, but
that’s sadly as far as I can reasonably go with my promises.

Sure, why don’t you put something together and post it to the Prawn
list. Who knows, someone might have a similar need and decide to
implement it…

-greg

17

Greg,

The last time I looked at Prawn (quiet a while ago) I don’t remember
seeing the equivalent of add_text_wrap which became the basis for a
layout API I wrote which allowed one to define a series of text boxes
specifying x,y,width, height, and rotation angle and border and then
flow text into the first box and have it cascade through the rest. I’d
like to contribute something like this to Prawn, but it would be nice
if the fundamentals were there to support it. Did I miss the obvious
or does Prawn now support a function that allows one to flow text into
a box of specified width with the text which doesn’t fit returned?

John-Mason

18

On Sat, Jan 24, 2009 at 5:45 PM, John-Mason P. Shackelford
[email protected] wrote:

a box of specified width with the text which doesn’t fit returned?
I describe how to do this here:

http://prawn.lighthouseapp.com/projects/9398/tickets/113-single-line-of-text

But maybe instead, Prawn::Document#text_box should return the
remaining parts of the string that were not rendered?
Aside from returning the remainder and handling rotation,
Prawn#text_box sounds exactly like what you’ve described here.

http://is.gd/h6x9

What do you think?

-greg

19

On Sun, Jan 18, 2009 at 6:53 AM, Jocke S. [email protected]
wrote:

Hi Greg,

I’m replying to this off-list, simply because I don’t really feel this is an
issue that needs to be debated in public. If you feel it should be public,
please feel free to reply on-list.

Okay, I have done that, to help encourage discussion on the topic and
because you have good points.

I hope my words don’t come across as negative. My intention is to let you
know how things are in our business. A business that’s led by real world
constraints such as budgets and time. I personally wish for unlimited
resources, but that’s just dreaming. :wink:

I didn’t find anything you said in this message to be negative or
insulting, and I’m glad you shared your thoughts. Of course… there
are things worth discussing here.

On 18 Jan 2009, at 01:35, Gregory B. wrote:

= Are you happy with Prawn as it is and have already migrated your new
projects to it?

I haven’t even tried Prawn. Why? Because PDF::Write works and I frankly
don’t have time to “play around” with stuff that’s not a priority. I suspect
that one day I need to try out Prawn, and I have 100% faith in that it’ll be
just fine for our needs.

Do you mean it works in projects you already have built, or that you
are using PDF::Writer for new projects? In the former case, I’ve got
a lot of projects that are that way. We built them in PDF::Writer,
they ‘work’, and they’ll probably never get translated. But 90% of
the time, it’d be crazy for me to use it for new projects because
Prawn is such a time saver and will be a major benefit down the line
since it is actively developed. There are those 10% cases from time
to time, but those get smaller each day (For me, others might have a
different experience)

With this in mind, I’d like to have clear migration instructions from
PDF::Writer to, then, PDF::Document.

This is a great idea, and you can be sure that this will exist by the
time PDF::Document 1.0 is out. I might even put something together
for Prawn in the interim. Or even better, any volunteers? :slight_smile:

The requirement is simply that I need a template that will be applied to all
pages of the “print-out”. Such as headers, footers, and a good bonus would
be to define default fonts/sizes/colours etc.

This requirement could also be defined as a one-page-document that can be
read into PDF::Document and used as a template. This would obviously provide
for a greater level of customisation for non-programmers (read: graphic
designers etc).

Just for the record, I think this is an interesting feature. It’s not
present in PDF::Writer, so it’s not at the top of the queue in terms
of my personal goals, but I like the idea a lot and would welcome a
prawn-paper extension, possibly even as part of the ‘official’
project. Those interested in working on such a thing should contact
me on the Prawn mailing list[0].

breath I’ll state that our system will, in time, switch to PDF::Document. :slight_smile:
I think there may have been a misunderstanding. I didn’t mean people
should go eradicate existing PDF::Writer projects and replace them
with Prawn, because I’m not even doing that (well, not everywhere,
anyway). What I’m suggesting is that people should use Prawn for
their new projects once it becomes PDF::Document because my current
plans are to drop all support for PDF::Writer.

Now you’ve been lucky and not run into issues (with either
performance, bugs, etc) in PDF::Writer, but many others are not so
lucky, and without a maintainer, PDF::Writer will continue to rot in
the face of these issues. Sure, we can get it up on github and hope
for the best, but I don’t think that’s any real solution. I plan to
do one or two more release of PDF::Writer before I retire it, just to
clear the patch pool, but after that, the ‘official’ development will
completely stop unless someone stands up and takes up the role of
maintaining it.

This is why the best solution I can see is for PDF::Writer users to
spend an hour or two learning Prawn to see how close it fits their
needs. If a huge group feels like it’s way off and will continue to
be way off after 1.0, the they should elect a maintainer and get in
touch with me for a smooth transition.

I also want to thank you for your continued work and support. Both on Prawn
and PDF::Writer.

Thanks for the kind words,

-greg

[0] http://groups.google.com/group/prawn-ruby

20

On Thu, Jan 29, 2009 at 9:46 PM, John-Mason P. Shackelford
[email protected] wrote:

Greg,

If Prawn#text_box returned the remaining text and supported
justification (at least left and center) and rotation, I’d have what
I need.

Good to know. Please file a ticket in lighthouse:
http://prawn.lighthouseapp.com/projects/9398-prawn