Doc: Fix language issues in Qt Help overview docs

Change-Id: Ie0da8077bc28c8377161ba83078443c6d760dc67
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
Reviewed-by: Jarek Kobus <jaroslaw.kobus@qt.io>

1 files changed, 44 insertions, 45 deletions

diff --git a/src/assistant/help/doc/src/qthelp.qdoc b/src/assistant/help/doc/src/qthelp.qdoc
index 69afe5b2a..daf3277fd 100644
--- a/src/assistant/help/doc/src/qthelp.qdoc
+++ b/src/assistant/help/doc/src/qthelp.qdoc
@@ -34,7 +34,7 @@
 
     \keyword help system
 
-    These classes provide for all forms of online-help in your application,
+    These classes provide online-help for your application,
     with three levels of detail:
 
     \list 1
@@ -229,13 +229,13 @@
     compressed help file. Along with the actual help data, like
     the table of contents, index keywords and help documents, it
     contains some extra information like a namespace to identify
-    the help file. One help project stands for one documentation,
+    the help file. One help project stands for one documentation set,
     for example the \l{Qt Assistant Manual}.
 
     \section1 Qt Help Project File Format
 
     The file format is XML-based. For a better understanding of
-    the format we'll discuss the following example:
+    the format we will discuss the following example:
 
     \snippet doc_src_qthelp.qdoc 7
 
@@ -243,7 +243,7 @@
 
     To enable the QHelpEngine to retrieve the proper documentation to
     a given link, every documentation set has to have a unique
-    identifier. A unique identifier makes is also possible for the
+    identifier. A unique identifier also makes it possible for the
     help collection to keep track of a documentation set without relying
     on its file name. The Qt help system uses a namespace as identifier
     which is defined by the mandatory namespace tags. In the example
@@ -252,50 +252,49 @@
     \target Virtual Folders
     \section2 Virtual Folders
 
-    Having a namespace for every documentation naturally means that
-    the documentation sets are quite separated. From the help engines
-    point of view this is beneficial, but from the documentors view
-    it is often desirable to cross reference certain topic from one
+    Having a namespace for every documentation set naturally means that
+    the documentation sets are quite separated. From the help engine's
+    point of view, this is beneficial. However, from the writer's view
+    it is often desirable to cross reference certain topics from one
     manual to another without having to specify absolute links. To
     solve this problem, the help system introduced the concept of
     virtual folders.
 
     A virtual folder will become the root directory of all files
-    referenced in a compressed help file. When two documentations
+    referenced in a compressed help file. When two documentation sets
     share the same virtual folder, they can use relative paths when
-    defining hyperlinks pointing to the other documentation. If a
-    file is contained in both documentations or manuals, the one
-    from the current manual has precedence over the other.
+    defining hyperlinks pointing to each other. If a file is contained
+    in both documentation sets, the one from the current set has
+    precedence over the other.
 
     \snippet doc_src_qthelp.qdoc 8
 
