The Crash Course to DocBook

10.2. GUI Interface Elements

Accel - Keycap used with a meta key to activate a graphical user interface
KeyCap - Text printed on a physical key on a computer keyboard, not necessarily the same thing as a KeyCode
KeyCode - Computer's numeric designation of a key on a computer keyboard
KeyCombo - Combination of input actions
KeySym - Key symbol name, which is not necessarily the same thing as a Keycap
MenuChoice - Menu selection or series of such selections
MouseButton - Conventional name of a mouse button
Interface - Element of a graphical user interface
InterfaceDefinition - Full or short name of a formal specification of a graphical user interface
GUIButton - Text on a button in a graphical user interface
GUIIcon - Graphic and, or, text appearing as a icon in a graphical user interface
GUILabel - Text in a graphical user interface
GUIMenu - Name of a menu in a graphical user interface
GUIMenuItem - Name of a terminal menu item in a graphical user interface
GUISubmenu - Name of a submenu in a graphical user interface
Action - Function invoked in response to a user event

One could almost say that there are too many tags in DocBook for describing GUI elements. Most of the tags listed above can be used in a variety of contexts, but a few, such as <keycap>, must be used within other tags. The example and explanation below will not cover all of the tags listed above. This list is for your convenience since the DocBook Reference does not group tags by their function.

All of the GUI tags can be used within the context of a regular paragraph. So if I wanted to talk about the Trash icon or the Empty Trash button, I would just use the <guiicon> and <guibutton> tags like this: <guiicon>Trash</guiicon> icon, <guibutton>Empty Trash</guibutton> button. Note that all GUI tags may also contain inline graphics.

Below is a more complicated example of GUI tag usage.

Example 10-5. guimenu and shortcut


<variablelist>
<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo><keycap>Ctrl</keycap><keycap>n</keycap></keycombo>
</shortcut>
<guimenu>File</guimenu>
<guimenuitem>New</guimenuitem>
</menuchoice></term>
<listitem><para><action>Creates a new document</action></para></listitem>
</varlistentry>
<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo><keycap>Ctrl</keycap><keycap>s</keycap></keycombo>
</shortcut>
<guimenu>File</guimenu>
<guimenuitem>Save</guimenuitem>
</menuchoice></term>
<listitem><para><action>Saves the document</action></para></listitem>
</varlistentry>
<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo><keycap>Ctrl</keycap><keycap>q</keycap></keycombo>
</shortcut>
<guimenu>File</guimenu>
<guimenuitem>Quit</guimenuitem>
</menuchoice></term>
<listitem><para><action>Quits</action> application>Kapp</application></para></listitem>
</varlistentry>
</variablelist>
 

I hope your eyes haven't glazed over at the sight of all those tags! The most complicated part of this example is the <Shortcut> tag which labels keyboard shortcuts for menuitems. Shortcut contains either a KeyCombo or a single KeyCap that contains the key or group of keys the use would press to invoke that menuitem from the keyboard. It is important to use the KeyCombo and KeyCap tags within the Shortcut tag because it is incorrect to use character data (the Ctrl-q text for example) within a shortcut.

Other tags worth mentioning from the example are menuchoice, action, and application. menuchoice labels a menu choice and should contain the shortcut (if any) the name of the menu in GUIMenu, and the name of the menuitem in guimenuitem. Action simply labels a phrase that describes what the menuitem (or other interface element) does. application is a tag used to label the names of applications.

The example would look something like this when converted:

File->New (Ctrl-n)

Creates a new document

File->Save (Ctrl-s)

Saves the document

File->Quit (Ctrl-q)

Quits Kapp