Help markup

Help Markup

This page documents the markup used by the Rich Label widget. This is a markup language based on the Pango markup already being used by other GUI2 widgets to show formatted text, combined with features of the earlier GUI1 help markup. Specifically, you can add links, tables and images (inline and floating) alongside formatted text.

Both GUI1 style syntax (<img>src='path/to/myimage.png'</img>) and newer HTML style syntax (<img src='path/to/myimage.png'/>) are supported. The new syntax is recommended. The internal parser doesn't support nested tags when using the old syntax.

Tags

The form of a tag roughly follows HTML, with one significant exception – standalone tags with no content must have a slash before the closing angle bracket. Since the markup language is usually embedded in WML, which uses double quotes, it's recommended to use single quotes in the markup for attribute values. The quotes are optional when the value contains no spaces, however.

The old GUI1 tag style places the attributes inside the tag contents, instead of in the tag header (ie, after the > instead of before it). This format is not compatible with Pango and is thus not recommended.

Tags can be nested arbitrarily deep, as long as only the HTML-style syntax is used.

Escapes

There are two ways of escaping characters in the help markup. The simplest is to precede the character with a backslash. Whenever a backslash is encountered, it is removed, and the following character is taken as literal even if it would usually have a special meaning.

The other way is to use XML character entities. The markup supports the following character entities:

&	Ampersand (&)
"	Double quote (")
'	Apostrophe (')
&lt:	Left angle bracket (<)
&gt;	Right angle bracket (>)
&#ddd;	Unicode character given by decimal ddd
&#xhhhh;	Unicode character given by hexadecimal hhhh

Specific Tags

Formatting Tags

• bold/b: Makes the text bold.
• italic/i: Makes the text italic.
• underline/u: Adds an underline to text.
• header/h: Shows the text formatted as a heading (serif font at size 20 and color white).
• span/format: Applies various types of formatting to the marked up text. Similar to the Pango span tag, but only the following attributes are supported:
  • face/font_family
  • size/font_size
  • color/fgcolor/foreground
  • bgcolor/background
  • weight: Supported values are thin, light, normal (default), semibold, bold, heavy. Depends on selected font family.
  • style: Supported values are italic, oblique, normal (default). Depends on selected font family.

For documentation on these attributes of span/format, please see the Pango docs.

Image Tags

• img: Inserts an image, whose path is specified by the src attribute.
  • src: WML path of the image to be shown, i.e., units/drakes/armageddon.png
  • float: Whether the image is to be shown as a floating image anchored to the current line with text wrapped around it or as an inline image block between paragraphs. Inline mode is default.
  • align: Horizontal alignment of the image with respect to the page. Supported values: left (default), right or middle/center. middle/center only supports single inline images at the moment.

Note:

1. Consecutive images with no text characters in between them will be stacked horizontally for inline images and stacked vertically for floating images. middle/center alignment does not support stacking.
2. Inline image automatically generate a linebreak before them, but not after them. To insert a linebreak between an image and the following text, just start the text with a linebreak character ('\n').

Links

• ref: Insert a link. The name of the link is the value specified inside <ref> and </ref>.
  • dst: Destination of the link.

Rich Label by itself does nothing when the link is clicked. It is upto the dialog that uses the rich label to attach a link handler callback function to the rich label via the register_link_callback function. When a link is clicked, the callback function set via register_link_callback will be called with the appropriate name and dst values for the clicked link.

Table Tags

• table: Starts the table.
  • col: (mandatory) Number of columns of the table.
  • width: (optional) Width of the table (in pixels).
• jump: Go to the next column.
• br: Go to the next row.
• endtable: Closes the table.

For now these are all empty (<jump/>) tags, see the example below.

Example:

<table col=3 width=400/>
    Hello<jump/>Hello2<jump/>Hello3<br/>
    Hello<jump/>Hello2<jump/>Hello3<br/>
<endtable/>