FAQ

Frequently asked questions about PDF Clown Project.

For months I've been receiving several pleasant feedbacks from all around the globe: legal matters and volunteering seem to be the hottest topics, so that I've decided to distill them into this FAQ list.

Introduction

What is PDF Clown Project?

PDF Clown Project is an abstract library devoted to the manipulation of PDF files, implemented on multiple platforms (Java™ 6, .NET 4.0).

ehmm... another PDF cruncher?! Not exactly: I strived to get rid of a number of cumbersome libraries, bulky and graceless, in favor of a simple, consistent, elegant (such an abused word!) piece of code that could do plainly what I needed (and what could be useful for you too, I hope).

Where does the name 'PDF Clown' come from?

That's a joking combination of two circumstances: I love clowns (so smiling!) and, in the fanciful world of circus, clowns are companions of acrobats (any reference to existing products is purely accidental *;o)).

Smiling might be a major therapy for the world: could people just respect one another, we'd have solved a large portion of current troubles. There's a nice piece of poetry on the web describing smiles:

A smile costs nothing,
but gives much.

It enriches those who receive it,
without impoverishing those who give it.

It takes nothing but a moment,
but the memory of it sometimes lasts forever.

None is so rich or mighty that he can get along without it,
and none is so poor but that he can be made rich by it.

A smile creates happiness in the home,
fosters good will in business,
and is the countersign of friendship.

It brings rest to the weary,
cheer to the discouraged,
sunshine to the sad,
and is nature's best antidote for trouble.

Yet it cannot be bought, begged, borrowed, or stolen,
for it is something that is of no value to anyone until it is given away.

And, if you meet someone who is too weary to give you a smile, leave one of yours.
For no one needs a smile quite so much as he who has none left to give.

--Anonymous

What is the difference between 'PDF Clown' and 'PDF Jester'?

According to the context of use, 'PDF Clown' refers either to the abstract PDF Clown Project or to its implementation for the .NET framework (also known as 'PDF Clown for .NET'); on the other hand, 'PDF Jester' refers to the implementation of the abstract PDF Clown Project for the Java™ platform (also known as 'PDF Clown for Java').

What can I do with PDF Clown?

PDF Clown provides a core library that exposes the PDF structure in a simple yet powerful object-oriented hierarchy. It will be eventually released a set of command-line tools built upon the library in order to allow direct access to common functionalities as file merging, file splitting, watermarking and so on.

The library can be used in applications running on any supported platform (Java 6, .NET 4.0) to manipulate PDF files.

I like the PDF Clown library a lot: how can I help?

