ライブラリのドキュメント

Curl 言語は、Curl ソースコードに API ドキュメントを追加することができる特別なマークアップを提供します。ライブラリ API のドキュメントを参照してください。Curl マークアップを追加して、ユーザーガイドドキュメントを作成することが出来ます。これらのツールでは、作成した Curl ライブラリのドキュメントの作成とデプロイを行うことが出来ます。

Curl ユーザーガイドは、ドキュメントのコンテンツを含む幾つかの Curl アプレットファイルから構成されます。コンテンツは、幾つかのレベルの章と見出しを含むブックで構成されます。ブックのタイトルと、ブックを構成するファイルは、_outline.scurl という名前の特別なファイル内で定義されます。章と見出しは、エントリのインデックス記述のマークアップを含むアプレットファイル内で定義されます。特殊な Curl スクリプトがドキュメントアプレットと _outline.scurl を処理し、Curl ドキュメントビューワで表示出来るブック構造を生成します。結果のドキュメントは、閉じたり開いたりすることが出来る、コンテンツのテーブル(TOC)、インデックス、章、見出しのノードを含んでいます。

以下のリストは、ユーザーガイドドキュメントを作成、デプロイする時に行う必要があるステップの概要を示しています。:

以下の章では、これらのステップの詳細を説明します。

各ブックのディレクトリの作成

Curl ライブラリユーザーガイドのコンテンツを構成する最も良い方法は、ガイド内のブック毎にディレクトリを作成することです。ユーザーガイドの TOC とインデックスを生成する Curl スクリプトは、引数としてディレクトリの名前を取ります。そのディレクトリは、ブックのアプレットと、ブックのタイトルとブック内のファイルの順序を定義する _outline.scurl ファイルを含んでいます。_outline.scurl ファイルがこのディレクトリの外部ファイルを参照することは可能ですが、処理をより複雑にしてしまいます。

デプロイされたユーザーガイドは、docs と呼ばれる親ディレクトリ内の言語固有のディレクトリに存在します。Curl のデプロイプロセスは、docs ディレクトリを作成し、API リファレンスの素材を含むディレクトリと適切な言語固有のディレクトリを作成します。このプロセスは、自動的にインデックスと TOC スクリプトを実行したり、ユーザーガイドコンテンツをデプロイロケーションにコピーしたりしません。スクリプトを手動で実行し、ガイドディレクトリとコピーすることでユーザーガイドを言語固有のディレクトリにデプロイする必要があります。

アプレットファイルの作成

ドキュメントアプレットは、普通の Curl アプレットですが、インデックスのサポートの為に、CURL.IDE.GUIDE パッケージをインポートする必要がありません。そのパッケージは、heading と image の代替定義を提供するので、シンボルは、パッケージから明示的にインポートされるか、override? = true を使ってパッケージがインポートされる必要があります。ドキュメントアプレットは、DocDocument ドキュメントスタイルを使用します。：

典型的なドキュメントアプレットは、以下のコードで始まります。:

{import * from CURL.IDE.DOCUMENTATION}
{import * from CURL.IDE.GUIDE, override? = true}
{document-style DocDocument}

ユーザーガイドコンテンツを作成する時に、Curl オブジェクト指向言語の全ての機能を利用することが出来ます。以下の章では、ドキュメントの作成で特に便利な幾つかのテキストプロシージャとテキストフォーマットを説明します。幾つかは、ドキュメントに特化した機能を提供し、他の場所では説明されていません。

Structure

以下の Curl マークアップは、ユーザーガイドに構造を与え、TOC を生成するスクリプトによって使用されます。

{chapter ...}

chapter は、章の開始をマークし、Curl ユーザーガイドドキュメントのフォントと色をレンダリングする章のタイトル記述します。また、リンクの宛先とインデックスの引数も取り、これらは、章のタイトルの前である必要があります。

TOC を生成するスクリプトは、アプレットファイルで {chapter } マークアップを探し、TOC 内で章ノードを配置するのに使用します。アプレットファイルは、一つだけ {chapter } を含むことができ、それはファイル内の全ての {heading } マークアップの前であるか、TOC 内でブランクの章である必要があります。それはまた、レベル 1 {heading } が続くか、TOC 内でブランクの章である必要があります。必ずしも全てのファイルに {chapter } は必要ありません。章は、複数のアプレットファイルから構成することも出来ます。

このプロシージャは、以下のシンタックスを持ちます。:

{heading ...}

TOC 生成スクリプトは、heading プロシージャを使用して、TOC 内に見出しノードを配置します。見出しレベルは、数値順に従うか、TOC 内でブランクの見出しである必要があります。

見出しの使用のより一般的な情報は、見出しを参照してください。

インデックス

以下の Curl マークアップでは、インデックスエントリの指定が出来ます。インデックス生成スクリプトは、これらを使用して、ユーザーガイドのインデックスを作成します。

