目錄(TOC)

識別碼:org.eclipse.help.toc

說明:用來登錄個別外掛程式的線上說明構成要素。

每個提供說明檔的外掛程式通常都應該執行下列動作:

toc 延伸點的「配置標記」(這是進入 plugin.xml 檔的標記)

    <!ELEMENT toc EMPTY>
    <!ATTLIST toc file CDATA #REQUIRED>
    <!ATTLIST toc primary (true | false) "false">
    <!ATTLIST toc extradir CDATA #IMPLIED>

toc 的「配置標記」(這是放入 TOC 檔的標記)

    <!ELEMENT toc (topic | anchor | link)* >
    <!ATTLIST toc link_to CDATA #IMPLIED >
    <!ATTLIST toc label CDATA #REQUIRED >

    <!ELEMENT topic (topic | anchor | link )* >
    <!ATTLIST topic label CDATA #REQUIRED >
    <!ATTLIST topic href CDATA #IMPLIED >

    <!ELEMENT anchor EMPTY >
    <!ATTLIST anchor id ID  #REQUIRED >

    <!ELEMENT link EMPTY >
    <!ATTLIST link toc CDATA #REQUIRED >

一般來說,需要提供線上說明的外掛程式通常會定義它自己的 TOC 檔。最後,說明系統會配置成當作某些動作來啟動,且可以利用 TOC 檔的路徑來執行這些動作。

主題元素

提供所有說明 topic 元素作為 toc 儲存器元素的一部份。 它們可以採用階層式結構,也可以列成單純的清單。

topic 元素是「目錄」結構的基礎。topic 元素有兩個典型用法:

1.避免提供文件檔的鏈結 - 通常是 HTML 檔。
2.在相同或不同的處理中,作為其他 toc 的儲存器。

1. 作為鏈結的 topic
topic 最簡單的用法是作為文件檔的鏈結。

<topic label="Some concept file" href="concepts/some_file.html" />

href 屬性相對於 manifest 檔所屬的外掛程式。如果您需要存取另一外掛程式中的檔案,您可以利用這個語法

<topic label="topic in another plug-in" href="../other.plugin.id/concepts/some_other_file.html" />

2. 作為儲存器的 topic
topic 第二常用的用途是作為其他 toc 的儲存器。儲存器主題本身也永遠可以指向特定檔案。

<topic label="Integrated Development Environment" href="concepts/ciover.htm" >
  <topic label="Starting the IDE" href="concepts/blah.htm" />
  ...
</topic>

link 元素

link 元素容許鏈結另一個 toc 檔中所定義的「目錄」。 所有 toc 屬性中所定義的 toc 檔的主題將出現在目錄中, 就如同已經定義它們以直接代替 link 元素。若要包括來自 api.xml 檔的 toc, 您可以撰寫

<topic label="References" >
  ...
  <link toc="api.xml" />
  ...
</topic>

anchor 元素

anchor 元素定義一個點,以容許鏈結其他 toc 檔至這個導覽, 以及在不使用 link 元素的情況下延伸它,以便從這裡參照其他 toc 檔。若要在 "ZZZ" 文件後插入具有多個主題的「目錄」,請定義如下的 anchor:

...
<topic label="zzz" href="zzz.html" />
<anchor id="moreapi" />
...

toc 元素

toc 元素是用以群組這個檔案中所定義的主題及其他元素的「目錄」。 當目錄顯示給使用者時,label 用以向使用者識別這個目錄。 選用的 link_to 屬性容許將這個檔案的 toc 鏈結至導覽階層中較高的另一個 toc 檔。link_to 屬性值必須在另一個 toc 檔指定一個錨點。若要將 myapi.xml 中的 toc 鏈結至在另一個外掛程式中指定的 api.xml 檔,請使用下列語法

<toc link_to="../anotherPlugin/api.xml#moreapi" label="My Tool API"/>
...
<toc />