Great! There's a wide spectrum of opportunities for volunteering:

  • criticism: to let the project grow, it's important to know its shortcomings and its points of merit (tell us what you like more of PDF Clown and what you disapprove/doubt);
  • real-life requirements/proposals (wishlist): what would be nice to include among the PDF Clown functionalities?
  • culture-specific features: I have a latin-based culture, so it'd be really valuable the contribution of guys from other world regions to address culture-specific issues such as non-latin font management;
  • samples: real-life examples using PDF Clown (did you find an original way to exploit PDF Clown? We'll include such samples in the distribution -- along with your attribution, obviously!);
  • bug reporting: let us know if you discovered any bug using the library;
  • communication: inform your friends/colleagues about this project.
PDF Clown is Open-Source Software: so I can do whatever I want with it, can't I?

Gotcha! Yeah, PDF Clown is Open-Source Software, a special breed of it in fact: Free Software. But being Free Software or simply Open-Source Software doesn't imply that you have an unlimited right upon it!!!

You can do only what's prescribed by the applicable license (LGPL, see below): if you don't agree with this license, you are not allowed to use PDF Clown, neither in binary nor in source form. This license is used especially to protect the product against possible abuses.

PDF Clown is "free" in the sense that its contributors, approving the economical, political and philosophical implications of the FLOSS paradigm, judged beneficial for the community to make it available as a common effort for sharing knowledge, without lucrative bottom lines or oppressive per-user fees.

So if you got any benefit from using PDF Clown, it'd be humanly appreciable to honor our gift supporting this project in any of the following mutualistic ways:

  • contributing code to enhance the library;
  • sharing your expertise with other users;
  • promoting the use of PDF Clown by putting a link on your site, recommending it to other people on mailing lists and user forums, writing articles about it in magazines, and so on;
  • promoting the general adoption of FLOSS by your company, your local administration and your government.

Thank you!

Can PDF Clown be used by commercial applications?

Surely, yes. It suffices that your company agrees to the LGPL: your commercial applications will keep closed and profitable, but any modification (enhancement or bug-fix) to the PDF Clown's implementation that you may have applied will have to be made available as open source at no cost.

It is allowed to use PDF Clown in your own product as long as you don't change the copyright notices. You also have to distribute the source code of PDF Clown to your clients.

So: you can use PDF Clown's library from your commercial software without hassle (LGPL is your friend), but you can't inject PDF Clown's code inside your closed-source commercial software.

See the next FAQ to get further information about LGPL.

LGPL sounds confusing to me: could you explain it?

LGPL is the license applied to the PDF Clown library.

LGPL distinguishes between works *based* on the library and works which *use* the library:

  • [use] your software can be linked (both statically and dynamically) to the PDF Clown library without distributing your source code;
  • [based] if you make any modification to the PDF Clown library, such modified version MUST be distributed along with its source code (including your modifications).

So: your software can *use* the PDF Clown library keeping closed its own code, but if you *adapt* the PDF Clown library, the modified library's source code MUST be distributed. Note that also in the latter case your software can use the PDF Clown library keeping closed its own code.

When you distribute your program you have to respect some requirements:

  • give notice that your program uses PDF Clown, and that PDF Clown is covered by LGPL;
  • supply the PDF Clown library source code, or give notice of the way it can be obtained (mentioning its home URL (http://clown.stefanochizzolini.it) and its repository URL (http://sourceforge.net/projects/clown))
  • supply a copy of the LGPL;
  • if there is a section of your documentation and/or a dialog box displayed by your program that give copyright notices, then you need to show PDF Clown's copyright notice as well.

I am busy with writing a PDF utility myself. Can I get inspiration from inspecting PDF Clown's source code?

Surely, yes. FLOSS is meant to expand knowledge about technical issues and solutions, allowing operators to find better (more effective, less costly) approaches to cope with common problems. But isn't meant to deprive and despoil original contributions in favor of lucrative exploitations. That's unethical and idiotic because it misses the whole point: open source is a value-added asset in itself that derives from the honest collaboration of a community; each participant devolves some effort and receives comparably more benefit from the shared resources, but she relies on the reciprocal fairness of the other agents. Foul play is real shame.

If you are involved in implementing PDF-related functionalities that overlap PDF Clown's, it may be sensible if you consider delegating such functionalities to PDF Clown, extending it the way you like and concentrating yourself on your core value instead: this way you could benefit from a shared, publicly-maintained, consolidated PDF library instead of trying to reinvent the wheel (community debugging, maintenance and contributions could reduce your development costs and efforts).

I invite you to consider embracing the open source model for your PDF manipulation functionality and contributing to PDF Clown's codebase: that would trigger a virtuous circle that will benefit you firstly! If you wanted to preserve your business value, you could decouple your valuable proprietary code from the PDF-library code; this way you could gain the best of the two models: control strategic code and exploit public, well-maintained code.

So: you can "inspire" yourself examining PDF Clown's source code (legal), but you cannot appropriate of portions of it hiding them inside your closed-source code or removing their copyright notices (illegal): PDF Clown is a copyright-protected product, keep in mind!

Getting started

How do I install PDF Clown?

First of all, you need to download its source code distribution (see Downloads page), then uncompress it. This distribution ships with precompiled bytecode along with its source, so that all you have to do to consume it is just to reference its library in your classpath. See README files included in the distribution for more info.

Is there a manual?

Currently, PDF Clown's documentation is fairly uncomplete (sorry!), as it's been only partially written during the past few months. It will be progressively expanded accordingly to your feedback (let me know!). Anyway, available resources to skim through are all attached to the source code distribution: samples (and their documentation), user guide, API Reference, developer guide and metadocumentation (README files, CHANGELOGs, and so on).