Home‎ > ‎Pisa‎ > ‎

Pisa ドキュメント

pisa 3.0.29

XHTML/HTML/CSS to PDF converter

(C)opyright by Dirk Holtwick, Germany
日本語訳: 林秀樹 linxs@linxs.org / オリジナル» http://www.xhtml2pdf.com/doc/pisa-en.html

はじめに

pisa は、Reportlab Toolkit, pyPDF, TechGame Networks CSS ライブラリ、および HTML5lib に基づき Python で書かれた HTML/XHTML/CSS から PDF へのコンバータです。 パーフェクトに印刷できるウェブページを生成することを最重要視したものではなく、広く知られているツールとして HTML と CSS を使用してアプリケーションの中で PDF ファイルを生成することを目指しています。 例えば、(本書のような)説明書を生成したり、請求書などの文書を生成できます。

インストール

pisa は Python のパッケージなので、Python のインストールが必要です。当面は Python 2.3 - 2.5 がサポートされています。Python 3000 については、2.x 系列とは互換性がないので、特別な対応が必要でしょう。 Python 3000 が安定し次第、対応版をリリースする予定です。

pisa をインストールする最も簡単な方法は、easy_install を使用することです:

$ easy_install pisa

pisa のソースコードをダウンロードして、メインディレクトリに入って次のコマンドを実行することもできます (Linux と MacOS では、sudo コマンドを前置することもできます):

$ python setup.py install
pisa の動作には、いくつかの Python パッケージを追加でインストールする必要があります。 各パッケージのセットアップの指示に従ってください:

Windows 用コンパイル済みバージョン

Windows 用に、Python と必要な全ライブラリを含むコンパイル済みバージョンを用意しています。パッケージには xhtml2pdf.exe を入れてあります。 xhtml2pdf.exe が置かれるディレクトリを Windows の PATH 変数に追加してください。

Windows 版は、「ダウンロード」セクションのウェブサイト <http://www.xhtml2pdf.com> を通して配布します。

コマンドライン

pisa をあなたのアプリケーションへ統合するのでないなら、pisa の機能を利用する簡単なインターフェースとしてコマンドラインツールを使用できます。xhtml2pdf --help とだけ実行すると、以下のヘルプ情報が得られます:

pisa 3.0.28 (Build 2008-11-21)
(C) 2002-2008 Dirk Holtwick <dirk.holtwick@gmail.com>, Germany
Website http://www.htmltopdf.org

USAGE: pisa [オプション] SRC [DEST]

SRC
HTMLファイルか * プレースホルダを使用するファイルパターンの名前。
stdin から読みたい場合は、ファイル名として「-」を使用してください。
また、URL を指定して HTTP 経由でロードすることも可能です。
    "?" のような文字を含む場合は <src> を引用符で囲んでください。

DEST
生成結果の PDF ファイルを stdout へ書き出す場合は「-」を指定します。
    保存先ファイルが Adobe Reader のような他のアプリケーションですでに
    開かれていないことを確認してください。保存先が「書込可能」でない
    場合は、似た名前を自動的に決定して付けます。

[オプション]
    --css, -c: 省略時の CSS 定義ファイルのパス。
    --css-dump: 省略時の CSS 定義を STDOUT へ書き出します。
    --debug, -d: デバッグ情報を示してください。
    --encoding: SRC のキャラクタコード化方式。 指定しないと(省略時の動作)、
この情報は HTML ヘッダから抜粋されます。
    --help, -h: この説明文を表示します。
    --quiet, -q: メッセージを全く表示しません。
    --start-viewer, -s: Windows および MacOSX で PDF デフォルトビューア
(たとえば Adobe Reader)を起動します。
    --version: バージョン情報を表示します。
    --warn, -w: 警告を表示します。
    --xml, --xhtml, -x: 強制的に XML Mode で構文解析します。(ファイル名が
".xml" で終わる場合は自動的に使用されます)
    --html: 強制的に HTML Mode で構文解析します。(省略時の動作)

HTML データの変換

HTML ファイル test.html から PDF を生成するには、次のとおり実行します:

$ xhtml2pdf -s test.html
結果として生成される PDF は test.pdf というファイル名になります (Adobe Reader などがこのファイルをロックしていたら test-0.pdf などとなります)。-s オプションを指定すると PDF ファイルを OS のデフォルトビューアで開くことに注意してください。

複数のファイルを変換するのに、*? のようなワイルドカードパターンを使用できます:

$ xhtml2pdf "test/test-*.html"

インターネットからページを直接生成することも可能です:

