The &kmyapplication; Handbook

The KDE DocBook Authors guide Lauri Watts Revision 1.00.00 (2004-08-22) Copyright (c) 2000, 2001, 2002, 2003 Lauri Watts Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License". A quick reference guide to the current KDE DocBook markup standards __________________________________________________________________ Table of Contents 1. General KDE markup style guide 2. Purpose of this document Other reference material 3. The Prologue book and the bookinfo section 4. Chapters and Sections 5. The linking elements 6. Lists 7. Tables 8. The GUI elements, menus, toolbars and shortcuts. 9. Describing actions and commands 10. Questions and Answers 11. Images and Examples 12. General markup (not covered elsewhere) 13. Admonitions: Tips, hints, and Warnings. 14. The synopsis elements 15. Markup for programming 16. Making Callouts 17. References, indexes, and glossaries Making a glossary Making an Index Other Reference Sections 18. Tags we do not use 19. Alphabetical List of all elements 20. Credits and License A. Entities List of Examples 1.1. Managing translatable entities 3.1. Setting up the global ?kappname? entity 3.2. A KDE User Manual Prolog 3.3. The bookinfo section from the KDE template 6.1. A Segmented List 7.1. An template 7.2. A template 8.1. An example from a menu reference entry 10.1. Template 11.1. A screenshot example 14.1. How to markup a command synopsis 14.2. How to markup a function synopsis 16.1. Marking up callouts with . 16.2. Marking up callouts by embedding directly in text 17.1. How to markup a glossary 17.2. Index Chapter 1. General KDE markup style guide * Format for readability, and content, not for a formatted document. It is not your job or responsibility to make sure the final documentation looks good. If you use appropriate markup tags for the content of your documentation, the processing tools will ensure your document looks good. Do not substitute an inappropriate DocBook XML tag because you do not like the ?look? of the correct tag. You should use white space to make the DocBook source more readable to the writer. Please do not indent unless it is absolutely necessary. * Do what you can to ensure you turn in a valid DocBook file. The reviewers will correct any DocBook errors you create, but please try to reduce errors by checking your work before it is turned in. If you have the KDE tools installed, you can use the command checkXML index.docbook to check for syntax errors. No result from checkXML is a good result - it means there are no problems. * Non-English words should be tagged with Wort. * Underlining and CAPITALIZING entire words are leftovers from the days of typewriters. They are no longer appropriate for today's documents. * Do not use quotation marks in your documentation. If you want a word to appear within quotation marks, simply enclose it between quote tags. This software is provided as is. * There are three different ?dashes? that are commonly found in documentation. + The hyphen combines two or more words into one. For example, ?mother-in-law?. The hyphen can be entered directly from the keyboard. + The en-dash is used to seperate numbers/dates/etc.. For example, ?Sections 1?3 review basic concepts?. The en-dash can be encoded using –. + The em-dash is used to separate sentences, or to show that something is missing. This is rarely used in technical documentation, but it can be used to show that one sentence is interrupted by another. The em-dash can be encoded using —. * When trying to decide between an ordered and unordered list, simply ask yourself the following question: ?Does the order of the listed items matter?? or ?If I change the order of the listed items, does that change the meaning of the list??. If you answer ?No? to either question, then an unordered list is likely the logical choice. * All and tags must have an id. The id must be in all lower case, and with dashes separating words. For example, . * All elements must have a full closing tag unless they are empty elements. Empty elements must still be closed with a /. Incorrect: Blah blah Correct: Blah blah * No attribute minimization. Incorrect: attribute=value or attribute='value' Correct: attribute="value" * All entities must end with a semi-colon: Incorrect: %parameterentity or &generalentity Correct: %parameterentity; or &generalentity; * Element GIs (the first word in a tag) must be written in lower case only. Incorrect: or Correct: Entities are also case sensitive, and will result in validation errors if the case is wrong. * Specify date and application's version in the format: 2000-12-31 1.02.03 The is the date of the last update. The always matches the version number of the application that is described in the documentation (if any). A translated version of a documentation always has the same and as the English original. Please respect this, it is the only way to manage efficiently both the writing and the translation processes. * The list of entities for applications is maintained centrally. Entity names are the application name completely in lower case. In case the name you need does not exist yet, send a mail to to have it added. You may add it in the prologue for validation purposes (in case it's new), but don't forget to remove it when you submit the document, because there should not be any ?extra? entities defined in the document prologue. * For language-independent entities, use kdelibs/kdoctools/customization/entities/general.entities and for language-specific entities, use kdelibs/kdoctools/customization/lang/user.entities. Try to avoid clashes with existing KDE entities. * The en/user.entities file should be updated keeping in mind that translation must be possible. Here is an example of how this translation can be managed: Example 1.1. Managing translatable entities &LMB; is en entity which stands for ?Left Mouse Button? When translating to French for example, do not translate only the entity contents, please also translate the entity name to &BGS; (or &bgs;), to reflect the change in the initials: becomes Languages that decline nouns like German and Russian can use something like the following: * If you feel that some elements don't make fine enough a distinction, feel free to use the attribute role (but please tell the DocBook team, as otherwise you may find your document to be suddenly invalid). * Use for FAQs, not an . Please split up a FAQ into several chapters or sections if it gets big. The HTML files get too big otherwise, which the users may not like. * Abbreviations and acronyms should be marked up as well. Use the DocBook tags and respectivly. Please keep them apart: acronyms are things like GUI, KDE, GPL, while abbreviations are things like etc., i.e., e.g.. There are entities for the most common ones. * Use or each time you introduce a technically significant new word. * Keep in mind that the ?$? sign is introduced by the shell, and is not part of an environment variable's name: ls -l $KDEDIR is marked up as ls $KDEDIR export $KDEDIR=/usr/local/kde is marked up as: export $KDEDIR= /usr/local/kde * Only use for URL's and not for files, unlike in HTML. Don't use it for email addresses either, they have their own element, . * The elements and are disallowed and have been removed from the KDE customized DTD. (They are not meant for new technical documentation.) has been removed also: we are using SVN already. Chapter 2. Purpose of this document Table of Contents Other reference material The purpose of this document is to describe how markup has been standardized within KDE documentation only. This document is not to be considered more authoritative than the DocBook documentation, including the O'Reilly Duck book. However, there are places where the KDE DTD is more restrictive than, or just differs from, the OASIS DTD, and these are noted in this document. In these cases, follow the instructions here. Please read and make use of the other documentation available to you, which is much more comprehensive. This document is not intended to be more than a quick reference for KDE authors, to clarify how the DocBook XML elements are used within the KDE Documentation. Other reference material Please take a look at the following reference material, rather than relying on this document to answer all your questions. The Duck book The complete DocBook SGML (and now XML) reference. Available as a download in several formats, so you can keep a copy on your hard drive for reference. Also available for sale in hard copy - if you see yourself doing a lot of DocBook Authoring, you definitely ought to consider buying it. The Crash Course to Docbook A non-KDE specific crash course to marking up documentation. This is the starting point for all KDE documents, including the markup issues discussed here. Note that the current version is written for SGML, but the concepts are still correct for XML. The KDE Documentation Template Covers many things not mentioned here, including required and optional chapters, the preferred way to mark up the prologue and bookinfo sections, and how to deal with licensing and credits. It can be found in kdelibs/kdoctools/template.docbook in CVS. DocBook-XML (in German) A very nice book, in German only unfortunately, but comes highly recommended. Chapter 3. The Prologue Table of Contents book and the bookinfo section KMyApp"> ]> In general, this needs minimal changing from the template. The items you must change are the entities ?kappname?, ?package?, and ?English?. The entity ?kappname? looks like it's redundant (as the comment in the template notes), but it is important. This allows us to use one global text in all documents, and still refer to the specific application by its correct name. So it should be changed to refer to this new entity, but this time you should only change the part in quotes (?&kmyapplication;?) as follow: Example 3.1. Setting up the global ?kappname? entity From: To: In short: change any occurrence of ?kmyapplication? to the real name of your application. Do not use ?kappname? or ?kapp? directly in a document yourself. The entity ?package? is used similarly. It allows us to insert a single piece of ?boilerplate? text into every document, and have the correct package name inserted when the document is compiled. Use the cvs module name, in lower case, e.g. ?kdeedu? or ?kdebase?. The entity %addindex; is a toggle. If set to ?INCLUDE? a document index will be automatically generated. It is normally set instead to ?IGNORE?, and should not be changed unless you really do want to generate an index. You can find out more about indexes in Chapter 17, References, indexes, and glossaries. Example 3.2. A KDE User Manual Prolog Here is an example of a completely set up prolog, as it normally looks. This is the prolog from the AMOR documentation ]> Note The entity ?English? should be changed to reflect your language, if you are either writing original documentation in another language, or you are translating a document. For KDE the original documentation should always be in English, so you should not need to change this when writing. For informational purposes, the currently supported languages are: * Afrikaans * British-English * Bulgarian * Catalan * Czech * Danish * German * Greek * English * Spanish * Estonian * Finnish * Faroese * French * Hebrew * Hungarian * Indonesian * Italian * Japanese * Dutch * Norwegian (Note, this is only for compatibility, either Norwegian-Bokmal or Norwegian-Nynorsk should be used in preference.) * Norwegian-Bokmal * Norwegian-Nynorsk * Polish * Portuguese * Brasilian-Portuguese * Romanian * Russian * Slovak * Slovenian * Serbian * Swedish * Turkish * Ukrainian * Walloon * Xhosa * Continental-Chinese * Traditional-Chinese book and the bookinfo section The bookinfo section is most easily prepared by copying the KDE template. Contains the entire document. Most important thing to remember is the lang attribute, which must contain exactly &language;, and must not be changed. To set the language for the document, change the entity as described in the prologue section. Wraps the ?meta? information ? information about the document, not about the application it is documenting. Required in KDE documentation. No attributes. Wraps the author information, and may also contain information. Required in KDE documentation. No attributes. Required element in the header section of all KDE documentation. Use this element only for the author(s) of the document. Other contributers (developers, translators, and so on) should be credited in the section. No attributes. Used to wrap a person's name. You can use this directly in the text as well, but here it should be used to contain each author or contributor name. The contributor's first name. If the author normally uses more than a first and surname, you can add further names here. The author's surname. An email address for the maintainer of the document is required for KDE documentation. You do not have to use your primary private address, and you may be able to arrange for someone else (the developer perhaps) to receive the email regarding the document. In any case, there must be an address for users and translators to contact regarding errors and document bugs. Note In previous versions of DocBook, could not be used directly inside . Since DocBook XML V 4.2 (used by KDE for documents after KDE 3.1.x), this is possible, which simplifies this markup considerably. In other contexts in the document, is used to contain any email address, and is not used inside the address element. Similary to author, this is a wrapper around information describing other contributors to the document. Include here the contributor's name and email address as you do for the author. See the template for more details. The role attribute is required, and can contain any one of the following: + Translator + Developer + Reviewer + Graphist + Musician The othercredit element also includes the contrib element. The role this contributor played in the document or application preparation. This could contain something like: o Developer o Deutsche Uebersetzung o Reviewer o Traduction franc,aise This is used in very specific circumstances, where an organization (e.g. ?The KDE Team?) is being credited with authorship of a document. Authors writing about applications should not use this and should credit themselves. If you do find a need to use this, please be sure to include a maintainer's name and email address in the credits chapter of the document. This is a wrapper for copyright information. copyright must contain these elements: Add one year element for each year in which the document was changed or added to. Don't put more than one year in each tag, rather add more year elements, and use the 4 digit ?YYYY? format. The usual full name of the copyright holder(s). If there is more than one copyright holder (the document was previously maintained by another person, or is written collaboratively), then add more copyright sections, rather than trying to fit multiple names in the one section. Copyright is automatically held by the author of the document, but the copyright element is still required for all KDE documentation. None of the elements contained have any attributes. Please do not add more names or years to existing or elements. Add more, if they are required, or have multiple copyright sections. This contains, of course, a legal notice. This is absolutely required for any KDE document. In the context of this section, it should contain the &FDLNotice; entity, which inserts some information into the document about the document's license (and not the license of the application you are describing.) The date is very important. It is used not only by scripts for automatic processing of documentation, but is also central to revision control and co-ordination of translations. You must change the date if you have changed the original document, and you must not change the date if you are a translator. The format of the date is very important. It must be in the ISO, with ?literal? delimiters, in the form ?yyyy-mm-dd?. Please be extremely careful about this, and triple check it before you send in the document. This should match exactly the version of the application you are documenting. It should normally conform to the format X.x.xx (where X is a major version number and x are minor version numbers, however, you no longer have to pad the content to this length. That is to say, if the application has released version ?1.4?, you may write 1.4, and you do not need to make it 1.04.00 This is not the version of the document. There are no attributes, and this element is required in KDE documentation. In KDE Documentation, the abstract is required. It should be a short one- or two-sentence summary of the document. The abstract is not the place to put version or contact information, but it should say something about the application and its purpose. For example ?KFoo is a small fast network enabled foo generator, suitable for both beginner and advanced foo users.?. The abstract is your chance to sum up the application in a small paragraph ? in KHelpCenter it shows up on the first page as your document is selected, and the abstract frequently shows up in the summary of your document in web searches. A short overview of the application you are writing about is very valuable in this situation, ?This is the KFoo handbook and describes KFoo 1.2.? on its own, is not. A wrapper for a set of keywords suitable for search engines. Required for KDE Documentation, and there are no attributes. The keywordset should contain several s. Add one inside the for each search term. You must include at a minimum the terms ?KDE?, the name of the application you are documenting, and the name of the package it is found in, for example ?kdegames?. The keywords should be in order from most general first (that is, KDE) through less general, to the most specific. Add two or three more relevant words that people might search with, e.g., for the application KWrite you might add ?editor? and ?text?. This is required for KDE Documentation, and there are no attributes. This line is specific to KDE documentation. Although it's a comment, it is absolutely required in documents. It is used by the translation system as a placeholder for the translation teams to add their own role info. Translators should add more othercredit sections here as appropriate. Example 3.3. The bookinfo section from the KDE template The &kmyapplication; Handbook George N. Ugnacious gnu@kde.org 2002 George N. Ugnacious &FDLNotice; 2003-01-10 1.1. &kmyapplication; is an application specially designed to do nothing you would ever want. KDE kdeutils Kapp nothing nothing else Chapter 4. Chapters and Sections Use chapters to break up the document into smaller chunks. A chapter break should occur when a major subject change happens. Use sections within the chapter when the subject changes, but you are still discussing a particular aspect of a larger subject. For example, going from discussing how to use the application, to how to configure the application would be worthy of a new chapter. Moving from discussing how to specifically configure the application on SuSE, to how to specifically configure the application on Red Hat(R), would be a new section in a larger ?Configuration? chapter. Chapters must have an id. This is the only attribute used in KDE documentation. For KDE Documents, this id must be in lower case, and with a hyphen (-) to separate words. Please don't use spaces, underscores, or run the words together. For HTML generation, the chapter id and most id's are used to name the separate HTML pages, so take care to make them sensible and descriptive. For translators, these id's should be translated, but you will need to take care to also translate references to the id's in and elements in other parts of the document. Titles are used in many places, but the most common is the Chapter and Section headings. Make sure to use sensible titles, as these will also be that chapter's (or section's) entry in the table of contents, so people will rely on these to find the part of the document they are interested in. <sect1 id="">, <sect2>, <sect3>, <sect4>, <sect5> Use sections to break chapters up into smaller pieces. Use similar criteria on where to divide them as you would for chapters. Sections require a <title>. Sections are nested according to the number - a <sect2> can contain any number of <sect3>, which can contain <sect4>, but a <sect2> can't directly contain a <sect4>. <sect1> requires an id attribute, and you can use id's on the other section tags if you want to later link directly to them from other parts of the document. id is the only attribute used in KDE Documentation. <sect1info>, <sect2info>, <sect3info>, <sect4info>, <sect5info> The section info elements are rarely used in KDE Documentation. They are appropriate for documents where some smaller sections are contributed by third parties, or where the document covers multiple applications. The contents are more or less the same as those of the <bookinfo> section, although they tend to be briefer. Please ensure if you use these elements that you add the translation placeholder comments as you do in the prolog. <appendix> The standard installation instructions for all applications are contained in an <appendix>, and are normally required for KDE documents. Although the installation instructions as found in the template are reasonably complete, and need no customization for most applications, authors are very strongly encouraged to expand on them. For example, links to web pages, where to find libraries, plugins, screenshots of the application in a particular configuration, or any other information you can think of. If the application is only distributed with KDE, there is little use in repeating the same installation instructions for every manual. You may leave it out entirely, unless you have further information to add. For other purposes, appendices are used infrequently in KDE Documentation. An appendix can be found, for example, in the KPPP document, containing such things as Hayes Modem commands. Only use an appendix if you think it's very necessary. In most cases, the information it would contain would be better moved to the main document. In the example of KPPP, this information is vital to a few people, but extremely uninteresting to the majority, so it was placed in an appendix. Chapter 5. The linking elements <link linkend=""> The most common link. Use this to turn a word or phrase into a link to another part of the document. linkend is the only attribute we use. <ulink url=""> A link that refers to a document using it's URI. Use this for websites and ftp sites, but not for email addresses, which have their own specific tag. Please do not use this to link to other documents on the local system. <anchor id=""/> Marks a place in the document, which you can use to link to. Note that the id attribute on any other element where it is valid, will automatically generate an HTML anchor in generated HTML, so you do not need to duplicate these. Use anchors only when you need to jump into the middle of a longer page, for example, to a particular menu item, or to a particular option in a preference dialog. Note <anchor/> is an empty element, and must be closed with a /. <xref linkend=""/> A cross reference to another part of the document. Use this when you want to refer to the section without the name. This is one of very few unclosed elements allowed. linkend is the only attribute we currently use. Note <xref/> is an empty element, and must be closed with a /. <email> Use this to enclose an email address. Don't add ?mailto:? to the email address, and don't use <ulink url=""> for email addresses. No attributes required. Chapter 6. Lists <listitem> <listitem> is the main building block of almost all the lists. It should always contain some other markup, usually a <para> <orderedlist> Use this type of list when the order of the items matters, but they are not a set of steps that are carried out to achieve something. A good example is a list of things in order of importance. <itemizedlist> Use an itemized list when the order of the items is not important. <variablelist> A list that has two sections for each entry. Examples: A menu item, and what the menu item does, An action, and its result, or a term and its definition. This is a very common type of list. (Almost this entire document is composed of variable lists.) <variablelist> contains the following elements: <varlistentry> A <varlistentry> is a wrapper around each pair in the variable list. <term> To reuse the above examples, the <term> for each pair would be the menu item you are describing, the action, or the term you are defining. You can use the id attribute for this element, which is quite convenient in long lists such as a menu reference, enabling you to link directly to a particular menu item from another part of the document. <listitem> As described above the <listitem> is used inside a <varlistentry> to hold the second part of the pair: The result of choosing that menu item, for example, the consequences of an action, or the definition of the term. <procedure> Use a procedure list when you are listing a sequence of steps which are performed in a particular order. A procedure contains only one tag: <step> A step is one of the sequence of events that make up a procedure. <substeps> A step can contain substeps <simplelist> A simple list is just that - a simple list, with no formatting required. A simple list can contain only one type of element: <member> Members of a simple list. <segmentedlist> A Segmented list is a very particular type of list. Use sparingly, as it's very difficult to get these right, and most content appropriate for a segmented list could just as well fit the table model. Example 6.1. A Segmented List <segmentedlist> <segtitle>Name</segtitle> <segtitle>Occupation</segtitle> <segtitle>Favorite Food</segtitle> <seglistitem> <seg>Tux</seg> <seg>Linux Mascot</seg> <seg>Herring</seg> </seglistitem> <seglistitem> <seg>Konqui</seg> <seg>The KDE Dragon</seg> <seg>Gnomes</seg> </seglistitem> </segmentedlist> Name: Tux Occupation: Linux Mascot Favorite Food: Herring Name: Konqui Occupation: The KDE Dragon Favorite Food: Gnomes The segmented list contains the following elements: <segtitle> The title each segment will have <seglistitem> A set of entries in the list <seg> The contents of the entries in the list. In each <seglistitem> there is one <seg> for each <segtitle>. Chapter 7. Tables <informaltable> This is the table type used most in KDE Documentation. Please be very sure that what you are marking up as a table, is actually tabular data, as in many cases a <variablelist> is more appropriate. Please do not use any of the presentation attributes to make tables ?look nice?. The only attribute currently allowed in KDE Documents is pgwide. An <informaltable> must contain a <tgroup cols=""> entry. Informal tables have no specific title, if you wish the table to be titled and to have an entry in the table of contents, you should use <table>. Do not use any attributes other than pgwide on tables or informal tables for KDE documentation. <table> A formal table with a title. Tables will have their own separate entry in the table of contents. Other than the addition of a title, they are marked up the same as an <informaltable>. <tgroup cols=""> A <tgroup> is a required element in a table. The cols attribute is required, and should be completed with the number of columns the table is to hold. No other attributes used in KDE Documentation. A tgroup must contain a tbody <tbody> A tbody is a required element in a table. There are no attributes. The tbody contains rows. <row> A row corresponds directly with the rows of the table. Rows contain <entry> tags, one for each column in the table, as specified by the cols attribute on the <tgroup> tag. <entry> The entry is the basic building block of a table. Each entry corresponds to one ?data cell? in the table. There must be as many <entry> tags in each row as the cols attribute on the <tgroup> tag. There are no attributes used in KDE Documentation. <thead> <thead> can be used to create a heading row for the table. It must appear before the tbody element, and should normally contain one row and as many entry elements as the rest of the table. <tfoot> <tfoot> is not currently used in KDE Documentation. If you want to use it, please see the Duck book for information. Example 7.1. An <informaltable> template <informaltable> <tgroup cols="2"> <tbody> <row> <entry></entry> <entry></entry> </row> </tbody> </tgroup> </informaltable> Example 7.2. A <table> template <table> <title>

Chapter 8. The GUI elements, menus, toolbars and shortcuts. 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 closes the dialog.? 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 for the that looks like ->. Please note this is a KDE specific use of , and does not precisely follow the examples in the Duck Book. A menuchoice describes a menu entry. You should use anywhere you are describing how to reach a menu item. In normal text, there are no particular requirements. In a menu reference, the should also contain a element describing the keyboard shortcut, and the contents should also be marked up with as appropriate. A key combination that is a shortcut for a menu item. This is only used inside and contains or that is defined as the keyboard shortcut in the menu. In the markup, it appears before the actual menu entries inside the 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: + left or the entity &LMB; + middle or the entity &MMB; + right or the entity &RMB;. + wheel 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 , or , 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: + Click + Double-Click + Other + Press + Seq + Simul 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 8.1. An example from a menu reference entry &Ctrl; C Edit Copy Copy the selected text to the clipboard &Ctrl; V Edit Paste Paste the contents of the clipboard at the cursor. 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. Chapter 9. Describing actions and commands Use this for placeholder or sample text, that a user would not actually type, but would instead replace with the correct text for their environment. For example, Edit the file /usr/local/foo/bar, because it may already be established that /usr/local is only the default location of this file, and the user may have it installed to e.g. /opt/ instead. Use this to mark up the name of any software program mentioned in the text. Don't use this to mark up the actual command issued to execute the application. For example, Kate is the name of the editor, but kate is the name of the command that starts the Kate application. Note All KDE applications, and several non-KDE but very common applications, are provided as entities. For the KDE applications, using the entities will save you much typing, and will ensure that applications are always referred to with their correct name across all documentation. The entity is always the application's executable name, in lower case, e.g. &kcontrol;, &konqueror; or &kmail;. For non-KDE applications, one of the major reasons to use the entities is that there are legal implications, so far as we are required to acknowledge trademarks and copyrights held by others outside our organisation. You will find in Appendix A, Entities a list containing a list of the more common non-KDE application entities. Catch all element for gui interface items that do not have a more specific tag. You can use this to markup things like the ?View pane? in KHelpCenter, or the ?Board? in KJumpingCube. Any text that the user must type, including commands and data entry. Used to represent the computer screen (usually to represent a terminal or console.) Text contained in is considered to be literal text ? line breaks and white space are honored and it will be rendered with a mono-spaced font. Don't use screen when what you really want is an example, or an informal example. Text the user enters to instruct the computer or an application to do something. ls -al is a command (it's also userinput, and has options.) /join #kde in an irc client is a command (and again, is userinput.) Commands are not userinput when you are not expecting the user to actually type them, for example in the sentence ?The output from the ls command should show you...?, the text ?ls? is a command, but is not userinput in this context. Applications not marked up with the tag are also considered commands, for example, gcc, automake and autoconf. The prompt at which a user types input. For most KDE Documentation, this has been standardised as % (which is the % character).