wkhtmltopdf使用法の日本語訳
今年の2月に「markdownファイルをpdfファイルに変換する」という記事をアップしていますが、その前後に用意だけしてアップし忘れていた記事がありました。ずいぶんと遅れましたが、アップします。
「markdownファイルをpdfファイルに変換する」の事前の下調べをしていてpdfkitに行き当たりました。 pdfkitのマニュアルの中で、wkhtmltopdfのオプションすべてのを指定できると記述されていたので、どんなオプションがあるのか確認するためにhttps://wkhtmltopdf.org/usage/wkhtmltopdf.txtを訳してみました。といってもGoogle翻訳に丸投げですが。（pdfkitはpythonからwkhtmlyopdfを呼び出して使うものです）
私がしたことと言えば、翻訳単位毎に原文（英文）テキスト〜Google翻訳〜日本語テキストの間でコピーペーストを繰り返すだけの退屈な力仕事と、日本語テキストにする時にマークダウン化したことだけです。
wkhtmltopdfのサイトを見ると「現時点では、wkhtmltopdfの自動生成ドキュメントしかありません。 これは、wkhtmltopdf -Hを実行した場合と同じものです。」となっています。今回の原文ファイルがそのヘルプで表示される内容です。なので誰かのお役に立てるかも知れません。
何か問題があるかも知れませんが、おかしいと思われた時は原文を確認頂ければ幸いです。ついでにおかしい箇所を連絡頂けると助かります。
wkhtmltopdf使用法
https://wkhtmltopdf.org/usage/wkhtmltopdf.txt
wkhtmltopdf 0.12.5 (with patched qt)
梗概
wkhtmltopdf [GLOBAL OPTION]... [OBJECT]... <output file>
ドキュメントオブジェクト
wkhtmltopdfは、複数のオブジェクトを出力ファイルに配置できます。オブジェクトは、単一のWebページ、カバーWebページ、または目次のいずれかです。 オブジェクトは、コマンドラインで指定された順序に従い出力ドキュメントに配置されます。オプションは、オブジェクトごとまたはグローバルオプション領域で指定できます。 グローバルオプションセクションのオプションは、グローバルオプション領域にのみ配置できます。
ページオブジェクトは、単一のWebページのコンテンツを出力ドキュメントに挿入します。
(page)? <input url/file name> [PAGE OPTION]...
ページオブジェクトのオプションは、グローバルオプションおよびページオプション領域に配置できます。 該当するオプションは、ページオプションセクションとヘッダーならびにフッターのオプションセクションにあります。
カバーオブジェクトは、単一のWebページのコンテンツを出力ドキュメントに挿入します。ページは目次に表示されず、ヘッダーとフッターもありません。
cover <input url/file name> [PAGE OPTION]...
ページオブジェクトに指定できるすべてのオプションは、表紙にも指定できます。
目次オブジェクトは、目次を出力ドキュメントに挿入します。
toc [TOC OPTION]...
ページオブジェクトに指定できるすべてのオプションは、tocにも指定できます。さらに、TOCオプションセクションのオプションをさらに適用することもできます。 目次はXSLTを介して生成されます。これは、見た目を自由に設定できることを意味します。 これを行う方法のアイデアを得るには、デフォルトのxsltドキュメントをダンプできます。
--dump-default-toc-xsl、およびそれを提供することによって動作するアウトライン
--dump-outline、「アウトラインオプション」セクションを参照してください。
説明
wkhtmltopdfパッチを適用したqtを使用して、1つ以上のHTMLページをPDFドキュメントに変換します。
グローバルオプション
| オプション | 説明 |
|---|---|
| --collate | 複数部数を印刷するときに丁合する（デフォルト） |
| --no-collate | 複数の部数を印刷するときに照合しない |
| --cookie-jar <path> | 提供されたcookie jarファイルとの間でcookieを読み書きします |
| --copies <数> | PDFファイルに印刷するコピーの数（デフォルト1） |
| -d, --dpi <dpi> | dpiを明示的に変更します（これはX11ベースのシステムには影響しません）（デフォルト96） |
| -H, --extended-help | あまり一般的ではないコマンドスイッチの詳細を示し、より広範なヘルプを表示 |
| -g, --grayscale | PDFはグレースケールで生成されます |
| -h, --help | ヘルプを表示する |
| --htmldoc | 出力プログラムのHTMLヘルプ |
| --image-dpi <整数> | 画像を埋め込むとき、このdpiに縮小します（デフォルトは600） |
| --image-quality <整数> | jpeg圧縮画像がこの品質を使用する場合（デフォルト94） |
| --license | ライセンス情報を出力して終了する |
| --log-level <level> | ログレベルを設定します：none、error、warn、またはinfo（デフォルトinfo） |
| -l, --lowquality | 低品質のpdf / psを生成します。 結果のドキュメントスペースを縮小するのに便利 |
| --manpage | 出力プログラムのマニュアルページ |
| -B, --margin-bottom <unitreal> | ページの下余白を設定する |
| -L, --margin-left <unitreal> | ページの左マージンを設定します（デフォルトは10mm） |
| -R, --margin-right <unitreal> | ページの右マージンを設定します（デフォルトは10mm） |
| -T, --margin-top <unitreal> | ページ上部の余白を設定する |
| -O, --orientation <orientation> | 向きを横向きまたは縦向きに設定します（デフォルトはPortrait） |
| --page-height <unitreal> | ページ高さ |
| -s, --page-size <Size> | 用紙サイズをA4、レターなどに設定します。（デフォルトA4） |
| --page-width <unitreal> | ページ幅 |
| --no-pdf-compression | PDFオブジェクトでロスレス圧縮を使用しない |
| -q, --quiet | 冗長性を低くし、後方互換性のために維持します。 --log-level noneを使用した場合と同じ |
| --read-args-from-stdin | stdinからコマンドライン引数を読み取る |
| --readme | 出力プログラムのreadme |
| --title <text> | 生成されたpdfファイルのタイトル（指定されていない場合、最初のドキュメントのタイトルが使用されます） |
| --use-xserver | Xサーバーを使用します（一部のプラグインやその他のものは、X11がないと機能しない場合があります） |
| -V, --version | バージョン情報を出力して終了する |
アウトラインオプション
| オプション | 説明 |
|---|---|
| --dump-default-toc-xsl | デフォルトのTOC xslスタイルシートを標準出力にダンプします |
| --dump-outline <file> | アウトラインをファイルにダンプします |
| --outline | PDFにアウトラインを配置します（デフォルト） |
| --no-outline | PDFにアウトラインを入れないでください |
| --outline-depth <level> | アウトラインの深さを設定します（デフォルト4） |
ページオプション
| オプション | 説明 |
|---|---|
| --allow <path> | 指定されたフォルダーからのファイルのロードを許可します（繰り返し可能） |
| --background | 背景を印刷する（デフォルト） |
| --no-background | 背景を印刷しない |
| --bypass-proxy-for <value> | ホストのバイパスプロキシ（繰り返し可能） |
| --cache-dir <path> | Webキャッシュディレクトリ |
| --checkbox-checked-svg <path> | チェックボックスをレンダリングするときにこのSVGファイルを使用します |
| --checkbox-svg <path> | チェックされていないチェックボックスをレンダリングするときにこのSVGファイルを使用します |
| --cookie <name> <value> | 追加のCookie（繰り返し可能）を設定します。値はURLエンコードされている必要があります。 |
| --custom-header <name> <value> | 追加のHTTPヘッダーを設定する（繰り返し可能） |
| --custom-header-propagation | 各リソース要求に対して--custom-headerで指定されたHTTPヘッダーを追加します。 |
| --no-custom-header-propagation | 各リソースリクエストに対して--custom-headerで指定されたHTTPヘッダーを追加しないでください。 |
| --debug-javascript | JavaScriptデバッグ出力を表示する |
| --no-debug-javascript | JavaScriptデバッグ出力を表示しない（デフォルト） |
| --default-header | デフォルトのヘッダーを追加します。ページの名前を左側に、ページ番号を右側に追加します。これは次の略です。 --header-left = '[webpage]' --header-right = '[page] / [toPage]' --top 2cm --header-line |
| --encoding <encoding> | 入力用にデフォルトのテキストエンコーディングを設定します |
| --disable-external-links | リモートWebページへのリンクを作成しないでください |
| --enable-external-links | リモートWebページへのリンクを作成します（デフォルト） |
| --disable-forms | HTMLフォームフィールドをPDFフォームフィールドにしないでください（デフォルト） |
| --enable-forms | HTMLフォームフィールドをPDFフォームフィールドに変換する |
| --images | 画像をロードまたは印刷します（デフォルト） |
| --no-images | 画像をロードまたは印刷しないでください |
| --disable-internal-links | ローカルリンクを作成しないでください |
| --enable-internal-links | ローカルリンクを作成する（デフォルト） |
| -n, --disable-javascript | WebページでのJavaScriptの実行を許可しない |
| --enable-javascript | Webページがjavascriptを実行できるようにする（デフォルト） |
| --javascript-delay <msec> | JavaScriptが完了するまで数ミリ秒待機します（デフォルトは200） |
| --keep-relative-links | 相対外部リンクを相対外部リンクとして保持する |
| --load-error-handling <handler> | ロードに失敗したページの処理方法を指定します：abort、ignore、またはskip（デフォルトはabort） |
| --load-media-error-handling <handler> | ロードに失敗したメディアファイルの処理方法を指定します：abort、ignore、またはskip（デフォルトはignore） |
| --disable-local-file-access | --allowで明示的に許可されていない限り、他のローカルファイルを読み込むためのローカルファイルの変換を許可しません。 |
| --enable-local-file-access | 他のローカルファイルを読み込むためのローカルファイルの変換を許可しました。（デフォルト） |
| --minimum-font-size <int> | 最小フォントサイズ |
| --exclude-from-outline | 目次とアウトラインにページを含めないでください |
| --include-in-outline | 目次とアウトラインにページを含める（デフォルト） |
| --page-offset <offset> | 開始ページ番号を設定します（デフォルトは0） |
| --password <password> | HTTP認証パスワード |
| --disable-plugins | インストールされたプラグインを無効にする（デフォルト） |
| --enable-plugins | インストールされたプラグインを有効にします（プラグインはおそらく機能しません） |
| --post <name> <value> | 追加の投稿フィールドを追加（繰り返し可能） |
| --post-file <name> <path> | 追加のファイルを投稿する（繰り返し可能） |
| --print-media-type | 画面の代わりに印刷メディアタイプを使用する |
| --no-print-media-type | 画面の代わりに印刷メディアタイプを使用しないでください（デフォルト） |
| -p, --proxy <proxy> | プロキシを使用する |
| --proxy-hostname-lookup | ホスト名の解決にプロキシを使用する |
| --radiobutton-checked-svg <path> | チェックされたラジオボタンをレンダリングするときにこのSVGファイルを使用します |
| --radiobutton-svg <path> | 未チェックのラジオボタンをレンダリングするときにこのSVGファイルを使用します |
| --resolve-relative-links | 相対外部リンクを絶対リンクに解決します（デフォルト） |
| --run-script <js> | ページの読み込みが完了した後、この追加のJavaScriptを実行します（繰り返し可能） |
| --disable-smart-shrinking | ピクセル/ dpi比を一定にしないWebKitで使用されるインテリジェントな縮小戦略を無効にします |
| --enable-smart-shrinking | ピクセル/ dpi比を一定にしないWebKitで使用されるインテリジェントな縮小戦略を有効にします（デフォルト） |
| --ssl-crt-path <path> | OpenSSL PEM形式のSSLクライアント証明書公開キーへのパス。オプションで中間CAおよび信頼できる証明書が続きます |
| --ssl-key-password <password> | SSLクライアント証明書の秘密鍵のパスワード |
| --ssl-key-path <path> | OpenSSL PEM形式のSSLクライアント証明書秘密鍵へのパス |
| --stop-slow-scripts | 遅いJavaScriptの実行を停止する（デフォルト） |
| --no-stop-slow-scripts | 遅いJavaScriptの実行を停止しないでください |
| --disable-toc-back-links | セクションヘッダーからtocにリンクしない（デフォルト） |
| --enable-toc-back-links | セクションヘッダーからtocへのリンク |
| --user-style-sheet <url> | すべてのページで読み込むために、ユーザースタイルシートを指定する |
| --username <username> | HTTP認証ユーザー名 |
| --viewport-size <> | ウィンドウサイズをエミュレートするためのカスタムスクロールバーまたはCSS属性オーバーフローがある場合は、ビューポートサイズを設定します |
| --window-status <windowStatus> | window.statusがこの文字列と等しくなるまで待ってからページをレンダリングします |
| --zoom <float> | このズーム率を使用（デフォルトは1） |
ヘッダーとフッターのオプション
| オプション | 説明 |
|---|---|
| --footer-center <text> | 中央のフッターテキスト |
| --footer-font-name <name> | フッターのフォント名を設定する（デフォルトはArial） |
| --footer-font-size <size> | フッターのフォントサイズを設定する（デフォルトは12） |
| --footer-html <url> | HTMLフッターを追加します |
| --footer-left <text> | 左揃えのフッターテキスト |
| --footer-line | フッターの上に線を表示 |
| --no-footer-line | フッターの上に線を表示しない（デフォルト） |
| --footer-right <text> | 右揃えのフッターテキスト |
| --footer-spacing <real> | フッターとコンテンツの間隔（mm）（デフォルトは0） |
| --header-center <text> | 中央揃えのヘッダーテキスト |
| --header-font-name <name> | ヘッダーのフォント名を設定する（デフォルトはArial） |
| --header-font-size <size> | ヘッダーのフォントサイズを設定します（デフォルトは12） |
| --header-html <url> | htm |
| --header-left <text> | 左揃えのヘッダーテキスト |
| --header-line | ヘッダーの下に表示行 |
| --no-header-line | ヘッダーの下に行を表示しない（デフォルト） |
| --header-right <text> | 右揃えのヘッダーテキスト |
| --header-spacing <real> | ヘッダーとコンテンツの間隔（mm）（デフォルトは0） |
| --replace <name> <value> | 名前をヘッダーとフッターの値に置き換えます（繰り返し可能） |
TOCオプション
| オプション | 説明 |
|---|---|
| --disable-dotted-lines | 目次で点線を使用しないでください |
| --toc-header-text <text> | tocのヘッダーテキスト（デフォルトの目次） |
| --toc-level-indentation <width> | この長さによるtocインデントの見出しの各レベル（デフォルトは1em） |
| --disable-toc-links | tocからセクションにリンクしないでください |
| --toc-text-size-shrink <real> | tocの見出しの各レベルに対して、フォントはこの係数でスケーリングされます（デフォルトは0.8） |
| --xsl-style-sheet <file> | 目次の印刷に付属のxslスタイルシートを使用する |
ページサイズ
レンダリングされたドキュメントのデフォルトのページサイズはA4ですが、この--page-sizeオプションを使用すると、A3、Letter、Legalなど、他のほとんどのものに変更できます。 サポートされているページサイズの完全なリストについては、<http://qt-project.org/doc/qt-4.8/qprinter.html#PaperSize-enum>をご覧ください。
ページサイズをより詳細に制御するには、-page-heightおよび--page-widthオプションを使用できます。
stdinからの引数の読み取り
stdinからの引数の読み取り： バッチで多くのページを変換する必要があり、wkhtmltopdfが起動するには少し遅すぎると感じる場合は、-read-args-from-stdinを試してください。
--read-args-from-stdinの場合、stdinのwkhtmltopdfに送信された入力の各行は、wkhtmltopdfに指定された引数と指定された行で指定された引数を組み合わせて、wkhtmltopdfの個別の呼び出しとして機能します。
たとえば、次のことができます。
echo "http://qt-project.org/doc/qt-4.8/qapplication.html qapplication.pdf" >> cmds echo "cover google.com http://en.wikipedia.org/wiki/Qt_(software) qt.pdf" >> cmds wkhtmltopdf --read-args-from-stdin --book < cmds
プロキシの指定
デフォルトでは、環境変数からプロキシ情報が読み取られます。 proxy、all_proxyおよびhttp_proxy、プロキシオプションは、-pスイッチで指定することもできます。
<type> := "http://" | "socks5://"
<serif> := <username> (":" <password>)? "@"
<proxy> := "None" | <type>? <string>? <host> (":" <port>)?
以下にいくつかの例を示します（BNFに不慣れな場合）：
http://user:password@myproxyserver:8080
socks5://myproxyserver
None
フッターとヘッダー
--header-および--footer argumentsを使用して、ヘッダーとフッターをドキュメントに追加できます。 ヘッダーおよびフッターのテキスト文字列で、たとえば--header-left、次の変数が置換されます。
* [page] 現在印刷されているページの数に置き換えられます * [frompage] 印刷される最初のページの番号に置き換えられます * [topage] 印刷する最後のページの番号に置き換えられます * [webpage] 印刷されるページのURLに置き換えられます * [section] Replaced by the name of the current section * [subsection] 現在のセクションの名前に置き換えられます * [date] システムローカル形式の現在の日付に置き換えられます * [isodate] ISO 8601拡張形式の現在の日付に置き換えられます * [time] システムローカル形式の現在時刻に置き換えられます * [title] 現在のページオブジェクトのタイトルに置き換えられます * [doctitle] 出力ドキュメントのタイトルに置き換えられます * [sitepage] 変換中の現在のサイトのページ番号に置き換えられます * [sitepages] 変換中の現在のサイトのページ数に置き換えられます
--header-right "Page [page] of [toPage]"を指定する例として、テキストは "Page x of y"になります。xは現在のページの番号、yは最後のページの番号、ドキュメントの左上隅に表示されます。
ヘッダーとフッターもHTMLドキュメントで提供できます。 例として、-header-html header.htmlを指定し、header.htmlで次のコンテンツを使用できます。
<!DOCTYPE html> <html><head><script> function subst() { var vars = {}; var query_strings_from_url = document.location.search.substring(1).split('&'); for (var query_string in query_strings_from_url) { if (query_strings_from_url.hasOwnProperty(query_string)) { var temp_var = query_strings_from_url[query_string].split('=', 2); vars[temp_var[0]] = decodeURI(temp_var[1]); } } var css_selector_classes = ['page', 'frompage', 'topage', 'webpage', 'section', 'subsection', 'date', 'isodate', 'time', 'title', 'doctitle', 'sitepage', 'sitepages']; for (var css_class in css_selector_classes) { if (css_selector_classes.hasOwnProperty(css_class)) { var element = document.getElementsByClassName(css_selector_classes[css_class]); for (var j = 0; j < element.length; ++j) { element[j].textContent = vars[css_selector_classes[css_class]]; } } } } </script></head><body style="border:0; margin: 0;" onload="subst()"> <table style="border-bottom: 1px solid black; width: 100%"> <tr> <td class="section"></td> <td style="text-align:right"> Page <span class="page"></span> of <span class="topage"></span> </td> </tr> </table> </body></html>
この例からわかるように、引数はget形式でヘッダー/フッターhtmlドキュメントに送信されます。
オウトライン
qtがパッチされたWkhtmltopdfは、ブックマークとも呼ばれるPDFアウトラインをサポートしています。これは--outlineスイッチを指定することで有効にできます。
アウトラインは<h？>タグに基づいて生成されます。これを行う方法の詳細については、目次のセクションを参照してください。
HTMLドキュメントで<h？>タグが寛大に広がる場合、アウトラインツリーは非常に深くなることがあります。 --outline-depthスイッチを使用して、これをバインドできます。
目次
目次オブジェクトは、コマンドラインにtocオブジェクトを追加することにより、ドキュメントに追加できます。 たとえば：
wkhtmltopdf toc http://qt-project.org/doc/qt-4.8/qstring.html qstring.pdf
目次は、入力ドキュメントのHタグに基づいて生成されます。最初にXMLドキュメントが生成され、次にXSLTを使用してHTMLに変換されます。
生成されたXMLドキュメントは、-dump-outlineスイッチを使用してファイルにダンプすることで表示できます。 たとえば：
wkhtmltopdf --dump-outline toc.xml http://qt-project.org/doc/qt-4.8/qstring.html qstring.pdf
XSLTドキュメントは、-xsl-style-sheetスイッチを使用して指定できます。 たとえば：
wkhtmltopdf toc --xsl-style-sheet my.xsl http://qt-project.org/doc/qt-4.8/qstring.html qstring.pdf
--dump-default-toc-xslスイッチを使用して、デフォルトのXSLTスタイルシートを標準出力にダンプできます。 これは、独自のスタイルシートを書くための良いスタートです
wkhtmltopdf --dump-default-toc-xsl
XMLドキュメントはネームスペース"http://wkhtmltopdf.org/outline"にあり、"outline"と呼ばれるルートノードがあり、これには多数の"item"ノードが含まれています。 アイテムには、任意の数のアイテムを含めることができます。 これらは、アイテムが表すセクションのアウトラインサブセクションです。 アイテムノードには次の属性があります。
* "title" セクションの名前。
* "page" セクションが発生するページ番号。
* "link" セクションにリンクするURL。
* "backLink" セクションがリンクするアンカーの名前。
残りの目次オプションはデフォルトのスタイルシートにのみ影響するため、カスタムスタイルシートを指定する場合は機能しません。
連絡先
バグが発生したり、新しい機能をリクエストしたい場合は、<https://github.com/wkhtmltopdf/wkhtmltopdf/issues>をご覧ください。
以上、ここまでです。
