1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
|
-*- 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)
未定
|