{index ...}

index は、{index } プロシージャが置かれているドキュメントの場所にリンクするインデックスエントリを記述します。以下のシンタックスを使用します。：

{HeadingIndex ...}

HeadingIndex は、heading または chapter に関連するインデックスエントリを記述します。シンタックスは、index と同じです。

Curl コードのレンダリング

ユーザーガイドドキュメントは、しばしばコードサンプルを含む必要があります。以下の Curl マークアップで行うことが出来ます。

{code ...}

code は、空白を除いたり、改行を除去せずに等幅フォントでテキストを表示します。Curl ブラケットのような文字の特別な扱いを排除しますが、metavar や docref を特別扱いしません。

code フォーマットは、他のフォーマットほど便利ではありません。短い Curl 言語ソースコードサンプルには、ctext を使用してください。長い Curl 言語ソースコードサンプルには、curl-code を使用してください。他の等幅コンテンツには、 pre または、monospace を使用してください。

{ctext ...}

ctext は、空白と改行を保護する必要がなく、API ドキュメントの参照をとメタ変数を含む Curl 言語ソースコードの断片を表示します。これは、等幅テキストを表示し、Curl ブラケットのような、ほとんど全ての文字の特殊な扱いを排除します。しかし、ctext は、引数内の空白をつめず、改行に配慮しません。また、ctext 式のボディ内に以下のいずれかが見つかると特別な処理を適用します。:

例えば、{abs x} は、{ctext {abs x}} としてマークアップすることが出来ます。

{curl-code ...}

curl-code は、等幅フォントを使用し、Curl ソースエディタと同じ色で Curl 言語ソースコードを表示します。空白と改行は、尊重されます。curl-code ボディ内の各行のテキストが、空白で始まっていた場合、残りのテキストをフォーマットする前に、同じ量の空白が各行の先頭から取り除かれます。

複数行で、フォーマットされた Curl 言語サンプルには、curl-code を使用してください。curl-code は、通常、装飾素材の中で使用され、実行中のテキスト内では使用されません。Curl 言語サンプルが、自己完結で実行可能な場合は、curl-code よりも example の使用を検討して下さい。

{metavar ...}

metavar は、方程式内の変数のように見えるようにインデントされ、イタリック、セリフ体でテキストを表示します。Curl コードの断片または、Curl によって処理された実行時の値を表す用語には metavar を使用してください。例えば、以下の中の "x" には、metavar を使用してください。:

{abs x} 式は、x の絶対値を返します。

単語の強調や、Curl コードの断片や、Curl によって処理される実行時の値を表さない用語をイタリックにする目的で、metavar を使用しないでください。例えば、以下で、”very”を強調するのに使用しないでください。:

Security precautions are very important.

{pre ...}

pre は、空白と改行を保持して、等幅フォントでテキストを表示します。コードサンプル内でインデントを保持するのに便利です。pre の詳細の情報は、 pre を参照してください。

{example ...}

example は、ドキュメント内で、動作するコードサンプルを作成します。Curl ソースコードとそのソースコードを実行した結果を表示し、編集可能で、インタラクティブなサンプルとして表示します。

{small-caps ...}

コンテンツを全て大文字にし、フォントサイズを 20% 減らしてローマ字を表示します。実行中のテキストまたは見出しの中で、"CTRL+a のキーの組み合わせを押してください" や "SHIFT と Backspace の両方を押してください." の中でのような、キーボード上のキーの名前をフォーマットするのに、small-caps を使用してください。（大文字化は自動です。）small-caps は、サンプルコード内（タイトル以外）で使用することは出来ませんが、キーの名前は矛盾しないように綴り（例えば、Return や CONTROL ではなくて Enter と CTRL）、強調の為に太文字フォーマットを使用する必要があります。

リンク

ユーザーガイドドキュメントは、しばしばハイパーテキストリンクを用いて、関連するドキュメントの別の部分にリンクする必要があります。link マークアップと destination マークアップがこれを可能にします。

{link ...}

link プロシージャは、指定された Url へのハイパーテキストリンクを生成します。Url 文字列の後ろに、# と宛先テキストを追加することで、url に destination を含めることが出来ます。以下のコードは、前の章で定義された宛先へのリンクを生成します。

link の詳細情報は、link 構文を参照してください。

{destination ...}

destination テキストプロシージャは、ドキュメントの特定のポイントに link スクロールさせることが出来るポイントを識別する文字列を記述します。

destination-name 引数を追加することで、heading を宛先ポイントにすることが出来ます。：

destination の詳細は、destination 構文を参照してください。

{docref ...}

docref は、指定されたターゲットの API ドキュメントへのリンクを提供します。Curl API は、docref の変形として、docref-abbr、 docref-quiet、docref-abbr-quiet を提供します。

