[79] Re: Samba Doc project and SmartDoc

[Hiroshi MIURA <miura@samba.gr.jp>]

三浦です

SmartDocのターゲットと、わたしが当初想定した、オープンソースの
ドキュメント整備との違いを少し感じました。

当初、manに代表されるへルプシステムのドキュメントを、そのソースを
XMLとすることで、man, html, tex, pdfへと展開できることを
希望していました。

しかしながら、helpシステムとして、SmartDocは、javahelp形式を
お考えのようで、たしかに古いman形式を考えると、それも仕方ないかな
とおもえました。

となると、一般のユーザに対するインターフェースとしては、
HTMLが有力かつ、おそらく唯一のように思えます。

In message "[sdocusersj 77] Re: Samba Doc project and SmartDoc"
    on 00/07/24, ASAMI Tomoharu <dp8t-asm@asahi-net.or.jp> writes:
> 　浅海です。

> > それにはまだまだ課題も多い。現在のyodlを置き換えるには、
> > 1. plain text, Mandocの生成が欲しい。
> >    結構厳しいかも。表とかとりあえず要らないから、なんとかならないだろうか。
> 
> 　最新版の0.6.6では-format:plainで、それなりのプレインテキストが生成で
> きるようになっています。評価用途には使っていただけるのではないかと思い
> ます。
> 　MandocはUNIXのroff -manの形式のことでしょうか？

はい。roff -man 形式です。Texinfoのように、manを捨てる割りきりが
あってもいいのでしょうが、あまりに独自なのは受け入れられません。

わたしの認識では、info or manはあったほうが良いようにおもっていました。
もし、だめならHTMLでしょうか。
 
> > 2. 国際的プロジェクトで自国語*だけ*を自在にメンテナンスできる
> >    分散開発環境がほしい。
> >     たとえば、一つのリポジトリを使いつつも、複数言語を扱う仕組みが
> >     重要です。UTF-8をまともに扱えるエディターが少ない現状も考えると、
> >     各国の人がこのみのエディターで自国語のマニュアルを整備しつつ、
> >     結果として複数言語のドキュメントが集積できる仕組みがあると、
> >     俄然、採用の動機がたかまります。  
> 
> 　複雑なリポジトリメカニズムを構築するよりも、SmartDoc with UTF-8が最
> 適解ではないかと思います。
> 　ただ、管理の粒度を章や節単位にするのであれば、色々やり方はありそうで
> す。
> 
> <section locale="en" src="HelloWorld_en.sdoc"/>
> <section locale="ja" src="HelloWorld_ja.sdoc"/>
> 
> とか。

その後、いろいろXMLの勉強をしましたが、この方法が妥当におもえました。
外部ソースを参照するようにすれば、文字コードの問題もわりに解決できそうですね。
xmlの規約では、ファイル単位で文字コードを指定できるようですし。
 
> > 3. ガイジンを納得させるだけのオンライン/オフラインマニュアル(by English)が欲しい。
> >     これも重要でしょう。なにしろ、開発者の99%がガイジンです。:(
> 
> 　ううむ、ここがキツいですね。
> 　ボク個人の力では、きちんとした英語のマニュアルを作成するのはかなり厳
> しい感じです。

これは、オープンソースのつよみで、プロジェクトを結成して
マニュアル作成するのがよいでしょう。
#ただし、このところ、人材不足の感は否めない
 
> > 4. DocBookなどと、相互変換できるような環境が欲しい。
> >     すると説得しやすい.
> 
> 　これはXSLTを使ってPureSmartDocとDocBookの変換をすれば、問題ないでしょ
> う。

なるほど。
 
> > 5. 本家を説得する英語力がほしい。(あ、これは私の課題ね)
> >     これは、SmartDocには責任はない。です。
> > ということで、是非お力添えを。
> 
> 　Sambaで使っていただければ、SmartDocも本望でしょう。:-)
> 　できるだけ対応したいと思いますので、ご希望などありましたらお知らせ下
> さい。

ありがとうございます。まずは、samba-jpのメンバーが使ってみています。
なにかあったら、また投稿します。

-- 
SAMBA User Group Japan, devel. staff    http://www.samba.gr.jp/
Linux Kernel Hack Japan 	http://lkh.linux.or.jp/ (Now Constructing)
Project BLUE 				http://www.blue.gr.jp/
LUGS:=YLUGダイエット部,TLUC関東支部,TLUG,CLUG,たん清,ダンケ,すぃすぃ
三浦広志 ----- MIURA, Hiroshi 		http://www.momokuri.org/