Documentation Primer typos, etc.

[Yuri Chornoivan]

Hi,

Should be fixed now. Thanks for your work.

Need somebody to help to update online copy.

Best regards,
Yuri

пʼятниця, 13 березня 2020 р. 20:07:07 EET 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.