Revision as of 08:30, 2 September 2012
- 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 name or description of an icon.
- 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.
- Take care that the text exactly matches the label on screen. If it has a : on the dialog box, put the : into your documentation. Match the capitalization. There is a script in the kde-i18n module called check-gui-texts which you can use to help check that your text matches exactly what is in the application. During translation, the translators can use this script to generate translations from their translations of the GUI itself, but this will only work if the English text matches precisely.
- 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 how to reach 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 some occasions.
- The normal name of a mouse button. It will be normally be one of:
- <mousebutton>left</mousebutton> or the entity &LMB;
- <mousebutton>middle</mousebutton> or the entity &MMB;
- <mousebutton>right</mousebutton> or the entity &RMB;.
- 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. Although we previously used this in the menu references, we have since decided not to, the maintenance is too high, and it causes an enormous amount of work during translation.
Example: An example from a menu reference entry
<listitem><para><action>Copy the selected text</action> to the
<listitem><para><action>Paste</action> the contents of
the clipboard at the cursor.</para></listitem>
- 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.