Akio's Log

ソフトウェア開発、プロジェクトマネジメント、プログラミング、ランニングなどなど

CentOS4/CentOS5:doxygenでUTF-8日本語PDFのドキュメントを出力する

doxygenからUTF-8で日本語PDFファイルを作成する環境をCentOSに構築したのですが、予想以上にしんどい思いをしたので、まとめメモを作成しておきます。誰かの参考になれば幸いです。

背景

仕事で作ったプログラムの成果物のひとつとして、doxygenで出力したファイルを納品している。開発中は出力されたHTMLのままの方が何かと使い勝手も良いのだが、納品用のドキュメントとなると、PDFファイルとそれを印刷した紙のドキュメントが、やはりお客様には好まれるようだ。

doxygen自体は、導入してHTMLを出力させるだけであれば、簡単に使うことが出来る。graphvizをインストールすれば、関数の呼び出し関係やヘッダのインクルード関係など、ビジュアル的にも見栄えの良い図を生成することも出来る。ただし、PDFファイルへ出力しようとすると、日本語の処理でエラーが発生してしまい、うまく出力できない。

日本語でのPDFファイルを生成するには、UTF-8に対応した日本語LaTeX環境を整える必要があるので、早速インストールしてみた。

環境

  • CentOS4/CentOS5.3

やりたい事

  • UTF-8文字コードで書かれた、日本語交じりのソースファイルから、APIドキュメントのPDFファイルを生成する

使用したツール、バージョン

ptetex
  • ptetex3-20090610.tar.gz
  • tetex-src-3.0.tar.gz
  • tetex-texmf-3.0po.tar.gz

http://www.nn.iij4u.or.jp/~tutimura/tex/ptetex.html

概要

  1. doxygenをインストール
  2. graphvizをインストール
  3. ptetexをインストール

この3つでOK。

doxygenインストール

旧バージョンをyumで削除する

yumで追加できるdoxygenのバージョンが古いので、既にyumでインストール済みであれば、削除する。

まずバージョンチェック

  • CentOS4系:doxygen1.3.9
  • CentOS5系:doxygen1.4.7

# yum list |grep doxygen
doxygen.i386 1:1.3.9.1-1 installed

# yum list |grep doxygen
doxygen.i386 1:1.4.7-1.1 installed

yum remove で削除

# yum remove doxygen
Setting up Remove Process
Resolving Dependencies

    • > Populating transaction set with selected packages. Please wait.
    • > Running transaction check

(略)
Removed: doxygen.i386 1:1.3.9.1-1
Complete!

インストール

適当なディレクトリでファイルを解凍。一般的な手順でインストール実行

$ tar xvfz doxygen-1.5.9.src.tar.gz
$ cd doxygen-1.5.9
$ ./configure
$ make
$ make docs
$ su
# make install
# doxygen --version
1.5.9

graphviz

コールグラフ等を生成するためのgraphvizもインストールする。

最新版を入手する

http://www.graphviz.org/Download_source.php

インストール

$ tar xvfz graphviz-2.24.0.tar.gz
$ cd graphviz-2.24.0
$ ./configure
$ make
$ su
# make install

Doxyfile編集&HTML出力テスト

ここまでインストールできれば、コールグラフ入りのAPIドキュメントのHTMLは生成可能である。
なので、まずここで出力テストをしてみる。

Doxyfileの雛形作成

UTF-8で書かれたソースコードが、「sample_project」というディレクトリにあるという前提で。
「-g」オプションをつけてdoxygenを実行すると、設定ファイルの雛形を自動で生成してくれる。通常は、この雛形ファイルを編集して使うことになる。

$ cd sample_project
$ doxygen -g
$ vi Doxyfile

以下、設定ファイル上で編集した方が良さそうな項目をリストアップしてみる。ソースコード、出力形式ともにUTF-8を想定。

  • PROJECT_NAME = Sample Project
  • PROJECT_NUMBER = 1.0.0
  • OUTPUT_DIRECTORY = doxygen
  • OUTPUT_LANGUAGE = Japanese
  • JAVADOC_AUTOBRIEF = YES
  • TAB_SIZE = 4
  • OPTIMIZE_OUTPUT_FOR_C = YES
  • EXTRACT_ALL = YES
  • EXTRACT_PRIVATE = YES
  • EXTRACT_STATIC = YES
  • SORT_MEMBER_DOCS = NO
  • SOURCE_BROWSER = YES
  • STRIP_CODE_COMMENTS = NO
  • GENERATE_TREEVIEW = YES
  • LATEX_CMD_NAME = platex
  • PDF_HYPERLINKS = NO
  • USE_PDFLATEX = NO
  • HAVE_DOT = YES
  • UML_LOOK = YES

ここまで設定すれば、HTMLとしてドキュメントが出力される。

$ doxygen

