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>

1 files changed, 28 insertions, 0 deletions

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('{');