Jakarta Velocity を使った XML からドキュメントを生成するツールです。 多くの場合、XML から HTML を生成する用途に使われているようです。
ちなみに、このページとか、Jakarta のサイトも Anakia により生成されています。
Velocity とはテンプレートエンジンで、MVC(Model View Control) の分離を簡単に実現できます。
たとえば、HTML であれば Model は書かれている内容、 View は見栄え、Control は強引ですがリンクであると言えます。 Velocity はこれらを別々のファイルで扱い、表示の際に これらを元とした表示用のモノを作成します。
Anakia であれば、Model はコンテンツの書かれた XML ファイル、 View はコンテンツの配置方法を書いた site.vsl、ナビゲーションは サイト全体に適用される project.xml というファイルに定義されます。 これらが分離されることで、例えば、レイアウトを変更したい場合は site.vsl、サイト全体に対して変更したい部分があれば project.xml など、変更作業に伴う労力が少なくなります。
また、Java プログラマなら Velocity を使って Web アプリケーションを
作ったり、ドキュメントを書いたりしている人が増えてきました。
ドキュメントの場合は多くの場合、src/xdocs
というディレクトリにおかれ、Anakia で変換されることを前提としています。
メリットは MVC の分離や HTML 以外への変換などありますが、 逆にデメリットは次の通りです。Velocity は簡単な言語 VTL を使いますが、 この VTL は簡単過ぎて、細かい制御を行うことができません。 やろうと思うと Velocity 以外の部分で解決しないといけません。
また、一番最初、site.vsl を書くのがかなりメンドウです。 出力のフォーマットを複数サポートするのは、かなり難しいです。 私は開きなおって出力は HTML。PDF への出力は Mac OS X で行うと決めています。
とは言っても、やっぱり便利。GoLive などにお金を出すのはイヤな 人や Java プログラマやテキストエディタでページを書いている人などは 使った方が良いでしょう。使ってみると便利だよ。
Jakarta のサイトを見るのが良いでしょう。
$ cvs -d :pserver:anoncvs@cvs.apache.org:/home/cvspublic login $ cvs -z3 -d :pserver:anoncvs@cvs.apache.org:/home/cvspublic co jakarta-site2
パスワードは anoncvs です。
以上のコマンドを実行すると、カレントディレクトリに
jakarta-site2 というディレクトリが作成されます。
このディレクトリに入っている xml ファイルが jakarta
のサイトの元となるファイルです。
Anakia は Ant により起動されます。 そのため、Ant をインストールしないと Anakia は使えません。
しかし、この Ant は Java 版 make という位置付けで Java の開発には不可欠です。まだインストールしていない Java 開発者は早速インストールしましょう。
http://www.apache.org/dist/ant/binaries/ から Ant のバイナリをダウンロードします。 特に理由がなければ最新の 1.5.1 を使った方が良いでしょう。
$ gzip -cd jakarta-ant-1.5.1-bin.tar.gz | tar xvf -
でできたディレクトリのパスを環境変数 ANT_HOME に設定します。 また、J2SDK SE をインストールしているパスを環境変数 JAVA_HOME に設定します。
別の方法としてはホームディレクトリに .antrc を作成し、
以下の内容を書きましょう。
ANT_HOME=/usr/local/java/ant JAVA_HOME=/usr/local/java/j2sdkse
以上で Ant のインストールは終了です。 Ant を使い倒すには Ant 詳説 が便利でしょう。
次に Velocity をインストールしなければなりません。
配布サイト
から最新の Velocity をダウンロード、展開します。
(ここでは velocity-1.3 を使っています)
そして、展開されてできたディレクトリにある velocity-1.3.jar と
velocity-dep-1.3.jar、build/lib
以下にある jar ファイルを全て $ANT_HOME/lib
にコピーします。
しかし、Velocity に付いてきている log4j のバージョンが低いので、 log4j は最新のものに置き換えても大丈夫です。
Anakia は Velocity 1.3 に付いてきているので、 特に作業する必要はありません。
まずは初期設定をします。
このディレクトリ構成で以下の build.xml の書き方が変わります。
私の構成は以下のものです。
root +-- xdocs -------+-- stylesheet ----+ project.xml
| +-- index.xml
| +-- style.css
| :
+-- build.xml
+-- velocity.properties
+-- public_html
xdocs 以下に元となる xml ファイルを置き、public_html 以下に HTML ファイルが xdocs と同じディレクトリ構成で 生成されます。
入出力の文字コード、content-type を設定する必要があります。 私の設定は以下の通りです。
input.encoding=euc-jp output.encoding=euc-jp default.contentType=text/html; charset=euc-jp
これは特に変更する必要はないと思います。
build.xml には以下の内容を最低限書きます。と思ったのですが、 説明がメンドウなので、私の build.xml を載せます。
<?xml version="1.0" encoding="euc-jp" ?>
<!--
$Id: anakia.xml,v 1.6 2003/03/03 02:37:46 tamada Exp $
-->
<project name="tama-page" default="docs" basedir=".">
<property file="build.properties" />
<property name="project" value="tamada-site" />
<property name="src.xdocs" value="./xdocs" />
<property name="build.docs" value="public_html" />
<target name="available.check" unless="check.already">
<available classname="org.apache.velocity.anakia.AnakiaTask"
property="available.anakia">
<classpath path="${java.class.path}" />
</available>
<property name="check.already" value="true" />
</target>
<target name="docs" depends="available.check" if="available.anakia"
description="anakia を使い，ドキュメントを生成する">
<mkdir dir="${build.docs}" />
<taskdef name="anakia"
classname="org.apache.velocity.anakia.AnakiaTask">
<classpath path="${java.class.path}" />
</taskdef>
<anakia basedir="${src.xdocs}"
destdir="${build.docs}"
projectfile="stylesheets/project.xml"
style="${src.xdocs}/site.vsl"
extension=".html"
templatePath="${src.xdocs}/stylesheets">
<include name="**/*.xml" />
<exclude name="**/stylesheets/**" />
</anakia>
<copy todir="${build.docs}">
<fileset dir="${src.xdocs}">
<include name="**/*" />
<exclude name="**/*.xml" />
<exclude name="**/stylesheets/**" />
</fileset>
</copy>
</target>
<target name="clean">
<delete dir="public_html" />
<delete file="velocity.log" />
</target>
</project>
まず、最初に site.vsl を書く必要があります。
しかし、この site.vsl の書き方は Velocity の文法と
XPath の文法を知っていないと書けません。
なので、最初はどこからか取ってきて、それを元に変更していくのが 良いでしょう。私の site.vsl を使ってもらっても構いませんし、Jakarta site の site.vsl を使ってもらっても構いません。
ここでは私の site.vsl で話を進めます。
ナビゲーションに相当するファイルです。 生成されるコンテンツ全体からアクセスできるプロパティなどを 書きます。
多くの場合、著作権表示の文やトップのメニューの定義が来るでしょう。 ちなみに、私の project.xml は以下のようなものです。
<?xml version="1.0" encoding="euc-jp"?>
<project name="tama's web page">
<title>tama's web page</title>
<properties>
<backLevel>2</backLevel>
<property code="ja" label="Japanese">
<backLabel>ページのトップへ</backLabel>
<copyright>
Copyright (C) 1997-2003 by Haruaki TAMADA
All rights reserved.
</copyright>
<lastModified>Last Modified: </lastModified>
</property>
<property code="en" label="English">
<backLabel>Go to top of page</backLabel>
<copyright>
Copyright (C) 1997-2003 by Haruaki TAMADA
All rights reserved.
</copyright>
<lastModified>Last Modified: </lastModified>
</property>
</properties>
<menus lang="ja">
<menu title="コンテンツ">
<item name="トップ" href="/index.html" />
<item name="開発" href="/Products/index.html" />
<item name="日記" href="/Diary/index.html" />
<item name="掲示版" href="/cgi-bin/wwwboard.cgi" />
<item name="リンク" href="/cgi-bin/link.cgi" />
<item name="写真" href="/Picture/index.html" />
</menu>
</menus>
<menus lang="en">
<menu title="Contents">
<item name="Top" href="/index.html" />
<item name="Development" href="/Products/index.html" />
<item name="Diary" href="/Diary/index.html" />
<item name="BBS" href="/cgi-bin/wwwboard.cgi" />
<item name="Link" href="/cgi-bin/link.cgi" />
<item name="Picture" href="/Picture/index.html" />
</menu>
</menus>
</project>
英語のページに日本語が出ないように言語の選択を可能にしています。
メニューが <menus> 以下に複数並べられます。
<menu> 以下にメニューの項目、そして、
<menu> の属性 title にタイトルを
書きます。これらのメニューは私の site.vsl であれば
左に表示されるようにしています。
<properties> で定義しているものは
site.vsl からベタ書きのテキストを排除するためのものです。
<backLabel> と <backLevel>
については「ページのトップ」を御覧下さい。
コンテンツを書きます。 コンテンツファイルには大きく 設定、メニュー、コンテンツという 3 つの項目にわかれます。
コンテンツファイルのトップ要素は <document> ですが、
言語を指定する必要があります。
<document lang="ja"> の用に指定します。
製作者の名前、メールアドレス、また、ページのタイトルや キーワード、スタイルシートの設定などを行ないます。
<properties>
<author email="tamada@oikaze.com">Haruaki TAMADA</author>
<email>tamada@oikaze.com</email>
<title>Anakia の使い方</title>
<description>anakia のインストールから使い方まで</description>
<keywords>Java, Velocity, Anakia</keywords>
<style media="screen">/style.css</style>
<style media="print">/style_print.css</style>
</properties>
このページであれば上記のプロパティが設定されています。
もし、複数の言語のページがあった場合、自動的に切替えるリンクが欲しいものです。
その場合は以下のように <lang> タグを付け加えます。
<properties>
<author email="tamada@oikaze.com">Haruaki TAMADA</author>
<title>Simple Watermark Tool</title>
<description>Simple Watermark Tool</description>
<keywords>Java, Watermark, library</keywords>
<style media="screen">/style.css</style>
<style media="print">/style_print.css</style>
<lang>
<link code="ja">index.html</link>
<link code="en">index-e.html</link>
</lang>
</properties>
この例の用に <lang> タグを付け加えると
[ Japanese | English ] のようなリンクがページの上部に現れるようになります。
そして、現在のページの言語以外にリンクが張られます。
<lang> タグがない場合は上記のリンクは張られません。
ナビゲーションなどは project.xml の言語設定により
変わります。ページの言語についてはコンテンツファイルのルートタグ
<document> で lang 属性を加えて指定します。
各ページにおいても、そのページ独自のメニューが欲しい場合があると思います。 そのような場合、この部分を書きます。この部分を書かなければ メニューは project.xml で書かれたメニューのみが表示されるようになります。
<submenus> <menu title="タイトル"> メニューだ。 </menu> </submenus>
基本的に上記のように書きます。
<menu> は複数書くことができ、
中身は単なる HTML テキストです。上記の例の場合は
『メニューだ。』が単純に表示されます。
実際の中身です。<body> タグで表されます。
そして、<section> で内容を囲んでいきます。
<body>
<chapter label="ラベル" name="name" href="href">
<section label="子ラベル" name="subname" href="subhref">
<subsection label="subsection" name="nil" href="nil">
<paragraph label="subsection" name="nil" href="nil">
<subparagraph label="subsection" name="nil" href="nil">
<p>実際の中身</p>
</subparagraph>
</paragraph>
</subsection>
</section>
</chapter>
</body>
処理的には <chapter> <subparagraph>
まで chapter, section, subsection, paragraph, subparagraph の順に
label 属性の値を
<h2>、<h3> で囲みます。
もし、<chapter> などの name もしくは href に
値が指定されていた場合は HTML のアンカータグ(<a>) を加えます。
しかし、velocity では一度セットした値は削除されません。
そのため、<chapter> などの name や href
を書いた後の <section> で name や href を
書かないと一番最後に定義された値になってしまいます。
(説明がわかりにくいなぁ)
以下のような例の場合で説明します。
<body>
<chapter label="chapter だ" href="totoc" name="chapter">
<section label="section だ">
<p>本文・・・</p>
</section>
</chapter>
</body>
上の例の場合、<section> は href も name
も指定していないのでアンカータグが付けられることを期待していしていません。
しかし、<chapter> で href, name を指定しており、
<section> では値を指定していないため、
<chapter> で指定された値が <section>
に引き継がれ、あたかも <chapter> で href と name
を指定したように処理されます。
それを防ぐために name="nil" と書くことで
値を無視することができるようにしています。(site.vsl にて)
ページのタイトルには topofpage という
アンカー名が付いており、project.xml の
<properties> 内で <backLabel> と
<backLevel> を定義することにより、指定された場所にて
以下のような HTML が出力されます。(言語設定が ja の場合)
<p class="gototop"> <a href="#topofpage">ページのトップへ</a> </p>
この時、project.xml では以下のように定義されています。
<properties>
<backLevel>2</backLevel>
<property lang="ja" label="Japanese">
<backLabel>ページのトップへ</backLabel>
</property>
<property lang="en" label="English">
<backLabel>Go to top of page</backLabel>
</property>
</properties>
コンテンツファイルの言語設定が en の場合は
<p class="gototop"> <a href="#topofpage">Go to toop of page</a> </p>
のように出力されます。
この時、<backLevel>2</backLevel> の 2
というのは chapter の後ということであり、2 〜 6 の間で指定でき、
それぞれ 2 が chapter、3 が section、4 が subsection、5 が
paragraph、6 が subparagraph が終了した時となります。
もし、<backLabel> が指定されていない場合、
アンカーは張られますが、アンカー文字列がないため、何も表示されないように見えます。
また、<backLevel> がない場合は上記の
HTML コードは一切出力されません。
| コンテンツ |
|---|
| リンク |
| おしながき |