每個提供說明檔的外掛程式通常都應該執行下列動作:
選擇性地,可以使用 index
元素預先建置並登錄搜尋索引,以執行第一次搜尋嘗試。每一個外掛程式只能登錄一個索引 - 多個 index
元素會導致未定義的行為。
<!ELEMENT extension (toc* , index?)>
<!ATTLIST extension
point CDATA #REQUIRED
id CDATA #IMPLIED
name CDATA #IMPLIED>
<!ELEMENT toc EMPTY>
<!ATTLIST toc
file CDATA #REQUIRED
primary (true | false) "false"
extradir CDATA #IMPLIED>
toc 檔的配置標記:
<!ELEMENT toc (topic | anchor | link)*
>
<!ATTLIST toc link_to CDATA #IMPLIED >
<!ATTLIST toc label CDATA #REQUIRED >
<!ATTLIST toc topic CDATA #IMPLIED >
<!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 元素是用來將主題分組以及在這個檔案中定義的其他元素的「目錄」。 當對使用者顯示目錄時,系統會使用標籤來向使用者識別目錄。 選用的 topic 屬性就是說明 TOC 之主題檔案的路徑。 選用的 link_to 屬性容許將這個檔案中的 toc 鏈結至另一個位於導覽階層更高位置的 toc 檔。 link_to 屬性鏈結值必須在另一個 toc 檔中指定錨點。 如果要將 myapi.xml 中的 toc 鏈結至在另一個外掛程式中指定的 api.xml 檔,請使用下列語法
<toc link_to="../anotherPlugin/api.xml#moreapi" label="My Tool
API"/>
...
<toc />
其中 # 字元用以從錨點 ID 區隔出 toc 檔案名稱。
<!ELEMENT index EMPTY>
<!ATTLIST index
path CDATA #REQUIRED>
(自 3.1 後)容許宣告由此外掛程式提供的文件所建立的預先建置之搜尋索引之選用性元素。
index/
、nl/ja/JP/index/
、nl/en/US/index/
等等)。.(在 plugin.xml 檔中)
<extension point=
"org.eclipse.help.toc"
>
<toc file=
"maindocs.html"
primary=
"true"
/>
<toc file=
"task.xml"
/>
<toc file=
"sample.xml"
extradir=
"samples"
/>
<index path=
"index/"
/>
</extension>
(在 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>
假設更多文件存在於以 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 目錄前,說明系統將在這個目錄下尋找檔案。
Copyright (c) 2000, 2005 IBM Corporation and others.
All rights reserved.
本程式與隨附的資料依照 Elipse Public License 1.0 版此次發行所隨附的條款而提供,
可以在以下網址取得:http://www.eclipse.org/legal/epl-v10.html