6 ヘルプ情報ファイル

この章では、OHJおよびOHWで使用する、ヘルプ情報ファイル(目次ファイル、索引ファイル、およびリンク・ファイル)について説明します。ヘルプ情報ファイルには、ヘルプ・システムのコンテンツに関する情報が含まれます。

この章には次の項が含まれます:

• 第6.1項「ヘルプ情報ファイルについて」

• 第6.2項「目次ファイル」

• 第6.3項「マスター目次」

• 第6.4項「索引ファイル」

• 第6.5項「検索索引ファイル」

• 第6.6項「リンク・ファイル」

6.1 ヘルプ情報ファイルについて

ヘルプ情報ファイルは、目次ファイル、索引ファイル、およびリンク・ファイルの3つのタイプにカテゴリ分けできます。これらのファイルは、すべてXMLファイルです。

6.2 目次ファイル

目次(TOC)ファイルは、目次のコンテンツおよびレイアウトを記述するXMLファイルです。このファイルは、通常、「目次」タブとしてレンダリングされます。各ヘルプセットjarファイルには1つの目次ファイルが必要になることに注意してください。

ヘルプセットのjarファイルに、複数の子ヘルプセットが含まれている場合は、親ヘルプセットの目次のコンテンツとレイアウトを制御するためにマスター目次ファイルを使用します。

6.2.1 TOCの要素

表6-1に、目次ファイルで使用される要素を示します。

表6-1 TOCファイルの要素

要素	説明
<toc>	目次を定義します。この要素には、<tocitem>要素が含まれます。<toc>要素の属性は、次のとおりです。 version: 目次ファイル形式の仕様のバージョン。例に示されるバージョン1.0です。
<tocitem>	目次のエントリを定義します。<tocitem>要素に他の<tocitem>要素を含め、トピックの階層を作成できます。tocitem_2内にtocitem_1をネストすると、tocitem_1がtocitem_2内の階層に含まれるよう定義されます。<tocitem>要素でサポートされる属性は、次のとおりです。 target: ユーザーが項目を選択したときに表示されるトピックのトピックID。トピックIDは、マップ・ファイルに保持されます。親ノード(階層で、自身の下に他の項目を含む項目)には、ターゲットが含まれる場合と含まれない場合があります。ノードにターゲットが含まれていないときに、そのノードを選択すると、そのノードの子項目および子ノードが表示されます。 目次エントリから外部URLを開くには、url属性が目的の外部URLに設定されたトピックIDを使用します。すべての外部URLが新しいブラウザ・ウィンドウで自動的に開くことに注意してください。詳細は、第5.3.1項「マップ・ファイル要素」を参照してください。 text: この項目の目次に表示されるテキスト。 image: この項目の横に表示されるイメージ。この属性の値は、マップ・ファイルに指定されているイメージIDとなります。

次に、簡単な目次ファイルの例を示します。

<?xml version='1.0'?>
  <toc version="1.0">
  <tocitem text="Introduction to My Product" image="prodIcon">
    <tocitem target="aboutmyp" text="About My Product" />
    <tocitem target="architec" text="My Product Architecture" />
    <tocitem target="feature1" text="About Feature One" />
    <tocitem target="feature2" text="About Feature Two" />
    <tocitem target="feature3" text="About Feature Three" />
    <tocitem text="Learning My product">
      <tocitem target="qtour" text="Quick Tour" />
      <tocitem target="docguide" text="Guide to Documentation" />
    </tocitem>
  </tocitem>
  <tocitem text="Step-by-step Procedures" image="prodIcon">
    <tocitem text="Basic Tasks">
      <tocitem target="task1" text="To..." />
      <tocitem target="task2" text="To..." />
      <tocitem target="task3" text="To..." />
    </tocitem>
    <tocitem text="Working with ...">
      <tocitem target="task4" text="To..." />
      <tocitem target="task5" text="To..." />
    </tocitem>
  </tocitem>
  </toc>

この定義で作成されるTOC階層は、次のとおりです。

• Introduction to My Product

  • About My Product

  • My Product Architecture

  • About Feature One

  • About Feature Two

  • About Feature Three

  • Learning My Product

    • Quick Tour

    • Guide to Documentation

• Step-by-step Procedures

  • Basic Tasks

    • To...

    • To...

    • To...

  • Working with ...

    • To ...

    • To ...

6.3 マスター目次

マスター目次ファイルは、すべての子ヘルプセットのTOC構造を制御し、他の目次ファイルを管理します。ヘルプセット・ファイルを宣言する前に、マスター目次を宣言する必要があります。

6.3.1 マスター目次の構成方法