Doxyfileの置いてあるディレクトリ上でdoxygenコマンドを実行すると、指定した出力ディレクトリの「html」ディレクトリ配下にドキュメントが出力される。ブラウザ等でhtml以下のindex.htmlを開けば確認が出来る。

日本語LaTeX環境(teTeX用日本語パッチ)のインストール

日本語PDF化までもう少し。

ファイルを入手する

http://www.nn.iij4u.or.jp/~tutimura/tex/ptetex.html

  • ptetex3-20090610.tar.gz
  • tetex-src-3.0.tar.gz
  • tetex-texmf-3.0po.tar.gz

それぞれ、最新の日付のファイルを使用する。
入手したファイルを、同一ディレクトリ上に保存する。

/ptetex3/ -+- tetex-src-3.0.tar.gz

+- tetex-texmf-3.0po.tar.gz
+- ptetex3-20090610.tar.gz
+- my_option(後から作る)

基本的には、配布ファイル内にあるREADMEの通りに進めればOK。

ファイル展開

$ cd ***/ptetex3
$ $ tar xvfz ptetex3-20090610.tar.gz
$ cd ptetex3-20090610

オプション指定

ここでの指定がよくわからなかったので、このサイトの情報を参考にした。
http://d.hatena.ne.jp/stdout/20090224/1235444757
また、こちらのサイトにも書いてあるが、XDVIオプションとPXDVIオプションを「echo」にしないと、make実行中にエラーが発生してしまうので、注意する。
2008-12-13

設定ファイルmy_option.sampleの雛形をコピーして、上位ディレクトリにmy_optionファイルとして保存する。

$ cp my_option.sample ../my_option

修正した項目はこちら。(※my_optionファイル自体のエンコーディングがISO-8859なので、viだと文字化けが発生するので注意)

### 日本語 pTeX 拡張あり (pdvips, pxdvi)
JAPANESE=international

### ptex/platex コマンドの入出力文字コードを指定(ディフォルトは EUC
### 'UTF8' は ptetex3 の独自拡張
KANJI_CODE=UTF8

### kanji <=> unicode 変換に iconv を使う
conf_option --enable-kanji-iconv

### make test で xdvi を除外する
XDVI=echo
PXDVI=echo

コンパイル実行

makeコマンドでコンパイル実行。5〜10分くらい時間がかかるので、コーヒーを沸かして待つ。

$ make

インストール実行

$ su
# make install

PATHの設定

/usr/local/teTeX/binにパスを通す。

$ PATH=/usr/local/teTeX/bin:$PATH; export PATH

確認後は、.bashrcなどに記入しておく。

テスト

簡単なtexファイルを作成してテストを行う。

$ vi test.tex
\documentclass{jsarticle}
\begin{document}
testtest
日本語テスト
\end{document}


dviへ変換。xdviコマンドではなく、ptetexでインストールした、日本語対応の「pxdvi」コマンドでファイルを閲覧してみる。

$ platex text.tex
$ pxdvi test.dvi


dviファイルをPostscriptファイルへ変換。dvipsコマンドではなく、「pdvips」コマンドを使用する。

$ pdvips test.dvi
$ ggv test.ps    ## CentOS4の場合
$ evince test.ps    ##CentOS5の場合


dviファイルをpdfファイルへ変換する。「dvipdfmx」コマンドを使用する。

$ dvipdfmx test.dvi

doxygenMakefileから実行するために・・・

doxygenが生成するMakefileを見ると、「dvi->ps」と「ps->pdf」の2段階でPDFファイルに変換している事がわかる。それぞれ、「pdvips」コマンドと「ps2pdf」コマンドが対応する。

日本語PDFファイルを生成するためには、dvipsコマンドではなくpdvipsコマンドが実行されなくてはならないので、以下のようにしてみた。

# cd /usr/local/teTeX/bin
# ln -s -i pdvips dvips

強制的にpdvipsコマンドにリンクを貼るようにした。

最終チェック

最後に「通し」でチェックしてみる

$ cd sample_project
$ doxygen //doxygne実行
$ cd doxygen/latex //LaTeX生成ディレクトリに移動
$ make //コンパイル
$ make pdf //内部ではpdvipsとps2pdf

デフォルトでは「refman.pdf」ファイルが生成される。あとは、PDFビューワで確認する。

これで終了。お疲れ様でした。

トラブルシューティング

ptetexのmakeが通るようになるまで、いくつか引っかかった点があったので、トラブルシューティングとしてまとめておく。

my_optionファイルの設定

We are NOT going to compile xdvi. We have two choices.
1. (with xdvi) Check if we have X11 headers.
2. (without xdvi) Set XDVI=echo in "my_option" to omit xdvi test.

こういったエラーが発生する場合は、my_optionファイルで設定を見なおす

### make test で xdvi を除外する
XDVI=echo
PXDVI=echo

xorg-x11-develの不足(CentOS4のみ?)

あと、こんなエラーも出てきた。

