說明及套裝上下文相關說明內容

內容相關說明是藉由建立 UI 程式碼中宣告的環境定義 ID,與線上說明中相關主題鏈結清單和說明的關聯性,來加以描述。  這些關聯會建立在 XML 檔內。 您可以建立任意數目的 XML 檔, 其中含有每一個外掛程式的環境定義說明關聯。 每一個環境定義 ID 的說明和鏈結, 會產生在 XML 檔的 <context> 元素內。 每一個環境定義元素都有一個選用的 <description> 元素, 可用來說明 UI 物件;以及任意數目的 <topic> 元素,可鏈結到線上文件。

自 3.1 以來,環境定義元素可選擇性地置換用來在「說明」視圖中,呈現環境定義說明資訊的預設標題。

<contexts>
	<context id="panic_button" title="Panic Button Title">
		<description>This is the panic button.</description>
		<topic href="tasks/pushing_the_panic_button.htm" label="Pushing the panic button"/>
		<topic href="reference/panic_button.htm" label="Panic Button Reference"/>
	</context>
	...
</contexts>

在 XML 檔案中說明環境定義時,您已備妥參照外掛程式 Manifest 中的環境定義檔案。請注意上述環境定義 ID 不完整。只要在定義環境定義 ID 的外掛程式 Manifest 中提供環境定義檔案, 這是被容許的。換句話說,環境定義 ID 被解析為提供 XML 檔案的外掛程式 ID。

外掛程式使用 org.eclipse.help.contexts 延伸點提供環境定義檔案。

   <extension point="org.eclipse.help.contexts">
      <contexts name="myContextHelp.xml"  />
   </extension>

您可以納入 plugin 屬性,從其他外掛程式參照環境定義檔。 如此可讓您將所有文件(包括內容相關說明)群組在一個外掛程式中, 再從 UI 程式碼外掛程式或某些其他的相關外掛程式中參照它。

   <extension point="org.eclipse.help.contexts">
      <contexts name="myContextHelp.xml" plugin="com.example.helpExample"  />
   </extension>

如您所見,您有許多彈性將環境定義組織成內含在一或多個外掛程式中的一或多個檔案。 主要的考量是檔案中的環境定義 ID 要正確地解析。 如果您未完整定義環境定義 ID, 您必須在宣告環境定義 ID 的外掛程式中提供環境定義 XML 檔。 如果您在環境定義 XML 檔中使用完整的環境定義 ID, 則您有完全的彈性來定義 XML 檔的位置,以及哪些外掛程式會提供環境定義。

來自多個外掛程式的上下文相關說明

另一個層次的彈性是,針對不同外掛程式中的相同環境定義 ID,提供上下文相關說明的功能。 這非常有用,比方說,如果有多組不同的文件外掛程式可能會或可能不會安裝在使用者的配置中。  如此可讓每一個文件外掛程式獨立地宣告其環境定義。 一般使用者會看到所有提供小組件 ID 之環境定義的外掛程式,所合併的上下文相關說明內容。

請注意,小組件必須使用完整的環境定義 ID,因為沒有文件外掛程式會宣告環境定義 ID。 當多個外掛程式針對同一個環境定義 ID 提供上下文相關說明時, 會先顯示宣告環境定義(UI 外掛程式)之外掛程式中所定義的內容。 其他的說明和鏈結會以隨意的順序附加。