Pisa Api en

pisa
Simple PDF generator
(C)opyright by spirito GmbH, 2005-2007

Introduction
PDF 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 in
there documentation, too.
Commands that are not recognized by PML will be ignored. Therefore it should be possible to use normal HTML
with PML.
The command line tool

For first tests with PML you may want use the command line tool. Under Windows open a DOS shell and change
directory 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 command
line 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 image
support 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 pisa

pdf = 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:
Page 2
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> first
08: <li> second
09: </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 of
the document is defined and will be used in line 10 and 11. The template is named "secondPage" and consits of
one frame with an offset to the paper border of 1cm and a width and height of 10cm. In line 5 the content part starts
with a heading and continues with an ordered list, defined like in HTML. Line 12 is printed on the second page as
described before.
Positioning
Usually 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 for
HTML!
Page size
A lot of page sizes are predefined, for a complete list have a look at the <document> command. The default size is
"DIN A4".
Templates
xxx
Tables
xxx
Links
xxx
Images
xxx
Cascading Style Sheets

PML 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 3
• 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 the
usage 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 4
API Reference
Legend
Each tag is described on by one. It starts with the name of the tag followed by "(block)" if it needs a corresponding
closing tag, like e.g. <p> and </p>. Then the attributes are described in alphabetic order. Required attributes are
marked 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 used
by PISA is "Helvetica" (XXX). These fonts are predefined by default for PDF:
Courier
Courier-Bold
Courier-BoldOblique
Courier-Oblique
Helvetica
Helvetica-Bold
Helvetica-BoldOblique
Helvetica-Oblique
Symbol
Times-Bold
Times-BoldItalic
Times-Italic
Times-Roman
Zapf-Dingbats
Color
Color value. Usually RGB color definitions written as hexadecimal are used like "#ff0000" or "#f00". Some color
names 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 like
these:
• "cm" for centimeters

