# HSP Docs Library の使い方、ドキュメントの書き方

HSP Docs Library (HDL) は、HSP のドキュメントをまとめて 検索・閲覧 するためのブラウザです。

hs ヘルプファイル、txt/HTML ドキュメント、サンプルスクリプトを一括して検索したり、相互参照したりすることができます。

## HSP Docs Library が読み込むファイル

ライブラリのファイルは、次のディレクトリから検索されます。

ディレクトリ | 検索されるファイル
--- | ---
doclib | *.hs *.txt *.htm *.html *.hsp
hsphelp | *.hs
sample | *.hsp
common | *.as *.hsp (ドキュメント付けされたヘッダファイル)

HDL のライブラリに新たなドキュメントを追加する場合は、ファイルを doclib ディレクトリに配置してください。

プラグインやモジュールごとに、doclib ディレクトリ下にカテゴリ ディレクトリを作成し、 その中に関連ドキュメント (hs, hsp サンプル, txt, HTML 文書やそれで使われる画像、スタイルシートなど) をまとめると、 ファイル数が多くなっても管理しやすくなります。

ドキュメントの文字コードは、Shift_JIS と UTF-8 がサポートされています。このドキュメントは、UTF-8 で保存されています。

## HSP Docs Library のドキュメント セクション

HDL では、読み込まれたファイルの集合を ライブラリ と呼びます。ライブラリは コマンドヘルプ, ドキュメント, サンプル という 3 つの セクション に分かれます。 それぞれのセクションは、さらに カテゴリ に細分化されます。カテゴリの下に、コンテンツ本体である ページ があります。

.hs ヘルプファイルの内容は、コマンドヘルプ セクションに振り分けられます。コマンドヘルプセクション内のカテゴリは、使用プラグインごとに分けられます。

.txt .htm .html ファイルは、ドキュメント セクションに振り分けられます。

.hsp ファイルは、サンプル セクションに振り分けられます。 ドキュメントセクションとサンプルセクション内のカテゴリは、実際にファイルが置かれているディレクトリ名で分けられます。サブディレクトリに属していないファイルは、「デフォルト」カテゴリに区分されます。

common ディレクトリにドキュメント付けされたヘッダファイル (.as .hsp) がある場合は、その内容はコマンドヘルプセクションに区分されます。

## hs ファイルの作成方法

HDL は、コマンドヘルプマニュアル用のヘルプファイルとして、HSP 独自の hs 形式のヘルプファイルをサポートしています。

hs ファイルの書式については、HS_BIBLE.txt を参照してください。

### hs ファイルのインライン HTML

HDL には、hs ファイルの %inst フィールド内で "html{" と書いた行から "}html" と書いた行までの間を、ダイレクトに HTML として表示する「インライン HTML」という機能があります。

これは hs ファイルとしての仕様ではなく HDL の表示上の仕様で、hs ファイルで HTML の表現を一部利用することができます。

    ; hs ファイル書式例

    %index
    stickf
    キー入力情報取得

    %inst
    stickf 関数は、以下のような複数のキーの状態の OR 値を返します。
    html{
    <table border=1>
    <tr><th>値</th><th>キー</th></tr>
    <tr><td>1</td><td>カーソルキー左(←)</td></tr>
    <tr><td>2</td><td>カーソルキー上(↑)</td></tr>
    <tr><td>4</td><td>カーソルキー右(→)</td></tr>
    <tr><td>8</td><td>カーソルキー下(↓)</td></tr>
    <tr><td>16</td><td>スペースキー</td></tr>
    <tr><td>32</td><td>Enterキー</td></tr>
    <tr><td>64</td><td>Ctrlキー</td></tr>
    <tr><td>128</td><td>ESCキー</td></tr>
    </table>
    }html

インライン HTML の区間について、中の HTML の書式は HDL によってチェックされません。 誤った HTML が記述されているとページ全体のレイアウトが崩れたりする可能性もありますので、hs データの配布などを行う場合は十分にチェックを行ってください。 また、情報の意味づけに関係しない、装飾的な目的での HTML の使用は避けるようにしてください。

インライン HTML ではアクティブスクリプト (javascript 等) の記述を行わないでください。 スクリプトの実行に関するいくつかのキーワードは、使用を制限されています。インライン HTML で使用した要素のスタイルは、外部 CSS の影響を受ける場合があります。

HDL の出力ページのドキュメントタイプは、HTML 5 です。

### (複雑なため推奨しません) ヘッダファイルと hs ドキュメンテーションコメント

HDL は、common ディレクトリ下のヘッダファイル (.as .hsp) を、ドキュメント付けされたヘッダファイルとして読み込みます。

ドキュメント付けされたヘッダファイルとは、ヘッダファイルに hs 形式のドキュメンテーションコメントを追加した形式のファイルで、 ヘッダファイルとしての機能とコマンドヘルプマニュアルとしての機能をあわせ持ったファイルをさします。

