svnbook日本語訳のPDF版を作成する

db2latexの使用メモ

Author:	Testuya Saito
Contact:	t2psyto_at_gmail.com
Revision:	1
Date:	2006/02/28

はじめに
必要な環境とパッケージ
- 注意: オリジナルのdb2latexは使わないこと
svnbook関連のファイルを配置する
docbook-xslの commons/common.mod.xsl と commons/ja.xml にパッチをあてる
カスタムxslファイル(svnbook.xsl)の作成
DocBookからPDFを作るまでのコマンド手順
手作業での修正
既知の問題点

はじめに

svnbook日本語訳のPDF版が欲しかったので、 db2latex を使用して、DocBook から LaTeX を経由して PDF を生成する方法を試してみました。

必要な環境とパッケージ

ディストリビューション:

Debian Sarge

インストールしておくパッケージ:

db2latex-xsl

http://packages.debian.org/stable/text/db2latex-xsl

xsltproc
TeX環境（※）
- 基本的には、日本語pTeX + dvipdfmxで、LaTeX→PDFができればよいはず。
- 参考: http://cise.edu.mie-u.ac.jp/~okumura/texwiki/?Linux%2FDebian

svnbook関連:

svnbookの日本語訳DocBookファイル
- http://subversion.bluegate.org/book.r1906-1-jp.tar.gz
svnbookで使用している画像ファイル
- http://svn.red-bean.com/svnbook/trunk/src/en/book/images/
DTDファイル
- http://svn.red-bean.com/svnbook/trunk/src/tools/dtd/

注意: オリジナルのdb2latexは使わないこと

http://db2latex.sourceforge.net で配布しているオリジナルのdb2latex ではうまくいかなかった。xsltprocに通すと以下ようなのエラーがでた。:

compilation error: file db2latex-xsl/xsl/qandaset.mod.xsl line 366 element template
xsl:template: error duplicate name 'question.answer.label'

上記の問題は、debianパッケージ db2latex-xsl-0.8pre1-3 以降で修正されています。

参照: http://bugs.debian.org/293989

他にも、debian の db2latex-xsl パッケージには、オリジナルの db2latex にいくつか修正が施されているようです。

上記のような理由から、Debianパッケージ版 db2latex の利用をおすすめします。

svnbook関連のファイルを配置する

svnbookに必要なファイルをダウンロードして、以下のように配置します。

作業用ディレクトリ workspace の作成:

~/$ mkdir workspace
~/$ cd workspace/

svnbook日本語訳のDocBookアーカイブをダウンロードして展開:

~/workspace$ wget http://subversion.bluegate.org/book.r1906-1-jp.tar.gz
~/workspace$ tar xzvf book.r1906-1-jp.tar.gz

svnbookが使用するDTDファイル群を、workspace/tools/dtd 以下に配置。ダウンロードにはsvnを使う。:

~/workspace$ mkdir tools
~/workspace$ cd tools
~/workspace/tools$ svn checkout http://svn.red-bean.com/svnbook/trunk/src/tools/dtd

workspaceの直下に、PDF生成用のディレクトリを作成:

~/workspace$ mkdir pdf
~/workspace$ cd pdf

pdfディレクトリ以下に、svnbookの画像ファイルを配置する。画像ファイルのダウンロードにはsvnを使う。:

~/workspace/pdf$ svn checkout http://svn.red-bean.com/svnbook/trunk/src/en/book/images