其中 # 字元用以從錨點識別碼區隔出 toc 檔案名稱。

範例:

以下是使用 toc 延伸點的範例。 假設下列項目適用於 ID 為 "org.eclipse.help.examples.ex1" 的外掛程式。 (這個範例要作為一般範例,且應該記住,從下列所有 toc 檔產生的相同文件階層也可以利用另外的 toc 檔的各種組合來建立。)

(在 plugin.xml 檔中)

 <extension point="org.eclipse.help.toc">
  <toc file="maindocs.xml" primary="true" />
  <toc file="task.xml"/>
  <toc file="sample.xml" extradir="samples" />
 </extension>
 

(in file maindocs.xml)

<toc label="Help System Example">
 <topic label="Introduction" href="intro.html"/>
 <topic label="Tasks">
  <topic label="Creating a Project" href="tasks/task1.html">
   <topic label="Creating a Web Project" href="tasks/task11.html"/>
   <topic label="Creating a Java Project" href="tasks/task12.html"/>
  </topic>
  <link toc="task.xml" />
  <topic label="Testing a Project" href="tasks/taskn.html"/>
 </topic>
 <topic label="Samples">
  <topic label="Creating Java Project" href="samples/sample1.html">
   <topic label="Launch a Wizard" href="samples/sample11.html"/>
   <topic label="Set Options" href="samples/sample12.html"/>
   <topic label="Finish Creating Project" href="samples/sample13.html"/>
  </topic>
  <anchor id="samples" />
 </topic>
</toc>


(在 tasks.xml 檔中)

<toc label="Building a Project">
 <topic label="Building a Project" href="build/building.html">
  <topic label="Building a Web Project" href="build/web.html"/>
  <topic label="Building a Java Project" href="build/java.html"/>
 </topic>
</toc>


(在 samples.xml 檔中)

<toc link_to="maindocs.xml#samples" label="Using The Compile Tool">
 <topic label="The Compile Tool Sample" href="compilesample/example.html">
  <topic label="Step 1" href="compilesample/step1.html"/>
  <topic label="Step 2" href="compilesample/step2.html"/>
  <topic label="Step 3" href="compilesample/step3.html"/>
  <topic label="Step 4" href="compilesample/step4.html"/>
 </topic>
</toc>


以下是 Eclipse 工作台中所產生的文件階層:

Help Sample

假設更多文件存在於以 samples 起始的路徑,它們將不會顯示在導覽樹狀結構中,但可以使用搜尋來存取。 這是因為在 plugin.xml 檔案<toc file="sample.xml" extradir="samples" /> 元素的 extradir 屬性的存在。 例如,搜尋「建立 Java 專案」會傳回「建立 Java 專案的其他方法」文件,路徑為 samples/sample2.html。

國際化

TOC XML 檔案可被翻譯並結果副本(和翻譯過的標籤)必須被放置在 nl/<language>/<country> 或 nl/<language> 目錄。<language> 和 <country> 使用語言環境碼的兩個字母來表示。例如,繁體中文翻譯放置在 nl/zh/TW 目錄下。 nl/<language>/<country> 目錄比 nl/<language>具有高優先權。只有在 nl/<language>/<country>目錄找不到檔案時,才會使用在 nl/<language> 目錄下的檔案。最後才會搜尋根目錄下的外掛。

可以藉由建立包含翻譯後版本文件的 doc.zip 檔,將這個 zip 檔中的文件本土化,並將 doc.zip 放置在
nl/<language>/<country> 或 nl/<language> 目錄下。在預設為 plugin 目錄前,說明系統將在這個目錄下尋找檔案。
 

API 資訊 使用這個延伸點不需要任何程式碼。 只需要提供 plugin.xml 檔中所提及的適當 manifest 檔就行了。
 

提供的實作方式: Eclipse 平台所提供的說明系統 UI 之預設實作方式能充分支援 toc 延伸點。


Copyright IBM Corp. and others 2000, 2002. All Rights Reserved.