[Seasar-kvasir 20] Re: ドキュメント作成手順について

[Tsunenaga Hanyuda]

羽生田です。

まず余談ですがJavaOne、明日午後から行きます(遅)。

YOKOTA Takehiko wrote:

>>生成ツールを使ったりすると思うのですが、何か想定しているもの・お勧めのも
>>のがあればここで挙げていきたいと思います。
> 
> そうですね、ベタでHTMLで書くよりは、なんらかの形式で書いておいて、HTMLや
> 他の形式にもコンバートできると便利かもしれませんね。

はい。基本的にはそのイメージで考えています。

> 
>>ひとまず私はAnakiaかdocbookしか思いつかないのですが...Anakiaは使い慣れて
>>はいますが、クロスリファレンスやマニュアルとしてパッケージングするには
>>docbookの方が便利ですね(切り口がアナログですけど)。
> 
> 
> Anakiaは使ったことありません…。
> docbookって知りません…。

Anakiaですが、Antタスクなので比較的すぐ使えます。
ただしドキュメントの構造が複雑になるとテンプレートに改良が必要になってく
ることと、処理用のVelocimacro(VelocityのVTL)の記述が大変になるので注意が
必要です。Velocityのサイトによれば他のXSL変換技術に比べ「超」高速な出力
を得られます。

docbookは主にLinuxのドキュメントなどで使われているマニュアルやHOWTOの記
述用の仕組みで、独自のDTDで定められたXMLをHTMLやPostscript、PDF、manペー
ジに変換します。ドキュメント記述用なのでタグ付けも比較的わかりやすいです。

↓例としてはこんな感じです。
Linux From Scratch [訳]
http://www.linux.or.jp/JF/JFdocs/LFS-BOOK/

短所はWindowsでは環境が揃わないと(Cygwinとか...)使えないこと(Linux環境な
らすぐ使えます)、タグが膨大なので覚えることが相当数あること、でしょう
か。その分、ソースコード記述用のタグなど定義しなくても揃っています。

> というわけで、簡単に「元文書ファイルをHTMLにしてサイト上に公開するまでの
> 手順」を教えてください。手順は簡単な方がいいですよね。
> 
> ちなみに自分が思いつくのは
> ・Wiki形式
> ・APT（Maven2のサイトでの形式。
>   http://maven.apache.org/guides/mini/guide-apt-format.html）
> くらいですかね。どれがいいかは別として。
> 

Wikiは seasar.orgサイト上でWikiが使えるのであればそれに越したことは無い
という気がしますが、大量になったとき＆混沌としてきたときにまとめるのが大
変なのかなぁ、と。議論＆FAQ作成については最適だと思います。

APTは使ったことがないのですが結構よさそうですね。パッと見ですが、画像は
どうするのだろう...
＃名前を見たときDebianのaptかと思いましたが

(以下相当な偏見ベースで)
ブレーンストーミング的に進めていく(中途半端でも公開)ならWiki
とにかく書くスピードを速めるならAPT
タグ付けのわかりやすさとドキュメントの多角化を念頭に置くならdocbook
今あるサイトの見た目に出来るだけ近づけるならAnakia

という感じです。

で肝心の「元文書ファイルをHTMLにしてサイト上に公開するまでの手順」です
が、Wikiを除いて基本的にはどのツールを使っても同じで

 元文書作成→ツールにかける→出来たものをコミット

のようになるわけで、結局のところインプットするファイルの違いから始まって
環境の準備やら完成後の見た目やら書きやすさ・カスタマイズのしやすさといっ
た結構細かい点で差異が出るという感じです。私としてはどれでも構いません
(上記の中ではAnakiaを使うことが多いです)。

長くなってすいません…
この際ひととおり使ってみますか(^^

--
羽生田 恒永
hanizo ＠ pm.highway.ne.jp