附註:說明系統仍在開發中,應該還需要有些更動,才能夠進入穩定狀態。 在這個階段將它提供出來是為了取得先期使用者的意見,但使用者必須瞭解,提供機制的細節可能會有截然不同的更動。 |
說明:用來登錄個別外掛程式的線上說明構成要素。
每個提供說明檔的外掛程式通常都應該執行下列動作:
<!ELEMENT topics EMPTY>
<!ATTLIST topics name CDATA #REQUIRED>
<!ELEMENT topics (topic)* ) >
<!ATTLIST topics id ID #REQUIRED >
<!ELEMENT topic (topic)* >
<!ATTLIST topic id ID #IMPLIED >
<!ATTLIST topic label CDATA #REQUIRED >
<!ATTLIST topic href CDATA #IMPLIED
>
infoset 的配置標記(這是放在 infoset 處理檔的項目):
<!ELEMENT infoset (infoview)* >
<!ATTLIST infoset id ID
#REQUIRED >
<!ATTLIST infoset label CDATA
#REQUIRED >
<!ATTLIST infoset href CDATA
#IMPLIED >
<!ATTLIST infoset standalone
(false|true) false #IMPLIED >
<!ELEMENT infoview EMPTY>
<!ATTLIST infoview id ID #REQUIRED >
<!ATTLIST infoview label CDATA #IMPLIED >
insert actions 的配置標記(這是放在插入動作處理檔的項目):
<!ELEMENT actions (insert)* >
<!ATTLIST actions infoview CDATA #REQUIRED
>
<!ATTLIST actions standalone (true | false)
false #IMPLIED >
<!ELEMENT insert (insert) >
<!ATTLIST insert from CDATA #REQUIRED >
<!ATTLIST insert to CDATA #REQUIRED >
<!ATTLIST insert as (child
| first-child | last-child | prev-sib | next-sib) "child" >
<!ATTLIST insert label CDATA #IMPLIED >
一般來說,需要提供線上說明的外掛程式通常會定義它自己的主題處理及將主題佈線到正確位置所需要的動作處理。 最後,說明系統會配置成當作某些動作來啟動,且可以利用資訊集的 ID 來執行這些動作。
外掛程式所能使用的 XML 元素有四個類型:主題、資訊集、動作及插入等元素。
主題元素
關於主題元素,所有主題都會作為主題儲存器元素的一部份來提供。 它們可以採用階層式結構,也可以列成單純的清單。 主題處理可視為資料來源,可供進一步將主題交錯和組織到含不同檢視畫面視景的整合 Web 中。 另外,主題也可以藉由指定其 ID 來加以處理,但您也可以指定包含主題群組的主題或主題元素之 ID 來處理一群主題。 稍後,在要檢視的主題或其它主題在佈線時,會維護主題處理中所定義的結構(遵循插入動作所進行的改變)。
主題元素是導覽結構的基礎。 主題元素有三個典型用法:
1. 避免提供文件檔的鏈結 - 通常是 HTML 檔。
2. 在相同或不同的處理中,作為其它主題的儲存器。
3. 在相同或不同的處理中,提供其它主題的插入點。
1. 作為鏈結的 topic
topic 最簡單的用法是作為文件檔的鏈結。
<topic label="Some concept file" href="concepts/some_file.html" />
href 屬性相對於處理檔所屬的外掛程式。如果您需要存取另一外掛程式中的檔案,您可以利用這個語法
<topic label="topic in another plug-in" href="/other.plugin.id/concepts/some_other_file.html" />
2. 作為儲存器的 topic
topic 第二常用的用途是作為其它主題的儲存器。儲存器主題本身也永遠可以指向特定檔案。
<topic label="Integrated Development Environment" href="concepts/ciover.htm"
>
<topic label="Starting the IDE" href="concepts/blah.htm"
/>
...
</topic>
3. 作為插入點的 topic
topic 可以作為插入點來使用。它們會提供一個邏輯位置,供其它 topic 來嘗試及合併。如果要作為插入點,topic 必須有 id 屬性。
infoset 元素
資訊集元素是文件 Web 的進入點。它可算是檢視畫面的集成。
檢視畫面用來進行文件 Web 的高層次語意分組。它們是用資訊集所定義的 infoview 元素來定義的。 文件團隊可以利用檢視畫面來產生入門、作業和參照區段(或產品團隊所定義的其它檢視畫面)。 平台不會指定實際的區段,只會指定定義它們的機制。
比方說,可能會有一個定義的「作業檢視畫面」是「如何執行某些動作」視景中的所有主題的合併。 另外還可以定義一個「元件檢視畫面」來作為顯示所有元件及其文件的主題樹。
infoview 元素代表可跨越不同外掛程式來「共用」之主題的儲存器。它是整份文件的視景。 有時會有些不同的外掛程式提供到相同的邏輯文件元件。這個元素可確保在「元件檢視」期間,它們能正確合併到一致的檢視畫面中。
actions 元素
動作處理含有要在主題和檢視畫面上執行的 Scripting 動作。 目前只有一種插入動作,它用來將主題和檢視畫面一起寫到含多個檢視畫面的整合資訊 Web 中。
動作是結構化的動作(插入),因而適用於某些資訊檢視畫面。 因此,處理中的所有插入動作都會在單一資訊檢視畫面中建置主題階層。
insert 元素
元件化導覽最複雜的部份之一,就是如何以導覽的連續流程來建立整合的資訊結構。 如果要執行這個動作,我們需要有發佈插入點的機制,選取要使用哪個插入點,以及指出要在哪裡插入主題(母項、子項、之前、之後)。
插入點可以是主題或檢視畫面。主題藉由提供 ID 來指出它要成為插入點。 檢視畫面必須有 ID。只有完整的 ID 才能作為參照。 比方說,org.eclipse.help.examples.ex1 外掛程式中 <topic id="concepts" label="concepts"> 主題的完整主體 ID 是 org.eclipse.help.examples.ex1.concepts。
由於插入點通常是在其它外掛程式中,且這些外掛程式無法安裝,因此,使用者可以指定替代的插入點。 依預設,如果沒有任何選項順利完成的話,主題會停在它的元件階層之下。 "to" 屬性指定目標插入點。 "from" 屬性所指定的主題是插入的主題。以下是插入主題的可能方式,它們是利用 as 屬性來指定的:
這時會提供替代的插入點,且會在上一個無法執行時執行它。
插入元素的巢狀插入子元素提供了這些替代項。
這可以視是插入動作失敗時的「後退」機制,這時會執行巢狀插入動作。
滿足第一個選項插入點之後,會忽略另一個替代的插入點。
範例:
以下是使用 contributions 延伸點的範例 : 假設下列項目適用於 ID 為 "org.eclipse.help.examples.ex1" 的外掛程式。 (這個範例要作為一般範例,且應該記住,從下列中所有提供檔案產生的相同文件階層也可以利用主題和動作檔案的各種組合來建立。)
(在 plugin.xml 檔中)
<!-- 利用說明系統構成要素延伸點來定義資訊集、-->
<!-- 主題以及動作提供檔。為了清晰而使用兩次 -->
<!-- 延伸點,一次定義資訊集及其檢視畫面,另 -->
<!-- 一次定義主題及其相關動作。 -->
<extension point="org.eclipse.help.contributions">
<infoset name="infoset.xml"/>
</extension>
<extension point="org.eclipse.help.contributions">
<topics name="infosetTopics.xml"/>
<actions name="infosetActions.xml"/>
</extension>
<!-- 配置這個外掛程式的說明構成要素 -->
<!-- 這部份應該在文件外掛程式中 -->
<extension point="org.eclipse.help.contributions">
<topics name="topics.xml"/>
<actions name="topicsActions.xml"
/>
</extension>
(在 infoset.xml 檔中)
<!-- 定義 Infoset 及它所擁有的任何檢視畫面。-->
<infoset id="ex1InfosetId" label="%help_system_example">
<infoview id="topicsView" label="%topics"/>
</infoset>
(在 infosetTopics.xml 檔中)
<!-- 現在,定義保留一般主題的「儲存器」主題。如此 -->
<!-- 能夠將所有這些一般主題快速插入資訊集中的 -->
<!-- 檢視畫面之下。 -->
<topics id="topLevelTopics">
<topic id="concepts" label="%concepts"/>
<topic id="tasks" label="%tasks"/>
<topic id="references" label="%references"/>
<topic id="samples" label="%samples"/>
</topics>
定義上述一般主題所包含的主題:
(在 topics.xml 檔中)
<topics id="topics">
<topic id="aConceptId" label="%introduction" href="concepts/concept.html"/>
<topic id="aTaskId" label="%creating_a_project" href="tasks/task1.html">
<topic id="aSubTaskId1" label="%creating_a_web_project" href="tasks/task2.html"/>
<topic id="aSubTaskId2" label="%creating_a_java_project" href="tasks/task3.html"/>
</topic>
<topic id="aReferenceId" label="%interfaces" href="ref/ref1.html"/>
<topic id="aSampleId" label="%help_system_sample" href="MissingFile.html"/>
</topics>
現在,定義建立文件階層所需要的插入動作:
(在 infosetActions.xml 檔中)
<actions infoview="org.eclipse.help.examples.ex1.topicsView">(在 topicsActions.xml 檔中)
<insert from="org.eclipse.help.examples.ex1.topLevelTopics"
to="org.eclipse.help.examples.ex1.topicsView" as="child"/>
</actions>
<actions infoview="org.eclipse.help.examples.ex1.topicsView">以下是 Eclipse 工作台中所產生的文件階層:
<insert from="org.eclipse.help.examples.ex1.aConceptId"
to="org.eclipse.help.examples.ex1.concepts" as="child"/><insert from="org.eclipse.help.examples.ex1.aTaskId"
to="org.eclipse.help.examples.ex1.tasks" as="child"/><insert from="org.eclipse.help.examples.ex1.aReferenceId"
to="org.eclipse.help.examples.ex1.references" as="child"/><insert from="org.eclipse.help.examples.ex1.aSampleId"
to="org.eclipse.help.examples.ex1.samples" as="child"/>
</actions>
API 資訊: 使用這個延伸點不需要任何程式碼。
只需要提供 plugin.xml 檔中所提及的適當處理檔就行了。
提供的實作: Eclipse 平台所提供的說明系統 UI 之預設實作能充分支援 contributions 延伸點。