リスト

行頭文字付きリストと行頭番号付きリストはどちらもユーザードキュメント内で便利です。行頭文字付きリスト、行頭番号付きリストを参照してください。Curl は、term と definition で構成されるリストの特殊なリストマークアップを提供します。定義リストを参照してください。

Illustrations

figure プロシージャと image プロシージャでは、ドキュメントにスクリーンキャプチャや他の図や画像を追加することが出来ます。

{figure ...}

{image ...}

image では、スクリーンキャプチャのような画像ファイルをドキュメントに含めることが出来ます。詳細の情報は、image を参照してください。

アウトラインファイルの作成

_outline.scurl ファイルは、二つの特殊なテキストプロシージャを使用して、ディレクトリ内のアプレットファイルがどのようにブックに構成されるのかを指定します。book 式は、ブックの名前を記述し、ファイル内の最初のコードである必要があります。file 式が、book に続き、ブック内の各アプレットファイルに対応し、ブック内に現れる順である必要があります。

例えば、content-1.curl から content-4.curl までの４つのコンテンツファイルがあり、content-1.curl が章１を含んでいるような場合、以下のコードが _outline.scurl ファイルに含まれます。:

{book {text This is Book One}}

{file {url "content-1.curl"}}
{file {url "content-2.curl"}}
{file {url "content-3.curl"}}
{file {url "content-4.curl"}}

結果は、以下のコンテンツのテーブルになります。：

以下の章では、book と file の詳細を説明します。

{book ...}

{book } テキストプロシージャは、ブックの構造を定義し、ブックの TOC を生成するのに必要な情報を提供する _outline.scurl ファイルの中だけで使用してください。このプロシージャは、一つの引数を取り、それは、ブックのタイトルのテキストです。そのテキストをクォーテーションマーク() で囲んではいけません。囲んだ場合、クォーテーションは、ブックのタイトルに表示されます。以下のコードは、ブックのタイトルを "Utility Library User's Guide" と定義しています。

_outline.scurl 内に一つの {book } 構文だけを書くことができ、それは、全ての {file} 構文の前に来る必要があります。ライブラリドキュメントで二つ以上のブックが必要な場合は、各ブック毎にディレクトリを作成し、{book } を一つだけ含む _outline.scurl ファイルをそれぞれのディレクトリに作成してください。

{file ...}

{file } テキストプロシージャは、_outline.scurl ファイルの中でだけ使用してください。このプロシージャは、ブック内に含まれるファイルを指定する Url を引数として取ります。_outline.scurl ファイルと同じディレクトリにないファイルを追加することが出来ますが、ブック内の全てのファイルをデプロイディレクトリにコピーすることを覚えて置かなくてはなりません。以下の構文は、ブックに "chapter-one.curl" と呼ばれるファイルを追加しています。

コンテンツのテーブルとインデクスの作成

コンテンツのテーブル

ライブラリのユーザーガイドコンテンツを作成すると、Curl スクリプト curl://install/ide/bin/make-guide-contents.xcurl を実行して、TOC を生成することが出来ます。このスクリプトは、バッチファイルからまたはコマンドプロンプトから直接実行される必要があります。スクリプトは、_outline.scurl ファイルのコンテンツを処理し、ドキュメントファイル内の heading と chapter をマークアップします。

このテーブルは、TOC 生成コマンドラインインターフェースを説明します。:

例えば、以下のコマンドをコマンドプロンプトウィンドウで１行で入力し、dguide と呼ばれるディレクトリで TOC 生成ツールを実行します。

インデックス

ライブラリのユーザーガイドコンテンツを生成したら、Curl スクリプト curl://install/ide/bin/make-guide-index.xcurl を実行して、ドキュメントインデックスを生成します。このスクリプトは、バッチファイルからまたはコマンドプロンプトから直接実行される必要があります。スクリプトは、ドキュメントファイルを読み込み、HeadingIndex マークアップと index マークアップを処理し、全文検索をサポートするデータを生成します。

デプロイディレクトリへのコピー

Curl デプロイプロセスでは、ライブラリをデプロイする時にライブラリ内のパッケージの API ドキュメントを生成することが出来ます。 API リファレンスとCurl 開発者ガイドは、ライブラリがEclipseのCurlの設定ダイアログページにある インストール済みのライブラリ を使用してインストールされた後、Curlドキュメンテーションビューワで見ることが可能です。詳細については、Eclipse ヘルプドキュメント内のCurl 開発ユーザーガイドを参照してください。

Copyright © 1998-2019 SCSK Corporation. All rights reserved.
Curl, the Curl logo, Surge, and the Surge logo are trademarks of SCSK Corporation. that are registered in the United States. Surge Lab, the Surge Lab logo, and the Surge Lab Visual Layout Editor (VLE) logo are trademarks of SCSK Corporation.