Added optional [block] option to \htmlonly

doc/commands.doc

@@ -2729,7 +2729,7 @@ class Receiver
   \sa section \ref cmdfcurlyopen "\\f{" and section \ref formulas "formulas".
 
 <hr>
-\section cmdhtmlonly \\htmlonly
+\section cmdhtmlonly \\htmlonly ["[block]"]
 
   \addindex \\htmlonly
   Starts a block of text that will be verbatim included in the
@@ -2738,9 +2738,14 @@ class Receiver
 
   This command can be used to include HTML code that is too complex
   for doxygen (i.e. applets, java-scripts, and HTML tags that
-  require attributes). You can use the \ref cmdlatexonly "\\latexonly" and 
-  \ref cmdendlatexonly "\\endlatexonly"
-  pair to provide a proper \f$\mbox{\LaTeX}\f$ alternative.
+  require specific attributes).
+
+  Normally the contents between \ref cmdhtmlonly "\\htmlonly" and
+  \ref cmdendhtmlonly "\\endhtmlonly" 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 \\htmlonly[block] to make doxygen
+  end the current paragraph and restart it after \\endhtmlonly.
 
   \note environment variables (like \$(HOME) ) are resolved inside a
   HTML-only block.

doc/install.doc

@@ -21,7 +21,7 @@
 
 First go to the 
 <a href="http://www.doxygen.org/download.html">download</a> page
-to get the latest distribution, if you did not downloaded doxygen already.
+to get the latest distribution, if you have not downloaded doxygen already.
 
 \section install_src_unix Compiling from source on UNIX
 

src/docparser.cpp

@@ -1320,7 +1320,7 @@ reparsetoken:
           {
             doctokenizerYYsetStateHtmlOnly();
             tok = doctokenizerYYlex();
-            children.append(new DocVerbatim(parent,g_context,g_token->verb,DocVerbatim::HtmlOnly,g_isExample,g_exampleName));
+            children.append(new DocVerbatim(parent,g_context,g_token->verb,DocVerbatim::HtmlOnly,g_isExample,g_exampleName,g_token->name=="block"));
             if (tok==0) warn_doc_error(g_fileName,doctokenizerYYlineno,"htmlonly section ended without end marker");
             doctokenizerYYsetStatePara();
           }
@@ -1745,10 +1745,10 @@ DocAnchor::DocAnchor(DocNode *parent,const QCString &id,bool newAnchor)
 
 DocVerbatim::DocVerbatim(DocNode *parent,const QCString &context,
     const QCString &text, Type t,bool isExample,
-    const QCString &exampleFile,const QCString &lang) 
+    const QCString &exampleFile,bool isBlock,const QCString &lang)
   : m_context(context), m_text(text), m_type(t),
     m_isExample(isExample), m_exampleFile(exampleFile),
-    m_relPath(g_relPath), m_lang(lang)
+    m_relPath(g_relPath), m_lang(lang), m_isBlock(isBlock)
 {
   m_parent = parent;
 }
@@ -5280,7 +5280,7 @@ int DocPara::handleStartCode()
     if (g_token->verb.at(i)=='\n') li=i+1;
     i++;
   }
-  m_children.append(new DocVerbatim(this,g_context,stripIndentation(g_token->verb.mid(li)),DocVerbatim::Code,g_isExample,g_exampleName,lang));
+  m_children.append(new DocVerbatim(this,g_context,stripIndentation(g_token->verb.mid(li)),DocVerbatim::Code,g_isExample,g_exampleName,FALSE,lang));
   if (retval==0) warn_doc_error(g_fileName,doctokenizerYYlineno,"code section ended without end marker");
   doctokenizerYYsetStatePara();
   return retval;
@@ -5468,7 +5468,7 @@ int DocPara::handleCommand(const QCString &cmdName)
       {
         doctokenizerYYsetStateHtmlOnly();
         retval = doctokenizerYYlex();
-        m_children.append(new DocVerbatim(this,g_context,g_token->verb,DocVerbatim::HtmlOnly,g_isExample,g_exampleName));
+        m_children.append(new DocVerbatim(this,g_context,g_token->verb,DocVerbatim::HtmlOnly,g_isExample,g_exampleName,g_token->name=="block"));
         if (retval==0) warn_doc_error(g_fileName,doctokenizerYYlineno,"htmlonly section ended without end marker");
         doctokenizerYYsetStatePara();
       }

src/docparser.h

