HS_BIBLE.txt

doclib\HS_BIBLE.txt » Plain Format

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
                                                           2005/06/12
  HSP HELP Browser 用 hs ファイルの標準仕様

  Copyright (C) 2001-2005 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 ファイルに対して完全な
上位互換となっていますが、より柔軟な書式にも対応しています。

本書が解説するのは、あくまで、「HSP HELP Browser 用の」hs ファイルの仕
様ですので注意してください。



■ 改定履歴
‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾
2004/04/07 (HSP HELP Browser 1.40 実装)
・作成

2005/05/25 (HSP HELP Browser 1.50 実装)
・行頭の特殊文字 '%', '^' のエスケープ仕様を追加
・パラメータ書式の関数型表記仕様を追加
・重複するシンボル名のリネームを廃止

2005/06/12
・誤植修正


■ 言葉の定義
‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾
・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 行目以降は各パラ
メータの概要説明としてください。
パラメータを持たないシンボルの場合は、"パラメータ無し" 等と書かないで、
空にしておいてください。
※
HSP HELP Browser 1.50 以降では、パラメータ書式が '(' で始まる場合、関
数型の引数表記として認識します。(閉じ括弧があるかどうかを問いません)


・%inst (解説文)
ヘルプ内の解説文を記述します。この部分がヘルプページのメインとなります。
英数字は半角文字を使用し、改行は段落ごとに行うことを推奨します。
等幅フォントが使用されますので、以下のような記号を用いた図がずれないで
表示されます。
                    |
                  --+--
          |

・%sample (サンプルスクリプト)
サンプルスクリプトがあれば記述します。

・%href (関連キーワード)
そのヘルプページに関連する用語を記述します。複数のキーワードを登録する
場合は、複数行にわたって書きます。

・%group (グループ)
シンボルの属するグループを定義します。記述例は、"画面制御命令", "文字
列操作命令", "入出力制御命令" などです。



■ タグの解説
‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾
文字列データ中で行頭が '^' で始まる物をタグといい、テキストの処理を制
御する機能があります。
この機能は過去の hs ファイルとの互換性のために残されていますが、hs フ
ァイルの作成や保守がしにくくなるため、HSP HELP Browser 用の hs ファイ
ルではとくに使用する必要はありません。

・^
行を空行にします。HSP HELP Browser では、このタグを使用しなくても解説
文やサンプルスクリプト中の空行はそのまま空行として残されますので、この
タグを使用する必要はありません。

・^p
字下げモードの切り替えをします。HSP HELP Browser では、このタグを用い
ても字下げは行われません。字下げを行う場合は、タブや空白文字を使用して
ください。

※
説明文の中などで '^' で始まる行がある場合は、行頭を '^^' とすることで
タグとして認識しないようにすることができます。



■ コメントについて
‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾
';' で始まる行はコメントとみなされ、無視されます。
また、'%' もしくは '^' で始まる制御行では、制御文字列以降の ';' からが
コメントとして扱われます。

・コメントの例
; -------- comment
%index ; -------- comment

特にサンプルスクリプト中でスクリプトのコメント用に ';' を使う場合は、
それを行頭に書かないように注意してください。';' の前にスペースやタブが
あればコメントとみなされません。



■ メモ
‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾
・大文字を含むシンボル
シンボルは大文字/小文字を問わず使用でき、そのままの状態で表示されます。

・特殊文字 '%', '^' のエスケープについて
hs ファイルでは、行頭の '%' と '^' 文字は、メンバ定義キーワードおよび
タグとして認識されます。説明文などで、行頭に '%' や '^' を記述する場合
は、"%%", "^^" と文字を続けて書いてください。これにより、特殊文字がエ
スケープされて、一文字としてデータベースに格納されます。
行頭以外では、エスケープを行う必要はありません。



■ 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 ; -------- 

...



━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━