提要內容檔 XML 格式

3.0 版

這份文件用一系列的 DTD 片段(機器可讀的 XML 綱目)來說明提要內容檔的結構。

cheatsheet

<!ELEMENT cheatsheet (intro, item+)> 
<!ATTLIST cheatsheet 
  title               CDATA #REQUIRED
>

<cheatsheet> 元素定義提要內容檔的主體。 <cheatsheet> 的屬性如下:

intro

<!ELEMENT intro (description)>
<!ATTLIST intro 
  contextId           CDATA #IMPLIED 
  href                CDATA #IMPLIED 
>

<intro> 元素用來說明要顯示的提要簡介。 <description> 子元素包含簡介的主體。 <intro> 的屬性如下:

description

<!ELEMENT description EMPTY>
<!ATTLIST description 
>

<description> 元素用來保留提要或提要項目的說明。 說明由簡單的格式化標示所解譯的文字組成。 提要會自動格式化和佈置文字,使它合理呈現在 UI 中。 在文字之內,對稱的 <b>...</b> 標示會使含括的文字呈現粗體,<br/> 元素可用來強迫換行。 目前只支援這些格式化標示(不過,將來可能會加入其他格式化標示)。 文字中的某些字元在 XML 剖析器中有特別意義;特別是要分別寫入 "<"、">"、"&"、"'" 和 """(雙引號),而不是寫入 "&lt;"、"&gt;"、"&amp;" 、"&apos;" 和 "&quot;"。 空白字元(空格和換行)是當作單字分隔字元來處理的;相鄰的空格和換行會當作單一單元來處理,且會呈現為單一空格和換行。 系統不處理緊接在 <description> 和 <br/> 標示之後的空白字元,在 </description> 標示之前的空白字元會保留原狀。

item

<!ELEMENT item (description ([action|perform-when] | (subitem|repeated-subitem|conditional-subitem)*))> 
<!ATTLIST item 
  title               CDATA #REQUIRED
  skip                ("true" | "false") "false"
  contextId           CDATA #IMPLIED 
  href                CDATA #IMPLIED
>

每個 <item> 元素都會說明提要中的一個最上層步驟。 <item> 可能是簡單或複合的。 <item> 的屬性如下:

org.eclipse.ui.cheatsheets.cheatSheetItemExtension 可讓項目的其他自訂控制項顯示在 UI 中。 這個延伸點的構成要素會宣告可能出現在 <item> 元素的其他字串值屬性的名稱。

簡單項目有一個說明和一個選用的動作。 在一般呈現中,使用者多半能夠見到提要項目的標題。 只有當步驟是在執行程序中,才會顯示項目的說明。 <action>(或 <perform-when>)元素的存在通常會與使用者能夠按一下來執行步驟動作的按鈕相關聯。 如果動作不存在,這個步驟就是使用者必須手動執行,再明確表示他們已順利完成的步驟。

複合步驟會依照 <subitem> 子元素所指定而分解成子步驟。 使用者必須遵循嚴格的項目順序,但給定項目的子項目可以依照任何次序來執行。 項目內的所有子項目都必須嘗試(或跳過),之後,才能進入下一個項目。 (這表示必須依順序執行的動作不能用子項目來表示。)

<conditional-subitem> 子元素可讓步驟依先前的步驟已取得值的提要變數來調整子步驟的呈現。 <repeated-subitem> 子元素可讓步驟併入一組類似的子步驟。 同樣地,確切的一組子步驟也可以是基於已在先前的步驟中取得值的提要變數。

subitem

<!ELEMENT subitem ( [action|perform-when] )> 
<!ATTLIST subitem 
  label               CDATA #REQUIRED
  skip                ("true" | "false") "false"
  when                CDATA #IMPLIED
>

每個 <subitem> 元素都會說明提要中的一個子步驟。 <subitem> 會帶著一個簡單的文字標籤,但沒有較長的說明也沒有進一步的子項目。 <subitem> 的屬性如下:

子項目有一個選用的動作。 <action>(或 <perform-when>)元素的存在通常會關聯於使用者能夠按一下來執子步驟動作的按鈕。 如果動作不存在,這個子步驟就是使用者必須手動執行,再明確表示他們已順利完成的步驟。

項目必須遵循嚴格的順序,但給定項目的子項目可以依照任何次序來執行。 項目內的所有子項目都必須嘗試(或跳過),之後,才能進入下一個項目。 (這表示必須依順序執行的動作不能用子項目來表示。)

conditional-subitem

<!ELEMENT conditional-subitem (subitem+)> 
<!ATTLIST conditional-subitem 
  condition               CDATA #REQUIRED
>

各個 <conditional-subitem> 元素用來說明形式可能會隨著項目展開時之已知條件而不同的單一子步驟。 <conditional-subitem> 的屬性如下:

<conditional-subitem> 元素的 condition 屬性用來提供字串值(這個值一定來自提要變數)。 每個 <subitem> 子項必須帶著含有明確字串值的 when 屬性。 當項目展開時,含相符的值的 <subitem> 元素會取代 <conditional-subitem> 元素。 如果沒有含相符的值的 <subitem> 元素,就會將它視為錯誤。

比方說,如果名稱為 "v1" 的提要變數有 "b" 值,當展開下列項目時

<item ...> 
  <conditional-subitem condition="${v1}">
     <subitem when="a" label="Step for A." />
     <subitem when="b" label="Step for B." />
     </conditional-subitem>
</item>
就會選取第二個子項目,且項目會展開成相當於下列內容
<item ...> 
  <subitem label="Step for B."/>
</item>

repeated-subitem

<!ELEMENT repeated-subitem (subitem)> 
<!ATTLIST repeated-subitem 
  values               CDATA #REQUIRED
>

各個 <repeated-subitem> 元素用來說明展開成 0、1 或更多個類似子步驟的子項目。 <repeated-subitem> 的屬性如下:

values 屬性提供逗號分隔的字串清單;<subitem> 子項提供範本。 當項目展開時,含有對應的字串值所取代的 "this" 變數之 <subitem> 元素的副本會取代 <repeated-subitem> 元素。

比方說,如果名稱為 "v1" 的提要變數有 "1,b,three" 值,當展開下列項目時

<item ...> 
  <repeated-subitem values="${v1}">
     <subitem label="Step ${this}.">
        <action class="com.xyz.myaction" pluginId="com.xyz" param1="${this}"/>
  </subitem>
  </repeated-subitem>
</item>
項目會展開成相當於下列內容:
<item ...> 
  <subitem label="Step 1.">
     <action class="com.xyz.myaction" pluginId="com.xyz" param1="1"/>
  </subitem>
  <subitem label="Step b.">
     <action class="com.xyz.myaction" pluginId="com.xyz" param1="b"/>
  </subitem>
  <subitem label="Step three.">
     <action class="com.xyz.myaction" pluginId="com.xyz" param1="three"/>
  </subitem>
</item>

action

<!ELEMENT action EMPTY> 
<!ATTLIST action 
  class               CDATA #REQUIRED
  pluginId            CDATA #REQUIRED
  param1              CDATA #IMPLIED
  ...
  param9              CDATA #IMPLIED
  confirm             ("true" | "false") "false"
  when                CDATA #IMPLIED
>

每個 <action> 元素都會說明提要中的一個動作。 <action> 的屬性如下:

perform-when

<!ELEMENT perform-when (action+)> 
<!ATTLIST perform-when 
  condition               CDATA #REQUIRED
>

每個 <perform-when> 元素都會說明提要中的一個動作。 <perform-when> 的屬性如下:

<conditional-subitem> 元素的 condition 屬性用來提供字串值(這個值一定來自提要變數)。 每個 <subitem> 子項必須帶著含有明確字串值的 when 屬性。 當項目展開時,含相符的值的 <subitem> 元素會取代 <conditional-subitem> 元素。 如果沒有含相符的值的 <subitem> 元素,就會將它視為錯誤。

比方說,如果名稱為 "v1" 的提要變數有 "b" 值,當展開下列項目時

<item ...>
  <subitem label="Main step">
     <perform-when condition="${v1}">
        <action when="a" class="com.xyz.action1" pluginId="com.xyz" />
        <action when="b" class="com.xyz.action2" pluginId="com.xyz" />
     </conditional-subitem>
  </subitem>
</item>
就會選取第二個動作,且項目會展開成相當於下列內容
<item ...> 
  <subitem label="Main step">
     <action class="com.xyz.action2" pluginId="com.xyz" />
  </subitem>
</item>

範例

以下是非常簡單的提要內容檔的範例:

<?xml version="1.0" encoding="UTF-8"?>
<cheatsheet title="Example">
  <intro>
    <description>Example cheat sheet with two steps.</description>
</intro>
  <item title="Step 1">
     <description>This is a step with an action.</description>
     <action class="com.xyz.myaction" pluginId="com.xyz"/>
</item>
  <item title="Step 2">
     <description>This is a fully manual step.</description>
</item>
</cheatsheet>