16.1 ドキュメントスタイルの作成

ドキュメントスタイルには、プロジェクトに関する情報の表示方法を定義できます。わずかな時間で、プロジェクトに配置したすべての要素を含むドキュメントを生成し、それらの情報の表示方法を指定するドキュメントスタイルを定義できます。

16.1.1 ドキュメントスタイルの作成

  1. ［Project (プロジェクト)］ビューでプロジェクトを選択し、［Documentation (ドキュメント)］アイコンを右クリックします。

  2. ［New (新規)］>［Document Generation Style (ドキュメント生成スタイル(.docgen))］の順にクリックします。

    ドキュメント生成スタイルの選択

    ドキュメント生成スタイル(.docgen)は、Designer付属のデフォルトのスタイルです。

  3. スタイルの名前(拡張子は.docgen)を指定するか、デフォルト名のままで、［Finish (完了)］をクリックします。

    新規スタイルの命名

    .docgenファイルが作成されます。このファイルは、ユーザ独自のスタイルテンプレートを設計するための基礎として使用できます。.docgenテンプレートは、変更できるように［スタイルエディタ］ビュー内に置かれます(「スタイルのカスタマイズ」を参照)。新規スタイルテンプレート内の定義済み要素は繰り返し使用できます。

  4. .docgenファイルを作成し、自分のニーズに合わせて変更したら、Documentationフォルダ内の.docgenファイルを右クリックして、［Generate Doc for this Style (このスタイルのドキュメントを生成)］を選択します。

    ドキュメントの生成
    • 既存の.pdfファイルを上書きする場合は、［Overwrite existing file (既存ファイルを上書き)］チェックボックスをオンにします。
    • XMLソースファイルを確認するには、［Output XML source files (XMLソースファイルを出力)］チェックボックスをオンにします。
    • モデル図をPDFファイルに取り込むには、［Capture Model diagrams (モデル図の取り込み)］チェックボックスをオンにします。

  5. ［OK］をクリックするとドキュメントが生成されます。

    設計した要素の特定部分についてのみ記述した部分的なドキュメントを作成することもできます。具体的な方法については、スタイルの一部の文書化を参照してください。

  6. 今リリースのDesignerには、ドキュメントをRTF (リッチテキスト形式)で出力する機能が含まれています。これはまだ正式な機能ではありませんが、使用できます。［Window (ウィンドウ)］>［Preferences (初期設定)］をクリックして、［Preferences (初期設定)］ウィンドウを開きます。続いて、［Designer for IDM］にある［Doc Generation (ドキュメントの生成)］を選択してください。

    RTF形式でのドキュメント生成を有効にする

    ［Enable pre-release functionality for DocGen (DocGenのプレリリース機能を有効にする)］を選択すると、ドキュメント生成時にRTF形式を選択できます。

    一度有効にすると、RTFを出力形式として使用できるようになる

16.1.2 スタイルとプロジェクトのさまざまな組み合わせ

プロジェクトのドキュメント生成には、Designer付属のデフォルトのスタイルまたはユーザがカスタマイズしたスタイルを使用できます。

たとえば、Blanston2というスタイルを作成したとします。スタイルBlanston2を自分の用途に合わせてカスタマイズし、セクション 16.1.1, ドキュメントスタイルの作成で説明した手順に従って、DocumentationフォルダにBlanston2.docgenという名前で保存します。このスタイルを使用して、Blanston2プロジェクトまたはその他のプロジェクトのドキュメントを作成できます。

