Cheat Sheet Content File XML Format

Version 3.0

This document describes the cheat sheet content file structure as a series of DTD fragments (machine readable XML schema).

cheatsheet element

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

The <cheatsheet> element defines the body of the cheat sheet content file. <cheatsheet> attributes are as follows:

<!ELEMENT intro EMPTY> 
<!ATTLIST intro 
  href                CDATA #IMPLIED 
>

intro element

The <intro> element is used to describe the cheat sheet introduction to be displayed. The text between the <intro> and </intro> tags is the introduction. <intro> attributes are as follows:

Text formatting and line breaks

In the cheat sheet content file, you should keep all text on the same line as the <intro> or <item> tag. At execution time, the cheat sheet automatically wraps the text to make it show up correctly in UI. A line break in the text in the cheat sheet content file is interpreted as a line break in the displayed cheat sheet.

[TODO (lorne)  - Many editors do not well with arbitrary length lines. It would be better to have a more HTML-like convention where line breaks are not significant, and there embedded tags (like <br>) are used to indicate line breaks.]

item element

<!ELEMENT item (subitem*)> 
<!ATTLIST item 
  title               CDATA #REQUIRED
  kind                ("action" | "manual" | "both")
  skip                ("true" | "false") "false"
  class               CDATA #IMPLIED
  pluginId            CDATA #IMPLIED
  actionparam0        CDATA #IMPLIED
  actionparam1        CDATA #IMPLIED
  ...
  actionparam9        CDATA #IMPLIED
  href                CDATA #IMPLIED
>

Each <item> element describes one top-level item (or step) in a cheat sheet. The <item> is either simple, in which case the text between the <item> and </item> tags is displayed in the UI as the item's description, or is complex, in which case the <subitem> elements between the the <item> and </item> tags break the step down into sub-steps. <item> attributes are as follows:

The org.eclipse.ui.cheatsheets.cheatSheetItemExtension allows additional custom controls for the item to be displayed in the UI. Contributions to this extension point declare the names of additional, string-valued attributes that may appear on <item> elements.

subitem element

<!ELEMENT subitem EMPTY> 
<!ATTLIST subitem 
  label               CDATA #REQUIRED
  kind                ("action" | "manual" | "both")
  skip                ("true" | "false") "false"
  class               CDATA #IMPLIED
  pluginId            CDATA #IMPLIED
  actionparam0        CDATA #IMPLIED
  actionparam1        CDATA #IMPLIED
  ...
  actionparam9        CDATA #IMPLIED
>

Each <subitem> element describes a sub-item (or sub-step) in a cheat sheet. A <subitem> carries a simple text label, but has neither a lengthy description nor further sub-items. There should be a least 2 sub-items within the item. Each sub-item has its own action buttons.

Note that help and extension items buttons are generally presented only on items, not sub-items.

Unlike items, which must be followed in strict sequence, the sub-items of a given item can be performed in any order. All sub-items within an item have to be attempted (or skipped) before progressing to the next item. (Which means actions that must be performed in a required sequence should not be represented as sub-items.)

<subitem> attributes are as follows (the semantics of the kind, class, pluginId, and actionparamN are the same as <item>):

Example

The following is a very simple example of a cheat sheet content file:

<?xml version="1.0" encoding="UTF-8"?>
<cheatSheet title="Two-step program">
  
  <intro>Welcome to the 2-step program.</intro>

  <item title="Step 1" kind="manual">Press the button to proceed to step 2.</item>
  <item title="Step 2" kind="manual">Press the button to complete the 2-step program.</item>
</cheatSheet>