HSP スクリプト中にドキュメンテーションコメントを記入する場合、下記のような書式を使用します。 このスクリプトは、HSP スクリプトとしても hs ヘルプファイルとしてもその仕様を満たし、どちらの形式としても正しく処理されます。

    ;============================================================
    ; ドキュメンテーションコメントつきヘッダファイル
    ;============================================================
    /* ～ モジュール情報 (hs デフォルトレコード)
    %dll
    dxmodule

    %ver
    1.67

    %date
    2008/05/01

    %*/ ; <--- これ以降は hs ファイルとしてはコメントになる
    ;------------------------------------------------------------

    #module

    ;===========================================================
    /* ～ ドキュメント部分
    %index
    dxsetcam
    カメラ位置設定

    %prm
    x1, y1, z1, x2, y2, z2

    %inst
    カメラの座標 x1, y1, z1 と向き (ターゲット位置 x2, y2, z2) 設定します。

    %group
    3D 制御命令

    %*/
    ;------------------------------------------------------------
    ; ～ 実装部分
    #deffunc dxsetcam double p1, double p2, double p3, double p4, double p5, double p6
    	//
    	return
    //
    #global

ドキュメンテーションコメントは、HSP スクリプトの複数行コメント (/* ～ */) 内に、hs ヘルプファイルの書式仕様にしたがって記述します。 この、hs 形式のフィールドタグを含む複数行コメントを、ドキュメントブロックと呼びます。

ドキュメントブロックの終了部分は、% 記号を使って、以降が hs 形式としてコメントとなるように処理します。 hs 形式では、定義されていないフィールドタグがあると、以降の行はコメントとみなされます。 この処理を忘れると、HSP スクリプト部分まで hs ドキュメントの一部として認識されてしまう可能性があります。

この部分の記述は、下記のいずれかの書き方を推奨します。

    %*/

    %rem
    */

ドキュメントブロックの中では、ドキュメントとして複数行コメント (/* ～ */) を表現することはできません。

このルールに従って書かれたファイルは、拡張子を .hs に変更するだけで、 ドキュメンテーションコメントをサポートしない hs ヘルプツールからも読み込むことが出来ます。

## ドキュメントのサムネイル画像 (HDL 1.40 で廃止されました)

ドキュメントのサムネイル画像表示機能は、複雑であまり利用されなかったため廃止されました。

## ドキュメント作成者へのお願い

ドキュメントやサンプルスクリプト作成の際には、下記の点に留意いただけますと、視認性、検索性が向上します。

### HTML ドキュメントに適切なタイトルを付ける

HTML ファイルの title タグの内容は、ドキュメントのタイトルとして認識されます。 タイトルは、ドキュメントの中身が何であるか分かりやすいものにしてください。

### テキストやサンプルスクリプトにはわかりやすいファイル名を付ける

サンプルスクリプトや txt ファイルは、ファイル名がそのタイトルとなります。 "test1.hsp" のようなファイル名は、中身が何であるか推測できないため、避けるべきです。

これは、サンプルやドキュメントのディレクトリ名 (= カテゴリ名) にも言えます。

### hs ファイルの改行はビューアーの自動折り返しに任せる

hs ファイルの本文を固定字数で改行すると、 ビューアーのウィンドウサイズやフォントサイズによっては読みづらくなる場合があります。 パラグラフの折り返しは、ビューアーのウィンドウ幅に任せるようにしてください。

### HTML ドキュメントの横幅を固定指定しない

HTML ドキュメントの横幅は絶対値に固定しないで、ブラウザのウィンドウ幅を小さくしていても読めるようにしてください。

## (参考) 命令コマンドヘルプの基本形

命令コマンドヘルプの解説文について、次の段落スタイルのものが、文章が簡潔になり分かりやすい傾向にあるようです。

段落 ・ この命令は○○○をするものです。(機能の説明)
段落 ・ p1 で、○○○を指定します。この値は．．．(引数の説明)
段落 ・ p2 で、○○○を指定します。この値は．．．(引数の説明)
段落 ・ この命令で注意すべき点は、．．．(注意事項、制限事項の説明)
段落 ・ この命令が成功すると、システム変数 stat に．．．(戻り値の説明)

### 悪い例

dxsetlocal

この命令は、px～pz, m00～m22 で指定された座標変換マトリクスを、dxsetcam 以外の すべての dxmodule 命令に適用されるローカル座標系として設定します。

…× 文の構造が複雑

### マシな例

dxsetlocal

ローカル座標系を設定します。
px～pz, m00～m22 で、座標変換マトリクスを指定します。
ローカル座標系は、dxsetcam 以外のすべての dxmodule 命令に適用されます。

…○ 簡単

## アップデート情報

HDL の最新バージョンは、s.programe net http://spn.php.xdomain.jp/ で公開されています。