スタイルから開始してプロジェクトを選択

  1. ［Project (プロジェクト)］ビューでBlanston2プロジェクトを開き、DocumentationフォルダのBlanston2.docgenファイルを右クリックします。

  2. ［Generate Doc for this Style (このスタイルのドキュメントを生成する)］をクリックします。

  3. ［Generate Documentation (ドキュメントの生成)］ウィンドウで、［Input Settings (入力設定)］タブをクリックして、現在のスタイルテンプレート(この例ではBlanston3)を使用してドキュメントを作成するプロジェクトを選択します。

    文書化するプロジェクトを選択する

  4. ［Output Settings (出力の設定)］タブを選択して［Specify Output Criteria (出力条件の指定)］ウィンドウを開き、必要な情報を入力して、［OK］をクリックします。詳細については、ドキュメントの生成を参照してください。

プロジェクトから開始してスタイルを選択

  1. Blanston2と別のプロジェクト(例えばBlanston1)を開いて、［プロジェクト］ビューに移動し、［Documentation (ドキュメント)］>［New (新規)］>［Documentation Generation Style (.docgen) (ドキュメント生成スタイル(.docgen))］をクリックします。

  2. 新しい.docgenファイル(この例ではBlanston2.docgen)を選択して、［Next (次へ)］をクリックします。

  3. 基本スタイル(この例ではBlanston.docgen)を選択して、［Finish (完了)］をクリックします。

    基本スタイルの選択

    スタイルエディタ内にBlanston2.docgenファイルが開きます。スタイルには通常、会社名など、プロジェクト固有の情報が含まれているため、上記の情報を使用して、テンプレートが転送されているかどうかを確認してください。スタイルエディタの［Generate Documentation (ドキュメントの生成)］アイコンをクリックすると、ドキュメントが生成されます。Blanston1プロジェクトで頻繁にBlanston2.docgen スタイルを使用する場合は、Blanston1 Documentation フォルダのBlanston2スタイル、または.docgenファイルを、スタイルテンプレートライブラリにコピーします。詳細については、セクション 16.4.4, Styles Template Library (スタイルテンプレートライブラリ)へのStyle File (スタイルファイル)の保存を参照してください。

スタイルの一部の文書化

プロジェクト全体のドキュメントを生成する代わりに、選択したセクションだけのドキュメントを生成することもできます。

  1. ［Style Editor (スタイルエディタ)］ペインでBlanston2.docgenファイルを開き、スタイルの一部を右クリックします。

  2. ［Generate Doc for this Style (このセクションのドキュメントを生成する)］を選択します。

  3. ［Generate Documentation (ドキュメントの生成)］ウィンドウで、［Filename (ファイル名)］フィールドに別のプロジェクト名(例えば、ExecutivSumofMergerなど)を入力してから、［OK］をクリックします。

    1セクションのドキュメントの生成

生成するセクションの作成

選択したセクションだけのドキュメントを生成して、同僚がそれぞれの部分に関する情報を提供するとします。各セクションおよびその子セクションには、［Include this section in the final document (このセクションを最終ドキュメントに含める)］というチェックボックスがあります。デフォルトでは、このチェックボックスはすべてオンになっています(下図参照)。

図 16-1 ［環境設定セクション］のチェックボックス

  1. ドキュメントを生成しないセクションのチェックボックスをオフにすることで、ドキュメントのサイズと内容を制御できます。

    「Appendix B: Schema (付録B: スキーマ)」セクションには、次の3つのチェックボックスがあります。［Include this section in the final document (このセクションを最終ドキュメントに含める)］、［Document all custom Identity Vault Schema even if not marked for documentation (ドキュメントの対象としてマークされていないものも含めてすべてのカスタムのアイデンティティボールトスキーマを文書化する)］、および［Document all Application Schema even if not marked for documentation (ドキュメントの対象としてマークされていないものも含めてすべてのアプリケーションスキーマを文書化する)］の3つです。

    Appendix B: Schema

    ［Include this section in the final document (このセクションを最終ドキュメントに含める)］チェックボックスを使用すると、付録Bの情報をドキュメントに含めるかどうかを指定できます。デフォルトはオンで、情報を含めるように設定されています。

  2. アプリケーションまたはアイデンティティボールトのスキーマをドキュメントに含めない場合は、このチェックボックスをオフにします。

    ［Document all custom Identity Vault Schema even if not marked for documentation (ドキュメントの対象としてマークされていないものも含めてすべてのカスタムのアイデンティティボールトスキーマを文書化する)］チェックボックスを使用すると、アイデンティティボールトスキーマ(アイデンティティボールトからインポートするか、ユーザが自分で作成したもの)を文書化するかどうかを制御できます。アイデンティティボールトスキーマ全体を含むプロジェクトをインポートし、そのプロジェクトに関するドキュメントを生成すると、600ページ以上のスキーマ情報が追加されます。これは、アイデンティティボールトの基本スキーマと追加スキーマがすべてドキュメントに含まれるためです。

    Novellでは、必要がない限り、アイデンティティボールトスキーマ全体を文書化することはお勧めしていません。最大の問題は、メモリ不足が発生する可能性があるという点です。ドキュメント生成時にメモリ不足が発生した場合の対処法については、セクション 19.5, ドキュメント生成時の問題を参照してください。

