GUI Labels

This is a draft specification. It is likely that changes will still be made before the final specification.

Use the gui element to mark up the label of a control in a graphical user interface. You can use gui for all sorts of controls, including buttons, check boxes, and menu items. If necessary, you can use the style attribute to indicate what kind of control is being marked up.

Notes

The gui element can contain a mixture of text and any general inline elements.
The gui element can occur in any general inline context, including inside most inline elements, some basic block elements, and certain informational elements.
The gui element can also occur inside the guiseq element, where it has special meaning.
The gui element can link to other pages or documents. See Ubiquitous Linking for more information.
The style attribute takes a space-separated list of style hints. Processing tools should adjust their behavior according to those style hints they understand.

Typical style hints include:

button	The text of a button
checkbox	The label for a check box
group	The label for a group of controls
input	The label for any text entry control
menu	The name of a menu
menuitem	The name of an item in a menu
radiobutton	The label for a radio button
tab	The label on a tab

The gui element can have attributes from external namespaces. See External Namespaces for more information on external-namespace attributes.

Examples

Use gui to mark up the text of a button:

Click the <gui>Close</gui> button to close the window.

Click the Close button to close the window.

Use gui to mark up the label on a tab:

The <gui>Filters</gui> tab contains options to change the behavior
of your keyboard to meet certain accessibility needs.

The Filters tab contains options to change the behavior of your keyboard to meet certain accessibility needs.

Processing Expectations

No particular special rendering is required for gui elements. Interface labels may be rendered with lightened text or other subtle styling effects to distinguish them from the surrounding text.

In certain environments, interface labels may be decorated with an icon or other effect based on the style attribute. For example, in a table of options where the first element of each row is a gui element, those with the checkbox style hint could be decorated with a check box icon.

Comparison to Other Formats

The gui element is similar to the deprecated interface element in DocBook 4. DocBook 3 introduced more specific elements for marking up parts of a user interface: guibutton, guiicon, guilabel, guimenu, guimenuitem, and guisubmenu. Mallard does not provide specific elements. If necessary, use a style hint to indicate the type of user interface control.

The gui element is similar to the uicontrol element in DITA. DITA provides the wintitle element for marking up the title of a window. You may use the gui element for this purpose. In some cases, the app element may be more appropriate.

Schema

The formal definition of the Mallard language is maintained in RELAX NG Compact Syntax in code blocks within this specification. This is the formal definition for the gui element. The namespace declarations for this definition are on the page Pages.

mal_inline_gui = element gui {
  mal_inline_gui_attr,
  mal_inline_gui_inline
}
mal_inline_gui_attr = (
  mal_attr_link *,
  attribute style { xsd:NMTOKENS } ?,
  mal_inline_attr,
  mal_attr_external *
)
mal_inline_gui_inline = mal_inline