Documentation Primer typos, etc.

[John Hayes]

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.