Advice on PDF::Writer

ruby-talk
1

Hi, folks. I'm in the middle of a major overhaul to PDF::Writer. The
API is changing significantly. Here are a couple of changes:

    # Set the stroke style. Assume a PDF object instance.
  pdf.set_stroke_style(5, :round, :bevel, [3, 5], 1)
    # becomes
  PDF::Writer::StrokeStyle.new(5) do |ss|
    ss.cap = :round
    ss.join = :bevel
    ss.dash = { :pattern => [ 3, 5 ], :phase => 1 }
    pdf.stroke_style ss
  end

    # Draw a circle at (250, 250) with radius 50. The outline should
    # be red and the fill should be blue.
  pdf.set_color(1, 0, 0)
  pdf.set_stroke_color(0, 0, 1)
  pdf.filled_ellipse(250, 250, 50)
  pdf.ellipse(250, 250, 50)
    # becomes
  pdf.stroke_color(Color::Red)
  pdf.fill_color(Color::Blue)
  pdf.circle_at(250, 250, 50).fill_stroke

The PDF::EZWriter class has entirely disappeared -- it has been
absorbed into the PDF::Writer class. There are no provisions made
for backwards compatibility in any case (original versions did; this
has not been the case for three weeks when I realised that the API
changes I needed to make were far larger than could be comfortably
worked around with the old APIs).

However, there is one major API (tables) that I am finding difficult
to turn into the form that I prefer.

I'm nearly ready to release this new version of PDF::Writer -- we're
going from a technology preview (dubbed 0.1.0 when I made a gem) to
a 1.0 release. The problem is that if I release without this API
change, the next release will be API-incompatible; not as
incompatible as PDF::Writer 0.1 to PDF::Writer 1.0, but incompatible
nonetheless. (I'm not sure how much of the old API could be
translated into the new code.)

So, the question: do I release this drastically new and improved
version of PDF::Writer now, or can people wait a bit longer for me
to finish the table API?

-austin

···

--
Austin Ziegler * halostatue@gmail.com
               * Alternate: austin@halostatue.ca

2

Hi,

So, the question: do I release this drastically new and improved
version of PDF::Writer now, or can people wait a bit longer for me
to finish the table API?

I vote for release as 1.0 without the complete API. Else, you will get
to the 0.9.10.1 numbers as many projects do, :slight_smile: (but regret, I
think, because it confuses some users.)

People can create their own "PDF widgets" as well, which will be
probably simpler than a generic "table widget".

Cheers,
Joao

3

So, the question: do I release this drastically new and improved
version of PDF::Writer now, or can people wait a bit longer for me
to finish the table API?

I say release, but call it not-quite-1.0

4

Austin Ziegler ha scritto:

Hi, folks. I'm in the middle of a major overhaul to PDF::Writer. The
API is changing significantly. Here are a couple of changes:

    # Set the stroke style. Assume a PDF object instance.
  pdf.set_stroke_style(5, :round, :bevel, [3, 5], 1)
    # becomes
  PDF::Writer::StrokeStyle.new(5) do |ss|
    ss.cap = :round
    ss.join = :bevel
    ss.dash = { :pattern => [ 3, 5 ], :phase => 1 }
    pdf.stroke_style ss
  end

question: why this is not:
  pdf.stroke_style= ss
(this is a question valid for a lot of examples you just showed)

It seem to me that your convention would make sense in the case you used a TkRuby-like approach by doing initialization with an instance-evaled block, but looking at the StrokeStyle initialization above it does not seem so.

5

> So, the question: do I release this drastically new and improved
> version of PDF::Writer now, or can people wait a bit longer for me
> to finish the table API?

I vote for release as 1.0 without the complete API. Else, you will get
to the 0.9.10.1 numbers as many projects do, :slight_smile: (but regret, I
think, because it confuses some users.)

+1 I say do it :slight_smile:

Having the thing out will help to improve things faster and relieve
Austin from the pressure of packing everything in a short period of
time.

Another good reason for releasing now is not all generated documents
will make use of tables.

Developers who jump to use PDF:Writer now will help to debug the
library in its current state, and that will benefit a the following
1.0 release

I know a few developers who have already expressed their desire to
have PDF::Writer available now, so you can roughly count my vote as at
least 2 others more.

cheers,
                        vruz

6

This is partially because of internal implementation issues. The
table code draws lines around tables:

  stroke_style StrokeStyle.new(options[:inner_line])

If I used the assignment form, I would need:

  self.stroke_style = StrokeStyle.new(options[:inner_line])

I have also been debating switching from the yield form to the
instance_eval form, but I am undecided as yet. It will not make a
significant difference in the code as I've written it; mostly it
will be a difference in documentation.

-austin

···

On Tue, 15 Mar 2005 23:02:23 +0900, gabriele renzi <surrender_it@remove-yahoo.it> wrote:

Austin Ziegler ha scritto:

Hi, folks. I'm in the middle of a major overhaul to PDF::Writer.
The API is changing significantly. Here are a couple of changes:

   # Set the stroke style. Assume a PDF object instance.
pdf.set_stroke_style(5, :round, :bevel, [3, 5], 1)
   # becomes
PDF::Writer::StrokeStyle.new(5) do |ss|
   ss.cap = :round
   ss.join = :bevel
   ss.dash = { :pattern => [ 3, 5 ], :phase => 1 }
   pdf.stroke_style ss
end

question: why this is not:
pdf.stroke_style = ss
(this is a question valid for a lot of examples you just showed)

It seem to me that your convention would make sense in the case
you used a TkRuby-like approach by doing initialization with an
instance-evaled block, but looking at the StrokeStyle
initialization above it does not seem so.

--
Austin Ziegler * halostatue@gmail.com
               * Alternate: austin@halostatue.ca