文書化するアイデンティティボールトスキーマを選択するには:

  1. ［Modeler (モデラ)］ビューで［Identity Vault (アイデンティティボールト)］アイコンを右クリックし、［Manage Schema (スキーマの管理)］を選択します。

  2. ［Manage Schema (スキーマの管理)］ウィンドウで、文書化するクラスを選択し、［Document this Class (このクラスを文書化する)］をクリックします。

    <Ctrl>キーまたは<Shift>キーを使用すると、複数のクラスを選択できます。クラスを選択して［Document this Class (このクラスを文書化する)］をクリックすると、選択したクラスが文書リストに追加されます。

    文書化するクラスと属性を選択する

  3. ［OK］をクリックします。

「Appendix B: Schema (付録B: スキーマ)」セクションで［Document all custom Identity Vault Schema even if not marked for documentation (ドキュメントの対象としてマークされていないものも含めてすべてのカスタムのアイデンティティボールトスキーマを文書化する)］チェックボックスをオンにすると、スキーマインポートウィザードで指定したアイデンティティボールトスキーマの選択部分は事実上すべて無効になります。これまでの内容を次に要約します。

  • 「Appendix B: Schema (付録B: スキーマ)」セクションで［Document all custom Identity Vault Schema (すべてのカスタムのアイデンティティボールトスキーマを文書化する)］チェックボックスをオンにすると、すべてのアイデンティティボールトスキーマが文書化されます。
  • 「Appendix B: Schema (付録B: スキーマ)」セクションで［Document all custom Identity Vault Schema (すべてのカスタムのアイデンティティボールトスキーマを文書化する)］チェックボックスをオフにすると、［Manage Schema (スキーマの管理)］オプションで選択したアイデンティティボールトスキーマだけが文書化されます。
  • 「Appendix B: Schema (付録B: スキーマ)」セクションで［Document all custom Identity Vault Schema (すべてのカスタムのアイデンティティボールトスキーマを文書化する)］チェックボックスをオフにし、かつ［Manage Schema (スキーマの管理)］オプションでどのアイデンティティボールトスキーマも選択しなかった場合、スキーマは一切文書化されません。