$ xhtml2pdf -s http://www.xhtml2pdf.com/

特殊プロパティの使用

思い通りに変換できない場合、追加の情報が役立つかもしれません。-w で警告を出力したり、-d でデバッグ出力を追加することもできます。

別の理由として、構文解析の失敗も考えられます。-xhtml あるいは -html オプションを検討してみてください。pisa は HTML5lib パーサを使用しています。このパーサは内部で二つの構文解析モードを用意しています: HTML 用と XHTML 用です。

HTML 出力を生成する場合、pisa は内部の省略時CSS定義を使用します(さもなくば、すべてのタグが変化なしで表示されます)。どんな感じになるかを見るには、次のとおり起動してみてください:

$ xhtml2pdf --css-dump > xhtml2pdf-default.css

CSS がファイル pisa-default.css へ書き出されます。これを改造したり、あるいはまったくすべて定義し直した上で、-css オプションで利用することができます:

$ xhtml2pdf --css=xhtml2pdf-default.css test.html

Python モジュール

XXX 完成待ち

Python プログラムへの統合はとても簡単です。 簡単な「Hello World」の例から始めてみましょう:

import ho.pisa as pisa (1)

def helloWorld():
filename = __file__ + ".pdf" (2)
pdf = pisa.CreatePDF( (3)
"Hello <strong>World</strong>",
file(filename, "wb"))
if not pdf.err: (4)
pisa.startViewer(filename) (5)

if __name__=="__main__":
pisa.showLogging() (6)
helloWorld()

コメント:

(1) pisa Python モジュールをインポートします。
(2) サンプルファイル名を決定します。デモプログラムが test.py として保存された場合、ファイル名は test.py.pdf となります。
(3) CreatePDF メソッドを読取元と保存先を指定して呼び出します。この場合、読取元は文字列、保存先はファイルオブジェクトです。後で他の値について取り上げます(XXX残課題!)。 結果として返されたオブジェクトは pdf へ保存されます。
(4) pdf.err プロパティを検査して、エラーが発生していないか確認します。
(5) 何のエラーも発生していなければ、補助関数が生成結果のファイルを PDF リーダで開きます。
(6) エラーと警告をログエントリとして書き込みます。Python 標準の logging モジュールを使用します。この補助関数を使うと、警告をコンソールへ出力できます。

PDF の生成

pisa の中心となる関数は CreatePDF() です。引数を次の順でとります:

  • src: 解析対象。ファイルハンドルや StringUnicode オブジェクト(こちらの方が良い)を指定できます。
  • dest: PDF 生成結果の保存先。ファイルオブジェクトでなければなりません。CreatePDF はこの保存先をクローズしません。 (XXX ファイル名も許容するか?)
  • path: 原点となるファイルパスまたは URL。画像やスタイルシートの相対パスを解釈するのに必要です。(XXX src から自動的に計算するか?)
  • link_callback: 特殊ファイルパス用ハンドラ(下記参照)。
  • debug: ** 非推奨 **
  • show_error_as_pdf: 真偽値。エラーを PDF へ書き出すかどうかを指示します。簡単なウェブアプリケーションのようにエラー表示の方法に選択の余地がない場合に便利です。
  • default_css:  省略時 CSS 定義を String で渡します。Noneを設定した場合は、pisa の定義済み CSS を使用します。
  • xhtml: 真偽値。強制的に XHTML としてソースを構文解析します。何も指定しなければ HTML5 パーサが推測を行います。
  • encoding: ソースの符号化方式(訳注: utf-8 や euc-jp などの指定)。何も指定しなければ HTML5 パーサが推測を行いますが、メタ情報のない HTML の場合は推測ができないので、この引数が役立ちます。

Link callback

一般の画像やバックグラウンド画像、スタイルシートは、HTML 文書からロードされます。通常 pisa は、こうしたファイルがローカルドライブにあると想定しています。 また、それらはオリジナルからの相対パスで参照されるかもしれません。しかし、プログラマが意図しているのは、HTTP リクエスト経由でのインターネットからのロードかもしれませんし、データベースや何か他のところからのロードかもしれません。このため、こうしたリクエストを扱う link_callback を定義できます。

XXX

ウェブアプリケーション

XXX

省略時の値

省略時の値に関する注は次のとおりです:

  • 通常、PDF ファイルの原点(0、0)は左下隅にあります。 pisa の場合は、HTML と同様に左上隅が原点です。
  • 省略時のページサイズは、A4・縦長方向(ポートレート)です。
  • 最初のレイアウトテンプレートの名前は body ですが、デフォルトテンプレートを定義するにはこの名前を空のままにしておくほうがよいでしょう。(XXX 今後変更の可能性あり!)

