-*- mode: outline; mode: auto-fill; -*-

* tdoc形式について

次のような形式を持つ=podと=cutに囲まれた範囲が、TiarraDoc(tdoc)として
認識されます。

=pod
ヘッダのキー: ヘッダの値
ヘッダのキー: ヘッダの値
...

内容
=cut

このように、"キー: 値"の行が一つ以上続き、その後に空行が来るような形を
していないpodはtdocパーサによって無視されます。

tdocデータはファイル内の何処にあっても構いませんが、そのtdocが説明する
パッケージ内の範囲に無ければなりません。つまり、複数のパッケージを持
つ*.pmファイルの中では、パッケージFooについてのtdocはパッケージFoo内に
置く必要があります。
tdocパーサはperlのpackage文を認識し、どのパッケージについての説明であ
るかを判断します。

tdocデータはsample.confの生成とhtmlドキュメントの生成の両方に使われま
す。また、将来これ以外の使い方がされる可能性もあります。

** ヘッダ

ヘッダに記述すべき内容は、通常のモジュール(module下のもの)、内部モジュー
ル(main下のもの)、そしてドキュメント生成元データ(doc-src下の*.tdoc)そ
れぞれに於て異なります。

*** 通常のモジュールのヘッダ(module下のもの)

通常のモジュールは、ヘッダとして"info"と"default"を持ちます。
infoはモジュールの簡単な説明(一行)、defaultは値として"on"または"off"を
持つ真偽値で、それぞれsample.conf内でデフォルトで"+"になっているか"-"
になっているかを示します。

例(System::Reload):

=pod
info: confファイルやモジュールの更新をリロードするコマンドを追加する。
default: on

# リロードを実行するコマンド名。省略されるとコマンドを追加しません。
# 例えば"load"を設定すると、"/load"と発言しようとした時にリロードを実行します。
# この時コマンドはTiarraが握り潰すので、IRCプロトコル上で定義された
# コマンド名を設定すべきではありません。
command: load
=cut

*** 内部モジュール(main下のもの)

未定

*** ドキュメント生成元データ(doc-src下の*.tdoc)

未定


** 内容

ドキュメント内容もヘッダと同じように、通常モジュール、内部モジュール、
ドキュメント生成元データのそれぞれに於て異ります。

*** 通常モジュール

通常モジュールは、"#"で始まる行と"key: value"の形そしている行、そして
"-key: value"の形をしている行の三種類の形式で記述します。
空の行やこれらの形を持たない行は、パーサによって無視されます。

"#"で始まる行は、後述する"key: value"の説明の為にあります。
連続する"#"行はtdocパーサによって一つに纏められ、先頭の空白が削除され
た後にsample.conf、htmlの各形式に整形されます。
纏められた"#"行の先頭に共通する空白は全て削除されますが、共通*しない*
空白は残されます。

例:
#  foo
#  bar
#  baz

以上の三行は纏められ、先頭の空白が削除される。sample.confでの整形結果
は結果は次の通り。

# foo
# bar
# baz

例:
#  foo
#    bar
#  baz

以上の三行は纏められ、全ての行に存在する空白が削除される。結果は次の通
り。

# foo
#   bar
# baz

"key: value"形式の行は、そのモジュールの設定項目を表します。
同様に、"-key: value"形式の行は、そのモジュールの設定項目ではあっても、
sample.confではデフォルトでコメントアウトされている項目を表します。

*** 内部モジュール(main下のもの)

未定

*** ドキュメント生成元データ(doc-src下の*.tdoc)

未定
