PDF版作成のカスタマイズ設定 - pgsql-jp/jpug-doc GitHub Wiki

PDF版作成のカスタマイズ設定

日本語マニュアルのPDFを作成する場合は、本家の設定に加えて日本語マニュアル用の設定を追加する必要があります。 また、デフォルトから変更した方が見栄えが良くなる設定も説明をします。

この文章はまだ検討中の項目が含まれます。より良い設定等ありましたら、ご指摘下さい。

PDF版作成の流れ

元のソースは SGMLで管理されています。

PDFは以下のようにいくつかの変換を経て作成されます。

DocBook SGML(history.sgml,info.sgml....) → XML(postgres.xml) → fo.tmp(postgres-A4.fo.tmp) → fo(postgres-A4.fo) → (postgres-A4-fop.pdf)

postgres.xml までは、xhtml版等他の形式に変換される中間形式になります。

その後、xmllint, xsltproc によりXMLの変換をし、Apache-FOPにより最終的に postgres-A4-fop.pdf が作成されます。

PDFの作成

doc/src/sgml/ 内で以下のようにすればpdfが作成できます。

$ make postgres-A4-fop.pdf

一部の章みのPDFの作成

全体のPDFを作成しようとする時間が掛かるため一部の章だけ作成するには以下のようにします。

必要な章名を指定してビルドします。walの章であれば、wal.sgmlの最初の方に「chapter id="wal"」となっていて、このwalを指定します。

$ make "XSLTPROCFLAGS= --stringparam rootid wal" postgres-A4-fop.pdf

カスタマイズ対象ファイル

PDFのカスタマイズをする場合は、ほとんど doc/src/sgml/ にある stylesheet-fo.xsl の設定を変更します。これはxsltprocが使用して、DocBookので設定とカスタマイズされた設定から印刷イメージの体裁を入れたFOPで処理出来る形式にします。

