虎の巻コンテンツ・ファイル 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;」を使用します。 空白文字 (スペースおよび改行) は語のセパレーターとして扱われます。 また、隣接するスペースおよび改行は、単一ユニットとして扱われ、1 つのスペースまたは 1 つの改行として表現されます。 <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> エレメントは、虎の巻内の 1 つのトップレベル・ステップを記述します。 <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 属性を持っている必要があります。 項目が展開されると、<conditional-subitem> エレメントは、 一致する値を持つ <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>
このとき、2 番目のサブ項目が選択され、項目は以下と同等のものに展開されます。
<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> の子はテンプレートを提供します。 項目が展開されると、<repeated-subitem> エレメントは、対応するストリング値によって 置換される変数 "this" を持つ <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 属性を持っている必要があります。 項目が展開されると、<conditional-subitem> エレメントは、 一致する値を持つ <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>
このとき、2 番目のアクションが選択され、項目は以下と同等のものに展開されます。
<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>