「Appendix B: Schema (付録B: スキーマ)」ページの3つめのチェックボックス［Document all Application Schema even if not marked for documentation (ドキュメントの対象としてマークされていないものも含めてすべてのアプリケーションスキーマを文書化する)］を使用すると、文書化するドライバのアプリケーションクラスを選択できます。「Appendix B: Schema (付録B: スキーマ)」セクションで［Document all Application Schema even if not marked for documentation (ドキュメントの対象としてマークされていないものも含めてすべてのアプリケーションスキーマを文書化する)］チェックボックスをオンにすると、すべてのアプリケーションスキーマが文書化されます。スキーマ全体を文書化する代わりに、文書化するアプリケーションスキーマを選択することもできます。詳細については、次の例を参照してください。

  1. ドライバのアプリケーションクラスを選択するために、モデラ内でプロジェクトを表示します。

  2. ドライバアイコンを右クリックして［Manage Schema (スキーマの管理)］を選択します。

    スキーマの管理

  3. ［Application Classes (アプリケーションクラス)］ダイアログボックスが開き、追加または削除できるクラスのリストが表示されます。右側には、クラス用に既に作成されている属性が表示されます。［Application Classes (アプリケーションクラス)］ウィンドウにクラスが表示されない場合は、現在、そのドライバ用に作成されているクラスが存在しないことを意味します。

    アプリケーションクラス

  4. 右下隅には、［Document this Class (このクラスを文書化する)］チェックボックスが表示されます。このチェックボックスをオンにすると、スキーマ全体を文書化するのではなく、Document Generator (ドキュメントジェネレータ)を使用して文書化するアプリケーションクラスを選択できます。

「Appendix B: Schema (付録B: スキーマ)」セクションで［Document all Application Schema even if not marked for documentation (ドキュメントの対象としてマークされていないものも含めてすべてのアプリケーションスキーマを文書化する)］チェックボックスをオンにすると、［Application Classes (アプリケーションクラス)］ウィンドウで指定したドライバアプリケーションスキーマの選択部分が事実上すべて無効になります。これまでの内容を次に要約します。

  • 「Appendix B: Schema (付録B: スキーマ)」セクションで［Document all Application Schema even if not marked for documentation (ドキュメントの対象としてマークされていないものも含めてすべてのアプリケーションスキーマを文書化する)］チェックボックスをオンにすると、すべてのアプリケーションスキーマが文書化されます。
  • 「Appendix B: Schema (付録B: スキーマ)」セクションで［Document all Application Schema (すべてのアプリケーションスキーマを文書化する)］チェックボックスをオフにすると、［Application Classes (アプリケーションクラス)］ウィンドウで選択したアプリケーションスキーマだけが文書化されます。
  • 「Appendix B: Schema (付録B: スキーマ)」セクションで［Document all Application Schema (すべてのアプリケーションスキーマを文書化する)］チェックボックスをオフにして、かつ［Application Classes (アプリケーションクラス)］ウィンドウでアプリケーションスキーマを選択しなかった場合、スキーマは文書化されません。
生成したレポートからの不要なアイデンティティボールトスキーマの削除

アイデンティティボールトスキーマ全体を含むプロジェクトをインポートし、そのプロジェクトに関するドキュメントを生成すると、600ページ以上のスキーマ情報が追加されます。これは、アイデンティティボールトの基本スキーマがすべてドキュメントに含まれるためです。

