| Oracle® Fusion Middleware Oracle Helpによるヘルプ・システムの開発 12c (12.2.1.1) E77341-01 |
|
 前 |
 次 |
この章では、OHJおよびOHWで使用する、ヘルプ情報ファイル(目次ファイル、索引ファイル、およびリンク・ファイル)について説明します。ヘルプ情報ファイルには、ヘルプ・システムのコンテンツに関する情報が含まれます。
この章の内容は次のとおりです。
ヘルプ情報ファイルは、目次ファイル、索引ファイル、およびリンク・ファイルの3つのタイプにカテゴリ分けできます。これらのファイルは、すべてXMLファイルです。
目次(TOC)ファイルは、目次のコンテンツおよびレイアウトを記述するXMLファイルです。このファイルは、通常、「目次」タブとしてレンダリングされます。各ヘルプセットjarファイルには1つの目次ファイルが必要になることに注意してください。
ヘルプセットのjarファイルに、複数の子ヘルプセットが含まれている場合は、親ヘルプセットの目次のコンテンツとレイアウトを制御するためにマスター目次ファイルを使用します。
表6-1に、目次ファイルで使用される要素を示します。
表6-1 TOCファイルの要素
| 要素 | 説明 |
|---|---|
|
|
目次を定義します。この要素には、
|
|
|
目次のエントリを定義します。
|
次に、簡単な目次ファイルの例を示します。
<?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 ...
マスター目次ファイルは、すべての子ヘルプセットのTOC構造を制御し、他の目次ファイルを管理します。ヘルプセット・ファイルを宣言する前に、マスター目次を宣言する必要があります。
マスター目次を使用する場合は、最初にOracle Help for the Web構成ファイルを構成しておく必要があります。
マスター目次ヘルプセット・ファイルは、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"/>
マスター目次ヘルプセット・ファイルは、最初に宣言する必要があります。その他のヘルプセット・ファイルは、その後に宣言します。
マスター・ヘルプセット・ファイルを作成します。
マスター目次ヘルプセットのエントリは、次に示すmaster.hsファイルから抜粋したコード例のように、その他のTOCエントリに似ています。
<view>
<type>oracle.help.navigator.tocNavigator.TOCNavigator</type>
<data engine="oracle.help.engine.XMLTOCEngine">toc.xml</data>
</view>
すべての目次構造を定義する、マスター目次の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>
マスター目次ファイルでは、コンテンツの構造を制御しますが、そのコンテンツはヘルプセット・ファイルで定義する必要があります。
索引ファイルは、索引のコンテンツとレイアウトを記述するXMLファイルです。通常は、「索引」タブとしてレンダリングされます。
表6-2に、索引ファイルで使用される要素を示します。
表6-2 索引ファイルの要素
| 要素 | 説明 |
|---|---|
|
|
索引を定義します。この中には、 |
|
|
キーワード・リストに表示される索引項目を定義します。index_item_2内にindex_item_1をネストすると、index_item_1がindex_item_2の階層に含まれ、索引でindex_item_2の下にインデントされて表示されるよう定義されます。Oracle Helpでは、現在2レベルのキーワードのみがサポートされています。索引ビューでは、2レベルを超えるネストは縮小されます。 索引項目に複数のトピックが関連付けられている場合、各トピックは、
|
|
|
索引リストで親索引項目が選択されたときにトピック・リストに表示される索引エントリを定義します。このタグで使用される属性は、次のとおりです。
|
次に、簡単な索引ファイルの例を示します。
<?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" />
検索索引ファイルは、ユーザーがOracle Helpで(通常は「検索」タブから)テキスト検索を実行する場合に使用されます。このファイルでは、固有のバイナリ形式が使用されます。Oracle Helpをサポートするサード・パーティのヘルプ・オーサリング・ツールでは、このファイルを生成できます。さらに、OHJDKには、検索索引ファイルを生成する2つのユーティリティが含まれます。
ヘルプセット・オーサリング・ウィザード: 検索索引の生成などの限定的なオーサリング・サポートが提供されます。詳細は、第9章「Oracle Helpシステムのオーサリング」を参照してください。
テキスト検索インデクサ: 検索索引を生成するJavaコマンドライン・ツールです。詳細は、第11章「テキスト検索インデクサの使用方法」を参照してください。
リンク・ファイルは、リンクIDを定義し、複数のトピックID(マップ・ファイルで定義されます)にリンクIDを関連付けるXMLファイルです。リンクID(リンク・キーワード)は、IDに関連付けられているトピックへのリンクのリストを表示するために、トピック・ファイルのalinkプロトコルで使用できます。つまり、関連リンクによって、1つのHTMLリンクを複数のターゲットに関連付けることができます。これにより、ユーザーは目的のターゲットを選択できるようになります。
表6-3に、リンク・ファイルで使用される要素を示します。
表6-3 リンク・ファイルの要素
| 要素 | 説明 |
|---|---|
|
|
リンク・ファイルを定義します。 |
|
|
関連リンクを定義します。
|
|
|
関連リンクをクリックしたときに表示されるリンク・リスト内のエントリを定義します。この要素でサポートされる属性は、次のとおりです。
|
次の例では、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をクリックすると、マップ・ファイルのabout_dogs IDにマップされているトピックが表示されます。