CSS

pisa は、たくさんのカスケーディングスタイルシート(CSS)をサポートします。 以下のスタイルがサポートされています:

background-color
border-bottom-color
border-bottom-style
border-bottom-width
border-left-color
border-left-style
border-left-width
border-right-color
border-right-style
border-right-width
border-top-color
border-top-style
border-top-width
color
display
font-family
font-size
font-style
font-weight
height
line-height
list-style-type
margin-bottom
margin-left
margin-right
margin-top
padding-bottom
padding-left
padding-right
padding-top
page-break-after
page-break-before
size
text-align
text-decoration
text-indent
vertical-align
white-space
width
zoom

訳注: (pisa 3.0.32) スタイルには次の形式も使用できます。
font
background
margin
padding
border
border-width
border-color
border-style
border-bottom
border-left
border-right
border-top
font-style には normal, italic, oblique を指定できます。
font-variant には normal, small-caps を指定できます。
font-weight には light, lighter, normal, bold, bolder, 100, 200, 300, ..., 900 を指定できます。
border-style には none, hidden, dotted, dashed, solid, double, groove, ridge, inset, outset を指定できます。
サイズ指定時の単位には pt, px, ex, pc, in, cm, mm, %, em のいずれかを指定できます。

ベンダー独自のスタイルもいくつか追加されています:

-pdf-frame-border
-pdf-frame-break
-pdf-frame-content
-pdf-keep-with-next
-pdf-next-page
-pdf-outline
-pdf-outline-level
-pdf-outline-open
-pdf-page-break

レイアウトの定義

ページとフレーム

ページをレイアウトするには、特殊な CSS @キーワードおよびプロパティを用います。すべての特殊プロパティは CSS 2.1 での定義に従いベンダー固有であることがわかるように -pdf で始まる名前になっています。レイアウトは @page キーワードを使用してページごとに定義されます。テキストは単独または複数のフレームへ流し込まれます。フレームは @pageブロックの中で @frame で定義します。

例:
@page {
@frame {
margin: 1cm;
}
}

この例ではページテンプレートに名前をつけていません(が、デフォルトテンプレートとして使用されます)。ページには1個のフレームがあり、ページの各辺に対して 1cm のマージンをとっています。ページの最初のフレームは @page ブロックそのものの中で定義することもできます。次のように書いても同じです:

@page {
margin: 1cm;
}

さらにフレームを定義したければ、単に @frame ブロックを追加するだけです。フレームの大きさを定義するには、次のプロパティを用います:

  • marign
  • margin-top
  • margin-left
  • margin-right
  • margin-bottom
  • top
  • left
  • right
  • bottom
  • width
  • height

より複雑な例を見てみましょう:

@page lastPage {
top: 1cm;
left: 2cm;
right: 2cm;
height: 2cm;
@frame middle {
margin: 3cm;
}
@frame footer {
bottom: 2cm;
margin-left: 1cm;
margin-right: 1cm;
height: 1cm;
}
}

レイアウト体系:

top
+--------------------------+ ----
| margin-top | ↑
| +---------------+ | |
| | | |
| | | | height
| | | |

特段の指定がない場合、Frame はページ全体を占め左上隅から開始し右下隅で終了するように定義されます。フレームの位置は、top left  bottom  right を用いて指定できます。top がゼロでない状態で height を指定した場合、bottom が変更されます。 (XXX top が未定義で bottom だけ定義した場合、height は...)

ページの大きさと向き

ページレイアウトでは、CSS 3 で定義されているとおり、size プロパティを用いてページの大きさと用紙の向きを定義することもできます。A5判・ポートレート(縦長方向)を定義する例です(なお、省略時の用紙の向きはポートレートです):

@page {
size: a5 landscape;
margin: 1cm;
}

ページの大きさの指定では、次の識別子を使用できます:

  • a0a6
  • b0b6
  • letter
  • legal
  • elevenseventeen

PDF 透かし/背景画像

PDF 背景画像を使用するには、次のように background-image プロパティにソースファイルを指定します:

@page {
background-image: url(bg.pdf);
}

固定フレーム

ヘッダーとフッターのように固定(static)であるべきフレームもあります。「固定」の意味は、どのページにも表示されるがページの内容には影響しないということです。変化するであろう唯一の情報は、ページ番号です。ID で指定した要素を固定フレームの内容とする方法を示す簡単な例を挙げます。この例では、ID は footer です。