マスター目次を使用する場合は、最初にOracle Help for the Web構成ファイルを構成しておく必要があります。

1. マスター目次ヘルプセット・ファイルは、Oracle Help for the Web構成ファイル内で宣言します。

   次の例は、構成ファイルから抜粋したコードを示しています。

   <books>
     <helpSet id="master" location="master/src/helpset/master.hs"/>
     <helpSet id="ohguide" location="ohguide/src/helpset/ohguide.hs"/>
     <helpSet id="blafdoc" location="blafdoc/src/helpset/blafdoc.hs"/>
     <helpSet id="shake" location="shakespeare/src/helpset/shakespeare.hs"/>
   </books>
   

   前述の例では、マスター目次ヘルプセット・ファイルを次のコードで宣言しています。

   <helpSet id="master" location="master/src/helpset/master.hs"/>

   マスター目次ヘルプセット・ファイルは、最初に宣言する必要があります。その他のヘルプセット・ファイルは、その後に宣言します。

2. マスター・ヘルプセット・ファイルを作成します。

   マスター目次ヘルプセットのエントリは、次に示すmaster.hsファイルから抜粋したコード例のように、その他のTOCエントリに似ています。

     <view>
       <type>oracle.help.navigator.tocNavigator.TOCNavigator</type>
       <data engine="oracle.help.engine.XMLTOCEngine">toc.xml</data>
     </view>
   

3. すべての目次構造を定義する、マスター目次のXMLファイルを作成します。

   このマスター目次のXMLファイルは、その他のtoc.xmlファイルと似ていますが、このファイルには<tocfile>要素が含まれています。<tocfile>要素では、次の例で示すように、子目次のXMLファイルの場所を定義します。

    <toc version="1.0">
     <tocitem text="Root">
       <tocitem text="Some random node">
         <tocfile location="ohguide/toc.xml" />
         <tocfile location="javadoc/toc.xml" />
       </tocitem>
       <tocfile location="blafdoc/toc.xml;shakespeare/shakespeare.hhc" />
     </tocitem>
     <!-- All helpset toc files not explicitly declared in this file will be
          inserted under the following node. This includes toc files that are
          located in a subhelpset. -->
     <tocitem text="Extension Help Content">
       <tocfile location="*" />
     </tocitem>
   </toc>
   

   マスター目次ファイルでは、コンテンツの構造を制御しますが、そのコンテンツはヘルプセット・ファイルで定義する必要があります。

6.4 索引ファイル

索引ファイルは、索引のコンテンツとレイアウトを記述するXMLファイルです。通常は、「索引」タブとしてレンダリングされます。

6.4.1 索引の要素

表6-2に、索引ファイルで使用される要素を示します。

表6-2 索引ファイルの要素

要素	説明
<index>	索引を定義します。この中には、<indexitem>タグと<indexentry>タグを含めることができます。
<indexitem>	キーワード・リストに表示される索引項目を定義します。index_item_2内にindex_item_1をネストすると、index_item_1がindex_item_2の階層に含まれ、索引でindex_item_2の下にインデントされて表示されるよう定義されます。Oracle Helpでは、現在2レベルのキーワードのみがサポートされています。索引ビューでは、2レベルを超えるネストは縮小されます。 索引項目に複数のトピックが関連付けられている場合、各トピックは、<indexentry>要素で定義された索引エントリとしてリストする必要があります。 <indexitem>要素の属性は、次のとおりです。 target: ユーザーがエントリを選択したときに表示されるトピックのトピックID(マップ・ファイルで定義されています)。
<indexentry>	索引リストで親索引項目が選択されたときにトピック・リストに表示される索引エントリを定義します。このタグで使用される属性は、次のとおりです。 target: ユーザーがエントリを選択したときに表示されるトピックのトピックID(マップ・ファイルで定義されています)。

次に、簡単な索引ファイルの例を示します。

<?xml version='1.0' ?>
  <index version="1.0">
  
  <indexitem target="Add_Icon"
      text="Add Icon Command">
    <indexitem target="addtosheet"
        text="Adding an icon to a sheet />
    <indexitem target="addtoworkbook"
        text="Adding an icon to a workbook" />   
  </indexitem>
  
  <indexitem target="Sheet_Background"
       text="Adding a background to a sheet" />
 
  <indexitem text="Adding a new sheet to a workbook">
    <indexentry target="New_Sheet_command"
        text="New Sheet Command />
    <indexentry target="Add_new_sheet"
        text="To add a new sheet to a workbook" />
  </indexitem>
  
  <indexitem target="Add_item_to_sheet"
      text="Adding an item to a sheet" />
  </index>

