Repository files navigation

Prawn is a pure Ruby PDF generation library that provides a lot of greatfunctionality while trying to remain simple and reasonably performant. Here aresome of the important features we provide:

• Vector drawing support, including lines, polygons, curves, ellipses, etc.
• Extensive text rendering support, including flowing text and limited inlineformatting options.
• Support for both PDF builtin fonts as well as embedded TrueType fonts
• A variety of low level tools for basic layout needs, including a simple gridsystem
• PNG and JPG image embedding, with flexible scaling options
• Security features including encryption and password protection
• Tools for rendering repeatable content (i.e headers, footers, and pagenumbers)
• Comprehensive internationalization features, including full support for UTF-8based fonts, right-to-left text rendering, fallback font support, and extensionpoints for customizable text wrapping.
• Support for PDF outlines for document navigation
• Low level PDF features, allowing users to create custom extensions by droppingdown all the way to the PDF object tree layer. (Mostly useful to those withknowledge of the PDF specification)
• Lots of other stuff!

If you are looking for a highly flexible PDF document generation system, Prawnmight be the tool for you. It is not a reporting tool or a publishing toolchain,though it could be fairly easily used to build those things.

One thing Prawn is not, and will never be, is an HTML to PDF generator. Forthose needs, consider looking intoFerrum. We do have basic support for inline stylingbut it is limited to a very small subset of functionality and is not suitablefor rendering rich HTML documents.

Because Prawn is pure Ruby and all of its runtime dependencies are maintained byus, it should work pretty much anywhere. We officially support all Ruby versionssuported by Ruby Core Team and JRuby versions of matching Ruby version. Howeverwe will accept patches to fix problems on other Ruby platforms if they aren'ttoo invasive.

Prawn is distributed via RubyGems, and can be installed the usual way that youinstall gems: by simply typinggem install prawn on the command line.

You can also install from git if you'd like, themaster branch contains thelatest developments. We're trying to keepmaster branch in working order butyou may encounter some rough edges and fresh bugs along with bugfixes. Weencourage you to trymaster branch with your application.

If the following code runs and produces a working PDF file, you've successfullyinstalled Prawn.

require"prawn"Prawn::Document.generate("hello.pdf")dotext"Hello World!"end

Of course, you'll probably want to do more interesting things than that...

The manual is a series of examples that demonstrate use of the wide range offeatures Prawn provides. You can get a generated version of the latest releasedPrawn version on thePrawn website. The examplesthemselves can be found in themanual directory in this repository.

Please note that while the manual is a great introduction and guide to Prawnit's not exhaustive. Please refer to API docs for more complete information onwhat Prawn provides and how to use it.

To build the manual, here's what you need to do:

1. Clone the repository
2. Rungem install -g
3. Runrake manual, which will generatemanual.pdf in the project root

We're trying to not break things unnecessarily but we don't formally followSemantic Versioning. The reason is that we release a number of experimentalAPIs. We don't make any promises on their stability. You can assume the stableportion of the API follows Semantic Versioning.

Also note that bug fixes can change behaviour. We don't consider that to bea breaking change for the purposes of versioning. Please test your applicationsafter updating Prawn.

Be sure to read the release notes inCHANGELOG.md eachtime we cut a new release, and lock your gems accordingly.

The easiest way to get help with Prawn is to post a message to ourDiscussions.

Feel free to post any Prawn related question there, our community is veryresponsive and will be happy to help you figure out how to use Prawn, or helpyou determine whether it's the right tool for the task you are working on.

Please make your posts as specific as possible, including code samples andoutput where relevant. Do not post any information that should not be sharedpublicly, and be sure to reduce your example code as much as possible so thatthose who are responding to your question can more easily see what the issuemight be.

Prawn adheres to theContributor Covenant. Unacceptablebehavior can be reported toconduct@prawnpdf.org which is monitored by the coreteam.

If you've found a bug or want to submit a patch, please enter a ticket into ourGitHub tracker.

We strongly encourage bug reports to come with failing tests or at least areduced example that demonstrates the problem. Similarly, patches should includetests, API documentation, and an update to the manual where relevant. Feel freeto send a pull request early though, if you just want some feedback or a codereview before preparing your code to be merged.

If you are unsure about whether or not you've found a bug, or want to check tosee whether we'd be interested in the feature you want to add before you startworking on it, feel free to post to our mailing list.

You can run our test suite in a few different ways:

1. Runningrake will run the entire test suite excluding any unresolved issues
2. Runningrspec will run the entire test suite including unresolved issues
3. Runningrspec -t unresolved will runonly unresolved issues
4. Runningrspec -t issue:NUMBER will run the tests for a specific issue

These filters make it possible for us to add failing test cases for bugs thatare currently being researched or worked on, without breaking the typical fullsuite run.

Prawn has always been heavily dependent on community contributions, with dozensof people contributing code over the years. In that sense, the lines haveblurred to the point where we no longer have a strong distinction between coredevelopers and contributors.

That said, there are a few folks who have been responsible for cutting releases,merging important pull requests, and making major decisions about the overalldirection of the project.

These are the folks to contact if you have a maintenance-related issue withPrawn:

• Alexander Mankuta (PointlessOne)

These folks have helped out in a maintenance role in the past, but are no longeractively involved in the project:

• Gregory Brown (practicingruby)
• Brad Ediger (bradediger)
• James Healy (yob)
• Daniel Nelson (Bluejade)
• Jonathan Greenberg (jonsgreen)
• Jamis Buck (jamis)
• Evan Sharp (PacketMonkey)

Prawn is released under a slightly modified form of the License of Ruby,allowing you to choose between Matz's terms, the GPLv2, or GPLv3. For details,please see the LICENSE, GPLv2, and GPLv3 files.

If you contribute to Prawn, you will retain your own copyright but must agree tolicense your code under the same terms as the project itself.

Prawn was originally developed byGregoryBrown, under the auspices of the RubyMendicant Project, a grassroots initiative in which the Ruby communitycollectively provided funding so that Gregory could take several months off fromwork to focus on this project.

Over the last several years, we've received code contributions from dozens ofpeople, which is amazing considering the low-level nature of this project. Youcan find the full list of folks who have at least one patch accepted to Prawn onGitHubContributors page.

After a long period of inactivity, Prawn reached its 1.0 milestone in 2014thanks to some modest funding provided to Gregory by Madriska, Inc. (BradEdiger's company).