StandardTerminology

Differences between revisions 11 and 12
⇤ ← Revision 11 as of 2009-07-29 09:05:16 →
Size: 12731
Editor: dyndsl-091-096-008-091
Comment: The sentence beginning 'In large dialogs with many options ...' is still somewhat contorted after changing 'and' to 'or'.
← Revision 12 as of 2010-03-24 10:26:35 → ⇥
Size: 13196
Editor: c220-237-150-52
Comment: stylistic and grammar clean-ups
Deletions are marked like this. Additions are marked like this.
Line 5: Line 5:
This section provides a list of terms which are commonly found in technical documentation. You should use the spellings of words which are set-out in this section whenever you use those words in Ubuntu documentation.

This list is not exhaustive; for terminology that is not listed here, refer to the [[http://library.gnome.org/devel/gdp-style-guide/2.20/gnome-glossary-desktop.html.en|Gnome Desktop Style Guide Term List]].		 This section provides a list of terms that are commonly found in technical documentation. You should use the spellings of words as documented in this section whenever you use those words in Ubuntu documentation.

This list is not exhaustive. For terminology that is not listed here, refer to the [[http://library.gnome.org/devel/gdp-style-guide/2.20/gnome-glossary-desktop.html.en|Gnome Desktop Style Guide Term List]].
Line 13: Line 13:
=== How to refer to Ubuntu === === How to Refer to Ubuntu ===
Line 16: Line 17:
 1. You can use Kubuntu, Kubuntu system, Kubuntu environment, and Kubuntu distribution when referring to Ubuntu with the KDE desktop, but remember that it is still the Ubuntu operating system, not the Kubuntu operating system.  1. You can use "Kubuntu", "Kubuntu system", "Kubuntu environment", and "Kubuntu distribution" when referring to Ubuntu with the KDE desktop environment. Note that it is still the Ubuntu operating system, not the Kubuntu operating system.
Line 19: Line 20:
 1. You might find that you must use the term "Ubuntu Linux". If so, then try to work in the phrase "based on Debian GNU/Linux".
 1. If you use any of these terms, (Debian, GNU/Linux, Linux, distribution, distro) you must explain them in the text following their first use, as well as in the glossary (if there is a glossary). The only exception is when the audience of the document is already knowledgeable about the terms.
 1. If there is an About Ubuntu section in your document, then describe Ubuntu and its genealogy, including GNU/Linux, Debian, and the Linux kernel.		  1. You might find that you must use the term "Ubuntu Linux". If so, consider using the phrase "based on Debian GNU/Linux".
 1. If you use any of the following terms, you must explain them in the text following their first use, as well as in the glossary (if there is a glossary).
  1. Debian
  1. GNU/Linux    1. Linux    1. distribution
  1. distro
 The only exception is when the audience of the document is already familiar about the terms.
 1. If there is an About Ubuntu section in your document, describe Ubuntu and its genealogy, including GNU/Linux, Debian, and the Linux kernel.
Line 27: Line 34:
    ''Description:'' An on/off element used for selecting and deselecting an option. Usually signified by a check mark, but sometimes by an "X"

    ''Usage:'' The phrase "check box" is seldom used in text. It is more common to use words like select, deselect, and choose, depending on the user action being described. If there is any ending punctuation (such as a period, colon, or ellipsis) on the label associated with the check box, do not use the punctuation in your text.

    ''Doc''''''Book Tags:'' Since a check box usually has a label associated with it, use the guilabel tag for the check box name.

    ''Example:'' Select the <guilabel>Case sensitive</guilabel> option.		  * '''Description:''' An on/off element used for selecting and deselecting an option. Usually signified by a check mark, but sometimes by an "X".

 * '''Usage:''' The phrase "check box" is seldom used in text. It is more common to use words such as "select", "deselect", and "choose", depending on the user action being described. If there is any ending punctuation such as a period, colon, or ellipsis on the label associated with the check box, do not use the punctuation in your text.

 * '''Doc''''''Book Tags:''' Since a check box usually has a label associated with it, use the {{{<guilabel></guilabel>}}} tags for the check box name.

 * '''Example:''' Select the <guilabel>Case sensitive</guilabel> option.
Line 36: Line 43:
NOTE: the drop-down combination box is currently being discussed on the ubuntu-doc mailing list. The below information will likely be changed.
    ''Description:'' The combo box is the combination of a text box and a drop-down list. The list is activated by clicking the arrow to the right of the text box. You can either type into the text box, or select an item from the list.

    ''Usage:'' Use "choose" to tell the user what to select rather than specifying whether to use the drop-down list or the text box, with the possible exception of documents where users might be unfamiliar with combo boxes, such as a document for those who have never used a computer before. Avoid the term "combo box", use "drop-down combination box" instead.

    ''Doc''''''Book Tags:'' Since a combo box usually has a label associated with it, use the guilabel tag for the combo box name.

    ''Example:'' Choose <userinput>Ubuntu</userinput> from the <guilabel>Operating System</guilabel> drop-down combination box.
'''NOTE:''' The drop-down combination box is currently being discussed on the ubuntu-doc mailing list. The information below will likely be changed.

 * '''Description:''' The combo box is the combination of a text box and a drop-down list. The list is activated by clicking the arrow to the right of the text box. You can either type into the text box or select an item from the list.

 * '''Usage:''' Use "choose" to tell the user what to select rather than specifying whether to use the drop-down list or the text box. A possible exception is in documents where users might be unfamiliar with combo boxes, such as a document for those who have never used a computer before. Avoid the term "combo box". Use "drop-down combination box" instead.

 * '''Doc''''''Book Tags:''' Since a combo box usually has a label associated with it, use the {{{<guilabel></guilabel>}}} tags for the combo box name.

 * '''Example:''' Choose <userinput>Ubuntu</userinput> from the <guilabel>Operating System</guilabel> drop-down combination box.
Line 47: Line 56:
    ''Description:'' The classic button. You press it to start an action.  * '''Description:''' The classic button. You press it to start an action.
Line 49: Line 58:
    ''Usage:'' Many users may be more familiar with the term "button" than "command button." Additionally, you "click on" a button rather than "press" a button.

    ''Doc''''''Book Tags:'' Use the guibutton tag for the text on the button.

    ''Example:'' Click on the <guibutton>OK</guibutton> button.		  * '''Usage:''' Many users may be more familiar with the term "button" than "command button." Additionally, you "click on" a button rather than "press" a button.

 * '''Doc''''''Book Tags:''' Use the {{{<guibutton></guibutton>}}} tags for the text on the button.

 * '''Example:''' Click on the <guibutton>OK</guibutton> button.
Line 57: Line 66:
    ''Description:'' A control is any user interface element, such as a button, tab or drop-down box.

    ''Doc''''''Book Tags:'' None.

    ''Example:'' This option affects the color of all controls.		  * '''Description:''' A control is any user interface element, such as a button, tab, or drop-down box.

 * '''Doc''''''Book Tags:''' None.

 * '''Example:''' This option affects the color of all controls.
Line 65: Line 74:
    ''Description:'' A list of possible selections. One clicks on the drop-down button to the right of the current selection to see all possible options.

    ''Doc''''''Book Tags:'' Use the guilabel tag for the label of the drop-down list.

    ''Example:'' Use the <guilabel>size</guilabel> drop-down list to specify the size of your image.		  * '''Description:''' A list of possible selections. You click on the drop-down button to the right of the current selection to see all possible options.

 * '''Doc''''''Book Tags:''' Use the {{{<guilabel></guilabel>}}} tags for the label of the drop-down list.

 * '''Example:''' Use the <guilabel>size</guilabel> drop-down list to specify the size of your image.
Line 73: Line 82:
    ''Description:'' A dialog element that, when you click on the associated text, displays more dialog elements.

    ''Doc''''''Book Tags:'' Use the guilabel tag for the text associated with this element.

    ''Example:'' Select the filetype from the <guilabel>filetype</guilabel> drop-down list or click on the <guilabel>Filetypes by extension</guilabel> to select a filetype based on its file extension.		  * '''Description:''' A dialog element that, when you click on the associated text, displays more dialog elements.

 * '''Doc''''''Book Tags:''' Use the {{{<guilabel></guilabel>}}} tags for the text associated with this element.

 * '''Example:''' Select the filetype from the <guilabel>filetype</guilabel> drop-down list or click on the <guilabel>Filetypes by extension</guilabel> to select a filetype based on its file extension.
Line 81: Line 90:
    ''Description:'' A button with an ellipsis (...) on it, usually used to select a file.

    ''Doc''''''Book Tags:'' Use <guibutton>...</guibutton>.

    ''Example:'' Type the path to the file in the <guilabel>Icon</guilabel> text box, or click the <guibutton>...</guibutton> button to find a file.		  * '''Description:''' A button with an ellipsis ("...") on it, usually used to select a file.

 * '''Doc''''''Book Tags:''' Use the {{{<guibutton>...</guibutton>}}} tags for the text associated with this element.

 * '''Example:''' Type the path to the file in the <guilabel>Icon</guilabel> text box or click the <guibutton>...</guibutton> button to find a file.
Line 89: Line 98:
    ''Description:'' A box that groups elements of a dialog together. Often used in configuration dialogs.

    ''Usage:'' In large dialogs with many options, or if the user might not know where to find an option, specify which group the option is in if the dialog is broken up into groups. Avoid "group box," simply use "group" instead.		  * '''Description:''' A box that groups elements of a dialog together. Often used in configuration dialogs.

 * '''Usage:''' In large dialogs with many options. If the user might not know where to find an option, specify which group the option is in if the dialog is broken up into groups. Avoid "group box" and instead use "group."
Line 93: Line 102:
    ''Doc''''''Book Tags:'' Use the guilabel tag for the label of the group box.

    ''Example:'' Choose "emacs" from the <guilabel>external text editor</guilabel> drop-down box in the <guilabel>text editing</guilabel> group.		  * '''Doc''''''Book Tags:''' Use the {{{<guilabel></guilabel>}}} tags for the label of the group box.

 * '''Example:''' Choose "emacs" from the <guilabel>external text editor</guilabel> drop-down box in the <guilabel>text editing</guilabel> group.
Line 99: Line 108:
    ''Description:'' A GUI element that executes a command or starts a command when clicked. In the GNOME and KDE desktops, launchers appear as icons on the desktop and panels. They also appear as menu items on may menus, including the main menus.

    ''Doc''''''Book Tags:'' None.

    ''Example:'' To add this launcher, click on the <guibutton>Add</guibutton> button.		  * '''Description:''' A GUI element that executes a command or starts a command when clicked. In the GNOME and KDE desktops, launchers appear as icons on the desktop and panels. They also appear as menu items on menus, including the main menus.

 * '''Doc''''''Book Tags:''' None.

 * '''Example:''' To add this launcher, click on the <guibutton>Add</guibutton> button.
Line 107: Line 116:
    ''Description:'' A multi-line text box with static content from which a user can select one or more of several items. The selected item(s) are highlighted. A user can select multiple items with the shift key.

    ''Usage:'' Ask a user to select an item, not highlight an item.

    ''Doc''''''Book Tags:'' Use the guilabel tag for the name of the list box.

    ''Example:'' Select your screen resolution from the <guilabel>resolution</guilabel>		  * '''Description:''' A multi-line text box with static content from which a user can select one or more of several items. The selected item(s) are highlighted. A user can select multiple items with the Shift key.

 * '''Usage:''' Ask a user to select an item, not highlight an item.

 * '''Doc''''''Book Tags:''' Use the {{{<guilabel></guilabel>}}} tags for the name of the list box.

 * '''Example:''' Select your screen resolution from the <guilabel>resolution</guilabel>.
Line 117: Line 126:
    ''Description:'' The bar at the top of an application that has several menus with various commands.

    ''Usage:'' Use "menubar" (one word) rather than "menu bar".

    ''Doc''''''Book Tags:'' Use no tags for a menubar, but use the guimenu tag for the name of a menu.

    ''Example:'' Select <guimenuitem>Save As</guimenuitem> from the <guimenu>File</guimenu> menu of the menubar.		  * '''Description:''' The bar at the top of an application that has several menus with various commands.

 * '''Usage:''' Use "menubar" (one word) rather than "menu bar."

 * '''Doc''''''Book Tags:''' Use no tags for a menubar, but use the {{{<guimenu></guimenu>}}} tags for the name of a menu.

 * '''Example:''' Select <guimenuitem>Save As</guimenuitem> from the <guimenu>File</guimenu> menu of the menubar.
Line 127: Line 136:
    ''Description:'' An item of a menu.

    ''Doc''''''Book Tags:'' Use the guimenuitem tag.

    ''Example:'' Select the <guimenuitem>About</guimenuitem> item from the <guimenu>Help</guimenu> menu.		  * '''Description:''' An item of a menu.

 * '''Doc''''''Book Tags:''' Use the {{{<guimenuitem></guimenuitem>}}} tags.

 * '''Example:''' Select the <guimenuitem>About</guimenuitem> item from the <guimenu>Help</guimenu> menu.
Line 135: Line 144:
    ''Description:'' A parameter than can be on or off, usually represented by a check box.

    ''Usage:'' You "select" an option.

    ''Doc''''''Book Tags:'' Use the guilabel tag for the name of the option.

    ''Example:'' Select the <guilabel>Open in new window</guilabel> option if you want the image to open in a new window.		  * '''Description:''' A parameter that can be on or off, usually represented by a check box.

 * '''Usage:''' You "select" an option.

 * '''Doc''''''Book Tags:''' Use the {{{<guilabel></guilabel>}}} tags for the name of the option.

 * '''Example:''' Select the <guilabel>Open in new window</guilabel> option if you want the image to open in a new window.
Line 145: Line 154:
    ''Description:'' A menu that appears when you right-click or middle-click something. Also known as a context menu.

    ''Usage:'' Use the term "popup menu", not "context menu" or "pop-up menu."

    ''Doc''''''Book Tags:'' None.

    ''Example:'' Right-click a word to display a popup menu.		  * '''Description:''' A menu that appears when you right-click or middle-click something. Also known as a context menu.

 * '''Usage:''' Use the term "popup menu", not "context menu" or "pop-up menu."

 * '''Doc''''''Book Tags:''' None.

 * '''Example:''' Right-click a word to display a popup menu.
Line 154: Line 164:
    ''Description:'' A selectable control, ususally round, that is linked to other radio buttons. Only one radio button of a connected set may be selected at a time.

    ''Doc''''''Book Tags:'' Use the guilabel tag for the label of the radio button.

    ''Example:'' Select the <guilabel>do not show</guilabel> option.		  * '''Description:''' A selectable control, usually round, that is linked to other radio buttons. Only one radio button of a connected set may be selected at a time.

 * '''Doc''''''Book Tags:''' Use the {{{<guilabel></guilabel>}}} tag for the label of the radio button.

 * '''Example:''' Select the <guilabel>do not show</guilabel> option.
Line 162: Line 172:
    ''Description:'' A bar, usually on the right side of a control, that, when dragged, scrolls through the content of the control. Widely used for controls that display a lot of content, such as a web browser, text editor or email client. Buttons are usually present at the top and bottom of the scrollbar as an alternative to draggign the scrollbar.

    ''Usage:'' Use "scrollbar," not "scroll-bar" or "scroll bar."

    ''Doc''''''Book Tags:'' None.

    ''Example:'' Use the scrollbar to scroll through available commands.		  * '''Description:''' A bar, usually on the right side of a control, that, when dragged, scrolls through the content of the control. Widely used for controls that display a lot of content, such as a web browser, text editor, or email client. Buttons are usually present at the top and bottom of the scrollbar as an alternative to dragging the scrollbar.

 * '''Usage:''' Use "scrollbar," not "scroll-bar" or "scroll bar."

 * '''Doc''''''Book Tags:''' None.

 * '''Example:''' Use the scrollbar to scroll through available commands.
Line 172: Line 182:
    ''Description:'' A bar with a icon that can be dragged to select one of a range of things, such as text size. Almost exclusively used to select a volume.

    ''Doc''''''Book Tags:'' Use the guilabel tag for the name of the scrollbar.

    ''Example:'' If you do not hear any sound, use the <guilabel>volume</guilabel> slider to specify a louder volume.		  * '''Description:''' A bar with an icon that can be dragged to select one of a range of things, such as text size. Almost exclusively used to select a volume.

 * '''Doc''''''Book Tags:''' Use the {{{<guilabel></guilabel>}}} tags for the name of the scrollbar.

 * '''Example:''' If you do not hear any sound, use the <guilabel>volume</guilabel> slider to specify a louder volume.
Line 180: Line 190:
    ''Description:'' A text box with arrow button on the right side that can be used to select one of a range of options. The user may type into the spin box, or use the arrow buttons to scroll through available options. Often used for numeric inputs.

    ''Doc''''''Book Tags:'' Use the guilabel tag for the name of the spinbox.

    ''Example:'' Use the <guilabel>font size</guilabel> spin box to specify the font size.		  * '''Description:''' A text box with arrow buttons on the right side that can be used to select one of a range of options. The user may type into the spin box or use the arrow buttons to scroll through available options. Often used for numeric inputs.

 * '''Doc''''''Book Tags:''' Use the {{{<guilabel></guilabel>}}} tags for the name of the spin box.

 * '''Example:''' Use the <guilabel>font size</guilabel> spin box to specify the font size.
Line 188: Line 198:
    ''Description:'' description text here.

    ''Doc''''''Book Tags:'' the docbook tag to use for this item

    ''Example:'' an example of the term in use		  * '''Description:''' description text here.

 * '''Doc''''''Book Tags:''' the docbook tag to use for this item

 * '''Example:''' an example of the term in use
Line 196: Line 206:
    ''Description:'' description text here.

    ''Doc''''''Book Tags:'' the docbook tag to use for this item

    ''Example:'' an example of the term in use		  * '''Description:''' description text here.

 * '''Doc''''''Book Tags:''' the docbook tag to use for this item

 * '''Example:''' an example of the term in use
Line 204: Line 214:
    ''Description:'' description text here.

    ''Doc''''''Book Tags:'' the docbook tag to use for this item

    ''Example:'' an example of the term in use		  * '''Description:''' description text here.

 * '''Doc''''''Book Tags:''' the docbook tag to use for this item

 * '''Example:''' an example of the term in use
Line 212: Line 222:
    ''Description:'' description text here.

    ''Doc''''''Book Tags:'' the docbook tag to use for this item

    ''Example:'' an example of the term in use		  * '''Description:''' description text here.

 * '''Doc''''''Book Tags:''' the docbook tag to use for this item

 * '''Example:''' an example of the term in use
Line 220: Line 230:
    ''Description:'' description text here.

    ''Doc''''''Book Tags:'' the docbook tag to use for this item

    ''Example:'' an example of the term in use		  * '''Description:''' description text here.

 * '''Doc''''''Book Tags:''' the docbook tag to use for this item

 * '''Example:''' an example of the term in use
Line 228: Line 238:
    ''Description:'' description text here.

    ''Doc''''''Book Tags:'' the docbook tag to use for this item

    ''Example:'' an example of the term in use		  * '''Description:''' description text here.

 * '''Doc''''''Book Tags:''' the docbook tag to use for this item

 * '''Example:''' an example of the term in use
Line 236: Line 246:
    ''Description:'' description text here.

    ''Doc''''''Book Tags:'' the docbook tag to use for this item

    ''Example:'' an example of the term in use		  * '''Description:''' description text here.

 * '''Doc''''''Book Tags:''' the docbook tag to use for this item

 * '''Example:''' an example of the term in use
Line 244: Line 254:
    ''Description:'' description text here.

    ''Doc''''''Book Tags:'' the docbook tag to use for this item

    ''Example:'' an example of the term in use		  * '''Description:''' description text here.

 * '''Doc''''''Book Tags:''' the docbook tag to use for this item

 * '''Example:''' an example of the term in use
Line 252: Line 262:
    ''Description:'' description text here.

    ''Doc''''''Book Tags:'' the docbook tag to use for this item

    ''Example:'' an example of the term in use		  * '''Description:''' description text here.

 * '''Doc''''''Book Tags:''' the docbook tag to use for this item

 * '''Example:''' an example of the term in use
Line 260: Line 270:
    ''Description:'' description text here.

    ''Doc''''''Book Tags:'' the docbook tag to use for this item

    ''Example:'' an example of the term in use		  * '''Description:''' description text here.

 * '''Doc''''''Book Tags:''' the docbook tag to use for this item

 * '''Example:''' an example of the term in use
Line 268: Line 278:
    ''Description:'' description text here.

    ''Doc''''''Book Tags:'' the docbook tag to use for this item

    ''Example:'' an example of the term in use		  * '''Description:''' description text here.

 * '''Doc''''''Book Tags:''' the docbook tag to use for this item

 * '''Example:''' an example of the term in use
Line 276: Line 286:
=== Select vs highlight vs choose ===

Select an item from a list, choose an item from a menu. To choose an menu item, click on it.

Do not use highlight as a verb; use as a noun or adjective. The selected text is highlighted.		 === Select vs Highlight vs Choose ===

Select an item from a list. Choose an item from a menu. To choose a menu item, click on it.

Do not use "highlight" as a verb. Use it as a noun or adjective. The selected text is highlighted.
Line 283: Line 293:
Line 286: Line 297:

This section provides a list of terms that are commonly found in technical documentation. You should use the spellings of words as documented in this section whenever you use those words in Ubuntu documentation.

This list is not exhaustive. For terminology that is not listed here, refer to the Gnome Desktop Style Guide Term List.

Contents

  1. General
  2. GUI Terms
  3. User Actions

General

How to Refer to Ubuntu

  1. Use "Ubuntu operating system" the first time you refer to Ubuntu, then use "Ubuntu" thereafter. You can use the terms "Ubuntu system" and "Ubuntu environment" when they are more appropriate than "Ubuntu operating system."
  2. You can use "Ubuntu Linux distribution" or "Ubuntu Linux distro," but try to reserve those terms for audiences who do not need to have "distribution" or "distro" explained to them.
  3. You can use "Kubuntu", "Kubuntu system", "Kubuntu environment", and "Kubuntu distribution" when referring to Ubuntu with the KDE desktop environment. Note that it is still the Ubuntu operating system, not the Kubuntu operating system.
  4. Use "based on Debian GNU/Linux" when referring to Ubuntu's Debian roots.
  5. Use "Linux-based" when referring to Ubuntu's kernel roots.
  6. You might find that you must use the term "Ubuntu Linux". If so, consider using the phrase "based on Debian GNU/Linux".
  7. If you use any of the following terms, you must explain them in the text following their first use, as well as in the glossary (if there is a glossary).
    1. Debian
    2. GNU/Linux
    3. Linux
    4. distribution
    5. distro
    The only exception is when the audience of the document is already familiar about the terms.
  8. If there is an About Ubuntu section in your document, describe Ubuntu and its genealogy, including GNU/Linux, Debian, and the Linux kernel.

GUI Terms

check box

  • Description: An on/off element used for selecting and deselecting an option. Usually signified by a check mark, but sometimes by an "X".

  • Usage: The phrase "check box" is seldom used in text. It is more common to use words such as "select", "deselect", and "choose", depending on the user action being described. If there is any ending punctuation such as a period, colon, or ellipsis on the label associated with the check box, do not use the punctuation in your text.

  • DocBook Tags: Since a check box usually has a label associated with it, use the <guilabel></guilabel> tags for the check box name.

  • Example: Select the <guilabel>Case sensitive</guilabel> option.

NOTE: The drop-down combination box is currently being discussed on the ubuntu-doc mailing list. The information below will likely be changed.

  • Description: The combo box is the combination of a text box and a drop-down list. The list is activated by clicking the arrow to the right of the text box. You can either type into the text box or select an item from the list.

  • Usage: Use "choose" to tell the user what to select rather than specifying whether to use the drop-down list or the text box. A possible exception is in documents where users might be unfamiliar with combo boxes, such as a document for those who have never used a computer before. Avoid the term "combo box". Use "drop-down combination box" instead.

  • DocBook Tags: Since a combo box usually has a label associated with it, use the <guilabel></guilabel> tags for the combo box name.

  • Example: Choose <userinput>Ubuntu</userinput> from the <guilabel>Operating System</guilabel> drop-down combination box.

command button

  • Description: The classic button. You press it to start an action.

  • Usage: Many users may be more familiar with the term "button" than "command button." Additionally, you "click on" a button rather than "press" a button.

  • DocBook Tags: Use the <guibutton></guibutton> tags for the text on the button.

  • Example: Click on the <guibutton>OK</guibutton> button.

control

  • Description: A control is any user interface element, such as a button, tab, or drop-down box.

  • DocBook Tags: None.

  • Example: This option affects the color of all controls.

  • Description: A list of possible selections. You click on the drop-down button to the right of the current selection to see all possible options.

  • DocBook Tags: Use the <guilabel></guilabel> tags for the label of the drop-down list.

  • Example: Use the <guilabel>size</guilabel> drop-down list to specify the size of your image.

  • Description: A dialog element that, when you click on the associated text, displays more dialog elements.

  • DocBook Tags: Use the <guilabel></guilabel> tags for the text associated with this element.

  • Example: Select the filetype from the <guilabel>filetype</guilabel> drop-down list or click on the <guilabel>Filetypes by extension</guilabel> to select a filetype based on its file extension.

ellipsis button

  • Description: A button with an ellipsis ("...") on it, usually used to select a file.

  • DocBook Tags: Use the <guibutton>...</guibutton> tags for the text associated with this element.

  • Example: Type the path to the file in the <guilabel>Icon</guilabel> text box or click the <guibutton>...</guibutton> button to find a file.

group box

  • Description: A box that groups elements of a dialog together. Often used in configuration dialogs.

  • Usage: In large dialogs with many options. If the user might not know where to find an option, specify which group the option is in if the dialog is broken up into groups. Avoid "group box" and instead use "group."

  • DocBook Tags: Use the <guilabel></guilabel> tags for the label of the group box.

  • Example: Choose "emacs" from the <guilabel>external text editor</guilabel> drop-down box in the <guilabel>text editing</guilabel> group.

launcher

  • Description: A GUI element that executes a command or starts a command when clicked. In the GNOME and KDE desktops, launchers appear as icons on the desktop and panels. They also appear as menu items on menus, including the main menus.

  • DocBook Tags: None.

  • Example: To add this launcher, click on the <guibutton>Add</guibutton> button.

list box

  • Description: A multi-line text box with static content from which a user can select one or more of several items. The selected item(s) are highlighted. A user can select multiple items with the Shift key.

  • Usage: Ask a user to select an item, not highlight an item.

  • DocBook Tags: Use the <guilabel></guilabel> tags for the name of the list box.

  • Example: Select your screen resolution from the <guilabel>resolution</guilabel>.

  • Description: The bar at the top of an application that has several menus with various commands.

  • Usage: Use "menubar" (one word) rather than "menu bar."

  • DocBook Tags: Use no tags for a menubar, but use the <guimenu></guimenu> tags for the name of a menu.

  • Example: Select <guimenuitem>Save As</guimenuitem> from the <guimenu>File</guimenu> menu of the menubar.

  • Description: An item of a menu.

  • DocBook Tags: Use the <guimenuitem></guimenuitem> tags.

  • Example: Select the <guimenuitem>About</guimenuitem> item from the <guimenu>Help</guimenu> menu.

option

  • Description: A parameter that can be on or off, usually represented by a check box.

  • Usage: You "select" an option.

  • DocBook Tags: Use the <guilabel></guilabel> tags for the name of the option.

  • Example: Select the <guilabel>Open in new window</guilabel> option if you want the image to open in a new window.

  • Description: A menu that appears when you right-click or middle-click something. Also known as a context menu.

  • Usage: Use the term "popup menu", not "context menu" or "pop-up menu."

  • DocBook Tags: None.

  • Example: Right-click a word to display a popup menu.

radio button

  • Description: A selectable control, usually round, that is linked to other radio buttons. Only one radio button of a connected set may be selected at a time.

  • DocBook Tags: Use the <guilabel></guilabel> tag for the label of the radio button.

  • Example: Select the <guilabel>do not show</guilabel> option.

scrollbar

  • Description: A bar, usually on the right side of a control, that, when dragged, scrolls through the content of the control. Widely used for controls that display a lot of content, such as a web browser, text editor, or email client. Buttons are usually present at the top and bottom of the scrollbar as an alternative to dragging the scrollbar.

  • Usage: Use "scrollbar," not "scroll-bar" or "scroll bar."

  • DocBook Tags: None.

  • Example: Use the scrollbar to scroll through available commands.

slider

  • Description: A bar with an icon that can be dragged to select one of a range of things, such as text size. Almost exclusively used to select a volume.

  • DocBook Tags: Use the <guilabel></guilabel> tags for the name of the scrollbar.

  • Example: If you do not hear any sound, use the <guilabel>volume</guilabel> slider to specify a louder volume.

spin box

  • Description: A text box with arrow buttons on the right side that can be used to select one of a range of options. The user may type into the spin box or use the arrow buttons to scroll through available options. Often used for numeric inputs.

  • DocBook Tags: Use the <guilabel></guilabel> tags for the name of the spin box.

  • Example: Use the <guilabel>font size</guilabel> spin box to specify the font size.

statusbar

  • Description: description text here.

  • DocBook Tags: the docbook tag to use for this item

  • Example: an example of the term in use

  • Description: description text here.

  • DocBook Tags: the docbook tag to use for this item

  • Example: an example of the term in use

tab

  • Description: description text here.

  • DocBook Tags: the docbook tag to use for this item

  • Example: an example of the term in use

tabbed section

  • Description: description text here.

  • DocBook Tags: the docbook tag to use for this item

  • Example: an example of the term in use

terminal

  • Description: description text here.

  • DocBook Tags: the docbook tag to use for this item

  • Example: an example of the term in use

text box

  • Description: description text here.

  • DocBook Tags: the docbook tag to use for this item

  • Example: an example of the term in use

titlebar

  • Description: description text here.

  • DocBook Tags: the docbook tag to use for this item

  • Example: an example of the term in use

toolbar button

  • Description: description text here.

  • DocBook Tags: the docbook tag to use for this item

  • Example: an example of the term in use

username

  • Description: description text here.

  • DocBook Tags: the docbook tag to use for this item

  • Example: an example of the term in use

wallpaper

  • Description: description text here.

  • DocBook Tags: the docbook tag to use for this item

  • Example: an example of the term in use

workspace

  • Description: description text here.

  • DocBook Tags: the docbook tag to use for this item

  • Example: an example of the term in use

User Actions

Select vs Highlight vs Choose

Select an item from a list. Choose an item from a menu. To choose a menu item, click on it.

Do not use "highlight" as a verb. Use it as a noun or adjective. The selected text is highlighted.

Deselect vs Unselect

Deselect an option. An option that is not selected is unselected.

Back Up vs Backup

Back up a file. A file that can be used to restore a lost file is a backup.

CategoryDocteam

DocumentationTeam/StyleGuide/StandardTerminology (last edited 2010-03-24 10:26:35 by c220-237-150-52)