<html>
<style>
@page {
margin: 1cm;
margin-bottom: 2.5cm;
@frame footer {
-pdf-frame-content: footerContent;
bottom: 2cm;
margin-left: 1cm;
margin-right: 1cm;
height: 1cm;
}
}
</style>
<body>
Some text
<div id="footerContent">
This is a footer on page #<pdf:pagenumber>
</div>
</body>
</html>

デバッグしやすいように、各フレーム定義に「-pdf-frame-border: 1」というプロパティを追加することもできます。こうすると、フレームの境界線が表示されます。

フォント

何もしなくても数種類のフォントが PDF で利用できます。pisa がもともと管理しているフォント(とそれぞれの別名)の一覧を掲げます(フォント名は、大文字と小文字を区別しません):

  • Times-Roman: Times New Roman, Times, Georgia, serif
  • Helvetica: Arial, Verdana, Geneva, sansserif, sans
  • Courier: Courier New, monospace, monospaced, mono
  • ZapfDingbats
  • Symbol

しかし次のように、CSSの @font-face キーワードを用いて新しいフォントを埋め込むこともできます:

@font-face {
 font-family: Example, "Example Font";
src: url(example.ttf);
}

埋め込まれているフォントがどのような名前で参照されるかを font-family プロパティで定義します。src でフォントソースファイルの場所を指定します。TrueType フォントや Postscript フォントでもかまいません。前者のファイル名の末尾(訳注:拡張子)は .ttf 、後者のそれは .pfb.afm でなければなりません。Postscript フォントの場合は、<名前>.afm<名前>.pfb のようなファイル名を一つだけ渡してください。それ以外に必要なファイル名は自動的に決定されます。

フォントの装飾は次のように行えます:

/* Normal */
@font-face {
font-family: DejaMono;
src: url(font/DejaVuSansMono.ttf);
}

/* Bold */
@font-face {
font-family: DejaMono;
src: url(font/DejaVuSansMono-Bold.ttf);
font-weight: bold;
}

/* Italic */
@font-face {
font-family: DejaMono;
src: url(font/DejaVuSansMono-Oblique.ttf);
font-style: italic;
}

/* Bold and italic */
@font-face {
font-family: DejaMono;
src: url(font/DejaVuSansMono-BoldOblique.ttf);
font-weight: bold;
font-style: italic;
}

アウトライン/ブックマーク

PDF はアウトラインをサポートしています(Adobeでは「ブックマーク」と呼びます)。pisa ではアウトラインに表示される <h1>..<h6> タグがもともと定義されています。しかし、どんなタグにでも、アウトラインでどのように表示されるかを指定することができます。したがって、次のようなベンダー固有のスタイルを使用できます:

  • -pdf-outline
    アウトラインにブロック要素が出現する場合は true とします。
  • -pdf-outline-level
    アウトラインが表示されるレベルを、「0」から始まる値で指定します。上位レベルの指定が欠落している場合は、それらを現在のアウトラインと同じ名前で自動的に補完します。
  • -pdf-outline-open
    アウトラインを表示する際に連接させない(no-collapse)場合は true とします。

例:

h1 {
-pdf-outline: true;
-pdf-outline-level: 0;
-pdf-outline-open: false;
}

目次

pisa では目次(TOC)を自動的に生成できます。<h1> から <h6> までの見出しは、何もしなくてもTOCに挿入されます。 しかし、CSS プロパティの -pdf-outlinetrue/false を設定することにより、こうしたふるまいを変えることができます。 TOC を生成するには、単に文書に <pdf:toc /> を挿入します。 そして pdf.toc タグやpdftoc.pdftoclevel0 ないし pdftoc.pdftoclevel5 クラスのスタイルを定義すれば、見た目も変わります。見た目のよい CSS の簡単な例です:

pdftoc {
color: #666;
}
pdftoc.pdftoclevel0 {
font-weight: bold;
margin-top: 0.5em;
}
pdftoc.pdftoclevel1 {
margin-left: 1em;
}
pdftoc.pdftoclevel2 {
margin-left: 2em;
font-style: italic;
}

表はサポートされていますが、あなたが予想する挙動とは若干異なっているかもしれません。こうした制限は ReportLab の基本的な表処理メカニズムによるものです。

  • 主な制限として、1ページより長いセルはエラーを発生させます。
  • 表の左寄せ・右寄せや行内への配置ができません。

長いセル

pisa は利用可能なスペースより大きなセルを分割することはできません。処理を続行するために、この場合に何をすべきかを定義できます。-pdf-keep-in-frame-mode として次のいずれかを指定できます: "error", "overflow", "shrink", "truncate"。省略すると "shrink" となります。