アイデンティティボールトの基本スキーマがすべて必要というわけではない場合は、次の手順に従います。

  1. プロジェクトのワークスペースフォルダに移動し、.dataファイルを削除します。たとえば、Windowsワークステーションの場合、Blanston1_filesディレクトリはC:\Documents and Settings\Novell User\workspace\Blanston1\Blanston1_filesにあります。［Type (種類)］をクリックすると、すべての.dataファイルがまとめて表示されます。アイデンティティボールトの基本スキーマは、サイズが最大の.dataファイルにあります。

    アイデンティティボールトスキーマ

    アイデンティティボールトがプロジェクトに複数ある場合は、プロジェクトのフォルダにサイズの大きな.dataファイルが複数存在します。

  2. .dataファイルをテキストベースのエディタ(ワードパッドなど)を使用して開き、スキーマファイルが存在することを確認します。ファイルの先頭には<schema-def>と表示されます。

    スキーマ定義

  3. 自分のプロジェクトとアイデンティティボールトの間でアイデンティティボールトスキーマが異なっている部分(相違点)だけをインポートするとします。スキーマの相違点を取得するには、手順1の説明に従ってサイズの大きい.data ファイルをすべて削除し、次の手順に従ってプロジェクトのスキーマをインポートし直します。

    1. Designerの［Modeler (モデラ)］ビューでプロジェクトを開きます。アイデンティティボールトを右クリックして、［Live Operations (ライブ操作)］>［Import Schema (スキーマのインポート)］の順に選択します。

    2. ［Select Source for Import (インポートするソースの選択)］ページで、実際のアイデンティティボールトに接続している場合は［Import from eDirectory (eDirectoryからインポート)］を選択し、スキーマファイルをローカルに保存した場合は［Import from .sch File (.schファイルからインポート)］を選択します。［Import from eDirectory (eDirectoryからインポート)］で、接続情報としてホスト名、ユーザ名、およびパスワードを入力します。［Next (次へ)］をクリックします。

    3. ［Select Classes and Attributes for Import (インポートするクラスと属性の選択)］ページで、［View Differences (相違点の表示)］をクリックします。

      Schema Import Wizard (スキーマインポートウィザード)

    4. ［Schema Differences (スキーマの相違点)］ページに、アイデンティティボールトとプロジェクトとのスキーマの違いが表示されます。

      Schema Differences (スキーマの相違点)

    5. ［Select All (すべて選択)］をクリックします。これにより、［Select Classes and Attributes for Import (インポートするクラスと属性の選択)］ページに戻り、［Classes(クラス)］および［Attributes (属性)］の各見出しで相違点が選択されます。デフォルトでは、［Import All Associations (すべての関連付けのインポート)］ボックスもオンになっています。このチェックボックスをオンにしたまま［Finish (完了)］をクリックします。

    6. ［Import Summary (インポートの概要)］ページで、［OK］をクリックします。

  4. ［Manage Schema (スキーマの管理)］ウィンドウが表示されます。このウィンドウで、で説明した手順に従って文書化するクラスと属性を選択します。

必要な部分の文書化

これで、生成するドキュメントに含めるプロジェクトの一部分を指定できます。［Moderler (モデラ)］ビューまたは［Outline (アウトライン)］ビューを使用して、ドメイン、アイデンティティボールト、ドライバセット、ドライバ、アプリケーションを文書化できます(複数の項目を選択するには<Ctrl>キーを使用します)。

ドキュメントの生成は、スキーマメモ、クラス、属性とも関係しています。詳細については、セクション 12.0, スキーマの管理を参照してください。

次に例を示します。

  1. プロジェクト内の特定のドライバを文書化するには、［Modeler (モデラ)］または［Outline (アウトライン)］ビューでそのドライバを右クリックして、［Document Selection (ドキュメントの選択)］を選択します。

    ドライバの文書化

  2. ドキュメントの.docgenスタイルシートを選択して、ドキュメントのファイル名を指定し、ドライバのドキュメントを生成します。

デフォルトでは、アプリケーションを文書化すると、接続されたドライバ(とその関連オブジェクト)もドキュメントに含められます。同様に、特定のドライバを文書化すると、接続されたアプリケーションもドキュメントに含められます。この動作は、［Doc Generation’s Preferences (ドキュメント生成の初期設定)］ページで変更できます。

  1. ［Window (ウィンドウ)］>［Preferences (初期設定)］の順にクリックして、［Preferences (初期設定)］ウィンドウを開きます。

  2. ［Designer for IDM］にある［Doc Generation (ドキュメントの生成)］を選択します。

    関係の初期設定

［Document Applications and Drivers related to other selected items (他の選択済み項目と関連するアプリケーションおよびドライバの文書化)］はデフォルトで選択されており、直接関連する項目がドキュメントに含められます。例えば、デフォルトでは、ドライバセットをドキュメント化すると、直接の子(アプリケーション)および直接の親(アイデンティティボールトとドメイン)に関する一部の情報が含められ、ドライバセットのコンテキストが記述されます。このオプションをオフにすると、選択した項目の直接の子がドキュメントから除外されます。