QDoc: Add support for en-dash and em-dash

This patch modifies the DocParser such that QDoc will now treat two
consecutive hyphen characters (--) as markup that outputs an en dash
character, and three hyphens (---) as markup for an em dash.

As the rules governing use of en dashes and em dashes are defined by
style guides and not grammar, QDoc is left generally permissive of
their use. However, code blocks and content that is monospaced (passed
to the \c-command), must be left untouched, as otherwise, errors,
such as the mangling of the decrement operator in code snippets, could
occur.

Also ensure that the HTML QDoc generates uses the correct HTML entity
codes.

Of course, not feature of QDoc is complete without documentation.
Even though it strictly speaking isn't a command, due to the
organization of content in the QDoc manual, add documentation for en
dash and em dash sequences to the markup command section.

[ChangeLog][QDoc][QDoc now interprets -- as en dash, and --- as em dash.]

Fixes: QTBUG-105729
Change-Id: I2b6d547dcd9d8b4f1d9348f2596c7b0abc28d039
Reviewed-by: Luca Di Sera <luca.disera@qt.io>
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>

3 files changed, 129 insertions, 0 deletions

diff --git a/src/qdoc/doc/qdoc-manual-markupcmds.qdoc b/src/qdoc/doc/qdoc-manual-markupcmds.qdoc
index 0087072f5..360111802 100644
--- a/src/qdoc/doc/qdoc-manual-markupcmds.qdoc
+++ b/src/qdoc/doc/qdoc-manual-markupcmds.qdoc
@@ -78,6 +78,8 @@
     \li \l {raw-command} {\\unicode}
     \li \l {warning-command} {\\warning}
     \li \l {backslash-sequence} {\\\\}
+    \li \l {endash-sequence} {\--}
+    \li \l {emdash-sequence} {-\--}
     \endlist
 */
 
@@ -627,6 +629,101 @@
         like this: \c {C:\windows\home\}.
     \endquotation
 
+    \target endash-sequence
+    \section1 \-- (en dash)
+    QDoc renders double hyphens as an en dash. QDoc markup commands
+    designed to make their input appear verbatim---such as the \\c
+    command---won't replace the double hyphens with an en dash character.
+    For example:
+
+        \code
+        / *!
+            The \\c command -- useful if you want text in a monospace font --
+            is well documented.
+        * /
+        \endcode
+
+        QDoc renders this as:
+
+        \quotation
+            The \\c command -- useful if you want text in a monospace font --
+            is well documented.
+        \endquotation
+
+    However, other commands may require that the hyphens are escaped to ensure
+    QDoc renders the output as expected. For example;
+
+            \code
+            / *!
+                This \l {endash-sequence}{link to the -- (endash) sequence}
+                isn't escaped and QDoc therefore renders an endash in the link
+                text. However, the escaped
+                \l {endash-sequence}{link to the \-- (endash) sequence}
+                renders both hyphens as intended.
+            * /
+            \endcode
+
+            QDoc renders this as:
+
+            \quotation
+                This \l {endash-sequence}{link to the -- (endash) sequence}
+                isn't escaped and QDoc therefore renders an endash in the link
+                text. However, the escaped
+                \l {endash-sequence}{link to the \-- (endash) sequence}
+                renders both hyphens as intended.
+            \endquotation
+
+    See also \l {emdash-sequence}{\-\-- (em dash)}.
+
+    \target emdash-sequence
+    \section1 -\-- (em dash)
+
+        QDoc renders triple hyphens as an en dash. QDoc markup commands
+        designed to make their input appear verbatim---such as the \\c
+        command---won't replace the triple hyphens with an en dash character.
+        For example:
+
+            \code
+            / *!
+                The \\c command---useful when you want text to be rendered
+                verbatim---is well documented.
+            * /
+            \endcode
+
+            QDoc renders this as:
+
+            \quotation
+                The \\c command---useful when you want text to be rendered
+                verbatim---is well documented.
+            \endquotation
+
+        However, other commands may require that the hyphens are escaped to ensure
+        QDoc renders the output as expected. For example;
+
+                \code
+                / *!
+                    This \l {emdash-sequence}{link to the --- (emdash) sequence}
+                    isn't escaped and QDoc therefore renders an emdash in the link
+                    text. However, the escaped
+                    \l {emdash-sequence}{link to the -\-- (emdash) sequence}
+                    renders both hyphens as intended.
+                * /
+                \endcode
+
+                QDoc renders this as:
+
+                \quotation
+                    This \l {emdash-sequence}{link to the --- (emdash) sequence}
+                    isn't escaped and QDoc therefore renders an emdash in the link
+                    text. However, the escaped
+                    \l {emdash-sequence}{link to the -\-- (emdash) sequence}
+                    renders both hyphens as intended.
+                \endquotation
+
+        \note The escaped control sequence in this example is for the en dash.
+              This avoids a hyphen followed by an en dash in the output.
+
+    See also \l {endash-sequence}{\-- (en dash)}.
 */
 
 
diff --git a/src/qdoc/docparser.cpp b/src/qdoc/docparser.cpp
index d408b68c5..52dfec202 100644
--- a/src/qdoc/docparser.cpp
+++ b/src/qdoc/docparser.cpp
@@ -1138,6 +1138,34 @@ void DocParser::parse(const QString &source, DocPrivate *docPrivate,
             } // case '\\' (qdoc markup command)
             break;
         }
+        case '-': { // Catch en-dash (--) and em-dash (---) markup here.
+            enterPara();
+            qsizetype dashCount = 1;
+            ++m_position;
+
+            // Figure out how many hyphens in a row.
+            while ((m_position < m_inputLength) && (m_input.at(m_position) == '-')) {
+                ++dashCount;
+                ++m_position;
+            }
+
+            if (dashCount == 3) {
+                // 3 hyphens, append an em-dash character.
+                const QChar emDash(8212);
+                appendChar(emDash);
+            } else if (dashCount == 2) {
+                // 2 hyphens; append an en-dash character.
+                const QChar enDash(8211);
+                appendChar(enDash);
+            } else {
+                // dashCount is either one or more than three. Append a hyphen
+                // the appropriate number of times. This ensures '----' doesn't
+                // end up as an em-dash followed by a hyphen in the output.
+                for (qsizetype i = 0; i < dashCount; ++i)
+                    appendChar('-');
+            }
+            break;
+        }
         case '{':
             enterPara();
             appendChar('{');
diff --git a/src/qdoc/htmlgenerator.cpp b/src/qdoc/htmlgenerator.cpp
index f260bbbbe..4772a589b 100644
--- a/src/qdoc/htmlgenerator.cpp
+++ b/src/qdoc/htmlgenerator.cpp
@@ -3402,6 +3402,10 @@ QString HtmlGenerator::protect(const QString &string)
             APPEND("&lt;");
         } else if (ch == QLatin1Char('>')) {
             APPEND("&gt;");
+        } else if (ch == QChar(8211)) {
+            APPEND("&ndash;");
+        } else if (ch == QChar(8212)) {
+            APPEND("&mdash;");
         } else if (ch == QLatin1Char('"')) {
             APPEND("&quot;");
         } else if ((ch == QLatin1Char('*') && i + 1 < n && string.at(i) == QLatin1Char('/'))