この例のファイルでは、次の索引リストが作成されます。

Add Icon Command
    Adding an icon to a sheet
    Adding an icon to a workbook
  Adding a background to a sheet
  Adding a new sheet to a workbook
  Adding an item to a sheet

ユーザーがリストからAdding a new sheet to a workbookを選択すると、次のトピックのリストが表示されます。

New Sheet Command
  To add a new sheet to a workbook

「索引」ペインの最上位のキーワード・リストに表示されるインデントされたトピックAdding an icon to a sheetおよびAdding an icon to a workbookとは対照的に、このトピック・リストは「索引」ペインの下部に表示されます。

索引エントリがなく、直接関連付けられたターゲットがあるキーワード(Adding an item to a sheetなど)を選択すると、キーワード・リストと同じテキストがトピック・リストに表示されます。Oracle Helpでの索引の表示方法を考慮すると、<indexitem>タグでターゲットを使用しないことをお薦めします。かわりに、キーワードのターゲットが1つのみの場合でも、常に<indexentry>タグを使用して<indexitem>に関連付けられているトピックを指定するようにします。

つまり、次のコードを使用します。

<indexitem text="sheet backgrounds">
    <indexentry target="Sheet_Background" text="adding a background to a sheet" />
</indexitem>

次のコードは使用しないでください。

<indexitem target="Sheet_Background" text="adding a background to a sheet" />

6.5 検索索引ファイル

検索索引ファイルは、ユーザーがOracle Helpで(通常は「検索」タブから)テキスト検索を実行する場合に使用されます。このファイルでは、固有のバイナリ形式が使用されます。Oracle Helpをサポートするサード・パーティのヘルプ・オーサリング・ツールでは、このファイルを生成できます。さらに、OHJDKには、検索索引ファイルを生成する2つのユーティリティが含まれます。

• ヘルプセット・オーサリング・ウィザード: 検索索引の生成などの限定的なオーサリング・サポートが提供されます。詳細は、第9章「Oracle Helpシステムのオーサリング」を参照してください。

• テキスト検索インデクサ: 検索索引を生成するJavaコマンドライン・ツールです。詳細は、第11章「テキスト検索インデクサの使用方法」を参照してください。

6.6 リンク・ファイル

リンク・ファイルは、リンクIDを定義し、複数のトピックID(マップ・ファイルで定義されます)にリンクIDを関連付けるXMLファイルです。リンクID(リンク・キーワード)は、IDに関連付けられているトピックへのリンクのリストを表示するために、トピック・ファイルのalinkプロトコルで使用できます。つまり、関連リンクによって、1つのHTMLリンクを複数のターゲットに関連付けることができます。これにより、ユーザーは目的のターゲットを選択できるようになります。

6.6.1 リンク・ファイルの要素

表6-3に、リンク・ファイルで使用される要素を示します。

表6-3 リンク・ファイルの要素

要素	説明
<link>	リンク・ファイルを定義します。<link>要素には、<linkitem>要素およびその子要素の<linkentry>のみを含めることができます。
<linkitem>	関連リンクを定義します。<linkitem>要素には、<linkentry>要素のみを含めることができます。次の必須属性があります。 topicid: リンクIDを定義します。
<linkentry>	関連リンクをクリックしたときに表示されるリンク・リスト内のエントリを定義します。この要素でサポートされる属性は、次のとおりです。 target: ユーザーがエントリを選択したときに表示されるトピックのトピックID(マップ・ファイルで定義されています)を指定します。 text: リンク・リストに表示されるテキスト。

次の例では、2つの関連リンクを定義しています。

<?xml version='1.0' ?>
  <link version="1.0">
  
  <linkitem topic="dog_links">
    <linkentry target="about_dogs" text="About Dogs" />
    <linkentry target="dog_species" text="A List of Dog Species" />
    <linkentry target="dog_stories" text="Dog Stories" />
    <linkentry target="dog_lore" text="Dog Lore" />
  </linkitem>
  
  <linkitem topic="cat_links">
    <linkentry target="about_cats" text="About Cats" />
    <linkentry target="cat_species" text="A List of Cat Species" />
    <linkentry target="cat_stories" text="Cat Stories" />
  </linkitem>
  </link>

この例の最初のリンクIDを使用すると、リンク<a href="alink:dog_links">dogs</a>を定義できます。ユーザーがdogsリンクを選択すると、次のリンク・リストが表示されます。

About Dogs
A List of Dog Species
Dog Stories
Dog Lore

About Dogsをクリックすると、マップ・ファイルのabout_dogs IDにマップされているトピックが表示されます。