Doc: Revise Qt Quick Text reference page

* Fix typos.
* Show rich text Markdown example.
* Be consistent with relative clauses (that vs which).
* Where it makes sense, use active voice instead of passive voice.

Fixes: QTBUG-119485
Pick-to: 6.2 5.15
Change-Id: I7843a3276f277172e25f5891f08e2a830d713c4e
Reviewed-by: Shawn Rutledge <shawn.rutledge@qt.io>
(cherry picked from commit ec3b799824ef03cd332297024db57acce60e76ed)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>
(cherry picked from commit ce366ee66e33647cc7a48fb2f251cab112bb88cc)
(cherry picked from commit 1e58c059977ee5e07aa2df8df434d0fe24a1623d)

1 files changed, 44 insertions, 20 deletions

diff --git a/src/quick/items/qquicktext.cpp b/src/quick/items/qquicktext.cpp
index 0165395579..8e437b61a7 100644
--- a/src/quick/items/qquicktext.cpp
+++ b/src/quick/items/qquicktext.cpp
@@ -204,7 +204,7 @@ void QQuickTextPrivate::setBottomPadding(qreal value, bool reset)
     Used to decide if the Text should use antialiasing or not. Only Text
     with renderType of Text.NativeRendering can disable antialiasing.
 
-    The default is true.
+    The default is \c true.
 */
 
 void QQuickText::q_updateLayout()
@@ -1301,8 +1301,8 @@ void QQuickTextPrivate::updateDocumentText()
     \inherits Item
     \brief Specifies how to add formatted text to a scene.
 
-    Text items can display both plain and rich text. For example, red text with
-    a specific font and size can be defined like this:
+    Text items can display both plain and rich text. For example, you can define
+    red text with a specific font and size like this:
 
     \qml
     Text {
@@ -1313,25 +1313,47 @@ void QQuickTextPrivate::updateDocumentText()
     }
     \endqml
 
-    Rich text is defined using HTML-style markup:
+    Use HTML-style markup or Markdown to define rich text:
 
+    \if defined(onlinedocs)
+      \tab {build-qt-app}{tab-html}{HTML-style}{checked}
+      \tab {build-qt-app}{tab-md}{Markdown}{}
+      \tabcontent {tab-html}
+    \else
+      \section1 Using HTML-style
+    \endif
     \qml
     Text {
         text: "<b>Hello</b> <i>World!</i>"
     }
     \endqml
+    \if defined(onlinedocs)
+      \endtabcontent
+      \tabcontent {tab-md}
+    \else
+      \section1 Using Markdown
+    \endif
+    \qml
+    Text {
+        text: "**Hello** *World!*"
+    }
+    \endqml
+    \if defined(onlinedocs)
+      \endtabcontent
+    \endif
 
     \image declarative-text.png
 
-    If height and width are not explicitly set, Text will attempt to determine how
-    much room is needed and set it accordingly. Unless \l wrapMode is set, it will always
-    prefer width to height (all text will be placed on a single line).
+    If height and width are not explicitly set, Text will try to determine how
+    much room is needed and set it accordingly. Unless \l wrapMode is set, it
+    will always prefer width to height (all text will be placed on a single
+    line).
 
-    The \l elide property can alternatively be used to fit a single line of
-    plain text to a set width.
+    To fit a single line of plain text to a set width, you can use the \l elide
+    property.
 
-    Note that the \l{Supported HTML Subset} is limited. Also, if the text contains
-    HTML img tags that load remote images, the text is reloaded.
+    Note that the \l{Supported HTML Subset} is limited. Also, if the text
+    contains HTML img tags that load remote images, the text is reloaded.
 
     Text provides read-only text. For editable text, see \l TextEdit.
 
@@ -1359,7 +1381,7 @@ QQuickText::~QQuickText()
   \qmlproperty bool QtQuick::Text::clip
   This property holds whether the text is clipped.
 