• "mm" for milimeters
• "i", "in" or "inch" for inches
• "pt" or "px" for points
• (XXX)
Page 5
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 coordinates
of the left upper corner. The third and fourth values represent the width and height of the box. These last two
values may also be negative values, than they define the lower right corner seen as offset of the lower right corner
of the page. The value "1cm 1cm -1cm -1cm" means for example that the box has a marigin of 1cm on each side
from the papers border.
Position
Two values separated by spaces representing a position form the uper left corner. (XXX) Negative values are
relative offsets to the lower right corner..
Choice
One value out of a predefined set of values listed in the attributes definition.
Page 6
Tags
Definitions of tags supported by PML:
a (block)
class Class [default: 'a']
href String
name String
style 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 String
duration Integer
format 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 7
showoutline Boolean [default: '0']
subject String
title String
First tag of a document wich defines the essential attributes of the PDF document. "format" defines the size of the
pages. "orientation" is one of "portrait" and "landscape". "author" and "title" will be part of the documents
informations. "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 Size
pos* Position
src* File
valign 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* Position
to* Position
width Size [default: '1']
Only useable within <static>. Draws a line. Example:
<drawline from="1cm 1cm" to="-1cm -1cm">
drawlines
coords* String
Only useable within <static>. Draws multiple lines. Example:
<drawlines coords="1cm 1cm 1cm -1cm -1cm -1cm -1cm 1cm 1cm 1cm">
drawpoint
pos* Position
Only useable within <static>. Draws a point.
drawstring
align Choice 'left', 'center', 'right' [default: 'right']
class Class
pos* Position
rotate Integer [default: '0']
text* String
valign Choice 'top', 'middle', 'bottom' [default: 'bottom']
Only useable within <static>.Draws text at a certain position.
dt (block)
class Class [default: 'dt']
Page 8
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 Color
face Font
size Size
Font face and font size. Better use CSS.
fontembed
afm File
alias String
encoding String [default: 'WinAnsiEncoding']
name String
pfb File
print 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* Box
name String
Q.v. template.
h1 (block)
class Class [default: 'h1']
closed Integer
outline String
style Style
Header of 1st order. With "outline" you specify the name under wich this header may be reached via the PDF
outline structure.
h2 (block)
closed Integer
outline String
style Style
Page 9
Header of 2nd order. Q.v. <h1>.
h3 (block)
closed Integer
outline String
style Style
Header of 3rd order. Q.v. <h1>.
h4 (block)
closed Integer
outline String
style Style
Header of 4th order. Q.v. <h1>.
h5 (block)
closed Integer
outline String
style Style
h6 (block)
closed Integer
outline String
style Style
hr
class Class [default: 'hr']
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 Size
src* File
style Style
width Size
Inserts an image into the document. You should use the JPEG format since this is the native format for bitmap
Page 10
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 Size
maxwidth Size
mergespace 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 errors
in ReportLab toolkit. Then you better put a <keepinframe> around data to avoid these exceptions and get all
informations of the table shown. Mode can be one of: "error", raise an error in the normal way; "overflow", ignore ie
just draw it and report maxWidth, maxHeight; "shrink", shrinkToFit (is the default); "truncate", fit as much as
possible. 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* File
rel 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 11
ol (block)
class Class [default: 'ol']
style Style
type Choice '1', 'a', 'A', 'i', 'I' [default: '1']
Ordered list.
p (block)
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 Size
align Choice 'left', 'right', 'center', 'justify'
before Size
bgcolor Color
bold Boolean
bulletfont Font
bulletindent Size
bulletsize Size
color Color
first Size
font Font
italic Boolean
leading Size
left Size
name String
parent String [default: 'default']
right Size
size Size
underline Boolean
underlinecolor 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 12
style Style
Like HTML.
static (block)
border Boolean [default: '0']
box* Box
name 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 Color
border Size [default: '0']
bordercolor Color [default: '#000000']
cellpadding Size [default: '1']
class Class [default: 'table']
keepmaxheight Size
keepmaxwidth Size
keepmergespace Integer [default: '1']
keepmode Choice 'error', 'overflow', 'shrink', 'truncate' [default: 'shrink']
repeat Integer [default: '0']
style Style
valign 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 an
easy way to create consistant table headings.
Complex example:
Page 13
<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 sourround
the 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)
bgcolor Color
border Size
class Class [default: 'td']
colspan Integer
rowspan Integer
style Style
valign Choice 'top', 'bottom', 'middle'
width String
Table column.
template (block)
background File
format 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 the
text. And if the last frame of the page is full a new page is opened and there we start again with the first frame. So
the order of the frame definition is important! Frames that always contain the same text like e.g. title the of a book
repeated on each page, are called "static".
The template of the first page is called "default" and contains in the standard definition one frame with 1cm
margins. 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't
work it often helps to re-print the watermark PDF with Ghostscript again. If you use "background" the outlines are
lost (q.v. h1).
Q.v. frame and static.
Page 14
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)
bgcolor Color
border Size
class Class [default: 'th']
colspan Integer
rowspan Integer
style Style
width String
Table head.
tr (block)
bgcolor Color
border Size
class Class [default: 'tr']
style Style
Table row.
u (block)
class Class [default: 'u']
style Style
Underlined.
ul (block)
class Class [default: 'ul']
style Style
type Choice 'circle', 'disk', 'square' [default: 'disk']
Ungeordered list.
version
Prints the version number of current PISA.
Page 15
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 notice
PISA 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, <pisa@spirito.de>.
Page 16
Q Public License v1.0
Copyright © 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 under
the open source model.
This license applies to any software containing a notice placed by the copyright holder saying that it may be
distributed 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 on
the 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 and
all conditions in this license. Whole or partial distribution of the Software, or software items that link with the
Software, 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 - but
not 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 the
Software, 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 granted
to the initial developer of the Software to distribute your modification in future versions of the Software provided
such 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 versions
of 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 complete
machine-readable source code to the distributed Software, including all modifications, without any charge beyond
the 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 of
this license.
5. You may use the original or modified versions of the Software to compile, link and run application programs
legally developed by you or by others.
6. You may develop application programs, reusable components and other software items that link with the original
or 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 use
the 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 of
the items in both machine-executable and source code forms. The recipients must be able to do so without any
charges 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 of
the 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 17
not restricted to - lost revenue or profits or other direct, indirect, special, incidental or consequential damages, even
if they have been advised of the possibility of such damages, except to the extent invariable law, if any, provides
otherwise.
No Warranty
The Software and this license document are provided AS IS with NO WARRANTY OF ANY KIND, INCLUDING
THE 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.
Page 18

Pisa Api en

Transféré par

Informations du document

Description originale:

Titre original

Copyright

Formats disponibles

Partager ce document

Partager ou intégrer le document

Options de partage

Avez-vous trouvé ce document utile ?

Ce contenu est-il inapproprié ?

Droits d'auteur :

Formats disponibles

Pisa Api en

Transféré par

Droits d'auteur :

Formats disponibles

pisa

Simple PDF generator

(C)opyright by spirito GmbH, 2005-2007

The command line tool

pisa test.pml test.pdf

The Python module

python setup.py install

Windows users should install the special package.

import spirito.pisa2.pml as pisa

01: Hello World

Now for something more complex:

Cascading Style Sheets

<h1>Heading of first order</h1>

• "cm" for centimeters

Like HTML. Examples:

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

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

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

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

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

Only useable within <static>. Draws a point.

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

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

Emphasize that means italic. Same as <i>.

Font face and font size. Better use CSS.

<fontembed ttf="vera.ttf" name="tfont">

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

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

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

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

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

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

Loads external CSS file.

Create a new page after this position.

Defines the template to be used on the next page.

Creates an object of a specific size.

Bold face. Q.v. <b>.

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

Q.v. frame and static.

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

Everyone is permitted to copy and distribute this license document.

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

Vous aimerez peut-être aussi