AppleScriptDoc の書き方

AppleScriptDoc は AppleScript ソースコードに特殊なコメントとして書きます。「(*!」で始まって、「*)」でおわるコメントを AppleScriptDoc と見なします。このコメント中「@」で始まるタグでマークアップします。

細かい説明の前にサンプルを見ていただくのが、まずは手っ取り早いでしょう。

(*!

@references

Script factory || http://www.script-factory.net

@title AppleScriptDoc Sample Script Reference

* Authour : Kurita Tetsuro ((<scriptfactory@mac.com>))

* Home Page : ((<Script factory>))

This is a sample of AppleScriptDoc.

URLs are converted to the link like ((<http://www.script-factory.net>)).

The following links works only in Help viewer.

* The "Edit Script" link in the header.

* Open the script with Script Editor.

* The clipboad icons in the handler pages

* Place a template of the handler into the clipboard

== Example

@example

property sample : "@module"

script "ModuleLoader"'s setup(me)

say_something("hello")

@end

How is this example

(*!@group Methods*)

(*!

@abstruct

Show as message (a simple discription)

@description

This tag can be ommited, if there are nothing to describe.

@param a_message (Unicode text) : a message to be shown. ((<say_something>))

@param Several @param tags can be placed.

But the number of @param should be same to the number of arguments of the handler.

@result none : This tag can be omitted.

@example

say_something("message")

on say_something(a_message)

display dialog a_message

end say_something

(*!

== Tests of Block Regions

Here is paragraph

Here is vebatim (preformatted text)

Here is vebatim (preformatted text) too.

The following lines are a list.

(1) orderd list 1

(2) orderd list 2

* unorderd from here.

A link to the handler page ((<say_something>))

on run

tell script "OpenHelpBook" to do(path to me)

end run

Heading Tags

@title と @group の二つがあります。タグの行末までを内容とします。

必須タグは @title だけです。

@title

リファレンスマニュアルのタイトル。必須です。

@group

ハンドラをグループに分けて見出しを付けたいときに使います。なくてもかまいません。

Handler Tags

ハンドラの説明に使うタグです。順番はバラバラでもいいですが、ハンドラの直前に置かれている必要があります。ハンドラの開始行からシンタックスを取得するためです。

タグがある行から次のタグが現れるまでをその内容とします。

必須タグは @abstruct だけです。

@abstruct

ハンドラの簡単な説明。インデックスページとハンドラのページに出力されます。必須です。

@description

詳細なハンドラの説明。ハンドラのページにだけ出力されます。

@param

パラメータの説明。パラメータの数だけ並べてください。

@result

返り値の説明。

@syntax

ハンドラの呼び出し構文を記述します。通常は省略可能で AppleScriptDoc のコメント領域の直後にあるハンドラの定義部分から取得されます。

AppleScript としてコンパイルできるコードでなければいけません。

サンプルコード

@example タグから @end タグまでの領域に AppleScript のサンプルコードを記述できます。

カラーリングされたコードとして、出力されます。
スクリプトリンクが付与されますクリックするとサンプルコードがスクリプトエディタで開かれます。
AppleScript としてコンパイルできる必要があります。

ハイパーリンク

任意の単語「keyword」にハイパーリンクを設定するには、 ((<keyword>))　と記述します。

keyword がハンドラ名の時には、ハンドラページへのリンクが設定されます。
keyword が URL やメールアドレスのときは、自動的にリンクに変換されます。
任意の単語に任意の URL を設定するには @refrences タグで keyword と URL の関連付けを定義しておく必要があります。

@references

@references タグ以降の行でリンクが設定される単語と URL の関連付けを定義することができます。次のように、キーワードと URL を縦棒二本「||」で区切って列挙します。

@references
keyword1 || http://link.url.com
keyword2 || mailto:hallo@mail.co.jp
keyword3 || ../path/from/index/page.html

空白行もしくは他のタグで @references の内容は終了になります。

ブロック領域の変換規則

AppleScriptDoc の以下の領域では、複数の段落やリストを書くことができます。複数の段落やリストで構成される領域をブロックと呼ぶことにします。

Heading Tags（@title, @group) の直後に書いたテキスト
@abstruct, @description, @result の内容
その他、マークアップされていない領域（ex, @tag を含まない(*! 〜*) )

このような領域の解釈は以下のようになります（RDをパクっています）。

Heading

行頭が連続する「=」で始まる時、見出し行になります。レベルは「=」の数で決まります。

= h1要素に変換される
== h2 要素に変換される
=== h3 要素に変換される
・・・

Paragraph

空行で区切られた行を一つのパラグラフとします。HTML に変換後はパラグラフ要素（<p>〜</p>）になります。

Verbataim

行頭に空白やタブを含む領域は vervatim（preformated text）として扱います。HTML変換後は pre要素（<pre> 〜 </pre>）になります。

List

番号付きリスト(orderd list)と番号のないリスト(unorderd list)を使うことができます。リストのレベルはサンプルのようにインデントで決定されます。

orederd list

行頭が (1), (2) というように番号が振られている

unorderd list

行頭が「*」ではじまる。

Inline Elements

文字のスタイルや外部リンクなど XHTML のインライン要素を使うことができます。

HTML

HTML タグを混在させることができます。HTMLタグ以外での、「", &, <, >」は、実体参照に変換されます。