プログラムのドキュンメントを作るには長年Doxygenを使っています。Doxygenはソースコード修正とドキュメント修正を同時に行える上、生成したクリッカブル・リンクによりドキュメントの中をブラウズできるため大変便利です。一方、出力されるHTML文書は検索性に劣るため、学習中の文書をキーワードを手がかりに縦横無尽に読み漁ると言ったことができません。そこで、ここ数ヶ月ほどはDoxygenの文書をPDFとして出力する方法を試してみました。
結論としてはLaTeXを通して変換するのが一番よい方法のようです。
DoxygenのLaTeX対応
Doxygenには以前からLaTeX対応機能があります。この機能には実はPDFを生成するための機能もあり、これを使ってPDFを作る方法が一番きれいな文書を得ることができます。
最新のLaTeXのインストールにはTexliveパッケージを使うのが主流のようです。TexliveにはWindows, MacOS, Linux用のパッケージが用意されており、インストーラーからインストールできるので大変便利です。
ところでUbuntuにはtexliveパッケージがあるため、DoxygenからPDFを作るのに必要なパッケージのインストールは大変簡単です。
sudo apt-get install texlive-latex-base texlive-fonts-recommended texlive-fonts-extra texlive-latex-extra
LaTeXに関するDoxygenの設定は簡単です。図1にEcloxによるDoxygenの設定のページを示します。ポイントは
- Generate LaTeXをYesに
- LaTeX Command Nameをpdflatexに
- Use pdflatexをYESに
することです。
PDFへの変換
LaTeXへの出力は別に難しくありません。設定でLaTeX出力をYesにしてしまえば、あとはこれまでどおりDoxygenを走らせるだけです。
実行が完了するとlatexサブディレクトリが作られますので、シェルでその中に移動し、makeコマンドを実行します。
cd latex make
これでrefman.pdfという名前の文書が生成されます。残念ながらファイル名を好みのものに設定する方法はまだ知りません。ないかもしれません。
章順序の指定
Doxygenで作る文書が単なるコードの解説文書であるなら以上で終わりです。しかしながら、ついでに適当な解説文書もDoxygenで作りたい場合もあります。というのは、Doxygenで作った解説は関数名やクラス名が自動的にコードから生成されたリファレンスにリンクされるため、ユーザーにとって便利な文書になるからです。
そういった文書の場合、章の順序を設定したいことがあります。例えば次のようにです。
- はじめに
- 簡単な利用例
- 応用例
応用例が最初に来るような文書は、良い文書とは言えません。
このような場合、ファイル名をアルファベット順につけておくことで章の順序を矯正できます。例えば
- 01_preface.h
- 02_simple_example.h
- 02_advanced_example.h
としておき、それぞれにDoxygenの@pageコマンドを打ったドキュメントを収めておけば、ファイルのソート順にPDFの章付けがおこなわれます。
おわりに
Doxygenで作った文書をLaTeX経由でPDFに変換すると、非常に綺麗な体裁になり、ドキュメントを作るやる気が出ます。みなさんもお試しください。
