Strutsのタグリブドキュメント作成ツール
Strutsのソースを探索してみると,タグリブドキュンメント作成のためのプログラムやXSLファイルがあるようなので,試しに使ってみた.
Struts-1.1のソースには,タグリブドキュメント作成用らしきコードがある.これを使用するとTLDを拡張したようなXMLドキュメントを記述し,antタスクを実行することでJavadocのような雰囲気のタグリブドキュメントを生成し,さらにTLDも生成するといったことができる.カスタムタグのユーザが知りたい情報の最も基本的なものはTLDに記述されているので,それを拡張,修飾することでデータソースとするのはよい考えではないだろうか.ということで,本頁ではその環境構築方法とデータソースとなるXMLドキュメント作成方法などについて調査した結果を記述してみる.最後に簡単に試せるantビルドファイルを置いておくので,具体的にどういったものができるのかはそちらで試されたい.
今回必要なモノはStruts-1.1のソース(jakarta-struts-1.1-src.zip)から取り出した.まずダウンロードして展開し,以下に移動する.
jakarta-struts-1.1-src/contrib/tag-doc/ここにbuild.xmlがあるので,実行する.
ant distこれで出来上がる以下のjarファイルにクラスパスを通す.
jakarta-struts-1.1-src/contrib/tag-doc/dist/taglib-docs.jar
今回の作業の目標は,一つのファイルからカスタムタグユーザのドキュメントとTLDファイルを生成することである.そのデータソースとなるファイルの例は以下である.
jakarta-struts-1.1-src/doc/userGuide/struts-*.xmlこれらのファイルは本頁の目標にとっては例だが,実際にはStrutsのタグリブのドキュメントやTLDなどを生成するもとになっているファイルである.これらのファイルは基本的にTLDファイルをベースにした構造になっているようなので,TLDファイルの書き方を知っていれば,あとはどこに説明記述を追加するかを知るだけでよい.DTDが見あたらないので,セマンティクスを以下に記述する.
<?xml version="1.0"?>
<document url="おそらく生成されるtaglibドキュメントのHTMLファイル名.">
<properties>
<author>筆者</author>
<title>タイトル</title>
</properties>
<body>
<taglib>
<tlibversion>TLDファイルのバージョン</tlibversion>
<jspversion>JSPのバージョン</jspversion>
<shortname>このタグリブの省略名</shortname>
<display-name>表示名.ツール用.</display-name>
<uri>タグリブのURI</uri>
<info>
タグリブの詳細な説明.HTMLタグを使用することが可能.
ただしこのファイルはXMLファイルなので,タグを開いたら必ず閉じること.
</info>
<tag>
<name>カスタムタグ名</name>
<summary>
このカスタムタグのサマリ.カスタムタグ一覧頁に表示される.
</summary>
<tagclass>タグハンドラクラス</tagclass>
<teiclass>TEIクラス.</teiclass>
<bodycontent>bodycontent</bodycontent>
<info>
このカスタムタグの詳細な説明.
</info>
<attribute>
<name>属性名</name>
<required>必須か否か</required>
<rtexprvalue>属性値展開</rtexprvalue>
<info>
属性の説明.
</info>
</attribute>
</tag>
</taglib>
</body>
</document>
先述の
jakarta-struts-1.1-src/contrib/tag-doc/build.xmlにtaglibdocとtaglibreportに関するターゲットがある.以下はそれを若干修正したものである.
<target name="taglibdoc" >
<taskdef name="taglibdoc"
classname="org.apache.struts.taskdefs.TaglibDoc">
<classpath path="${taglibdocs.jar}"/>
</taskdef>
<taglibdoc destdir="${taglibdoc.dir}">
<fileset dir="${taglib.xml.dir}">
<include name="*.xml"/>
</fileset>
</taglibdoc>
</target>
<!-- taglibreport作成 -->
<target name="taglibreport" >
<taskdef name="taglibreport"
classname="org.apache.struts.taskdefs.TaglibReport">
<classpath path="${taglibdocs.jar}"/>
</taskdef>
<taglibreport destdir="${taglibreport.dir}">
<fileset dir="${taglib.xml.dir}">
<include name="*.xml"/>
</fileset>
</taglibreport>
</target>
これらのターゲットを実行することでtaglibdocやtaglibreportが作成される.
TLDの生成方法はStrutsの以下のビルドファイルのターゲットcompile.libraryに書いてある.
jakarta-struts-1.1-src/build.xml具体的にはantのstyleというタスクを使用する.以下はその抜粋.
<style basedir="${doc.dir}/userGuide"
destdir="${build.home}/library"
extension=".tld"
style="${doc.dir}/stylesheets/tld.xsl"
includes="struts-*.xml"/>
ということで,tldの生成には以下のxslファイルが必要である.
jakarta-struts-1.1-src/doc/stylesheets/tld.xsl
Strutsのタグリブドキュメント作成ツールを試したり,自分のビルド環境に組み込んでいくためのビルドファイルを作成したので,アップしてみる.これ.以下使用方法.
- Strutsソースのダウンロード.
- 以下を実行する.
ant taglibdocs.download
プロキシを使用している場合は動作しないので,その場合は手作業でディレクトリdownloadにjakarta-struts-1.1-src.zipを置く. - 必要なファイルの抽出.
- 以下を実行する.
ant taglibdocs.prepare
これで以下がStrutsのソースから作成,コピーされる.- lib/taglib-docs.jar
- doc/stylesheets/tld.xsl
- テスト.
- StrutsのタグリブのTLDファイルやドキュメントを作成する.以下を実行する.
ant taglibdocs.test
これで以下が作成されるので確認する.- src/main/WEB-INF/struts-*.tld
- doc/taglibdoc/index.html
- doc/taglibreport/index.html
- データソースのXMLファイル
- 以下に置く.
src/main/taglibxml/
taglibdocs.testを実行した場合はStrutsのタグリブ用のファイルがあるので,いらないのであれば消す. - tldファイル出力先
- 上に置いたXMLファイルからTLDを生成するには以下を実行する.
ant tld
これで以下にTLDファイルが出力される.src/main/WEB-INF/
taglibdocs.testを実行した場合はやはりStrutsのタグリブ用のファイルがあるので,いらないのであれば消す. - ドキュメント出力先
- 以下でタグリブ用ドキュメントが作成される.
ant taglibdoc ant taglibreport
前者でdoc/taglibdoc/に,後者でdoc/taglibreport/にドキュメントが生成される.
