More ...
HSP2.61:HS_BIBLE
- →HSP2.6:付属文書に戻る
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
2004/04/07
HSP HELP Browser (1.40 以降) 用 hs ファイルの標準仕様
Copyright (C) 2001-2004 S.Programs
http://sprocket.babyblue.jp/
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
■ はじめに
￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣
このドキュメントは、HSP HELP Browser がサポートする「HSP ヘルプソース
ファイル」(hs ファイル) の仕様を説明します。
HSP HELP Browser は、不具合の無い限り、この仕様書に従って書かれた hs
ファイルを正しく処理し、表示することができます。
HSP HELP Browser がサポートする hs ファイルは、HSP 2.55/2.6 に付属して
いるヘルプマネージャ用の .hs ファイルに対して完全な上位互換となってい
ますが、.hs ファイルより柔軟な書式に対応しています。
本書が解説するのは、あくまで、「HSP HELP Browser 用の」hs ファイルの仕
様ですので注意してください。
■ 言葉の定義
￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣
・hs ファイル (ヘスファイル)
一つかそれ以上の HSP HELP のページ情報が格納されたファイルです。
本書に示す hs ファイル書式にしたがった ASCII テキストファイルである必
要があります。拡張子は、"hs" です。
・ページ
HSP で使われる特定のシンボル (命令など) について説明した、解説文やサン
プルスクリプトなどのデータのひとまとまりをページと呼びます。
・メンバ
メンバとは、ページに含まれる各要素のことです。命令名や見出し、解説文な
どがそれに当たります。すべてのメンバは文字列データとなっています。
・グローバルメンバ
同じ hs ファイル内のすべてのページで共有されるグローバルなメンバです。
グローバルメンバは、hs ファイルの最初の %index までに書き終わります。
定義されなかったメンバは、デフォルト値 (空の文字列) が使用されます。
・ローカルメンバ
同じ hs ファイル内でもそれぞれのページごとに違った内容が定義されるロー
カルなメンバです。定義されなかった場合、デフォルト値 (空の文字列) が使
用されます。
■ メンバ定義キーワードの解説
￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣
'%' で始まるメンバ定義キーワードを使うことでメンバの定義ができます。
メンバ定義キーワードは、行頭に書く必要があります。キーワードは、大文字
小文字を問いません。
メンバのデータは、メンバ定義キーワード以降の行から始まります。
以下のメンバがページごとに記録されます。それぞれのメンバに許容される文
字列サイズは、15KB までです。また、ひとつのページの全データの容量は、
グローバルメンバのデータを含めて 50KB までです。
hs ファイル中に未定義なキーワード (%hoge など) がある場合、その中のデー
タは無視されます。
グローバルメンバ
・%dll 使用プラグイン/モジュール
・%author 著作者
・%date 日付
・%ver バージョン
・%note 備考 (補足情報等)
・%url 関連 URL
・%type タイプ
ローカルメンバ
・%index シンボル名, 見出し
・%prm パラメータ書式, パラメータ説明文
・%inst 解説文
・%href サンプルスクリプト
・%sample 関連キーワード
・%group グループ
■ 各メンバ定義キーワードの書き方
￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣
hs ファイルの各メンバの記述時の注意点をまとめます。
それぞれのメンバのサイズは、15KB 以内に収まるようにしてください。
□ グローバルメンバ
・%dll (使用プラグイン/モジュール)
使用するプラグインやモジュールがあれば、そのファイル名もしくは名称を記
述します。
1 つの hs ファイル内で定義できるのは一回だけです。最初の %index までに
記述してください。
・%author (著作者)
ヘルプで説明しているシンボルの著作者名を記述します。連名にする場合は、
複数行で書きます。
1 つの hs ファイル内で定義できるのは一回だけです。最初の %index までに
記述してください。
・%date (日付)
ヘルプで説明しているシンボルの日付を記述します。更新履歴などのために必
要であれば、複数行にわたって書くことができます。
1 つの hs ファイル内で定義できるのは一回だけです。最初の %index までに
記述してください。
・%ver (バージョン)
hs ファイルで説明しているもののバージョンを記述します。
1 つの hs ファイル内で定義できるのは一回だけです。最初の %index までに
記述してください。
・%note (備考)
ファイル内のページ全般について、備考や注意書きがあれば記述します。複数
行にわたって記述できます。
1 つの hs ファイル内で定義できるのは一回だけです。最初の %index までに
記述してください。
・%url (関連 URL)
関連する URL があれば記述します。複数の URL を記述する場合は、複数行に
します。
1 つの hs ファイル内で定義できるのは一回だけです。最初の %index までに
記述してください。
・%type (タイプ)
hs ファイルで説明しているシンボルのタイプを記述します。記述例は "拡張
命令", "ユーザー拡張命令" などです。
1 つの hs ファイル内で定義できるのは一回だけです。最初の %index までに
記述してください。
□ ローカルメンバ
・%index (シンボル名, 見出し)
ページ名と見出しを定義します。データの 1 行目がページ名、2 行目は見出
しとなります。同じページの %prm, %inst, %sample, %href, %group を記述
する前に定義します。
ページ名は、ヘルプページが対象とするシンボルと同じ物にします。見出しは、
機能を簡潔に表した、なるべく短いものにしてください。見出しには改行は使
えません。
・%prm (パラメータ書式, パラメータ説明文)
命令やマクロのパラメータを記述します。1 行目は書式、2 行目以降は各パラ
メータの概要説明としてください。
パラメータを持たないシンボルの場合は、"パラメータ無し" 等と書かないで、
空にしておいてください。
・%inst (解説文)
ヘルプ内の解説文を記述します。この部分がヘルプページのメインとなります。
英数字は半角文字を使用し、改行は段落ごとに行うことを推奨します。
等幅フォントが使用されますので、以下のような記号を用いた図がずれないで
表示されます。
|
--+--
|
・%sample (サンプルスクリプト)
サンプルスクリプトがあれば記述します。
・%href (関連キーワード)
そのヘルプページに関連する用語を記述します。複数のキーワードを登録する
場合は、複数行にわたって書きます。
・%group (グループ)
シンボルの属するグループを定義します。記述例は、"画面制御命令", "文字
列操作命令", "入出力制御命令" などです。
■ タグの解説
￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣
文字列データ中で行頭が '^' で始まる物をタグといい、テキストの処理を制
御する機能があります。
この機能は過去の hs ファイルとの互換性のために残されていますが、hs フ
ァイルの作成や保守がしにくくなるため、HSP HELP Browser 用の hs ファイ
ルではとくに使用する必要はありません。
・^
行を空行にします。HSP HELP Browser では、このタグを使用しなくても解説
文やサンプルスクリプト中の空行はそのまま空行として残されますので、この
タグを使用する必要はありません。
・^p
字下げモードの切り替えをします。HSP HELP Browser では、このタグを用い
ても字下げは行われません。字下げを行う場合は、タブや空白文字を使用して
ください。
■ コメントについて
￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣
';' で始まる行はコメントとみなされ、無視されます。
また、'%' もしくは '^' で始まる制御行では、制御文字列以降の ';' からが
コメントとして扱われます。
・コメントの例
; -------- comment
%index ; -------- comment
特にサンプルスクリプト中でスクリプトのコメント用に ';' を使う場合は、
それを行頭に書かないように注意してください。';' の前にスペースやタブが
あればコメントとみなされません。
■ メモ
￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣
・大文字を含むシンボル
命令名は大文字小文字を問わず使用できます。ただし、検索時は大文字と小文
字の区別はされません。
・同じスペルのシンボル
同じスペルのシンボルがある場合、シンボルのあとに "(2)" 等が付きます。
プラグインの命令名などは、そのプラグイン特有の添え字をつけるなどして、
なるべく衝突の少なそうなものを使用したほうがよいと思います。
■ hs ファイルの記述例
￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣
hoge.hs
;---------------------------------------------------------------
; hs ファイル記述例
;---------------------------------------------------------------
%type
ユーザー拡張命令
%ver
1.0
%note
hoge.as をインクルードする。
%date
2004/03/06
%author
Foo_taro
%dll
HogeModule
%url
http://www.hoge.foo/
http://www.hoge.foo/hoge/hoge.htm
%index ; -------- 初期化命令
initHoge
HogeModule を初期化
%prm
n1, "s2", v3
n1 : hoge 関数に与える初期値
"s2" : 文字列のための文字列
v3 : hoge 展開先の整数配列
%group
HOGE 制御命令
%inst
HogeModule を、現在の描画先ウィンドウにあわせて初期化します。
同時に、foo 関数テーブルの作成も行います。
HogeModule 使用時に、最初に実行してください。
%index ; --------
... (続く)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━