@@ -436,7 +436,7 @@ class DocVerbatim : public DocNode
     enum Type { Code, HtmlOnly, ManOnly, LatexOnly, RtfOnly, XmlOnly, Verbatim, Dot, Msc, DocbookOnly };
     DocVerbatim(DocNode *parent,const QCString &context,
                 const QCString &text, Type t,bool isExample,
-                const QCString &exampleFile,const QCString &lang=QCString());
+                const QCString &exampleFile,bool isBlock=FALSE,const QCString &lang=QCString());
     Kind kind() const            { return Kind_Verbatim; }
     Type type() const            { return m_type; }
     QCString text() const        { return m_text; }
@@ -446,6 +446,7 @@ class DocVerbatim : public DocNode
     QCString exampleFile() const { return m_exampleFile; }
     QCString relPath() const     { return m_relPath; }
     QCString language() const    { return m_lang; }
+    bool isBlock() const         { return m_isBlock; }
 
   private:
     QCString  m_context;
@@ -455,6 +456,7 @@ class DocVerbatim : public DocNode
     QCString  m_exampleFile;
     QCString  m_relPath;
     QCString  m_lang;
+    bool      m_isBlock;
 };
 
 

src/doctokenizer.l

@@ -406,6 +406,7 @@ REFWORD   {LABELID}|{REFWORD2}|{REFWORD3}|{LNKWORD2}
 %x St_CodeOpt
 %x St_XmlCode
 %x St_HtmlOnly
+%x St_HtmlOnlyOption
 %x St_ManOnly
 %x St_LatexOnly
 %x St_RtfOnly
@@ -767,6 +768,14 @@ REFWORD   {LABELID}|{REFWORD2}|{REFWORD3}|{LNKWORD2}
 <St_Code,St_XmlCode>.           {
   			 g_token->verb+=yytext;
   		       }
+<St_HtmlOnlyOption>" [block]" { // the space is added in commentscan.l
+                         g_token->name="block";
+                         BEGIN(St_HtmlOnly);
+                        }
+<St_HtmlOnlyOption>.|\n {
+                         unput(*yytext);
+                         BEGIN(St_HtmlOnly);
+                        }
 <St_HtmlOnly>{CMD}"endhtmlonly" {
                          return RetVal_OK;
                        }
@@ -1255,7 +1264,8 @@ void doctokenizerYYsetStateXmlCode()
 void doctokenizerYYsetStateHtmlOnly()
 {
   g_token->verb="";
-  BEGIN(St_HtmlOnly);
+  g_token->name="";
+  BEGIN(St_HtmlOnlyOption);
 }
 
 void doctokenizerYYsetStateManOnly()

src/htmldocvisitor.cpp

@@ -357,7 +357,9 @@ void HtmlDocVisitor::visit(DocVerbatim *s)
       forceStartParagraph(s);
       break;
     case DocVerbatim::HtmlOnly: 
+      if (s->isBlock()) forceEndParagraph(s);
       m_t << s->text(); 
+      if (s->isBlock()) forceStartParagraph(s);
       break;
     case DocVerbatim::ManOnly: 
     case DocVerbatim::LatexOnly: 
@@ -1999,7 +2001,7 @@ void HtmlDocVisitor::forceEndParagraph(DocNode *n)
     //printf("forceEnd first=%d last=%d\n",isFirst,isLast);
     if (isFirst && isLast) return;
 
-    m_t << "</p>" << endl;
+    m_t << "</p>";
   }
 }
 

src/latexdocvisitor.cpp

@@ -175,7 +175,7 @@ void LatexDocVisitor::visit(DocURL *u)
 void LatexDocVisitor::visit(DocLineBreak *)
 {
   if (m_hide) return;
-  m_t << "\\newline\n";
+  m_t << "~\\newline\n";
 }
 
 void LatexDocVisitor::visit(DocHorRuler *)

testing/020/indexpage.xml

@@ -6,6 +6,8 @@
     <detaileddescription>
       <para>Text. <htmlonly> 
 HTML
+</htmlonly> <htmlonly>
+HTML with block
 </htmlonly> <rtfonly> 
 RTF
 </rtfonly> <manonly> 

testing/020_only.dox

@@ -5,6 +5,9 @@
  * \htmlonly
  * HTML
  * \endhtmlonly
+ * \htmlonly[block]
+ * HTML with block
+ * \endhtmlonly
  * \rtfonly
  * RTF
  * \endrtfonly