PHPでDoxygenを前処理？
高木です。おはようございます。
以前から何度か書いているように、私はドキュメントを書くのにDoxygenをよく使います。
ソースコードのコメントとして埋め込むのはもちろん、ソースコードとは何の関係もない文書（たとえば弊社の就業規則とか）であってもDoxygenを使うのです。
Doxygenを使うのが最良の選択かと問われれば何ともいえませんが、少なくとも私はDoxygenに慣れていますし、Doxygenが好きだからそうしているにすぎません。
先日、「PlantUMLで数式を書いてみる。」という投稿で、DoxygenからPlantUMLを呼び出すことで数式を記述する話をしました。
私は数式を記述することも多いので、PlantUMLで数式を記述できるようになったのはありがたいことです。
これでシーケンス図などUMLで記述したドキュメントに数式を埋め込むのが簡単になりました。
ただ、一点問題もあるのです。
一点ですが、非常に大きな一点です。
PlantUMLで数式を単独で記述する場合、AsciiMath形式であれば@startmathから@endmathまでのブロック内に記述することになります。
同様に、LaTeX形式であれば@startlatexから@endlatexまでのブロック内に記述します。
しかし、Doxygenではそれら、すなわち@startmathなどを特殊コマンドとして認識してくれないのです。
また、これは以前からわかっていたことですが、文中の同じ行に数式を埋め込むこともできません。
もともとDoxygenに搭載されていた数式の記法ならできるんですけどね。
こういうことがあると、何とかして実現したくなるのが人情というものです。
そのときに真っ先に思い浮かぶのは、PCPなどでも使っているPHPです。
PHPはもともとが前処理用の言語なので、こういうときに使うにはもってこいですね。
もっとも、数式だけのことであれば、PlantUMLではなくDoxygen本来の数式記法を使えばいいじゃないかといわれそうです。
しかし、ほかにも前処理が必要になる理由があるのです。
DoxygenはHTMLまたはLaTeXのドキュメントを生成するのがデフォルトで、それらの形式に対するサポートが一番充実しています。
Windowsの環境ではLaTeXは扱いにくいこともあって私は使いませんので、そうなるとHTMLがメインということになります。
ほかにはRTF形式の出力もできます。
RTFだと結構きれいなドキュメントが生成できますが、ソースコードをドキュメント化するのではなく、通常のドキュメントの場合であれば、巻末の索引など余計なものも出力されてしまいます。
それ以外にもところどころ手作業で修正さざるを得ない箇所もあり、あまりうれしくありません。
そこで最近は、いったんHTMLで出力し、それをWordで読み込んでPDF化する方法を取り始めています。
これであれば、RTF形式ではサポートされない特殊コマンドも使えますし、いろいろ便利です。
しかし問題もあります。
@pageコマンドで複数ページからなるドキュメントを作った場合でも、RTF形式ならうまくひとつのファイルに連結されますが、HTMLでは別々のファイルになってしまいます。
最終的にひとつのPDFにするには、1ページにまとめないといけません。
あとからPDFを連結する方法もありますが、できれば避けたいものです。
そこで登場するのが前処理です。
PHPで前処理すれば、includeやrequireで別のファイルを取り込むことができます。
Doxygen本来の機能では、別のファイルを取り込むのは、ソースコードなど特殊なケースに限られていました。
さらに、PHPで前処理するのであれば、HTMLの場合でも目次を自動生成することができます。
ほかにも考えればいろいろなことができそうです。
従来はPHPのソースコードをDoxygenにかけてドキュメントを生成するのが普通の使い方でしたが、今回やろうとしていることはおおむねその逆です。
なんか、頭がこんがらがりそうですね。