Incorrect number tag sequence for xhtml with htmlinclude command poss…

…ible

Analogous to the `\htmlonly` also with the `\htmlinclude` command it is possible that some parts are added that cannot be inside a `<p> ... <\/p>` and thus we have to temporary close (and later reopen) the paragraph.
The option `[block]` has been added to the `\htmlinclude` command (analogous to the `\htmlonly` command).
Problem can be seen with the default doxygen test 30 (`[030_htmlinclude.dox]: test the \htmlinclude command`).

doc/commands.doc

@@ -2457,17 +2457,25 @@ Commands for displaying examples
   \ref cfg_example_path "EXAMPLE_PATH" tag of doxygen's configuration file.
 
 <hr>
-\section cmdhtmlinclude \\htmlinclude <file-name>
+\section cmdhtmlinclude \\htmlinclude ["[block]"] <file-name>
 
   \addindex \\htmlinclude
   This command includes the file \<file-name\> as is in the HTML documentation.
   The command is equivalent to pasting the file in the documentation and
   placing \ref cmdhtmlonly "\\htmlonly" and \ref cmdendhtmlonly "\\endhtmlonly"
   commands around it.
 
+  Normally the contents of the file indicated by \ref cmdhtmlinclude "\\htmlinclude"
+  is inserted as-is. When you
+  want to insert a HTML fragment that has block scope like a table or list
+  which should appear outside \<p\>..\</p\>, this can lead to invalid HTML.
+  You can use \\htmlinclude[block] to make doxygen
+  end the current paragraph and restart after the file is included.
+
   Files or directories that doxygen should look for can be specified using the
   \ref cfg_example_path "EXAMPLE_PATH" tag of doxygen's configuration file.
 
+  \sa section \ref cmdhtmlonly "\\htmlonly". 
 <hr>
 
 \section cmdlatexinclude \\latexinclude <file-name>
@@ -3126,8 +3134,9 @@ class Receiver
   \sa section \ref cmdmanonly "\\manonly", 
               \ref cmdlatexonly "\\latexonly", 
               \ref cmdrtfonly "\\rtfonly", 
-              \ref cmdxmlonly "\\xmlonly", and 
-              \ref cmddocbookonly "\\docbookonly".
+              \ref cmdxmlonly "\\xmlonly",
+              \ref cmddocbookonly "\\docbookonly", and
+              \ref cmdhtmlinclude "\\htmlinclude".
 
 <hr>
 \section cmdimage \\image['{'[option]'}'] <format> <file> ["caption"] [<sizeindication>=<size>]

src/docparser.cpp

@@ -5238,6 +5238,7 @@ void DocPara::handleInclude(const QCString &cmdName,DocInclude::Type t)
 {
   DBG(("handleInclude(%s)\n",qPrint(cmdName)));
   int tok=doctokenizerYYlex();
+  bool isBlock = false;
   if (tok==TK_WORD && g_token->name=="{")
   {
     doctokenizerYYsetStateOptions();
@@ -5262,6 +5263,14 @@ void DocPara::handleInclude(const QCString &cmdName,DocInclude::Type t)
     }
     tok=doctokenizerYYlex();
   }
+  else if (tok==TK_WORD && g_token->name=="[")
+  {
+    doctokenizerYYsetStateBlock();
+    tok=doctokenizerYYlex();
+    isBlock = (g_token->name.stripWhiteSpace() == "block");
+    doctokenizerYYsetStatePara();
+    tok=doctokenizerYYlex();
+  }
   else if (tok!=TK_WHITESPACE)
   {
     warn_doc_error(g_fileName,doctokenizerYYlineno,"expected whitespace after %s command",
@@ -5320,7 +5329,7 @@ void DocPara::handleInclude(const QCString &cmdName,DocInclude::Type t)
   }
   else
   {
-    DocInclude *inc = new DocInclude(this,fileName,g_context,t,g_isExample,g_exampleName,blockId);
+    DocInclude *inc = new DocInclude(this,fileName,g_context,t,g_isExample,g_exampleName,blockId,isBlock);
     m_children.append(inc);
     inc->parse();
   }

src/docparser.h

@@ -555,10 +555,10 @@ class DocInclude : public DocNode
     DocInclude(DocNode *parent,const QCString &file,
                const QCString context, Type t,
                bool isExample,const QCString exampleFile,
-               const QCString blockId) : 
+               const QCString blockId, bool isBlock) : 
       m_file(file), m_context(context), m_type(t),
       m_isExample(isExample), m_exampleFile(exampleFile),
