Documentation Primer typos, etc.
Albert Astals Cid
aacid at kde.org
Fri Mar 13 20:26:25 GMT 2020
El divendres, 13 de març de 2020, a les 20:30:01 CET, Yuri Chornoivan va escriure:
> Hi,
>
> Should be fixed now. Thanks for your work.
>
> Need somebody to help to update online copy.
They get regenerated every day around 2am CET
I just run a manual regeneration anyway
Cheers,
Albert
>
> 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.
>
>
>
>
>
More information about the kde-doc-english
mailing list