pisa_api_en

pisa

Simple PDF generator

(C)opyright by spirito GmbH, 2005-2007

Page 2

IntroductionPDF Markup Language (PML) is a SGML-Dialect that is very similar to HTML and in large parts is also compatible.PML is build o the PDF toolkit of tReportlab (http://www.reportlab.com/). You will find more interesting information inthere documentation, too.

Commands that are not recognized by PML will be ignored. Therefore it should be possible to use normal HTMLwith PML.

The command line toolFor first tests with PML you may want use the command line tool. Under Windows open a DOS shell and changedirectory to where the "pisa.exe" is. Now create a file named "test.pml" containing some text like "Hello World".Now start the translation of PML to PDF like this :

pisa test.pml test.pdf

The result is the new file "test.pdf"which can be viewed with e.g. Adobe Reader. Enter "pisa -h" on the commandline to see a small help and more options.

The Python module

Installation

Install "pisa" as usual e.g. like this:

python setup.py install

Windows users should install the special package.

You will need the reportlab package vesion 1.20 ( http://www.reportlab.com/download.html). For better imagesupport install also the optional PIL package ( http://www.pythonware.com/products/pil/).

Requirements

ReportlabLib: Install the most recent reportlablib starting with version 1.20. You get a nightly snapshot here: <http://reportlab.org/ftp/current.tgz>.

PIL: For integrating images in your PDF you need the Python Imaging Library: <http://www.pythonware.com/products/pil/>. JPG may also work without installation of PIL (XXX).

pyPDF: To integrate a PDF as background of a PDF page you need the pyPDF library in the most recent version <http://pybrary.net/pyPdf/>.

Usage

This is a very simple example:

import spirito.pisa2.pml as pisapdf = pisa.CreatePDF("Hello <b>World</b>", open("test.pdf","wb"))

After starting this program a file named test.pdf will be created with the content "Hello World".

Example

The usual "Hello world" example (all examples start with line numbers):

01: Hello World

Now for something more complex:

http://www.reportlab.com/

http://www.reportlab.com/download.html

http://www.pythonware.com/products/pil/

http://reportlab.org/ftp/current.tgz

http://www.pythonware.com/products/pil/

http://pybrary.net/pyPdf/

Page 3

01: <document pagesize="a4">02: <template name="secondPage">03: <frame box="1cm 1cm 10cm 10cm">04: </template>05: <h1>Hello</h1>06: <ol>07: <li> first08: <li> second09: </ol>10: <nexttemplate name="secondPage">11: <nextpage>12: Top left corner of second page.13: </document>

Exposition: In line 1 some document specific data are defined. From line 2 to 4 a template for the second page ofthe document is defined and will be used in line 10 and 11. The template is named "secondPage" and consits ofone frame with an offset to the paper border of 1cm and a width and height of 10cm. In line 5 the content part startswith a heading and continues with an ordered list, defined like in HTML. Line 12 is printed on the second page asdescribed before.

PositioningUsually the position (0,0) in PDF files is found in the lower left corner. For PML it is the upper left corner like it is forHTML!

Page sizeA lot of page sizes are predefined, for a complete list have a look at the <document> command. The default size is"DIN A4".

Templatesxxx

Tablesxxx

Linksxxx

Imagesxxx

Cascading Style SheetsPML supports a subset of Cascading Style Sheet (CSS). The following styles are supported:

• font-family• font-size• color• line-height• background-color• text-decoration: none, underline• font-weight: bold• text-align: left, center, right, justify• text-indent: italic, oblique• margin

Page 4

• margin-left• margin-right• margin-top• margin-bottom• border (and some derivates like border-right-color) (Just supported within tables for now!)

For now CSS support is not complete, so e.g. the right spelling of font names is important. An advantage is that theusage of sizes like centimeters is supported.

Example

A simple example :

<style type="text/css"></style>

<h1>Heading of first order</h1><p>Mormal <span class="test">text</span></p>

Page 5

API Reference

LegendEach tag is described on by one. It starts with the name of the tag followed by "(block)" if it needs a correspondingclosing tag, like e.g. <p> and </p>. Then the attributes are described in alphabetic order. Required attributes aremarked by a "*". The type describes the expected kind of value. If exists the default value follows in parantesis.

Types

Boolean

True or false. Values for "false" are: "false" and "0" (XXX). All other values are interpreted as "true".

Integer

Number like 123 .

String

Text like "abc".

File

A filename that my be relative like "../test.css" or absolute from the current document root "/test.gif". (XXX)

Font

Name of an installed or imported font. For importing a PS or TTF font see tag <fontembed>. The default font usedby PISA is "Helvetica" (XXX). These fonts are predefined by default for PDF:

CourierCourier-BoldCourier-BoldObliqueCourier-ObliqueHelveticaHelvetica-BoldHelvetica-BoldObliqueHelvetica-ObliqueSymbolTimes-BoldTimes-BoldItalicTimes-ItalicTimes-RomanZapf-Dingbats

Color

Color value. Usually RGB color definitions written as hexadecimal are used like "#ff0000" or "#f00". Some colornames are also supported like "red", "green", "blue", ... (Full list in Reportlab Toolkit).

Size

Floating point value representing points (not pixels!) the standard mesure in PDF. You may also use other units likethese:

• "cm" for centimeters• "mm" for milimeters• "i", "in" or "inch" for inches• "pt" or "px" for points• (XXX)

Page 6

Style

Name of CSS style.

Box

A group of for "sizes" that are separated by spaces. The first and second value represent the X and Y coordinatesof the left upper corner. The third and fourth values represent the width and height of the box. These last twovalues may also be negative values, than they define the lower right corner seen as offset of the lower right cornerof the page. The value "1cm 1cm -1cm -1cm" means for example that the box has a marigin of 1cm on each sidefrom the papers border.

Position

Two values separated by spaces representing a position form the uper left corner. (XXX) Negative values arerelative offsets to the lower right corner..

Choice

One value out of a predefined set of values listed in the attributes definition.

Page 7

TagsDefinitions of tags supported by PML:

a (block)

class Class [default: 'a']href Stringname Stringstyle Style

Like HTML. Examples:

<a href="#test">zur nächsten Seite</a>.<nextpage><a name="test"></a>Neue Seite

b (block)

class Class [default: 'b']style Style

Q.v. <strong>.

br

class Class [default: 'br']style Style

Line break.

dd (block)

class Class [default: 'dd']style Style

Description part of definiton liste. Q.v. <dl>.

div (block)

align Choice 'left', 'center', 'right', 'justify'class Class [default: 'div']style Style

Q.v. <p>.

dl (block)

class Class [default: 'dl']style Style

Definition list.

document (block)

author Stringduration Integerformat Choice 'a0', 'a1', 'a2', 'a3', 'a4', 'a5', 'a6', 'b0', 'b1', 'b2', 'b3', 'b4', 'b5', 'b6', 'letter', 'legal',

'elevenseventeen' [default: 'a4']fullscreen Boolean [default: '0']orientation Choice 'portrait', 'landscape'outline Integer

Page 8

showoutline Boolean [default: '0']subject Stringtitle String

First tag of a document wich defines the essential attributes of the PDF document. "format" defines the size of thepages. "orientation" is one of "portrait" and "landscape". "author" and "title" will be part of the documentsinformations. "fullscreen" should open the PDF using the full screen, if the viewer supports the option."showoutline" shows the headings for navigation (but not if you use watermarks by <template background="xyz"!).

drawimg

align Choice 'left', 'center', 'right' [default: 'right']height Sizepos* Positionsrc* Filevalign Choice 'top', 'middle', 'bottom' [default: 'bottom']width Size

Only useable within <static>. Draws an image at a position. May be used for simple backgrounds and watermarks.

drawline

color Color [default: '#000000']from* Positionto* Positionwidth Size [default: '1']

Only useable within <static>. Draws a line. Example:

<drawline from="1cm 1cm" to="-1cm -1cm">

drawlines

color Color [default: '#000000']coords* Stringwidth Size [default: '1']

Only useable within <static>. Draws multiple lines. Example:

<drawlines coords="1cm 1cm 1cm -1cm -1cm -1cm -1cm 1cm 1cm 1cm">

drawpoint

color Color [default: '#000000']pos* Positionwidth Size [default: '1']

Only useable within <static>. Draws a point.

drawstring

align Choice 'left', 'center', 'right' [default: 'right']class Classcolor Color [default: '#000000']pos* Positionrotate Integer [default: '0']text* Stringvalign Choice 'top', 'middle', 'bottom' [default: 'bottom']

Only useable within <static>.Draws text at a certain position.

dt (block)

class Class [default: 'dt']

Page 9

style Style

Definition part of the definition list. Q.v. <dl>.

em (block)

class Class [default: 'em']style Style

Emphasize that means italic. Same as <i>.

font (block)

color Colorface Fontsize Size

Font face and font size. Better use CSS.

fontembed

afm Filealias Stringencoding String [default: 'WinAnsiEncoding']name Stringpfb Fileprint Boolean [default: '0']ttf File

Embeds PostScript fonts. Files of the formats AFM and PFB are needed. For TrueType fints you need TTF files.The attribute "print" shows the real name of a PostScript font. Examples:

<fontembed ttf="vera.ttf" name="tfont"><fontembed afm="leerc.afm" pfb="leerc.pfb" name="pfont"><p><font face="tfont">TrueType, Umlaute: äöü</font></p><p><font face="pfont">PostScript, Umlaute: äöü</font></p

frame

border Boolean [default: '0']box* Boxname String

Q.v. template.

h1 (block)

class Class [default: 'h1']closed Integeroutline Stringstyle Style

Header of 1st order. With "outline" you specify the name under wich this header may be reached via the PDFoutline structure.

h2 (block)


Page 10

Header of 2nd order. Q.v. <h1>.

h3 (block)


Header of 3rd order. Q.v. <h1>.

h4 (block)


Header of 4th order. Q.v. <h1>.

h5 (block)



h6 (block)



hr

class Class [default: 'hr']color Color [default: '#000000']size Size [default: '1']style Style

Horizontal rule. Set "color" to change its appearance.

i (block)

class Class [default: 'i']style Style

Q.v. <em>.

img

align Choice 'left', 'center', 'right' [default: 'left']class Class [default: 'img']height Sizesrc* Filestyle Stylewidth Size

Inserts an image into the document. You should use the JPEG format since this is the native format for bitmap

pisa_en.html#h1

pisa_en.html#h1

pisa_en.html#h1

pisa_en.html#h1

Page 11

images in PDF, but you may also use any other format as long as the PIL library for Python is installed.(Experimental: SVG format is suported if the files suffix is "svg"). (XXX)

keepinframe (block)

maxheight Sizemaxwidth Sizemergespace Integer [default: '1']mode Choice 'error', 'overflow', 'shrink', 'truncate' [default: 'shrink']name String

Tries to keep block in one frame. This is very usefull for usage in tables, because big table cells may cause errorsin ReportLab toolkit. Then you better put a <keepinframe> around data to avoid these exceptions and get allinformations of the table shown. Mode can be one of: "error", raise an error in the normal way; "overflow", ignore iejust draw it and report maxWidth, maxHeight; "shrink", shrinkToFit (is the default); "truncate", fit as much aspossible. Example:

<table><tr><td><keepinframe maxwidth="10cm" maxheight="10cm">A lot of ... data</keepinframe></td></tr></table>

keeptogether (block)

Tries to keep the block in the same frame. Example:

<keeptogether><h1>Überschrift</h1><p>Text</p></keeptogether

li (block)

class Class [default: 'li']style Style

List element. Q.v. <ol> and <ul>.

link

href* Filerel String [default: 'stylesheet']type String [default: 'text/css']

Loads external CSS file.

nextframe

Jump to next unused frame on the same page or to the first on a new page. You may not jump to a named frame.

nextpage

template String

Create a new page after this position.

nexttemplate

name String [default: 'default']

Defines the template to be used on the next page.

Page 12

ol (block)

class Class [default: 'ol']style Styletype Choice '1', 'a', 'A', 'i', 'I' [default: '1']

Ordered list.

p (block)

align Choice 'left', 'center', 'right', 'justify'class Class [default: 'p']style Style

Paragraph.

pagenumber

example String [default: '0']

Prints current page number. The argument "example" defines the space the page number will require e.g. "00".

pdfclass

after Sizealign Choice 'left', 'right', 'center', 'justify'before Sizebgcolor Colorbold Booleanbulletfont Fontbulletindent Sizebulletsize Sizecolor Colorfirst Sizefont Fontitalic Booleanleading Sizeleft Sizename Stringparent String [default: 'default']right Sizesize Sizeunderline Booleanunderlinecolor Color

DEPRECATED! This one is for backward compatibility and work like the former <class> tag.

pre (block)

class Class [default: 'pre']style Style

Preformatted text.

spacer

height* Size

Creates an object of a specific size.

span (block)

class Class [default: 'span']

Page 13

style Style

Like HTML.

static (block)

border Boolean [default: '0']box* Boxname String

Q.v. template.

strong (block)

class Class [default: 'strong']style Style

Bold face. Q.v. <b>.

sub (block)

class Class [default: 'sub']style Style

Subscript.

sup (block)

class Class [default: 'sup']style Style

Q.v. <super>.

super (block)

class Class [default: 'super']style Style

Superscript.

table (block)

align Choice 'left', 'center', 'right' [default: 'left']bgcolor Colorborder Size [default: '0']bordercolor Color [default: '#000000']cellpadding Size [default: '1']class Class [default: 'table']keepmaxheight Sizekeepmaxwidth Sizekeepmergespace Integer [default: '1']keepmode Choice 'error', 'overflow', 'shrink', 'truncate' [default: 'shrink']repeat Integer [default: '0']style Stylevalign Choice 'top', 'bottom', 'middle' [default: 'middle']width String

Like HTML.

The "repeat" attribute sets the number of rows that are repeated if the table continues in a new frame. That is aneasy way to create consistant table headings.

Complex example:

Page 14

<table align="left" grid=#666666><tr><td width="8.0cm" bgcolor="#dddddd"><p style=myleft><b>Beschreibung</b></td><td width="1.6cm" bgcolor="#dddddd"><p style=myright><b>Menge</b></td><td width="3cm" bgcolor="#dddddd"><p style=myright><b>Einzelpreis</b></td><td width="3cm" bgcolor="#dddddd"><p style=myright><b>Betrag</b></td></tr></table>

If you have trouble with table cells that are to big for one page you have two workarounds. First you may sourroundthe cell content with a <keepinframe> tag, second add equivalent attributes to the table tag. Example:

<table keepmaxwidth="14cm" keepmaxheight="20cm" width="100%">...</table>

td (block)

align Choice 'left', 'center', 'right', 'justify'bgcolor Colorborder Sizebordercolor Color [default: '#000000']class Class [default: 'td']colspan Integerrowspan Integerstyle Stylevalign Choice 'top', 'bottom', 'middle'width String

Table column.

template (block)

background Fileformat Choice 'a0', 'a1', 'a2', 'a3', 'a4', 'a5', 'a6', 'b0', 'b1', 'b2', 'b3', 'b4', 'b5', 'b6', 'letter', 'legal',

'elevenseventeen' [default: 'a4']name String [default: 'default']orientation Choice 'portrait', 'landscape'

Defines the boxes resp. frames of a page in which the text flows. If a frame is full the next frame is used for thetext. And if the last frame of the page is full a new page is opened and there we start again with the first frame. Sothe order of the frame definition is important! Frames that always contain the same text like e.g. title the of a bookrepeated on each page, are called "static".

The template of the first page is called "default" and contains in the standard definition one frame with 1cmmargins. This template definiton can be overridden to change the layout of the first page.

The attribute "background" defines a PDF file that is set into the background of the current page. If this doesn'twork it often helps to re-print the watermark PDF with Ghostscript again. If you use "background" the outlines arelost (q.v. h1).

Q.v. frame and static.

Page 15

An example:

<template name="default"><frame name="head"box="17,3cm 2.8cm 3.3cm 20cm"><frame name="address"box="2.7cm 5.0cm 8.57cm 4.00cm"><frame name="body"box="3.5cm 10.5cm 13.9cm 17.5cm"></template>

<template name="sub"><static box="1cm 1cm 13,9cm 1cm">The big book, page <pagenumber>.</static><frame name="c"box="3.5cm 3.5cm 13.9cm 17.5cm"></template>

th (block)

align Choice 'left', 'center', 'right', 'justify'bgcolor Colorborder Sizebordercolor Color [default: '#000000']class Class [default: 'th']colspan Integerrowspan Integerstyle Stylevalign Choice 'top', 'bottom', 'middle'width String

Table head.

tr (block)

bgcolor Colorborder Sizebordercolor Color [default: '#000000']class Class [default: 'tr']style Stylevalign Choice 'top', 'bottom', 'middle'

Table row.

u (block)

class Class [default: 'u']style Style

Underlined.

ul (block)

class Class [default: 'ul']style Styletype Choice 'circle', 'disk', 'square' [default: 'disk']

Ungeordered list.

version

Prints the version number of current PISA.

Page 16

Known bugs• (XXX)

Future• Better usage of TTF fonts• Basis drawing functions• Better CSS support• Background pictures and PDF• SVG integration• Improve list feature• Improve PRE• Pagenumbers without need of "example" and page total• Table of content generation• Recent date• Title of document

Legal noticePISA is copyright by Dirk Holtwick, Germany.

PISA is distributed by spirito GmbH, Otawistr. 19, 47249 Duisburg, Germany, < http://www.spirito.de>, phone+49.203.3187777.

PISA is licensed under the Q Public License v1.0.

For commercial usage of PISA a developer license can be purchased at spirito GmbH, <[email protected]>.

http://www.spirito.de

mailto:[email protected]

Page 17

Q Public License v1.0Copyright © 1999 Trolltech AS, Norway.

Everyone is permitted to copy and distribute this license document.

The intent of this license is to establish freedom to share and change the software regulated by this license underthe open source model.

This license applies to any software containing a notice placed by the copyright holder saying that it may bedistributed under the terms of the Q Public License version 1.0. Such software is herein referred to as the Software.This license covers modification and distribution of the Software, use of third-party application programs based onthe Software, and development of free software which uses the Software.

Granted Rights

1. You are granted the non-exclusive rights set forth in this license provided you agree to and comply with any andall conditions in this license. Whole or partial distribution of the Software, or software items that link with theSoftware, in any form signifies acceptance of this license.

2. You may copy and distribute the Software in unmodified form provided that the entire package, including - butnot restricted to - copyright, trademark notices and disclaimers, as released by the initial developer of the Software,is distributed.

3. You may make modifications to the Software and distribute your modifications, in a form that is separate from theSoftware, such as patches. The following restrictions apply to modifications:

a. Modifications must not alter or remove any copyright notices in the Software.

b. When modifications to the Software are released under this license, a non-exclusive royalty-free right is grantedto the initial developer of the Software to distribute your modification in future versions of the Software providedsuch versions remain available under these terms in addition to any other license(s) of the initial developer.

4. You may distribute machine-executable forms of the Software or machine-executable forms of modified versionsof the Software, provided that you meet these restrictions:

a. You must include this license document in the distribution.

b. You must ensure that all recipients of the machine-executable forms are also able to receive the completemachine-readable source code to the distributed Software, including all modifications, without any charge beyondthe costs of data transfer, and place prominent notices in the distribution explaining this.

c. You must ensure that all modifications included in the machine-executable forms are available under the terms ofthis license.

5. You may use the original or modified versions of the Software to compile, link and run application programslegally developed by you or by others.

6. You may develop application programs, reusable components and other software items that link with the originalor modified versions of the Software. These items, when distributed, are subject to the following requirements:

a. You must ensure that all recipients of machine-executable forms of these items are also able to receive and usethe complete machine-readable source code to the items without any charge beyond the costs of data transfer.

b. You must explicitly license all recipients of your items to use and re-distribute original and modified versions ofthe items in both machine-executable and source code forms. The recipients must be able to do so without anycharges whatsoever, and they must be able to re-distribute to anyone they choose.

c. If the items are not available to the general public, and the initial developer of the Software requests a copy ofthe items, then you must supply one.

Limitations of Liability

In no event shall the initial developers or copyright holders be liable for any damages whatsoever, including - but

Page 18

not restricted to - lost revenue or profits or other direct, indirect, special, incidental or consequential damages, evenif they have been advised of the possibility of such damages, except to the extent invariable law, if any, providesotherwise.

No Warranty

The Software and this license document are provided AS IS with NO WARRANTY OF ANY KIND, INCLUDINGTHE WARRANTY OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.

Choice of Law

This license is governed by the Laws of Norway. Disputes shall be settled by Oslo City Court.

Documents

pisa_api_en