最終的にPDFで使用されるフォントについては、fop-font.shの実行によりfop.xconfが作成されます。(本家には入ってませんが、日本語マニュアルのレポジトリには含まれています）。

stylesheet-fo.xsl は DocBook の設定ファイルになっていて、Docbookのxsl(例:/usr/share/xml/docbook/stylesheet/docbook-xsl/fo)を stylesheet-fo.xsl で上書き変更するように設定します。

DocBookのカスタマイズ項目全てを説明は出来ないので、本家からの変更点を説明します。 これ以外にも多くのカスタマイズ出来る項目があるので、 DocBook XSL Stylesheets: Reference Documentation 等を参考に設定してみて下さい。

日本語版必須項目

日本語モード

デフォルトの様々な設定を日本語モードに設定する

<xsl:param name="l10n.gentext.default.language">ja</xsl:param>

日本語フォントの設定

一応Mac,Windows,Linux(Ubuntu)用のいくつかのフォントを指定しています。先に指定した順から見つかったフォントが使用されます。（このフォントを入れたほうが良いというフォントがありましたら教えて下さい） title は見出し、bodyが本文、monospaceはコード等の固定長フォントを指定しています。symbolはキーワードのような修飾になっている時に使用されるようです。dingbatとsansは日本語マニュアルでは使用されていないようですが、もし指定された時のためにあらかじめ入れています。

<xsl:param name="title.font.family" select="'YuGothic,Meiryo,MS-PGothic,Hiragino Kaku Gothic ProN,TakaoExGothic'"/>
<xsl:param name="body.font.family" select="'YuMincho,Meiryo,MS-PMincho,Hiragino Mincho ProN,TakaoExMincho'"/>
<xsl:param name="monospace.font.family" select="'Osaka-mono,MS-Gothic,TakaoGothic'"/>
<xsl:param name="symbol.font.family" select="'Osaka-mono,MS-Gothic,TakaoExGothic'"/>
<xsl:param name="dingbat.font.family" select="'YuGothic,Meiryo,MS-PGothic,Hiragino Kaku Gothic ProN,TakaoExGothic'"/>
<xsl:param name="sans.font.family" select="'YuGothic,Meiryo,MS-PGothic,Hiragino Kaku Gothic ProN,TakaoExMincho'"/>

インストールされていてもフォントが使用できない場合もあります。どのフォントが使用できるかは、以下のコマンドで確かめることが出来ます(fop.jar のパスを環境に合わせて変更して下さい）。

java -cp /usr/share/java/fop.jar org.apache.fop.tools.fontlist.FontListMain -c fop.xconf

以上で日本語の入ったPDFが出力できるようになります。フォントが見つからないような場合は文字が「####」のようになります。

日本語版推奨項目

本文インデント

本文のインデントを0に設定。DocBookでは見出しにぶら下がるように本文がインデントされますが、全体的に右に寄って表示されてしまうので、それを止めます。

<xsl:param name="body.start.indent">0</xsl:param>

行間

日本語では行間を広げたほうが見やすいと言われています。よく使用される設定は1.5倍です。以下で設定します。

<xsl:param name="line-height">150%</xsl:param>

テーブル(表)のフォント指定

テーブル(表)のフォントサイズを80%に設定。表の個別の幅の調整が難しいため、日本語にすると特に、はみ出すことが多くなります。 はみ出しを少し軽減するためにフォントを小さくします。

<xsl:attribute-set name="table.properties" use-attribute-sets="normal.para.spacing">
  <xsl:attribute name="font-size">80%</xsl:attribute>
  <xsl:attribute name="wrap-option">wrap</xsl:attribute>
  <xsl:attribute name="text-align">left</xsl:attribute>
  <xsl:attribute name="white-space-treatment">ignore</xsl:attribute>
</xsl:attribute-set>

警告や注記

警告や注記の背景をグレーにして青枠で囲みます。

<xsl:attribute-set name="nongraphical.admonition.properties">
  <xsl:attribute name="border">1pt solid blue</xsl:attribute>
  <xsl:attribute name="padding">10pt</xsl:attribute>
  <xsl:attribute name="background-color">#FCFCFC</xsl:attribute>
</xsl:attribute-set>

プログラムコードや出力メッセージ

プログラムコードや出力メッセージ(固定長で表示される)の背景をグレーにして黒枠で囲みます。

<xsl:param name="shade.verbatim">1</xsl:param>
<xsl:attribute-set name="shade.verbatim.style">
  <xsl:attribute name="border">1pt solid black</xsl:attribute>
  <xsl:attribute name="margin-left">0</xsl:attribute>
  <xsl:attribute name="margin-right">0</xsl:attribute>
  <xsl:attribute name="padding">5pt</xsl:attribute>
  <xsl:attribute name="background-color">#EFEFEF</xsl:attribute>
</xsl:attribute-set>

リンクの色

リンク等クリックして移動出来る項目の色を青にします。

<xsl:attribute-set name="xref.properties">
  <xsl:attribute name="color">blue</xsl:attribute>
</xsl:attribute-set>
<xsl:attribute-set name="simple.xlink.properties">
  <xsl:attribute name="color">blue</xsl:attribute>
</xsl:attribute-set>

見出しと本文のスペース調整

見出しと本文のスペースを調整して同じブロックに見えるように変更してます。 また見出しの色を設定してます。

<xsl:attribute-set name="section.title.properties">
  <xsl:attribute name="line-height">30pt</xsl:attribute>
  <xsl:attribute name="color"><xsl:value-of select="$title.color"/></xsl:attribute>
  <xsl:attribute name="space-before.minimum">0.5em</xsl:attribute>
  <xsl:attribute name="space-before.optimum">1.2em</xsl:attribute>
  <xsl:attribute name="space-before.maximum">1.4em</xsl:attribute>
  <xsl:attribute name="space-after.minimum">0.1em</xsl:attribute>
  <xsl:attribute name="space-after.optimum">0.1em</xsl:attribute>
  <xsl:attribute name="space-after.maximum">0.1em</xsl:attribute>
</xsl:attribute-set>
Add a custom footer
⚠️ **GitHub.com Fallback** ⚠️