These are my suggestions for the marked sentences below, based on what I am reading in the Documentation Primer. I decided to put it all in one file instead of putting it out piece by piece, hopefully these suggestions are helpful. I have tried to put enough context to help you find the sentences. There are typos and a lot of contractions, etc.
Cheers, John =================== Fundamentals [....] Most people reading this Fundamentals do not have an actual problem, they simply want to ^^^^ these achieve a goal, and don't yet know how, or where to find that information. =================== Kate Kate is an extensible and powerful text editor which is part of the kdebase module. Kate can syntax highlight DocBook documents out of the box, and is generally a very powerful editor, but you can get even more XML specific functionality installing the XML plugin for Kate. ^ by through (especially through Additional XML tools will be available trough the XML menu (in special, trough the Validate XML ^^^^^^ ^^^^^^^^^^^^^^^^^ menu item, which will allow you to check your DocBook documents). The output of this action will appear in the XML Checker Output button in the side bar located in the lower part of Kate's main window. =================== Using checkXML5 [....] This is possibly the most common type of error. It's caused either by an element that hasn't ^^^ It is has not ^^^^^ been closed, or by tags that overlap. The error above was generated by the following markup: =================== Chapter 5. DocBook Introduction All KDE documentation is produced in DocBook XML format, and writers are encouraged to learn it (although it's by no means necessary, and we're very happy to receive documentation ^^^ it is ^^^^^ we are written in plain text). [....] Overview DocBook is just an application of XML, so if you're familiar with XML, then you'll feel right at ^^^^^^ you are home. If not, don't worry, as most of the gory details aren't required knowledge for simply ^^^^^ do not writing and updating documentation. [....] Tags, entities, comments and other parts of XML that aren't simple text are referred to as ^^^^^^ are not “markup.” [....] Content and Presentation What's important is that the DocBook source has the information necessary to work out ^^^^^^ What is what is being referred to.) Entities [....] This means that you don't have to remember whether the help center program is ^^^^^ do not KHelpCenter, KHelpcenter or Khelpcenter: the entity (which is always entirely lowercase) automatically expands to the correct one. =================== Working With Other Documenters and Developers [....] The people you'll work with most often as a documentation writer are the documentation ^^^^^ you will team, the quality team (if you're a new contributor) and the maintainer of the application that you're working on. ^^^^^^^ you are [....] The main ways to contact the documentation team are via the (kde-doc-english AT kde.org) mailing list and on IRC in the fkde-docs channel on the server irc.freenode.net. ^^^^^^^^^^ #kde-docs [....] You don't need to feel like you're working entirely on your own – there are plenty of people ^^^^^ do not ^^^^^^ you are who are able to help. [....] The usual reason to contact a programmer is to ask about a feature or behavior of an application that you're documenting. ^^^^^^ you are [....] If you can't find a maintainer, ask on (kde-doc-english AT kde.org) or (kde-devel AT kde.org). ^^^^^ can not If asking on the kde-devel list, mention that you're writing the documentation for that ^^^^^^ you are application – it helps to identify you to those reading a busy list. In general, programmers and other developers are happy to help, and willing to work with you, so don't feel afraid of asking ^^^^^ do not them for information, and building up a working relationship. =================== Using bugs.kde.org [....] When filing bugs, especially for incorrect or outdated content, be specific about what's wrong. what is ^^^^^^ =================== General KDE markup style guide [....] A detailed explanation how to use this markup you find in the docbook templates. [reads better as below] You will find a detailed explanation on how to use this markup in the docbook templates. [....] 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 an email ^^^^^^ to (kde-docbook AT kde.org) 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, ^^^ it is ^^^^ do not because there should not be any “extra” entities defined in the document prologue. [....] If you feel that some elements don't make fine enough a distinction, feel free to use the ^^^^^ do not attribute role (but please tell the DocBook team, as otherwise you may find your document to be suddenly invalid). [....] Don't use it for email addresses either, they have their own element, <email>. ^^^^^ Do not =================== KDE DocBook Reference book and the bookinfo section <year> Add one year element for each year in which the document was changed or added to. Don't Do not ^^^^^ put more than one year in each tag, rather add more year elements, and use the 4 digit “YYYY” format. [....] <chapter id=""> Please don't use spaces, underscores, or run the words together. ^^^^^ do not [....] <email> Use this to enclose an email address. Don't add “mailto:” to the email address, and don't use ^^^^^ Do not do not ^^^^ <ulink url=""> for email addresses. [....] <application> Use this to mark up the name of any software program mentioned in the text. Don't use this to Do not ^^^^^ mark up the actual command issued to execute the application. [....] <screeninfo> Screeninfo is a description of the screenshot. It's common (but not required) to reuse this text ^^^ It is in the textobject element, as it saves translation time. [....] <imageobject> We don't currently use this functionality in KDE Documentation, but may do at some time in ^^^^^ do not the future. [....] <imagedata fileref="" format=""/> Keep the images in the same directory as your index.docbook, don't create a separate ^^^^^ do not directory to store them in. [....] <example> However, don't hesitate to use when you think it's necessary. ^^^^^ do not I've used them in this document to make it easy to quickly go to the small “template” ^^^ I have examples for complex markup, because you can find them directly from the table of contents. [....] General markup (not covered elsewhere) <emphasis> Don't use it to mark up file names, commands, or anything else. ^^^^^ Do not Emphasis loses it's power when over used. ^^^ its [....] Admonitions: Tips, hints, and Warnings. <important> When there is no danger of data loss, but you wish to make clear to the reader a consequence that isn't immediately obvious (e.g. when changing the font for one instance ^^^^ is not of a program also changes the default setting, and this isn't clear from the GUI.) ^^^^ is not [....] <tip> When you're giving a hint to make things easier or more productive for the reader. ^^^^^^ you are [....] <footnoteref linkend=""> You can refer to a footnote more than once, by using this element to refer to it's unique id. ^^^ its [....] The synopsis elements <funcdef> A function and it's return type. ^^^ its [....] <arg> Used inside <cmdsynopsis>. Since most KDE applications are GUI only, you won't see this will not ^^^^^ very often. See the entry for <cmdsynopsis> for a full explanation and example. [....] Markup for programming <classname> Used to identify the name of a class in a programming language. In KDE Documentation, you won't see this much in the user documentation, except for those applications which contain an ^^^^^ will not API reference chapter, and occasionally in others. [....] For non-programmers, as we're almost exclusively discussing KDE applications written in C++ ^^^^^^ we are and using Qt™, classnames are fairly easy to distinguish: They start with a capital Q or K, and are usually one word only, in the form of KApplication or QListBox. [....] <programlisting> You don't need to use this for short snippets that are inline in the text, but you should use it ^^^^^ do not for any examples longer than a line or two, or that are a separate block of text. [....] Making Callouts <co> Again it's really not as hard as it looks on first glance. This markup would generate the ^^^ it is following: [....] References, indexes, and glossaries <glossterm> When it's placed inside a <glossentry> it contains the term that glossary entry is defining (see ^^^ it is the example below to see this in action.) [....] <glossseealso otherterm=""> Since variable lists get heavy use in KDE Documents, it shouldn't take you long to pick up ^^^^^^^^^ should not how to do a glossary. [....] Making an Index <indexterm> Don't over use it - not every single occurrence of a word needs to be noted in the index, but ^^^^^ Do not every occurrence where that term is significant should be. [....] Tags we do not use They are included here for completeness, and so nobody can say “I didn't know did not ^^^^^ I wasn't supposed to use that!” ^^^^^^ was not (Unless the intent was for the short general response) [....] Alphabetical List of all elements Note We don't use all these elements in KDE Documentation - they are here for completeness. ^^^^^ do not Elements we don't use are listed in the section called “Tags we do not use” and appear in a ^^^^^ do not distinctive typeface below.