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

YOKOTA Takehiko skirnir
2005年 11月 10日 (木) 00:43:10 JST


横田です。

Tsunenaga Hanyuda wrote:
> 羽生田です。
> 
> まず余談ですがJavaOne、明日午後から行きます(遅)。

待ってまーす。^^)

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

Velocimacroを知らないとカスタマイズしづらいのですね。でもその辺は羽生田さ
んにお任せすればよいのか(笑)。

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

あ、みたことあります、こういう感じのサイト。

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

Windowsで環境を作りづらいのはつらいっすね。

で、野望としては、ドキュメントもMaven2でビルドできないかなーと思っていま
す。より正確には、ドキュメントのビルド(コンバート)も自動化したい、と。
Kvasir/Soraプロジェクトでは極力手動のプロセスを減らしたいのです。

#そういう意味ではMaven2のsiteプラグインを使うのも一つの手?でもまだ日本語
#まわりはいまいちっぽいし…。

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

すいません、説明不足でしたが、Wikiシステムそのものを使うという意味ではなく
て、Wikiの記法を使って記述してそれをコンバータでHTML化する、という意味合い
です。

#ちなみにKvasir/Soraの3.0.0-EA1はWiki記法をサポートしていて、メディアタイプ
#にtext/x-wikiを指定すればWiki記法で書いたページが表示可能です。なのでWiki
#→HTMLコンバータはさらっと作れる状態です。

> APTは使ったことがないのですが結構よさそうですね。パッと見ですが、画像は
> どうするのだろう...

それは私も気になっていました。画像埋め込みができないとつらいっすね…。

> #名前を見たときDebianのaptかと思いましたが

はい、私もそう思いました。^^;

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

それも良いですし、とりあえず私はplain text+α的な雰囲気でドキュメントを
書きますので、それと並行してドキュメント作成方式を検討する、というのでも
いいかもしれません。まずQuick Start的なドキュメントは早めに出したいので、
それはもう手動でHTML化してサイトに貼ってもいいかも。

で、検討するなら選択肢の一つとしてMaven2のsiteプラグインも調べたいっす。^^)

-- 
YOKOTA Takehiko
  skirnir @ t3.rim.or.jp


kvasir-user メーリングリストの案内