| Writing Documentation Using DocBook: A Crash Course | ||
|---|---|---|
| Prev | Chapter 10. Describing the Application's Interface | Next |
| 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:
Creates a new document
Saves the document
Quits Kapp