HSP Document Library ドキュメントルール

これから述べるドキュメントルールは、HDL 向けドキュメントファイルとして推奨される、文章の整形、タイトルやファイル名のつけ方について述べたものです。

これは機械的な仕様として定めるものではなく、HDL を抜きにしても、ドキュメントを統制のとれた読みやすいものにすることを目的としています。

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

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

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

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

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

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

これは HSP Document Library 以前の HSP HELP Browser 1.x / 2.x 向けにも強く推奨されるものです。

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

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

スクリーンドキュメント全般に言えることですが、HTML ドキュメントの横幅は絶対値に固定しないで、ブラウザのウィンドウ幅を小さくしていても読めるようにすべきです。

UXGA で見ている人はその環境なりに、SVGA で見ている人もその環境なりに、快適に読んでもらえるに越したことはありません。たとえば、ウィンドウ幅に対して本文ブロックが (CSS) width:95%; という指定ならどのようなウィンドウサイズでも対応できますが、width:640px; のような指定は、環境によってはやけに縦に細長いドキュメントだったり、また別の環境では横スクロールバーが出現するような幅だったりします。

5. ドキュメントの文字エンコードを Shift_JIS にする

これは HSP Document Library の技術的制約です。文字エンコードの自動変換などは行っていませんので、エンコードが Shift_JIS でないドキュメントは検索データベースに読み込むことができません。

(参考) 命令リファレンスの基本形

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

段落・この命令は○○○をするものです。(機能の説明)

段落・ p1 で、○○○を指定します。この値は．．．(引数の説明)

段落・ p2 で、○○○を指定します。この値は．．．(引数の説明)

段落・この命令で注意すべき点は、．．．(注意事項、制限事項の説明)

段落・この命令が成功すると、システム変数 stat に．．．(戻り値の説明)

悪い例

d3setlocal

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

…× 文の構造が複雑

マシな例