gmake[4]: Entering directory `/var/tmp/ptetex3/tetex-src-3.0/texk/pxdvik'
cd gui; gmake -w CC='gcc' CFLAGS='-g -O2 ' libgui.a
gmake[5]: Entering directory `/var/tmp/ptetex3/tetex-src-3.0/texk/pxdvik/gui'
gcc -DHAVE_CONFIG_H -I. -I. -I../.. -I../.. -W -Wall -Wunused -I.. -I./.. -DPS_GS -DXSERVER_INFO -g -O2 -c help-window.c -o help-window.o
help-window.c:29 から include されたファイル中:
../xdvi.h:131:20: X11/X.h: そのようなファイルやディレクトリはありません
../xdvi.h:153:59: X11/Xlib.h: そのようなファイルやディレクトリはありません
../xdvi.h:154:54: X11/Xutil.h: そのようなファイルやディレクトリはありません
../xdvi.h:155:21: X11/Xos.h: そのようなファイルやディレクトリはありません
../xdvi.h:157:24: X11/Xfuncs.h: そのようなファイルやディレクトリはありません
../xdvi.h:158:27: X11/Intrinsic.h: そのようなファイルやディレクトリはありません
../xdvi.h:179:49: X11/Xmd.h: そのようなファイルやディレクトリはありません
../xdvi.h:393:21: Xm/Xm.h: そのようなファイルやディレクトリはありません
In file included from help-window.c:29:
../xdvi.h:407: error: 文法エラー が "G_charset" の前にあります
../xdvi.h:407: 警告: `G_charset' の宣言で型がデフォルトの `int' とされました
(略)

どうも、x11関係のライブラリが入ってないっぽい。
yumxorg-x11-develをインストールしてみると、このエラーは解決できた。

# yum install xorg-x11-devel
(略)
Dependencies Resolved


=============================================================================
Package Arch Version Repository Size
=============================================================================
Installing:
xorg-x11-devel i386 6.8.2-1.EL.52 base 5.1 M
Installing for dependencies:
fontconfig-devel i386 2.2.3-13.el4 base 233 k
freetype-devel i386 2.1.9-8.el4.6 base 533 k
Updating for dependencies:
freetype i386 2.1.9-8.el4.6 base 764 k
xorg-x11 i386 6.8.2-1.EL.52 base 13 M
xorg-x11-libs i386 6.8.2-1.EL.52 base 2.7 M
xorg-x11-xfs i386 6.8.2-1.EL.52 base 325 k

Transaction Summary
=============================================================================
Install 3 Package(s)
Update 4 Package(s)
Remove 0 Package(s)
Total download size: 23 M
(略)

Xawライブラリの不足(CentOS5のみ?)

CentOS5系でも試していたところ、以下のようなエラーが発生した。

checking for X11/Xmu/Xmu.h... no
checking for T1_AddFont in -lt1... no
configure: warning: Standard T1 library not found. Compiling my own.
checking for Xaw library... not found
configure: error: Sorry, you will need at least the Xaw header/library files to compile xdvik.
configure: error: ./configure failed for pxdvik
configure: error: ./configure failed for texk
make[1]: *** [stage4] エラー 1
make[1]: ディレクトリ `/home/hanzawa/doxygen+latex/ptetex3/ptetex3-20090610' から出ます

Those messages are stored in 'log-0707-1444'.

make: *** [all0] エラー 1

Xawライブラリが不足しているようだ。「yum list」で調べたところ、libXaw-develが該当しているっぽいので、インストールする。

$ yum install libXaw-devel
(略)
Dependencies Resolved

=======================================================================================================
Package Arch Version Repository Size
=======================================================================================================
Installing:
libXaw-devel i386 1.0.2-8.1 base 68 k
Installing for dependencies:
libXmu-devel i386 1.0.2-5 base 21 k
libXpm-devel i386 3.5.5-3 base 31 k
libXt-devel i386 1.0.2-3.1.fc6 base 332 k
xorg-x11-util-macros i386 1.0.2-4.fc6 base 8.1 k

Transaction Summary
=======================================================================================================
Install 5 Package(s)
Update 0 Package(s)
Remove 0 Package(s)

Total download size: 460 k

(略)

libpng-develの不足(CentOS4のみ?)

さらに、こんなエラーも。

dvipdfmx-pdfdoc.o(.text+0x2788): In function `pdf_doc_end_page':
/var/tmp/ptetex3/tetex-src-3.0/texk/dvipdfmx/src/pdfdoc.c:96: undefined reference to `check_for_png'
collect2: ld はステータス 1 で終了しました

このエラーの解決には手こずってしまった。check_for_png は dvipdfmx の pngimage.c 内の関数なのですが、何故かリンクできない。
png関連のライブラリが怪しいと思い、yumpng関連のライブラリを調べてみると、「libpng」はインストールされているが、「libpng-devel」がインストールされていない事が判明。これだ。

# yum install libpng-devel

再度makeを実行したところ、ようやくコンパイル完了。いやー、しんどいしんどい。