Draft

1.2 (2019-02-09)

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
© 2008-2011 Shaun McCance
cc-by-sa 3.0 (us)

This work is licensed under a Creative Commons Attribution-Share Alike 3.0 United States License.

As a special exception, the copyright holders give you permission to copy, modify, and distribute the example code contained in this document under the terms of your choosing, without restriction.

Powered by
Mallard