Perlモジュール出力

バージョン1.2.18以降、Doxygenでは、"Perlモジュール出力"という新たな出力フォーマットを生成できます。この機能は、新しくてカスタマイズされた出力を生成するために使用するため、Doxygenソースを編集する必要がないよう、中間的フォーマットとして、設計されています。従って、目的はXML出力に似ています。これもDoxygenで生成できます。XML出力フォーマットはより標準的ですが、Perlモジュール出力のほうがより単純で使いやすいです。

Perlモジュール出力は、現状まだ試験的で、将来のバージョンでは互換性が低くなる可能性もありますが、これは起きてはよくないです。更に、ほかのDoxygen バックエンドの機能が欠けています。それでも、Perlモジュールベースの、LaTeX生成器に見られるように、有効な出力を生成することができています。

Perlモジュール出力バックエンドや、Perlモジュールベースの、LaTeX生成器にバグや問題を見つけたら、doxygen-developメーリングリストに報告してください。提案も歓迎です。

Usage

GENERATE_PERLMODタグがDoxyfile内で有効ならば、Doxygenは、出力ディレクトリのperlmod/サブディレクトリ内に、いくつかのファイルを生成します。以下に、それらのファイルを示します。

DoxyDocs.pm このファイルがPerlモジュールで、ドキュメントを実際に保有します。belowに記述されているPerlモジュール形式
DoxyModel.pm このPerlモジュールは、DoxyDocs.pmの構造を記述していますが、実際のドキュメントとは独立しています。詳細は、below参照
doxyrules.make このファイルには、Doxyfileから生成されるファイルをビルドしてクリーンするためのmakeルールを記述しています。さらに、これらファイルのパスや付随する情報を記述しています。このファイルは、ユーザ自身のMakefileにインクルードしていただくことが必要です。
Makefile このファイルは、doxyrules.makeをインクルードしている単純なファイルです。

DoxyDocs.pmに収めてあるドキュメントを有効に使うには、Perlモジュールベースの生成器(現状、PerlモジュールベースのLaTeX生成器を含みます)の一つを使うことです。あるいは、ユーザ自身でカスタマイズした生成器を書くこともできます。この作業は、Perlについて知識があれば、それほど難しくありません。これが、PerlモジュールバックエンドをDoxygenに入れている主目的です。その手順については、belowを参照

LaTeX 生成器の使い方

PerlモジュールベースのLaTeX生成器は、現状試験的で、不完全です。それでも有効に使えるはずです。ファイルとクラス内の関数、typedef、変数に関するドキュメントを生成できます。TeXマクロを再定義することで、カスタマイズすることもできます。ですが、その手順に関するドキュメントはまだありません。

PERLMOD_LATEXタグをYESにすると、出力ディレクトリのperlmod/サブディレクトリに、更にファイルを生成することができます。これらのファイルには、PerlスクリプトやLaTeXコードがあり、PDFLaTeX と LaTeXを使って、Perlモジュール出力からPDF,DVI出力を生成します。これらファイルの使用を自動化するルールも、doxyrules.make と the Makefileに追加されています。

生成されるファイルには、他に以下があります。

doxylatex.pl このPerlスクリプトは、DoxyDocs.pmとDoxyModel.pmを使って、<b>doxydocs.texを生成します。 doxydocs.texはTeXファイルで、LaTeXコードでアクセスできる形式で書かれたドキュメントでできています。このファイルは、直接LaTeXではありません。
doxyformat.tex このファイルには、doxydocs.texから、LaTeXにするのに適したLaTeXテキストへ、ドキュメントを変換するコードが書かれています。
doxylatex-template.pl このPerlスクリプトは、DoxyModel.pmを使って、<b>doxytemplate.texを生成します。このTeXファイルは、あるマクロのデフォルト値を定義しています。doxyformat.texに含まれ、それらマクロを明示的に定義する必要を省いています。
doxylatex.tex このファイルは、非常に単純なLaTeXドキュメントで、パッケージをロードして、 doxyformat.tex と doxydocs.texファイルをインクルードしています。このドキュメントは、LaTeX化されて、PDFとDVIドキュメントを作成します。そのルールは、<b>doxyrules.makeに追加されています。

PDF と DVI 出力の作成

この機能を試すには、LaTeX, PDFLaTeXと、doxylatex.texが使うパッケージを、インストールしておく必要があります。

以下のコマンドを使って、Doxyfileを最新バージョンにしてください。
```
doxygen -u Doxyfile
```
Doxyfile内で、GENERATE_PERLMOD と PERLMOD_LATEX両方をYESにしてください。
以下のコマンドを使って、そのDoxyfileでDoxygenを動かしてください
```
doxygen Doxyfile
```
perlmod/サブディレクトリが、出力ディレクトリにできているはずです。そこへ移動して、以下のコマンドを実行してください。
```
make pdf
```
doxylatex.pdfが、PDF形式で生成されます。
以下のコマンドを実行してください。
```
make dvi
```
doxylatex.dviが、DVI形式で生成されます。

ドキュメントフォーマット

DoxyDocs.pmには、Doxygenが生成したPerlモジュールドキュメントが格納されます。このモジュールは、非常に単純なモジュールで、２つのステートメントだけしかありません。$doxydocs変数への割り当てと、Perlモジュールを狩猟させる1;ステートメントとです。ドキュメントは、$doxydocs変数内に格納され、DoxyDocs.pmを使って、Perlスクリプトにてアクセスできます。

$doxydocsには、3種類のノードで構成される、木のような構造体が含まれます。そのノードとは、文字列、ハッシュ、リストです。

文字列 Perl文字列には、通常長さや文字に制限がありません。意味論は、木の中の位置に依存します。この型のノードには子がありません。
ハッシュ 匿名Perlハッシュに対する参照です。ハッシュには複数のフィールドがありえます。そして、それぞれ違ったキーがありえます。ハッシュフィールドの値は、文字列、ハッシュ、またはリストです。意味論は、ハッシュフィールドのキーと、木の中のハッシュ位置に依存します。ハッシュフィールドの値は、ノードの子です。
リスト 匿名Perlリストに対する参照です。リストには、未定義数の要素があり、それらは、ノードの子です。各要素は、同じタイプ(文字列、ハッシュ、リストのいずれか)であり、同じ意味論です。これは、木の中の位置によって決まります。

$doxydocs内に含まれるドキュメントは、単純なPerlスクリプトによって処理される際、特別な障害にはなりません。

データ構造

ドキュメントツリーの各ノードについての意味論を考慮に入れずに、DoxyDocs.pmに含まれるドキュメントを処理したいこともあるかもしれません。この目的のため、Doxygenは、DoxyModel.pmを生成します。このファイルのデータ構造は、ドキュメントツリーの各ノードの型と子を説明しています。

このセクションは最後まで記述されていません。現状、Doxygenが生成するPerlスクリプト(doxylatex.pl や doxytemplate-latex.pl)をごらんになって、DoxyModel.pmの使い方を知る参考にしてください。

次のセクションに行く / インデックスに戻る