latexでコンパイルする際に必要になるので、PNG画像ファイルに対応する .bb ファイルもついでに作成しておく。 (参考: http://pinna.cside4.jp/tips/latex/dvipdfm.html#DVIPDFM ):

~/workspace/pdf$ cd images
~/workspace/pdf/images$ ls *.png | xargs ebb

docbook-xslの commons/common.mod.xsl と commons/ja.xml にパッチをあてる

svnbook日本語訳のアーカイブに付属している docbook.diff にならって、 docbook-xslの commons/common.xsl と commons/ja.xml にパッチをあてます。

以下に示すパッチは my_docbook.diff にまとめてあります。

/usr/share/xml/docbook/stylesheet/db2latex/latex/common/common.xsl へのパッチ:

diff -ur /usr/share/xml/docbook/stylesheet/db2latex/latex/common/common.xsl.orig /usr/share/xml/docbook/stylesheet/db2latex/latex/common/common.xsl
--- /usr/share/xml/docbook/stylesheet/db2latex/latex/common/common.xsl.orig    2006-02-22 18:47:27.000000000 +0900
+++ /usr/share/xml/docbook/stylesheet/db2latex/latex/common/common.xsl 2006-02-27 00:51:54.000000000 +0900
@@ -538,7 +538,7 @@

   <xsl:apply-templates select="$node//firstname[1]"/>

-  <xsl:text> [FAMILY Given]</xsl:text>
+  <!-- <xsl:text> [FAMILY Given]</xsl:text> -->
 </xsl:template>

 <xsl:template name="person.name.last-first">

/usr/share/xml/docbook/stylesheet/db2latex/latex/common/ja.xml へのパッチ:

diff -ur /usr/share/xml/docbook/stylesheet/db2latex/latex/common/ja.xml.orig /usr/share/xml/docbook/stylesheet/db2latex/latex/common/ja.xml
--- /usr/share/xml/docbook/stylesheet/db2latex/latex/common/ja.xml.orig        2006-02-22 19:59:31.000000000 +0900
+++ /usr/share/xml/docbook/stylesheet/db2latex/latex/common/ja.xml     2006-02-27 09:01:00.000000000 +0900
@@ -366,6 +366,7 @@
     <l:template name="varlistentry" text="%n"/>
     <l:template name="warning" text="%t"/>
     <l:template name="page.citation" text=" [%p]"/>
+<!--
     <l:template name="bridgehead" text="%t&#38917;"/>
     <l:template name="refsection" text="%t&#38917;"/>
     <l:template name="refsect1" text="%t&#38917;"/>
@@ -378,6 +379,19 @@
     <l:template name="sect5" text="%t&#38917;"/>
     <l:template name="section" text="%t&#38917;"/>
     <l:template name="simplesect" text="%t&#38917;"/>
+-->
+    <l:template name="bridgehead" text="%t&#x306E;&#38917;"/>
+    <l:template name="refsection" text="%t&#x306E;&#38917;"/>
+    <l:template name="refsect1" text="%t&#x306E;&#38917;"/>
+    <l:template name="refsect2" text="%t&#x306E;&#38917;"/>
+    <l:template name="refsect3" text="%t&#x306E;&#38917;"/>
+    <l:template name="sect1" text="%t&#x306E;&#38917;"/>
+    <l:template name="sect2" text="%t&#x306E;&#38917;"/>
+    <l:template name="sect3" text="%t&#x306E;&#38917;"/>
+    <l:template name="sect4" text="%t&#x306E;&#38917;"/>
+    <l:template name="sect5" text="%t&#x306E;&#38917;"/>
+    <l:template name="section" text="%t&#x306E;&#38917;"/>
+    <l:template name="simplesect" text="%t&#x306E;&#38917;"/>
   </l:context>
   <l:context name="xref-number">
     <l:template name="answer" text="&#31572;&#65306;&#160;%n"/>
@@ -404,7 +418,10 @@
   <l:context name="xref-number-and-title">
     <l:template name="appendix" text="&#20184;&#37682;&#160;%n. %t"/>
     <l:template name="bridgehead" text="&#38917;&#160;%n. &#12300;%t&#12301;"/>
+<!--
     <l:template name="chapter" text="&#31456;&#160;%n. %t"/>
+-->
+    <l:template name="chapter" text="&#31532;%n&#31456; %t"/>
     <l:template name="equation" text="&#24335;&#160;%n. &#12300;%t&#12301;"/>
     <l:template name="example" text="&#20363;&#160;%n. &#12300;%t&#12301;"/>
     <l:template name="figure" text="&#22259;&#160;%n. &#12300;%t&#12301;"/>

カスタムxslファイル(svnbook.xsl)の作成

以下の内容のファイル svnbook.xsl を、ディレクトリ workspace 直下に作成します。

workspace/svnbook.xsl:

<?xml version='1.0'?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version='1.0'>

  <xsl:import href="/usr/share/xml/docbook/stylesheet/db2latex/latex/docbook.xsl"/>
  <xsl:output method="text" encoding="euc-jp" indent="yes"/>

  <xsl:variable name="latex.biblio.output">all</xsl:variable>
  <xsl:variable name="latex.document.font" select="'courier,helvet,times'"/>

  <xsl:variable name="latex.fancyhdr.truncation.partition"></xsl:variable>
  <xsl:variable name="latex.use.fancyhdr">1</xsl:variable>
  <xsl:variable name="latex.use.fancybox">1</xsl:variable>

  <xsl:variable name="latex.pdf.support">0</xsl:variable>
  <xsl:variable name="latex.math.support">0</xsl:variable>
  <xsl:variable name="latex.use.babel">0</xsl:variable>

  <xsl:variable name="admon.graphics.path">images</xsl:variable>
  <xsl:variable name="graphic.default.extension">.png</xsl:variable>

  <!--
  <xsl:variable name="latex.use.tabularx">1</xsl:variable>
  -->

  <xsl:variable name="latex.use.hyperref">1</xsl:variable>
  <xsl:variable name="latex.hyperref.param.common">  colorlinks=true,
  colorlinks=true,
  linkcolor=blue,
  citecolor=blue,
  filecolor=blue,
  pagecolor=blue,
  urlcolor=blue,
  bookmarks=true,
  bookmarksnumbered=true,
  bookmarkstype=toc</xsl:variable>
  <xsl:variable name="latex.hyperref.param.dvips">dvipdfm</xsl:variable>

<xsl:variable name="latex.book.preamblestart">
<xsl:text>%# -*- coding: euc-japan-unix -*-
% ========================  Begin of USER preamble.
\documentclass{jsbook}
\usepackage{txfonts}
\setlength{\textwidth}{\fullwidth}
\setlength{\evensidemargin}{\oddsidemargin}
\setlength\footskip{2.5\baselineskip}
\addtolength{\textheight}{-2.5\baselineskip}
\usepackage[dvipdfm]{color}
\usepackage[dvipdfm]{graphicx}
\AtBeginDvi{\special{pdf:tounicode EUC-UCS2}}
% ========================  End of USER preamble.
</xsl:text>
</xsl:variable>

</xsl:stylesheet>

DocBookからPDFを作るまでのコマンド手順

#DocBookからPDFを作るまでのコマンド手順を以下に示します。

DocBook から TeXソースを生成する

以下のコマンドを実行します。

~/workspace/pdf$ xsltproc -o svnbook.ja.tex ../svnbook.xsl ../book.arch/book.xml

TeXソースから DVIファイルを生成する

以下のコマンドを実行して、TeXソースからDVIファイルを生成します。

~/workspace/pdf$ platex svnbook.ja.tex

ただし、自動生成したTeXソースそのままではコンパイルがとおりません。がんばって手作業での修正を行ってください。

※目次の内容をきちんと反映させるために、2回コンパイルする必要があります。

DVIファイルから PDF を生成する

TeXソースのコンパイルができて、DVIファイルが得られたら、dvipdfmx で PDF を生成します。:

~/workspace/pdf$ dvipdfmx svnbook.ja.dvi

手作業での修正

db2latexで生成したTeXソースの修正作業の内容を以下に示します。

実体参照の置き換え漏れを直す

実体参照の置き換え漏れは、現時点では2つだけです。

" " は半角スペースです。 "—" は em-dash である。TeXで em-dash の記号を表現するには、 " --- " と記述します。

以下のパターンで置き換える。

" " -> " "
"—" -> " --- " # em-dash, 全ダッシュ

admonitionのアイコンファイル指定の修正

アイコン用の画像ファイルの拡張子".png"を付け足す。

以下のパターンで置き換える。

"\begin{admonition}{images/note}" -> "\begin{admonition}{images/note.png}"
"\begin{admonition}{images/tip}" -> "\begin{admonition}{images/tip.png}"
"\begin{admonition}{images/warning}" -> "\begin{admonition}{images/warning.png}"

エスケープミスの修正

記号 "\" のエスケープミスを直す。本文中で、改行文字とPATH区切り文字を書いている部分がひっかかる。

本文中で改行文字に言及している部分

「5. リポジトリの管理」→「リポジトリの保守」→「管理者用ツールキット」 →「svndumpfilter」のセクション。

' \r\n ' -> ' \\r\\n '
' \n ' -> ' \\n '

WindowsのPATHやレジストリのセパレータ記号

PATHのセパレータ "\" がエスケープできていないので直す。（※複数箇所ある。）

ここの修正作業ではうまい方法を思いつかなかったので、トライ・アンド・エラー式に「platexでコンパイル→エラー発生→該当箇所を直す」を繰り返した。

目次の追加

db2latexのTeXソースそのままだと、目次ページが作られません。

目次生成のTeXコマンドを追加

適当な行に、目次生成のTeXコマンド:

\tableofcontents

を挿入する。

個人的には、「序文」と「第1章」の間あたりがよいと思います。手元にある本を見ると、大体の本では、「まえがき」や「序文」の後ろに目次が配置さ9れているようでした。

「まえがき」や「序文」も目次に表示させる

"\chapter*{}" や "\section*{}" のように、アスタリスク記号つきのブロックは標準では目次に追加されません。目次に表示させるには "\addcontentsline" コマンドで明示的に指定します。

TeXソース中の「まえがき」や「序文」のブロックにある、 "\chapter*{}","\section*{}","\subsection*{}" の次の行に、それぞれ "\addcontentsline" コマンドを挿入する。

例: before:

\chapter*{まえがき}%
\label{svn.foreword}\hypertarget{svn.foreword}{}%

after:

\chapter*{まえがき}%
\addcontentsline{toc}{chapter}{まえがき}%
\label{svn.foreword}\hypertarget{svn.foreword}{}%

表のフォーマットを変更

表の幅が用紙サイズからはみ出さないように、表のフォーマットには tabular ではなく tabularx を使用するように変更します。

たとえば:

\begin{tabular}{|c|c|c|}
～～～～
\end{tabular}

を、以下のように書き換えます。:

\begin{tabularx}{\textwidth}{|X|X|X|}
～～～～
\end{tabularx}

db2latexがtabularxを使ってくれない

db2latexのヘルプ (latex.use.tabularx) を見ると、 svnbook.xsl(db2latexのカスタムxlsファイル) に:

<xsl:variable name="latex.use.tabularx">1</xsl:variable>

と書くだけで tabularx を使ってくれそうな雰囲気ですが、試してもうまくいきませんでした。

/usr/share/xml/docbook/stylesheet/db2latex/latex/table.mod.xsl を見ると、 tabularx が使用される実際の条件付けとして、 $latex.use.tabularx が 1 であることに加えて、table.mod.xsl の内部変数 $usex が 1 になるような条件がさらに必要なようです。

また、仮に db2latex が tabularx を使ってくれた場合でも、table.mod.xls に

\begin{tabularx}{\hline}

とハードコードされているので、テーブル幅が hline に固定されてしまうようです。

既知の問題点

手作業による修正でも解決できていないもの

ページスタイルを fancy にする "usapackage{fancyhdr}" 指定をしているにもかかわらず、各章の最初のページのスタイルだけが plain スタイルになってしまう。
章やセクションのタイトルで、なぜか2byte文字だけ小さいフォントになる
TeXソースの生成時、「No "ja" localization of "simplesect" exists; using "en".」みたいな worning がたくさんでる