-  Note that if the text does not fit in the bounding rectangle it will be abruptly chopped.
+  Note that if the text does not fit in the bounding rectangle, it will be abruptly chopped.
 
   If you want to display potentially long text in a limited space, you probably want to use \c elide instead.
 */
@@ -1448,7 +1470,8 @@ QQuickText::~QQuickText()
 
     Sets the family name of the font.
 
-    The family name is case insensitive and may optionally include a foundry name, e.g. "Helvetica [Cronyx]".
+    The family name is case insensitive and may optionally include a foundry
+    name, for example "Helvetica [Cronyx]".
     If the family is available from more than one foundry and the foundry isn't specified, an arbitrary foundry is chosen.
     If the family isn't available a family will be set using the font matching algorithm.
 */
@@ -1572,7 +1595,7 @@ QQuickText::~QQuickText()
     \value Font.PreferDefaultHinting    Use the default hinting level for the target platform.
     \value Font.PreferNoHinting         If possible, render text without hinting the outlines
            of the glyphs. The text layout will be typographically accurate, using the same metrics
-           as are used e.g. when printing.
+           as are used, for example, when printing.
     \value Font.PreferVerticalHinting   If possible, render text with no horizontal hinting,
            but align glyphs to the pixel grid in the vertical direction. The text will appear
            crisper on displays where the density is too low to give an accurate rendering
@@ -1609,7 +1632,7 @@ QQuickText::~QQuickText()
 
     Sometimes, a font will apply complex rules to a set of characters in order to
     display them correctly. In some writing systems, such as Brahmic scripts, this is
-    required in order for the text to be legible, but in e.g. Latin script, it is merely
+    required in order for the text to be legible, but in for example Latin script, it is merely
     a cosmetic feature. Setting the \c preferShaping property to false will disable all
     such features when they are not required, which will improve performance in most cases.
 
@@ -1619,6 +1642,7 @@ QQuickText::~QQuickText()
     Text { text: "Some text"; font.preferShaping: false }
     \endqml
 */
+
 QFont QQuickText::font() const
 {
     Q_D(const QQuickText);
@@ -2139,7 +2163,7 @@ void QQuickText::resetMaximumLineCount()
                                 \l {https://guides.github.com/features/mastering-markdown/}{GitHub}
                                 extensions for tables and task lists (since 5.14)
 
-    If the text format is \c Text.AutoText the Text item
+    If the text format is \c Text.AutoText, the Text item
     will automatically determine whether the text should be treated as
     styled text.  This determination is made using Qt::mightBeRichText(),
     which can detect the presence of an HTML tag on the first line of text,
@@ -2268,7 +2292,7 @@ void QQuickText::setElideMode(QQuickText::TextElideMode mode)
 /*!
     \qmlproperty url QtQuick::Text::baseUrl
 
-    This property specifies a base URL which is used to resolve relative URLs
+    This property specifies a base URL that is used to resolve relative URLs
     within the text.
 
     Urls are resolved to be within the same directory as the target of the base
@@ -2560,7 +2584,7 @@ void QQuickText::updatePolish()
     \qmlproperty real QtQuick::Text::contentWidth
 
     Returns the width of the text, including width past the width
-    which is covered due to insufficient wrapping if WrapMode is set.
+    that is covered due to insufficient wrapping if WrapMode is set.
 */
 qreal QQuickText::contentWidth() const
 {
@@ -2572,7 +2596,7 @@ qreal QQuickText::contentWidth() const
     \qmlproperty real QtQuick::Text::contentHeight
 
     Returns the height of the text, including height past the height
-    which is covered due to there being more text than fits in the set height.
+    that is covered due to there being more text than fits in the set height.
 */
 qreal QQuickText::contentHeight() const
 {
@@ -3347,7 +3371,7 @@ QJSValue QQuickText::fontInfo() const
     in a text flow.
 
     Note that the advance can be negative if the text flows from
-    the right to the left.
+    right to left.
 */
 QSizeF QQuickText::advance() const
 {