You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
<h1style="-pdf-outline: false;" class="pdf">Table of Contents</h1>
27
26
<divclass="pdf">
28
27
<pdf:toc/>
29
28
</div>
30
29
<h1>Introduction</h1>
31
-
<p><em>pisa</em> is a HTML/XHTML/CSS to PDF converter written in Python and based on Reportlab Toolkit, pyPDF, TechGame Networks CSS Library and HTML5lib. The primary focus is not on generating perfect printable webpages but to use HTML and CSS as commonly known tools to generate PDF files within Applications. For example generating documentations (like this one), generating invoices or other office documents etc.</p>
30
+
<p><em>xhtml2pdf</em> is a HTML/XHTML/CSS to PDF converter written in Python and based on Reportlab Toolkit, pyPDF, TechGame Networks CSS Library and HTML5lib. The primary focus is not on generating perfect printable webpages but to use HTML and CSS as commonly known tools to generate PDF files within Applications. For example generating documentations (like this one), generating invoices or other office documents etc.</p>
32
31
<h1>Installation</h1>
33
-
<p>As pisa is a Python pakage an installed version of Python <<ahref="http://www.python.org">http://www.python.org</a>> is needed. For the moment Python 2.3 to 2.5 is supported. For Python 3000 a special version will be needed, because it is not compatible with the 2.x series. A proper version will be made available as soon as Python 3000 becomes stable.</p>
34
-
<p>The easiest way to install <em>pisa</em> is to use easy_install:</p>
35
-
<pre>$ easy_install pisa</pre>
36
-
<p>But you may also download the source code of <em>pisa</em>, then enter the main directory and execute this command (on Linux and MacOS you may prepend a <code>sudo</code> command):</p>
32
+
<p>As xhtml2pdf is a Python pakage an installed version of Python <<ahref="http://www.python.org">http://www.python.org</a>> is needed. For the moment Python 2.3 to 2.5 is supported. For Python 3000 a special version will be needed, because it is not compatible with the 2.x series. A proper version will be made available as soon as Python 3000 becomes stable.</p>
33
+
<p>The easiest way to install <em>xhtml2pdf</em> is to use easy_install:</p>
34
+
<pre>$ easy_install xhtml2pdf</pre>
35
+
<p>But you may also download the source code of <em>xhtml2pdf</em>, then enter the main directory and execute this command (on Linux and MacOS you may prepend a <code>sudo</code> command):</p>
37
36
<pre>$ python setup.py install</pre>
38
-
<p><em>pisa</em> needs also some additional Python packages to be installed to work. Please follow the setup instruction for each package:</p>
37
+
<p><em>xhtml2pdf</em> needs also some additional Python packages to be installed to work. Please follow the setup instruction for each package:</p>
<p>For Windows a precompiled version exists that includes Python and all needed libraries. The package contains the file <code>xhtml2pdf.exe</code>. Please add the directory where <code>xhtml2pdf.exe</code> is placed to the Windows <code>PATH</code> variable.</p>
57
56
<p>The Windows version is distributed via the Website <<ahref="http://www.xhtml2pdf.com">http://www.xhtml2pdf.com</a>> in the "Download" section.</p>
58
57
<h1>Command line</h1>
59
-
<p>If you do not want to integrate <em>pisa</em> in your own application, you may use the command line tool that gives you a simple interface to the features of <em>pisa</em>. Just call <code>xhtml2pdf --help</code> to get the following help informations:</p>
58
+
<p>If you do not want to integrate <em>xhtml2pdf</em> in your own application, you may use the command line tool that gives you a simple interface to the features of <em>xhtml2pdf</em>. Just call <code>xhtml2pdf --help</code> to get the following help informations:</p>
60
59
<!--HELP--><pre></pre><!--HELP-->
61
60
<h2>Converting HTML data </h2>
62
61
<p>To generate a PDF from an HTML file called <code>test.html</code> call:</p>
@@ -68,62 +67,62 @@ <h2>Converting HTML data </h2>
<p>If the conversion doesn't work as expected some more informations may be usefull. You may turn on the output of warnings adding <code>-w</code> or even the debugging output by using <code>-d</code>.</p>
71
-
<p>Another reason could be, that the parsing failed. Consider trying the <code>-xhtml</code> and <code>-html</code> options. <em>pisa</em> uses the HTMLT5lib parser that offers two internal parsing modes: one for HTML and one for XHTML.</p>
72
-
<p>When generating the HTML output <em>pisa</em> uses an internal default CSS definition (otherwise all tags would appear with no diffences). To get an impression of how this one looks like start <em>pisa</em> like this:</p>
70
+
<p>Another reason could be, that the parsing failed. Consider trying the <code>-xhtml</code> and <code>-html</code> options. <em>xhtml2pdf</em> uses the HTMLT5lib parser that offers two internal parsing modes: one for HTML and one for XHTML.</p>
71
+
<p>When generating the HTML output <em>xhtml2pdf</em> uses an internal default CSS definition (otherwise all tags would appear with no diffences). To get an impression of how this one looks like start <em>xhtml2pdf</em> like this:</p>
<p>The CSS will be dumped into the file <code>pisa-default.css</code>. You may modify this or even take a totaly self defined one and hand it in by using the <code>-css</code> option, e.g.: </p>
73
+
<p>The CSS will be dumped into the file <code>xhtml2pdf-default.css</code>. You may modify this or even take a totaly self defined one and hand it in by using the <code>-css</code> option, e.g.: </p>
<p>(1) Import the <em>pisa</em> Python module <br/>
93
+
<p>(1) Import the <em>xhtml2pdf</em> Python module <br/>
95
94
(2) Calculate a sample filename. If your demo is saved under <code>test.py</code> the filename will be <code>test.py.pdf</code>.<br/>
96
95
(3) The function <code>CreatePDF</code> is called with the source and the destination. In this case the source is a string and the destination is a fileobject. Other values will be discussed later (XXX to do!). An object will be returned as result and saved in <code>pdf</code>. <br/>
97
96
(4) The property <code>pdf.err</code> is checked to find out if errors occured<br/>
98
97
(5) If no errors occured a helper function will open a PDF Reader with the resulting file<br/>
99
98
(6) Errors and warnings are written as log entries by using the Python standard module <code>logging</code>. This helper enables printing warnings on the console. </p>
100
99
<h2>Create PDF</h2>
101
-
<p>The main function of pisa is called CreatePDF(). It offers the following arguments in this order:</p>
100
+
<p>The main function of xhtml2pdf is called CreatePDF(). It offers the following arguments in this order:</p>
102
101
<ul>
103
102
<li><strong>src</strong>: The source to be parsed. This can be a file handle or a <code>String</code> - or even better - a <code>Unicode</code> object.</li>
104
103
<li><strong>dest</strong>: The destination for the resulting PDF. This has to be a file object wich will not be closed by <code>CreatePDF</code>. (XXX allow file name?) </li>
105
104
<li><strong>path</strong>: The original file path or URL. This is needed to calculate relative paths of images and style sheets. (XXX calculate automatically from src?) </li>
106
105
<li><strong>link_callback</strong>: Handler for special file paths (see below).</li>
<li><strong>show_error_as_pdf</strong>: Boolean that indicates that the errors will be dumped into a PDF. This is usefull if that is the only way to show the errors like in simple web applications.</li>
109
-
<li><strong>default_css</strong>: Here you can pass a default CSS definition in as a <code>String</code>. If set to <code>None</code> the predefined CSS of pisa is used. </li>
108
+
<li><strong>default_css</strong>: Here you can pass a default CSS definition in as a <code>String</code>. If set to <code>None</code> the predefined CSS of xhtml2pdf is used. </li>
110
109
<li><strong>xhtml</strong>: Boolean to force parsing the source as XHTML. By default the HTML5 parser tries to guess this. </li>
111
110
<li><strong>encoding</strong>: The encoding name of the source. By default this is guessed by the HTML5 parser. But HTML with no meta information this may not work an then this argument is helpfull. </li>
112
111
</ul>
113
112
<h2>Link callback</h2>
114
-
<p>Images, backgrounds and stylesheets are loaded form an HTML document. Normaly <em>pisa</em> expects these files to be found on the local drive. They may also be referenced relative to the original document. But the programmer might want to load form different kind of sources like the Internet via HTTP requests or from a database or anything else. Therefore you may define a <code>link_callback</code> that handles these reuests. </p>
113
+
<p>Images, backgrounds and stylesheets are loaded form an HTML document. Normaly <em>xhtml2pdf</em> expects these files to be found on the local drive. They may also be referenced relative to the original document. But the programmer might want to load form different kind of sources like the Internet via HTTP requests or from a database or anything else. Therefore you may define a <code>link_callback</code> that handles these reuests. </p>
115
114
<p>XXX</p>
116
115
<h2>Web applications</h2>
117
116
<p>XXX</p>
118
117
<h1>Defaults</h1>
119
118
<p>Some notes on some default values: </p>
120
119
<ul>
121
-
<li>Usually the position (0, 0) in PDF files is found in the lower left corner. For <em>pisa</em> it is the upper left corner like it is for HTML.</li>
120
+
<li>Usually the position (0, 0) in PDF files is found in the lower left corner. For <em>xhtml2pdf</em> it is the upper left corner like it is for HTML.</li>
122
121
<li>The default page size is the German DIN A4 with portrait orientation.</li>
123
122
<li>The name of the first layout template is <code>body</code>, but you better leave the name empty for defining the default template (XXX May be changed in the future!) </li>
124
123
</ul>
125
124
<h1>Cascading Style Sheets</h1>
126
-
<p><em>pisa</em> supports a lot of Cascading Style Sheet (CSS). The following styles are supported:</p>
125
+
<p><em>xhtml2pdf</em> supports a lot of Cascading Style Sheet (CSS). The following styles are supported:</p>
<p>For better debugging you may want to add this property for each frame definition: <code>-pdf-frame-border: 1</code>. It will paint a border around the frame. </p>
246
245
<h1>Fonts</h1>
247
-
<p>By default there is just a certain set of fonts available for PDF. Here is the complete list - and their repective alias names - <em>pisa</em> knows by default (the names are not case sensitive):</p>
246
+
<p>By default there is just a certain set of fonts available for PDF. Here is the complete list - and their repective alias names - <em>xhtml2pdf</em> knows by default (the names are not case sensitive):</p>
248
247
<ul>
249
248
<li><strong>Times-Roman</strong>: Times New Roman, Times, Georgia, serif </li>
250
249
<li><strong>Helvetica</strong>: Arial, Verdana, Geneva, sansserif, sans </li>
@@ -287,7 +286,7 @@ <h1>Fonts</h1>
287
286
font-style: italic;
288
287
}</pre>
289
288
<h1>Outlines/ Bookmarks </h1>
290
-
<p>PDF supports outlines (Adobe calls them "bookmarks"). By default <em>pisa</em> defines the <code><h1></code> to <code><h6></code> tags to be shown in the outline. But you can specify exactly for every tag which outline behaviour it should have. Therefore you may want to use the following vendor specific styles:</p>
289
+
<p>PDF supports outlines (Adobe calls them "bookmarks"). By default <em>xhtml2pdf</em> defines the <code><h1></code> to <code><h6></code> tags to be shown in the outline. But you can specify exactly for every tag which outline behaviour it should have. Therefore you may want to use the following vendor specific styles:</p>
291
290
<ul>
292
291
<li><code>-pdf-outline </code><br/>
293
292
set it to "true" if the block element should appear in the outline</li>
@@ -302,7 +301,7 @@ <h1>Outlines/ Bookmarks </h1>
302
301
-pdf-open: false;
303
302
}</pre>
304
303
<h1>Table of Contents</h1>
305
-
<p>It is possible to automatically generate a Table of Contents (TOC) with <em>pisa</em>. By default all headings from <code><h1></code> to <code><h6></code> will be inserted into that TOC. But you may change that behaviour by setting the CSS property <code>-pdf-outline</code> to <code>true</code> or <code>false</code>. To generate the TOC simply insert <code><pdf:toc /></code> into your document. You then may modify the look of it by defining styles for the <code>pdf:toc</code> tag and the classes <code>pdftoc.pdftoclevel0</code> to <code>pdftoc.pdftoclevel5</code>. Here is a simple example for a nice looking CSS:</p>
304
+
<p>It is possible to automatically generate a Table of Contents (TOC) with <em>xhtml2pdf</em>. By default all headings from <code><h1></code> to <code><h6></code> will be inserted into that TOC. But you may change that behaviour by setting the CSS property <code>-pdf-outline</code> to <code>true</code> or <code>false</code>. To generate the TOC simply insert <code><pdf:toc /></code> into your document. You then may modify the look of it by defining styles for the <code>pdf:toc</code> tag and the classes <code>pdftoc.pdftoclevel0</code> to <code>pdftoc.pdftoclevel5</code>. Here is a simple example for a nice looking CSS:</p>
306
305
<pre>pdftoc {
307
306
color: #666;
308
307
}
@@ -347,7 +346,7 @@ <h1>Barcodes</h1>
347
346
<p>You can embed barcodes automatically in a document. Various barcode formats are supported through the <code>type</code> attribute. If you want the original barcode text to be appeared on the document, simply add <code>humanreadable="1"</code>, otherwise simply omit this attribute. Alignment is achieved through <code>align</code> attribute and available values are any of <code>"baseline", "top", "middle", "bottom"</code> whereas default is <code>baseline</code>. Finally, bar width and height can be controlled through <code>barwidth</code> and <code>barheight</code> attributes respectively.</p>
348
347
<pre><pdf:barcode value="BARCODE TEXT COMES HERE" type="code128" humanreadable="1" align="right" /></pre>
349
348
<h1>Custom Tags </h1>
350
-
<p><em>pisa</em> provides some custom tags. They are all prefixed by the namespace identifier <code>pdf:</code>. As the HTML5 parser used by pisa does not know about these specific tags it may be confused if they are without a block. To avoid problems you may condsider sourrounding them by <code><div></code> tags, like this: </p>
349
+
<p><em>xhtml2pdf</em> provides some custom tags. They are all prefixed by the namespace identifier <code>pdf:</code>. As the HTML5 parser used by xhtml2pdf does not know about these specific tags it may be confused if they are without a block. To avoid problems you may condsider sourrounding them by <code><div></code> tags, like this: </p>
351
350
<pre><div>
352
351
<pdf:toc />
353
352
</div>
@@ -370,9 +369,6 @@ <h3>pdf:spacer</h3>
370
369
<h3>pdf:toc</h3>
371
370
<p> Creates a Table of Contents. </p>
372
371
<h1>License</h1>
373
-
<p><strong><em>pisa</em> is copyrighted by Dirk Holtwick, Germany.</strong><br/>
374
-
<em>pisa</em> is distributed by Dirk Holtwick, Schreiberstra�e 2, 47058 Duisburg, Germany.<br/>
375
-
<em>pisa</em> is licensed under the GNU Gerneral Public License version 2.</p>
376
-
<p><strong>For commercial usage of <em>pisa</em> a developer license can be purchased!</strong></p>
372
+
<p><strong><em>xhtml2pdf</em> is copyrighted by Dirk Holtwick, Germany.</strong><br/>
0 commit comments