-    The above example specifies 'doc' as virtual folder. If another
-    manual, e.g. for a small helper tool for 'My Application'
-    specifies the same folder, it is sufficient to write
-    'doc.html#section1' to reference the first section in the
-    'My Application' manual.
+    The above example specifies \e doc as virtual folder. If another
+    manual specifies the same folder, for example for a small helper
+    tool \e {My Application}, it is sufficient to write
+    \e {doc.html#section1} to reference the first section in the
+    \e {My Application} manual.
 
-    The virtual folder tag is mandatory and the folder must not
-    contain any '/'.
+    The virtual folder tag is mandatory and the folder name must not
+    contain any slashes (/).
 
     \target Custom Filters
     \section2 Custom Filters
 
-    Next in the Qt help project file are the optional definitions of
+    The Qt help project file contains optional definitions of
     custom filters. A custom filter contains a list of filter
     attributes which will be used later to display only the documentation
-    which has all those attributes assigned to. So, when setting the
-    current filter in the QHelpEngine to "My Application 1.0" only
-    the documentation which has "myapp" and "1.0" set as filter
+    set that has all those attributes assigned. So, when setting the
+    current filter in the QHelpEngine to \e {My Application 1.0} only
+    the documentation which has \e myapp and \e {1.0} set as filter
     attributes will be shown.
 
     \snippet doc_src_qthelp.qdoc 9
 
-    It is possible to define any number of custom filters in a help
-    project file. Important to know is, that the filter attributes have
-    not to be specified in the same project file; they can be defined
-    in any other help file. The definition of a filter attributes
-    takes place by specifying them in a filter section.
+    You can define any number of custom filters in a help project file.
+    It is important to know that you do not have to specify the filter
+    attributes in the same project file. These attributes can be defined
+    in any help file, in a filter section.
 
     \target Filter Section
     \section2 Filter Section
@@ -305,7 +304,7 @@
     consists of four parts, the filter attributes section, the table of
     contents, the keywords and the files list. In theory all parts are
     optional but not specifying anything there will result in an empty
-    documentation.
+    documentation set.
 
     \section3 Filter Attributes
 
@@ -317,22 +316,22 @@
 
     \snippet doc_src_qthelp.qdoc 10
 
-    In this case, the filter attributes 'myapp' and '1.0' are assigned
-    to the filter section, i.e. all contents specified in this section
-    will only be shown if the current custom filter has 'myapp' or '1.0'
-    or both as filter attributes.
+    In this case, the filter attributes \e myapp and \e {1.0} are assigned to
+    the filter section. This means that all contents specified in this section
+    will only be shown if the current custom filter has \e myapp or \e {1.0},
+    or both, as filter attributes.
 
-    \section3 Table of contents
+    \section3 Table of Contents
 
     \snippet doc_src_qthelp.qdoc 11
 
     One section tag represents one item in the table of contents. The
-    sections can be nested to any degree, but from a users perspective
+    sections can be nested to any degree, but from a user's perspective
     it should not be more than four or five levels. A section is defined
     by its title and reference. The reference, like all file references in a Qt
     help project, are relative to the help project file itself.
-    \note The referenced files must be inside the same directory (or within a
-    subdirectory) as the help project file. An absolute file path is not supported
+    \note The referenced files must be in the same directory as the help
+    project file (or in a subdirectory). An absolute file path is not supported
     either.
 
     \section3 Keywords
@@ -341,25 +340,25 @@
 
     The keyword section lists all keywords of this filter section. A
     keyword consists basically of a name and a file reference. If the
-    attribute 'name' is used then the keyword specified there will appear in
-    the visible index, i.e. it will be accessible through the QHelpIndexModel.
-    If 'id' is used, the keyword does not appear in the index and is
-    only accessible via the linksForIdentifier() function of the
-    QHelpEngineCore. 'name' and 'id' can be specified at the same time.
+    attribute \e name is used, the keyword specified there will appear in the
+    visible index. That is, it will be accessible through the QHelpIndexModel
+    class. If \e id is used, the keyword does not appear in the index and is
+    only accessible via \l QHelpEngineCore::linksForIdentifier(). \e name and
+    \e id can be specified at the same time.
 
     \section3 Files
 
     \snippet doc_src_qthelp.qdoc 13
 
     Finally, the actual documentation files have to be listed. Make sure
-    that all files necessary to display the help are mentioned, i.e.
-    stylesheets or similar files need to be there as well. The files, like all
+    that all files necessary to display the help are mentioned. That is,
+    stylesheets or similar files need to be listed as well. The files, like all
     file references in a Qt help project, are relative to the help project file
     itself. As the example shows, files (but not directories) can also be
     specified as patterns using wildcards. All listed files will be compressed
     and written to the Qt compressed help file. So, in the end, one single Qt
     help file contains all documentation files along with the contents and
     indices. \note The referenced files must be inside the same directory
-    (or within a subdirectory) as the help project file. An absolute file path
+    as the help project file (or in a subdirectory). An absolute file path
     is not supported either.
 */