インストール|HTML として出力する

AppleScriptDoc の書き方

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

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

(*!
@references
Script factory || http://www.script-factory.net

@title AppleScriptDoc Sample Script Reference

* Authour : Tetsuro KURITA ((<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 &quot;Edit Script&quot; 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

boot (module loader) for 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 handelr.
@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
show helpbook (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 のサンプルコードを記述できます。

ハイパーリンク

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

@references

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

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

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

ブロック領域の変換規則

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

このような領域の解釈は以下のようになります(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 markup characters

HTML のマークアップに使われる文字(", &, <, >)には、実体参照を用いる必要があります。AppleScriptDoc はこれらの文字を変換しません。

character entity
" &quote;
& &amp;
< &lt;
> &gt;
インストール|HTML として出力する