WARNING: Version 2.0 may break code due to the Unicode changes! See below
Many new features have been added, foremost amongst which is the support for unicode. This page
documents what has changed since version 1.20 in November 2004.
Goals for the 2.x series
The main rationale for 2.0 was an incompatible change at the character level: to properly support Unicode
input, with UTF8 throughout. Now that it's out we will maintain compatibility with 2.0. There are no pressing feature
wishlists and new features will be driven, as always, by contributions and the demands of projects.
New Features
General unicode support
The library now assumes all 8-bit input to Report Markup Language, Diagra and all Python APIs is UTF8; Python APIs accept Unicode objects as well.
This means that a large number of things that needed attention before "just work™". However,
if your app previously used anything beyond ASCII, you will need to make the necessary changes.
Report Markup Language
Pure UTF8 input
In previous versions, the RML input was assumed to be in the same encoding
as the fonts selected for output. If yo used built-in fonts throughout and Latin-1
text, you'd be fine; likewise if you used UTF8 input text and embedded TrueType fonts.
But if you used a TrueType font for a header and Helvetica for the body, you had to
encode accents and symbols differently. From now on the input files are supposed to
be pure UTF8 (as XML should be), and we handle the necessary font conversions when writing PDF
Change to DOCTYPE declaration
Since version 1.0 in 2000, the DTD has been named and referred to as rml_1_0.dtd.
However, we have made numerous additive changes over the last five years; our language does not
evolve as XML standards do, with a single correct language definition issued every 2-3 years. Bumping
the DTD number up on each change (and in particular to rml_2_0.dtd now would create work
for us and for all of customers and possible confusion. Because of
this we've shortened the recommended DTD name to rml.dtd. However, the parser will
accept all valid previous names. Just remember that features are determined by the version of
our software you are running, not the formal declaration.
XML standards purists will no doubt recoil at this; but they will presumably be using XSL-FO
rather than RML anyway ;-)
KeepInFrame tag
Sometimes the length of a piece of text you'd like to include in a fixed piece of
page "real estate" is not guaranteed to be constrained to a fixed maximum length. This is
particularly common with "fact sheet" layouts. The KeepInFrame tag makes such
layouts much easier - you can specify the content a frame should go into and it will
automatically skip to that frame. KeepInFrame also allows you to specify an appropriate action to
take when the text is too long for the space allocated for it. In particular, it can
shrink the text to fit, mask (truncate) overflowing text,
allow the text to overflow into the rest of the document, or raise an
error.
Link support in paragraphs
Platypus paragraphs can now contain link elements, which support both
internal links to the same PDF document, links to other local PDF documents, and URL
links to pages on the web. Some examples:
Improved convenience features for inserting unicode symbols and other characters
<unichar/> lets you conveniently insert unicode characters using the standard
long name or code point. Characters inserted with the <greek> tags
(e.g. <greek>lambda<greek>) or corresponding entity references (e.g. λ)
support arbitrary fonts (rather than only Zapf Dingbats).
Table spans and splitting improved
Cell spanning in tables used to go wrong sometimes when the table split over a page. We
believe this is improved, although there are so many table features that it's
hard to define correct behaviour in all cases.
keepWithNext attribute of paragraph styles
The keepWithNext attribute of paragraph styles now works robustly. This is the most basic
and important tool in widows-and-orphans control; you can specify that your heading styles should
always be kept together with the following paragraph, and they will never again appear at the
bottom of the page.
imageAndFlowables tag
The imageAndFlowables tag lets you flow text around an image. It offers the usual
attributes for specifying an image, padding on all four sides, and the option to place the image
to the left or right of the enclosing frame. A working example can be found on the last page of output
of test_002_paras.
PDF Images
The image tag now lets you bring in PDF files as images. If you have vector
artwork, logos or maps available to you as EPS, you can now distill them to PDF and use them with
far less code than before.
New image positioning attributes
The image tag now offers two new boolean attributes, preserveAspectRatio
and showBoundary, to aid positioning. The former will allow you to specify a bounding
box, and will scale the image to fit in the center of the box irrespective of its shape; this can cut
out large amounts of template calculations when positioning variable sized images. showBoundary
is very useful when working with images with a white/transparent background.
Variable image names
Images can now take a variable filename (in the file attribute). RML has a limited
ability to create variables with the namedString tag. These variables can now be used
within an image file name. This can be very useful when you want to have an image in the page template -
for example in a header or footer - which is always in the same place, but varies according to the chapter
of a document or position in the story. This could be used as follows: <image x="20" y="20" width="100" height="120" file="rml:customerImageName"/>
You can use namedString in your RML-generating main loop to set the variable, which will
be dynamically evaluated each time it is called.
Better Asian font support
Since all input is now UTF8, the encoding attribute is no longer needed when registering a CID Font.
We can also now load Asian TrueType fonts, some of which carry a .ttc extension, including the popular
MS Mincho and MS Gothic. However please note that parsing a 5Mb font file is not instantaneous; the use
of the CID fonts in the Adobe Reader language packs is faster as no content needs to go into the PDF file.
Chinese/Japanese/Korean (CJK) text wrapping
If you set the new wordWrap attribute of the paraStyle tag to "CJK",
it will enable a new wrapping algorithm. CJK text lacks spaces between words which made paragraphs unworkable
in 1.x. The new algorithm cannot yet handle multiple fragments in different fonts or languages in a paragraph.
It implements a basic "kinsoku shori" scheme whereby lines should hardly ever start with a punctuation mark
or closing bracket, nor end with an opening bracket; in such cases one more character is pushed into the
right margin. We'll be working to improve this further in the next release, as we are hosting substantial
Japanese language applications now.
Native support for JPEG CMYK images
ReportLab now takes advantage of PDF's native JPEG CMYK image support, so that JPEG
CMYK images are no longer (lossily) converted to RGB format before including them in
PDF.
Diagra
There have been extensive changes to Diagra to aid support and deployment in the field,
especially for customers doing batch data-aware drawings.
Visual run mode in Drawing Editor
You can now use File | GO to watch it step through charts visually,
limiting the maximum run size and overriding many parameters for the run in progress if you wish.
This helps in development and allows you to look for extreme cases in the data
save and replay command line options
If you run a chart with the save option, it will connect to a data source and save the data
in a local file ending in .dat. You can then use the replay option to generate charts off this
without even importing the database adaptor. This lets you take data on the road; quickly rerun
jobs which need extensive queries; and (most importantly of all) contact us for support by sending
through your chart AND the data causing the problem.
max command line option
You can now limit the number of charts in a run; this is very helpful when trying out
the first 3-5 charts on a query which might return thousands of rows.
Config files to override chart settings
A new, optional configuration file can take precedence over 'coded' chart properties.
Typically you would use this to set database connection parameters for a directory of
charts, but it can also apply an overall scale factor, change colours and modify many
other properties. This should allow you to have a small set of basic charts, and create
'variant families' without touching the code.
Barcodes
Support for generating barcodes has been added as an officially supported component
(this used to live separately in our contributions area). This has now seen real
production use and testing, with new support for the standard European EAN barcode types
(EAN 8 and EAN 13). Supported barcode types ("symbologies") include: EAN 8 and EAN13,
I2of5, Code128, Standard93, Extended93, Standard39, Extended39, MSI, Codabar, Code11,
FIM, POSTNET.
Improvements to Legending
Instead of manual placement, there is now a attachment point (N, S, E, W, etc.), so
that the legend is always automatically positioned correctly relative to the chart.
Swatches (the small sample squares of colour / pattern fill sometimes displayed in the
legend) can now be automatically created from the graph data. Legends can now have
automatically-computed totals (useful for financial applications).
More and better ways to place piechart labels
New smart algorithms for automatic pie chart label positioning have been added. You
can now produce nice-looking labels without manual positioning even for awkward cases in
big runs of charts.
Adjustable piechart slice ordering
For example. pie charts with lots of small slices can be configured to alternate
thin and thick slices to help the label placement algorithm work better.
Improved spiderplots
Noteworthy bug fixes
Fixes to TTF splitting (patch from Albertas Agejevas)
This affected some documents using font subsetting
Tables with spans improved splitting
Splitting of tables across pages did not work correctly when the table had row/column
spans
