issue doxygen#8788 Quotes in inline code confuse Markdown parser

Author: doxygen

doc/Doxyfile

@@ -70,3 +70,4 @@ LATEX_EXTRA_STYLESHEET = manual.sty
 LATEX_EMOJI_DIRECTORY  = ../doc
 WARN_AS_ERROR = FAIL_ON_WARNINGS
 HTML_PROJECT_COOKIE = doxygen_docs
+MARKDOWN_STRICT = NO

src/commentcnv.l

@@ -783,15 +783,15 @@ SLASHopt [/]*
                                    }
 <VerbatimCode>"''"                 {
                                      copyToOutput(yyscanner,yytext,yyleng);
-                                     if (yyextra->blockName=="``") // support for ``text''
+                                     if (!Config_getBool(MARKDOWN_STRICT) && yyextra->blockName=="``") // support for ``text''
                                      {
                                        yyextra->inVerbatim=false;
                                        BEGIN(yyextra->lastCommentContext);
                                      }
                                    }
 <VerbatimCode>"'"                  {
                                      copyToOutput(yyscanner,yytext,yyleng);
-                                     if (yyextra->blockName=="`") // support for `text'
+                                     if (!Config_getBool(MARKDOWN_STRICT) && yyextra->blockName=="`") // support for `text'
                                      {
                                        yyextra->inVerbatim=false;
                                        BEGIN(yyextra->lastCommentContext);

src/config.xml

@@ -698,6 +698,19 @@ Go to the <a href="commands.html">next</a> section or return to the
  The output of markdown processing is further processed by Doxygen, so you
  can mix Doxygen, HTML, and XML commands with Markdown formatting.
  Disable only in case of backward compatibilities issues.
+]]>
+      </docs>
+    </option>
+    <option type='bool' id='MARKDOWN_STRICT' defval='1' depends='MARKDOWN_SUPPORT'>
+      <docs>
+<![CDATA[
+ If the \c MARKDOWN_STRICT tag is enabled then Doxygen treats text in comments as Markdown formatted
+ also in cases where Doxygen's native markup format conflicts with that of Markdown. This is only relevant
+ in cases where backticks are used. Doxygen's native markup style allows a single quote to end a
+ text fragment started with a backtick and then treat it as a piece of quoted text, whereas in Markdown such text fragment
+ is treated as verbatim and only ends when a second matching backtick is found. Also, Doxygen's native markup
+ format requires double quotes to be escaped when they appear in a backtick section, whereas this is not needed
+ for Markdown.
 ]]>
       </docs>
     </option>

src/markdown.cpp

@@ -248,7 +248,17 @@ static QCString escapeSpecialChars(const QCString &s)
     switch (c)
     {
       case '"':
-        if (pc!='\\')  { insideQuote=!insideQuote; }
+        if (pc!='\\')
+        {
+          if (Config_getBool(MARKDOWN_STRICT))
+          {
+            result+='\\';
+          }
+          else // For Doxygen's markup style a quoted text is left untouched
+          {
+            insideQuote=!insideQuote;
+          }
+        }
         result+=c;
         break;
       case '<':
@@ -1641,6 +1651,7 @@ int Markdown::Private::processCodeSpan(std::string_view data,size_t offset)
   /* finding the next delimiter with the same amount of backticks */
   size_t i = 0;
   char pc = '`';
+  bool markdownStrict = Config_getBool(MARKDOWN_STRICT);
   for (end=nb; end<size; end++)
   {
     //AUTO_TRACE_ADD("c={} nb={} i={} size={}",data[end],nb,i,size);
@@ -1688,15 +1699,15 @@ int Markdown::Private::processCodeSpan(std::string_view data,size_t offset)
       pc = '\n';
       i = 0;
     }
-    else if (data[end]=='\'' && nb==1 && (end+1==size || (end+1<size && data[end+1]!='\'' && !isIdChar(data[end+1]))))
+    else if (!markdownStrict && data[end]=='\'' && nb==1 && (end+1==size || (end+1<size && data[end+1]!='\'' && !isIdChar(data[end+1]))))
     { // look for quoted strings like 'some word', but skip strings like `it's cool`
       out+="&lsquo;";
       out+=data.substr(nb,end-nb);
       out+="&rsquo;";
       AUTO_TRACE_EXIT("quoted end={}",end+1);
       return static_cast<int>(end+1);
     }
-    else if (data[end]=='\'' && nb==2 && end+1<size && data[end+1]=='\'')
+    else if (!markdownStrict && data[end]=='\'' && nb==2 && end+1<size && data[end+1]=='\'')
     { // look for '' to match a ``
       out+="&ldquo;";
       out+=data.substr(nb,end-nb);

src/scanner.l

@@ -7337,14 +7337,14 @@ NONLopt [^\n]*
                                           }
                                         }
 <DocCopyBlock>"''"/[^a-z_A-Z0-9-]       {
-                                          if (endVerbatimBlock(yyscanner,"``",2))
+                                          if (!Config_getBool(MARKDOWN_STRICT) && endVerbatimBlock(yyscanner,"``",2))
                                           {
                                             BEGIN(DocBlock);
                                           }
                                           yyextra->docBlock << yytext;
                                         }
 <DocCopyBlock>"'"/[^'a-z_A-Z0-9-]       {
-                                          if (endVerbatimBlock(yyscanner,"`",1))
+                                          if (!Config_getBool(MARKDOWN_STRICT) && endVerbatimBlock(yyscanner,"`",1))
                                           {
                                             BEGIN(DocBlock);
                                           }

testing/110_backticks.dox

@@ -1,4 +1,5 @@
 // objective: test various forms of backtick handling
+// config: MARKDOWN_STRICT = NO
 // check: indexpage.xml
 /** @mainpage
 Text with `single` backtick.  

testing/113/md_113__markdown__strict.xml

@@ -0,0 +1,18 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<doxygen xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="compound.xsd" version="" xml:lang="en-US">
+  <compounddef id="md_113__markdown__strict" kind="page">
+    <compoundname>md_113__markdown__strict</compoundname>
+    <title>113_markdown_strict</title>
+    <briefdescription>
+    </briefdescription>
+    <detaileddescription>
+      <para>Single quote inside backtick fragment should not end the verbatim section:</para>
+      <para>Declare <computeroutput>x</computeroutput> like this <computeroutput>var x='c'</computeroutput>.</para>
+      <para>Single quote inside double backtick fragment should not end the verbatim section:</para>
+      <para>Declare <computeroutput>y</computeroutput> like this <computeroutput>var y='d'</computeroutput>.</para>
+      <para>Double quotes characters do not need to be escaped in a verbatim fragment:</para>
+      <para>Unescaped <computeroutput>"</computeroutput>quotes<computeroutput>"</computeroutput>. </para>
+    </detaileddescription>
+    <location file="113_markdown_strict.md"/>
+  </compounddef>
+</doxygen>

testing/113_markdown_strict.md

@@ -0,0 +1,17 @@
+<!--
+// objective: test markdown strict setting
+// config: MARKDOWN_STRICT = YES
+// check: md_113__markdown__strict.xml
+-->
+
+Single quote inside backtick fragment should not end the verbatim section:
+
+Declare `x` like this `var x='c'`.
+
+Single quote inside double backtick fragment should not end the verbatim section:
+
+Declare `y` like this ``var y='d'``.
+
+Double quotes characters do not need to be escaped in a verbatim fragment:
+
+Unescaped `"`quotes`"`.