-      m_blockId(blockId) { m_parent = parent; }
+      m_blockId(blockId), m_isBlock(isBlock) { m_parent = parent; }
     Kind kind() const            { return Kind_Include; }
     QCString file() const        { return m_file; }
     QCString extension() const   { int i=m_file.findRev('.'); 
@@ -573,6 +573,7 @@ class DocInclude : public DocNode
     QCString blockId() const     { return m_blockId; }
     bool isExample() const       { return m_isExample; }
     QCString exampleFile() const { return m_exampleFile; }
+    bool isBlock() const         { return m_isBlock; }
     void accept(DocVisitor *v)   { v->visit(this); }
     void parse();
 
@@ -582,6 +583,7 @@ class DocInclude : public DocNode
     QCString  m_text;
     Type      m_type;
     bool      m_isExample;
+    bool      m_isBlock;
     QCString  m_exampleFile;
     QCString  m_blockId;
 };

src/doctokenizer.h

@@ -166,5 +166,6 @@ void doctokenizerYYsetStatePlantUML();
 void doctokenizerYYsetStateSetScope();
 void doctokenizerYYsetStatePlantUMLOpt();
 void doctokenizerYYsetStateOptions();
+void doctokenizerYYsetStateBlock();
 
 #endif

src/doctokenizer.l

@@ -455,6 +455,7 @@ REFWORD_NOCV   {FILEMASK}|{LABELID}|{REFWORD2_NOCV}|{REFWORD3}|{REFWORD4_NOCV}
 %x St_SetScope
 %x St_SetScopeEnd
 %x St_Options
+%x St_Block
 
 %x St_Sections
 %s St_SecLabel1
@@ -1219,6 +1220,12 @@ REFWORD_NOCV   {FILEMASK}|{LABELID}|{REFWORD2_NOCV}|{REFWORD3}|{REFWORD4_NOCV}
 <St_Options>"}"        {
                          return TK_WORD;
                        }
+<St_Block>{ID}         {
+                         g_token->name+=yytext;
+                       }
+<St_Block>"]"          {
+                         return TK_WORD;
+                       }
 <St_File>{FILEMASK}    {
   			 g_token->name = yytext;
 			 return TK_WORD;  
@@ -1587,6 +1594,12 @@ void doctokenizerYYsetStateOptions()
   BEGIN(St_Options);
 }
 
+void doctokenizerYYsetStateBlock()
+{
+  g_token->name="";
+  BEGIN(St_Block);
+}
+
 void doctokenizerYYcleanup()
 {
   yy_delete_buffer( YY_CURRENT_BUFFER );

src/htmldocvisitor.cpp

@@ -608,7 +608,12 @@ void HtmlDocVisitor::visit(DocInclude *inc)
     case DocInclude::DontInclude: 
       break;
     case DocInclude::HtmlInclude: 
-      m_t << inc->text(); 
+      {
+        bool forced = false;
+        if (inc->isBlock()) forced  = forceEndParagraph(inc);
+        m_t << inc->text();
+        if (inc->isBlock()) forceStartParagraph(inc, forced);
+      }
       break;
     case DocInclude::LatexInclude:
       break;

src/printdocvisitor.h

@@ -187,7 +187,10 @@ class PrintDocVisitor : public DocVisitor
         case DocInclude::Include: printf("include"); break;
         case DocInclude::IncWithLines: printf("incwithlines"); break;
         case DocInclude::DontInclude: printf("dontinclude"); break;
-        case DocInclude::HtmlInclude: printf("htmlinclude"); break;
+        case DocInclude::HtmlInclude:
+               printf("htmlinclude");
+               if (inc->isBlock()) printf(" block=\"yes\"");
+               break;
         case DocInclude::LatexInclude: printf("latexinclude"); break;
         case DocInclude::VerbInclude: printf("verbinclude"); break;
         case DocInclude::Snippet: printf("snippet"); break;

src/xmldocvisitor.cpp

@@ -329,7 +329,14 @@ void XmlDocVisitor::visit(DocInclude *inc)
     case DocInclude::DontInclude: 
       break;
     case DocInclude::HtmlInclude: 
-      m_t << "<htmlonly>";
+      if (inc->isBlock())
+      {
+        m_t << "<htmlonly block=\"yes\">";
+      }
+      else
+      {
+        m_t << "<htmlonly>";
+      }
       filter(inc->text());
       m_t << "</htmlonly>";
       break;

testing/030/indexpage.xml

@@ -6,7 +6,7 @@
     <briefdescription>
     </briefdescription>
     <detaileddescription>
-      <para>Some text. <htmlonly>&lt;h1&gt;Hello world&lt;/h1&gt;
+      <para>Some text. <htmlonly block="yes">&lt;h1&gt;Hello world&lt;/h1&gt;
 </htmlonly> More text. </para>
     </detaileddescription>
   </compounddef>

testing/030_htmlinclude.dox

@@ -2,6 +2,6 @@
 // check: indexpage.xml
 /** \mainpage
  * Some text.
- * \htmlinclude sample.html
+ * \htmlinclude[block] sample.html
  * More text.
  */