How to Write AppleScriptDoc

AppleScriptDoc is special comments in source cocde. The comments starts with "(*!" and ends with "*)" are AppleScriptDoc region. In this region, texts are markuped with tags starts with "@".

Before detail explanation, see the following sample.

(*!

@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

There are two tags of @title and @group. The contents of these tags are the text until end of the markuped line.

Required tag is only @title. @group is optional.

@title

The title of the manual. Only one @title must exists.

@group

This tag is used to add heading sections to indicate groups of handlers. This tag is optional.

Handler Tags

The tags to describe each handlers are listed. The order of tags is not important. But these tags should be placed in the comment region right before the handler definition.

The contents of these tags is the line having a tag and lines until next tag apears.

The required tag is only @abstruct.

@abstruct

A abstruct of handler's explanation. The abstruct is outputed in both of the index page and the handelr page.

@description

A detail description of the handler. The description is outputed only in the handler page.

@param

A description of a parameter. List this tags of the number of parameters.

@result

The description of the result of the handler.

@syntax

Describe calling syntax of the handler. Usually this tag should be omitted. If ommited, the syntax is obtained from the definition of the handler located just after the comment region of AppleScriptDoc.

The contents of this tag must be code which can be compiled as AppleScript.

Sample Code

The sample code of AppleScript can be placed between @example tag and @end tag.

The code will be colorized.
A script link will be appended. By clicking the script link, the sample code will be opend with the Script Editor.
The code must be able to be compiled.

Hyper Links

The word enclosed with "((<" and ">))" means a hyperlink, like "((<keyword>))"

If "keyword" is a handler name, the link to the handler page is generated.
If "keyword" is a url or a mail address, the link to the destination is generated.
To make a link for an arbitrary word, you need to correlate the word with a URL using @references tag.

@references

The correlations betwen a keyword and an url are defined in the region of continuous lines below @reference tag. List keywords and URLs sepatating with double vertical bars "||", as follows.

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

The region of the contents of @references tag is ended with an empty line or the other tag.

The formatting rules of block regions

In the following regions of AppleScriptDoc, paragraphs and lists can be described.

The lines after the line of headding tags(@title, @group).
The contents of @abstruct, @description and @result.
Other unmarkuped regions.

The formatting rules abeve regions are as follows. The rules are smilar to RD.

Heading

A line starts with continuous "=" is heading. The level of heading is determined by the number of the "=".

= formated as h1 element
== formated as h2 element
=== formated as h3 element
・・・

Paragraph

The lines separated with empty lines are paragraphs. The paragraphs is formatted as p element (<p> ~ </p>) of HTML.

Verbataim

The lines stats with spaces or tabs are vervatim (preformated text). These lines are formatted as a pre element (<pre> ~ </pre>) of HTML.

List

The oreder list and the unordred list can be used. The level of list items are determined by the indent levels of the lines.

orederd list

The begining of lines are numberd as (1), (2) ....

unorderd list

The lines starts with "*".

Inline Elements

You can use XHTML's inline elements for styles and external links.

HTML

You must use HTML tags. Characters of "<", ">", "&", """ except HTML tags are endoded to HTML entities.