The result of a user action. This does not need to be a complete sentence, or even more than a single word. For example, “This button <action>closes the dialog</action>.” The main place you will find this in KDE Documentation is in the Menu and Command reference chapters of the manuals.
The text on a button that you click on. Icons, Radio buttons and check boxes are not considered buttons in this sense.
The text of anything that is labelled on screen, and isn't a button, icon, menu, or menu item. For example, the name of a dialog box, the name of a tab in that dialog box, and the name of a label by a checkbox.
The top level name of a menu (that is, the name you can see on the menu bar when the menu isn't open).
The final item you select on the menu, that actually performs an action.
A submenu. That is, a menu which has items both above and below it in the hierarchy.
A keycap is a key as it is labelled on your keyboard. Home is a keycap on a standard English keyboard. Alt Gr is a standard key on many European keyboards.
The internal identifier for a key on the keyboard. Used very infrequently, but you may find need for it, for example when describing entries in rc files.
Right arrow is the <keysym> for the <keycap> that looks like ->. Please note this is a KDE specific use of <keysym>, and does not precisely follow the examples in the Duck Book.
A menuchoice describes a menu entry. You should use <menuchoice> anywhere you are describing a menu item. In normal text, there are no particular requirements. In a menu reference, the <menuchoice> should also contain a <shortcut> element describing the keyboard shortcut, and the contents should also be marked up with <accel> as appropriate.
A key combination that is a shortcut for a menu item. This is only used inside <menuchoice> and contains <keycombo> or <keycap> that is defined as the keyboard shortcut in the menu. In the markup, it appears before the actual menu entries inside the <menuchoice> You do not need to describe the shortcut every time the menu item is mentioned in the text, although it may be appropriate to do so on occasion.
The normal name of a mouse button. It will be normally be one of:
Wheel is used only in specific instructions for applications that support it, of course.
Use the entities where possible, they are a lot less typing and are simple to remember (which is why we have provided them.) If you are translating, check with your team leader, as the entities above are not translated, but you may have your own language specific ones to use in their place.
A keycombo is a sequence or combination of keypresses that are performed together. A keycombo can contain <keycap>, <keysym> or <mousebutton>, or any combination of these, in any order.
It is normal to have them in the order modifier, Alpha-numeric, Mouse. That is, Ctrl-A, not A-Ctrl, unless pressing A then Ctrl actually is the shortcut.
Keycombo requires an action attribute, describing exactly how the keys (or mouse buttons) are combined. The choices are:
You will most likely need to use Seq (for a sequence of keys that are pressed one after the other), or Simul for a combination of keys that are pressed at the same time.
The accelerator key that can be used to access a GUI menu without a mouse. This is indicated in the menu by an underlined letter. For KDE documentation, use this only in the menu reference chapter, or if you are specifically referring to an accelerator key any other place in the document. It is required in the menu reference chapter. There are no attributes in use in KDE documentation.
Example 9.1. An example from a menu reference entry
<varlistentry> <term><menuchoice> <shortcut> <keycombo action="simul"><keycap>Ctrl</keycap> <keycap>C</keycap></keycombo> </shortcut> <guimenu><accel>E</accel>dit</guimenu> <guimenuitem><accel>C</accel>opy</guimenuitem> </menuchoice></term> <listitem><para><action>Copy the selected text</action> to the clipboard</para></listitem> </varlistentry> <varlistentry> <term><menuchoice> <shortcut><keycombo action="simul"><keycap>Ctrl</keycap> <keycap>V</keycap> </keycombo></shortcut> <guimenu><accel>E</accel>dit</guimenu> <guimenuitem><accel>P</accel>aste</guimenuitem> </menuchoice></term> <listitem><para><action>Paste</action> the contents of the clipboard at the cursor.</para></listitem> </varlistentry>
Please note, this is very complicated markup, and until you have written a few it's very hard to follow, but it does get much easier with practise! Although indenting is discouraged in general, this is one place where you might want to use some indenting and white space to make it clearer while writing, at least when you are beginning. There are also no rules as to when you must start a new line for a new element, so format the markup to suit your own taste while you are writing, if that makes it easier for you to follow.