table {
-pdf-keep-in-frame-mode: shrink;
}

セルの幅

表のレンダラはテーブルの幅を自動的には調整できません。したがって、表や表の行あるいはセルの幅を明示する必要があります。

ヘッダ

改ページが表の途中で発生する場合、表の行を繰り返すことが可能です。繰り返される行の数は repeat プロパティで渡します。 例:

<table repeat="1">
<tr><th>Column 1</th><th>...</th></tr>
...
</table>

境界線

境界線がサポートされています。対応する CSS スタイルを使用してください。

画像

大きさ

JPG 画像は何もしなくてもサポートされています。Python Imaging Library (PIL)がインストールされていれば、PILがサポートするファイルタイプも使用できます。ピクセルをポイントへ変換するのは一筋縄ではいかないので、画像は PDF ではブラウザで見るよりも大きくなるかもしれません。これを調整には、zoom スタイルを使用できます。 簡単な例を示します:

img { zoom: 80%; }

位置/回り込み

Reportlab Toolkit が段落中での画像の使用をまだサポートしていないため、画像は常に別の段落として表示されます。このため、テキストの回り込みはまだできません。

バーコード

XXX 記載待ち

<pdf:barcode>


訳注: ここ にあるパッチをあてて様々なバーコードを出力できる状態にした上での挙動について次に記述します。

ReportLab で生成できる(1 次元)バーコードを、カスタムタグ <pdf:barcode> で埋め込むことができます。生成されるバーコードは、(X)HTML でのインライン要素となります。

<pdf:barcode value="EMBED CODE HERE" type="code128" humanreadable="1" barwidth="0.33mm" barheight="2cm" align="top">

次の属性を指定できます。
  • value: type で指定したバーコードで表現できるコードを指定します。必須属性です。
  • type: 次のいずれかを指定します。大文字/小文字は区別しません。省略時は Code128 です。
    • Code128
    • I2of5 または ITF
    • Code39
    • ExtendedCode39
    • Code93
    • ExtendedCode93
    • MSI
    • Codabar または NW7
    • Code11
    • FIM
    • Postnet
    • USPS4S (USPS 4-State)
    • EAN13 (EAN/JAN 13 digit)
    • EAN8 (EAN/JAN 8 digit)
  • humanreadable: 可読域を付加する場合は 1 とし、付加しない場合は 0 とします。省略時は 0 です。
  • barwidth: ナローバー(バーコードを構成する個々の矩形のうち最も幅が狭いもの)の幅を、10mm0.5in のように指定します。省略時は 0.01 インチ(EAN13/8 の場合は 0.33mm)です。最小幅(EAN13/8 の場合は 0.33mm、その他の場合は 0.0075 インチ)以下の値を指定した場合は、最小幅を指定したことになります。
  • barheight: バーコードの高さを指定します。EAN13/8の場合は、可読域の高さも含みます(小さすぎる値を指定した場合、バーが可読域に入り込むなどの異常が起きることがあります)。その他の場合は、可読域の高さは含みません。
  • align: 次のいずれかを指定します。大文字/小文字は区別しません。省略時は baseline です。baselinebottom は同じ結果となります。
    • baseline
    • top
    • middle
    • bottom

カスタムタグ

pisa はいくつかのカスタムタグを提供します。すべて名前空間指定 pdf: を前置します。 pisa が利用している HTML5 パーサはこれらのタグを知らないため、ブロックなしで使用するとうまく解釈されない可能性があります。 この問題を回避するため、カスタムタグを <div> タグで囲むことを検討してください:

<div>
<pdf:toc />
</div>

タグ定義

pdf:barcode
バーコードを作成します。
pdf:pagenumber
現在のページ番号を印刷します。 引数「example」でページ番号の文字数を定義します。例:「00」
pdf:nexttemplate
次のページで使用するテンプレートを指定します。
pdf:nextpage
このタグの直後で改ページします。
pdf:nextframe
同一ページの隣の未使用のフレーム、または次のページの最初のフレームへ移動します。名前の付いたフレームへは移動できません。
pdf:spacer
特定のサイズのオブジェクトを生成します。
pdf:toc
目次を生成します。

ライセンス

pisa is copyrighted by Dirk Holtwick, Germany.
pisa is distributed by Dirk Holtwick, Schreiberstraße 2, 47058 Duisburg, Germany.
pisa is licensed under the GNU Gerneral Public License version 2.

pisa の商業利用には、開発者ライセンスを購入できます!

Comments