VineSeed ML アーカイブ



[VineSeed:026029] Re: 7.x に向けたドキュメント整備要領の変更について

  • From: Yasumichi Akahoshi <yasumichi@xxxxxxxxxxxxx>
  • Subject: [VineSeed:026029] Re: 7.x に向けたドキュメント整備要領の変更について
  • Date: Sat, 19 Jan 2013 04:11:03 +0900
 赤星です。

> Vine のドキュメント内で実際に使っていた DocBook XML のタグ数は、
> 少ない印象を持っています。

 実際、そんなに多くのタグは使ってませんね。

> また、わたし自身が DocBook で記述するときは、
> そもそもタグを覚えていません(笑
> 適当なひな形とかこれまでタグ付けされた XML を参考にすれば、
> なんとかなるものです。
> どうしても詳しく知りたいときに、DocBook のドキュメントを見ていた程度でした。

 私自身も似たようなものです。どちらかと言えば、タグの多さよりもタグのバランス
に気をつけねばならず、大きな Book になると結構厳しいというのもあります。まあ、
xsltproc が吐くエラーをみれば、何とかなる程度ではありますが、今記述しているページ
のみのプレビューを見たいというような時には若干、コストがかかる気がしていました。

> Vine のドキュメント作成参入への敷居が下がるのと、
> 変更点がすぐに確認できるのは良いですね。

> trac wiki 記法の適当な parser はあるのでしょうか?
> 適当な軽量言語で既存のモジュールがあれば、変換処置も比較的簡単そうですね。
> # 「trac の python コードを読め、以上!」では無くてですね… (^^;;
> また、AsciiDoc の記法は Wiki のそれに近いので、
> asciidoc 記法に落とす手もあるかもしれません。

 asciidoc や reST など既に変換システムがあるようなもので書けるといいなとか、
wiki データを内部的には VCS で管理できるといいな、というような気はしてて
Debian で使われていると聞いた ikiwiki がそんな機能を備えているらしいのですが
(個人的に)実力が未知数のもの、新たな wiki 記法を覚える必要があるものを導入
するのは別にコストがかかるという気がして、とりあえずは trac で始めるのが
適切なのかなと考えました。

> テキストエディタから trac Wiki をいじれると、便利!?

 これは、テキストエディタで編集できるというよりもオフラインで編集できた方が
いいという解釈で良いですか?

> それからそもそも…
> Vine のドキュメント作成する範囲において、trac wiki の記法内で収まるのでしょうか?
> 赤星さんが trac wiki で Vine のドキュメント作成を試みようとお考えになられているので、
> きっと trac wiki の記法の使用内で、Vine のドキュメントを一通り記述できるのでしょう。

 今は試行錯誤の段階ですが、正直、制約はあると思っています。note, warning, important
に当たる部分をどう表記するかとか。収まるというより、収めるしかないかなと。多少の工夫
は必要そうです。(汗)

 今、とりあえず、大きく 7.x の仕様に依存しないと思われる

開発者ガイド
http://trac.vinelinux.org/wiki/docs/developers-guide

を移植中なのでここはこう表記したらいいんじゃないかとかあれば、ご教示いただけると幸いです。

-- 
Yasumichi Akahoshi
GnuPG fingerprint = 04D4 DB0D 37CB A251 2671  1BAB 2369 F522 E440 9DCF
_______________________________________________
VineSeed mailing list
VineSeed@xxxxxxxxxxxxx
http://lists.vinelinux.org/mailman/listinfo/vineseed