HTML tag details

A HTML tag `<details>` gives the possibility to specifies additional details that the user can open and close on demand. See e.g.: https://www.w3schools.com/tags/tag_details.asp Found indifferent Fossies pakages.
doxygen · Nov 11, 2021 · 04d6629 · 04d6629
1 parent 096a1c1
commit 04d6629
Show file tree

Hide file tree

Showing 17 changed files with 26,266 additions and 25,393 deletions.
diff --git a/addon/doxmlparser/doxmlparser/compound.py b/addon/doxmlparser/doxmlparser/compound.py
diff --git a/doc/htmlcmds.doc b/doc/htmlcmds.doc
@@ -49,6 +49,8 @@ of a HTML tag are passed on to the HTML output only
 <li><tt>\</DD\></tt>   Ends an item description.
 <li><tt>\<DEL\></tt>   Starts a section of deleted text, typically shown strike through text.
 <li><tt>\</DEL\></tt>  Ends a section of deleted text.
+<li><tt>\<DETAILS\></tt>  Starts a section of detailed text that the user can open and close (in HTML output))
+<li><tt>\</DETAILS\></tt> Ends a section of detailed text.
 <li><tt>\<DFN\></tt>   Starts a piece of text displayed in a typewriter font.
 <li><tt>\</DFN\></tt>  Ends a <tt>\<DFN\></tt> section.
 <li><tt>\<DIV></tt>    Starts a section with a specific style (HTML only)

diff --git a/doc/xmlcmds.doc b/doc/xmlcmds.doc
@@ -61,8 +61,12 @@ Here is the list of tags supported by doxygen:
 <li><tt>\<see cref="member"\></tt> Refers to a member. Similar to \ref cmdref "\\ref".
 <li><tt>\<seealso cref="member"\></tt> Starts a "See also" section referring
                          to "member". Similar to using \ref cmdsa "\\sa" member.
-<li><tt>\<summary\></tt> Identifies the brief description.
+<li><tt>\<summary\></tt>
+                         In case this tag is used outside a <tt>\<details\></tt> tag this ta
+                         identifies the brief description.
                          Similar to using \ref cmdbrief "\\brief".
+                         In case this tag is used inside a <tt>\<details\></tt> tag this tag
+                         identifies the heading of the <tt>\<details\></tt> tag.
 <li><tt>\<term\></tt>    Part of a <tt>\<list\></tt> command.
 <li><tt>\<typeparam name="paramName"\></tt> Marks a piece of text as the documentation
                          for type parameter "paramName". Similar to 

diff --git a/src/cmdmapper.cpp b/src/cmdmapper.cpp
@@ -202,6 +202,7 @@ CommandMap htmlTagMap[] =
   { "u",          HTML_UNDERLINE },
   { "ins",        HTML_INS },
   { "del",        HTML_DEL },
+  { "details",    HTML_DETAILS },
 
   { "c",            XML_C },
   // { "code",       XML_CODE },  <= ambiguous <code> is also a HTML tag

diff --git a/src/cmdmapper.h b/src/cmdmapper.h
@@ -186,6 +186,7 @@ enum HtmlTagType
   HTML_INS       = 36,
   HTML_DEL       = 37,
   HTML_S         = 38,
+  HTML_DETAILS   = 39,
 
   XML_CmdMask    = 0x100,
 

diff --git a/src/commentscan.l b/src/commentscan.l
@@ -406,6 +406,7 @@ struct commentscanYY_state
 
   QCString         guardExpr;
   int              roundCount = 0;
+  int              HTMLDetails = 0;
 
   bool             insideParBlock = FALSE;
   bool             inInternalDocs = FALSE;
@@ -471,8 +472,11 @@ CODE      [cC][oO][dD][eE]
 CAPTION   [cC][aA][pP][tT][iI][oO][nN]
 CENTER    [cC][eE][nN][tT][eE][rR]
 DIV       [dD][iI][vV]
+DETAILS   [dD][eE][tT][aA][iI][lL][sS]
 DETAILEDHTML {CENTER}|{DIV}|{PRE}|{UL}|{TABLE}|{OL}|{DL}|{P}|[Hh][1-6]|{IMG}|{HR}|{PARA}
 DETAILEDHTMLOPT {CODE}
+SUMMARY   [sS][uU][mM][mM][aA][rR][yY]
+REMARKS   [rR][eE][mM][aA][rR][kK][sS]
 BN        [ \t\n\r]
 BL        [ \t\r]*"\n"
 B         [ \t]
@@ -605,19 +609,28 @@ STopt  [^\n@\\]*
                                           // continue with the same input
                                           REJECT;
                                         }
-<Comment>"<summary>"                    { // start of a .NET XML style brief description
-                                          setOutput(yyscanner,OutputBrief);
+<Comment>"<"{DETAILS}{ATTR}">"          { // start of a HTML style details description
+                                          yyextra->HTMLDetails++;
+                                          setOutput(yyscanner,OutputDoc);
                                           addOutput(yyscanner,yytext);
                                         }
-<Comment>"<remarks>"                    { // start of a .NET XML style detailed description
-                                          setOutput(yyscanner,OutputDoc);
+<Comment>"</"{DETAILS}">"               { // end of a HTML style details description
+                                          if (yyextra->HTMLDetails) yyextra->HTMLDetails--;
                                           addOutput(yyscanner,yytext);
                                         }
-<Comment>"</summary>"                   { // start of a .NET XML style detailed description
+<Comment>"<"{SUMMARY}">"                { // start of a .NET XML style brief description
+                                          if (!yyextra->HTMLDetails) setOutput(yyscanner,OutputBrief);
                                           addOutput(yyscanner,yytext);
+                                        }
+<Comment>"<"{REMARKS}">"                { // start of a .NET XML style detailed description
                                           setOutput(yyscanner,OutputDoc);
+                                          addOutput(yyscanner,yytext);
+                                        }
+<Comment>"</"{SUMMARY}">"               { // start of a .NET XML style detailed description
+                                          addOutput(yyscanner,yytext);
+                                          if (!yyextra->HTMLDetails) setOutput(yyscanner,OutputDoc);
                                         }
-<Comment>"</remarks>"                   { // end of a brief or detailed description
+<Comment>"</"{REMARKS}">"               { // end of a brief or detailed description
                                           setOutput(yyscanner,OutputDoc);
                                           addOutput(yyscanner,yytext);
                                         }

diff --git a/src/docbookvisitor.cpp b/src/docbookvisitor.cpp
@@ -302,6 +302,21 @@ DB_VIS_C
     case DocStyleChange::Ins:        break;
     case DocStyleChange::Div:  /* HTML only */ break;
     case DocStyleChange::Span: /* HTML only */ break;
+    case DocStyleChange::Details: /* emulation of the <details> tag */
+      if (s->enable())
+      {
+        m_t << "\n";
+        m_t << "<para>";
+      }
+      else
+      {
+        m_t << "</para>";
+        m_t << "\n";
+      }
+      break;
+    case DocStyleChange::Summary: /* emulation of the <summary> tag inside a <details> tag */
+      if (s->enable()) m_t << "<emphasis role=\"bold\">";      else m_t << "</emphasis>";
+      break;
   }
 }
 

diff --git a/src/docparser.cpp b/src/docparser.cpp
@@ -92,7 +92,24 @@ static const std::set<std::string> g_plantumlEngine {
 
 using DefinitionStack = std::vector<const Definition *>;
 using DocNodeStack = std::stack<const DocNode *>;
-using DocStyleChangeStack = std::stack<const DocStyleChange *>;
+//using DocStyleChangeStack = std::stack<const DocStyleChange *>;
+
+template<typename T, typename Container = std::deque<T>>
+class iterable_stack
+: public std::stack<T, Container>
+{
+    using std::stack<T, Container>::c;
+
+public:
+
+    // expose just the iterators of the underlying container
+    auto begin() { return std::begin(c); }
+    auto end() { return std::end(c); }
+
+    auto begin() const { return std::begin(c); }
+    auto end() const { return std::end(c); }
+};
+using DocStyleChangeStack = iterable_stack<const DocStyleChange *>;
 
 /** Parser's context to store all global variables.
  */
@@ -618,6 +635,15 @@ static bool insideTable(DocNode *n)
   return FALSE;
 }
 
+static const DocStyleChange *insideDetails(DocStyleChangeStack styleStack)
+{
+  const DocStyleChange *retItem = NULL;
+  for (auto i : styleStack)
+  {
+     if (i->style() == DocStyleChange::Details) retItem = i;
+  }
+  return retItem;
+}
 //---------------------------------------------------------------------------
 /*! Looks for a documentation block with name commandName in the current
  *  context (g_parserContext.context). The resulting documentation string is
@@ -995,6 +1021,8 @@ const char *DocStyleChange::styleString() const
     case DocStyleChange::Del:          return "del";
     case DocStyleChange::Underline:    return "u";
     case DocStyleChange::Ins:          return "ins";
+    case DocStyleChange::Details:      return "details";
+    case DocStyleChange::Summary:      return "summary";
   }
   return "<invalid>";
 }
@@ -1553,6 +1581,16 @@ bool DocParser::defaultHandleToken(DocNode *parent,int tok, DocNodeList &childre
               handleStyleLeave(parent,children,DocStyleChange::Ins,tokenName);
             }
             break;
+          case HTML_DETAILS:
+            if (!context.token->endTag)
+            {
+              handleStyleEnter(parent,children,DocStyleChange::Details,tokenName,&context.token->attribs);
+            }
+            else
+            {
+              handleStyleLeave(parent,children,DocStyleChange::Details,tokenName);
+            }
+            break;
           case HTML_CODE:
           case XML_C:
             if (!context.token->endTag)
@@ -2987,7 +3025,6 @@ int DocHtmlHeader::parse()
   DBG(("DocHtmlHeader::parse() end\n"));
   return retval;
 }
-
 //---------------------------------------------------------------------------
 
 int DocHRef::parse()
@@ -6020,6 +6057,9 @@ int DocPara::handleHtmlStartTag(const QCString &tagName,const HtmlAttribList &ta
     case HTML_INS:
       if (!m_parser.context.token->emptyTag) m_parser.handleStyleEnter(this,m_children,DocStyleChange::Ins,tagName,&m_parser.context.token->attribs);
       break;
+    case HTML_DETAILS:
+      if (!m_parser.context.token->emptyTag) m_parser.handleStyleEnter(this,m_children,DocStyleChange::Details,tagName,&m_parser.context.token->attribs);
+      break;
     case HTML_CODE:
       if (m_parser.context.token->emptyTag) break;
       if (/*getLanguageFromFileName(m_parser.context.fileName)==SrcLangExt_CSharp ||*/ m_parser.context.xmlComment)
@@ -6144,6 +6184,11 @@ int DocPara::handleHtmlStartTag(const QCString &tagName,const HtmlAttribList &ta
       break;
 
     case XML_SUMMARY:
+      if (insideDetails(m_parser.context.styleStack))
+      {
+        if (!m_parser.context.token->emptyTag) m_parser.handleStyleEnter(this,m_children,DocStyleChange::Summary,tagName,&m_parser.context.token->attribs);
+        break;
+      }
     case XML_REMARKS:
     case XML_EXAMPLE:
       m_parser.context.xmlComment=TRUE;
@@ -6445,6 +6490,9 @@ int DocPara::handleHtmlEndTag(const QCString &tagName)
     case HTML_INS:
       m_parser.handleStyleLeave(this,m_children,DocStyleChange::Ins,tagName);
       break;
+    case HTML_DETAILS:
+      m_parser.handleStyleLeave(this,m_children,DocStyleChange::Details,tagName);
+      break;
     case HTML_CODE:
       m_parser.handleStyleLeave(this,m_children,DocStyleChange::Code,tagName);
       break;
@@ -6537,6 +6585,11 @@ int DocPara::handleHtmlEndTag(const QCString &tagName)
       //m_children.push_back(std::make_unique<DocStyleChange>(this,(uint)m_parser.context.nodeStack.size(),DocStyleChange::Bold,FALSE));
       break;
     case XML_SUMMARY:
+      if (insideDetails(m_parser.context.styleStack))
+      {
+        m_parser.handleStyleLeave(this,m_children,DocStyleChange::Summary,tagName);
+        break;
+      }
     case XML_REMARKS:
     case XML_PARA:
     case XML_VALUE:

diff --git a/src/docparser.h b/src/docparser.h
@@ -357,7 +357,9 @@ class DocStyleChange : public DocNode
                  Underline     = (1<<11),
                  Del           = (1<<12),
                  Ins           = (1<<13),
-                 S             = (1<<14)
+                 S             = (1<<14),
+                 Details       = (1<<15),
+                 Summary       = (1<<16)
                };
 
     DocStyleChange(DocParser &parser,DocNode *parent,uint position,Style s,const QCString &tagName,bool enable,

diff --git a/src/htmldocvisitor.cpp b/src/htmldocvisitor.cpp
@@ -252,6 +252,15 @@ static QCString htmlAttribsToString(const HtmlAttribList &attribs, QCString *pAl
         result+="=\""+convertToXML(att.value)+"\"";
       }
     }
+    else if (att.name=="open")
+    {
+        // The open attribute is a boolean attribute.
+        // Specifies that the details should be visible (open) to the user
+        // As it is a boolean attribute the initialisation value is of no interest
+        result+=" ";
+        result+=att.name;
+        result+="=\"true\"";
+    }
     else if (att.name=="nowrap") // In XHTML, attribute minimization is forbidden, and the nowrap attribute must be defined as <td nowrap="nowrap">.
     {
         result+=" ";
@@ -466,7 +475,12 @@ void HtmlDocVisitor::visit(DocStyleChange *s)
     case DocStyleChange::Span:
       if (s->enable()) m_t << "<span" << htmlAttribsToString(s->attribs()) << ">";  else m_t << "</span>";
       break;
-
+    case DocStyleChange::Details:
+      if (s->enable()) m_t << "<details" << htmlAttribsToString(s->attribs()) << ">\n"; else m_t << "</details>\n";
+      break;
+    case DocStyleChange::Summary:
+      if (s->enable()) m_t << "<summary" << htmlAttribsToString(s->attribs()) << ">";  else m_t << "</summary>";
+      break;
   }
 }
 

diff --git a/src/latexdocvisitor.cpp b/src/latexdocvisitor.cpp
@@ -350,6 +350,12 @@ void LatexDocVisitor::visit(DocStyleChange *s)
       break;
     case DocStyleChange::Div:  /* HTML only */ break;
     case DocStyleChange::Span: /* HTML only */ break;
+    case DocStyleChange::Details: /* emulation of the <details> tag */
+      if (!s->enable()) m_t << "\n\n";
+      break;
+    case DocStyleChange::Summary: /* emulation of the <summary> tag inside a <details> tag */
+      if (s->enable()) m_t << "{\\bfseries{";      else m_t << "}}";
+      break;
   }
 }
 

diff --git a/src/mandocvisitor.cpp b/src/mandocvisitor.cpp
@@ -185,6 +185,18 @@ void ManDocVisitor::visit(DocStyleChange *s)
       break;
     case DocStyleChange::Div:  /* HTML only */ break;
     case DocStyleChange::Span: /* HTML only */ break;
+    case DocStyleChange::Details: /* emulation of the <details> tag */
+      if (!s->enable())
+      {
+        if (!m_firstCol) m_t << "\n";
+        m_t << ".PP\n";
+        m_firstCol=TRUE;
+      }
+      break;
+    case DocStyleChange::Summary: /* emulation of the <summary> tag inside a <details> tag */
+      if (s->enable()) m_t << "\\fB";      else m_t << "\\fP";
+      m_firstCol=FALSE;
+      break;
   }
 }
 

diff --git a/src/perlmodgen.cpp b/src/perlmodgen.cpp
@@ -652,6 +652,12 @@ void PerlModDocVisitor::visit(DocStyleChange *s)
     case DocStyleChange::Preformatted:  style = "preformatted"; break;
     case DocStyleChange::Div:           style = "div"; break;
     case DocStyleChange::Span:          style = "span"; break;
+    case DocStyleChange::Details: /* emulation of the <details> tag */
+      style = "details";
+      break;
+    case DocStyleChange::Summary: /* emulation of the <summary> tag inside a <details> tag */
+      style = "summary";
+      break;
 
   }
   openItem("style");

diff --git a/src/printdocvisitor.h b/src/printdocvisitor.h
@@ -146,6 +146,30 @@ class PrintDocVisitor : public DocVisitor
         case DocStyleChange::Span:
           if (s->enable()) printf("<span>"); else printf("</span>");
           break;
+        case DocStyleChange::Details:
+          if (s->enable())
+          {
+            indent_pre();
+            printf("<details>\n"); 
+          }
+          else 
+          {
+            indent_post();
+            printf("</details>\n");
+          }
+          break;
+        case DocStyleChange::Summary:
+          if (s->enable())
+          {
+            indent_pre();
+            printf("<summary>\n"); 
+          }
+          else 
+          {
+            indent_post();
+            printf("</summary>\n");
+          }
+          break;
       }
     }
     void visit(DocVerbatim *s)

diff --git a/src/rtfdocvisitor.cpp b/src/rtfdocvisitor.cpp
@@ -283,6 +283,22 @@ void RTFDocVisitor::visit(DocStyleChange *s)
       break;
     case DocStyleChange::Div:  /* HTML only */ break;
     case DocStyleChange::Span: /* HTML only */ break;
+    case DocStyleChange::Details: /* emulation of the <details> tag */
+      if (s->enable())
+      {
+        m_t << "{\n";
+        m_t << "\\par\n";
+      }
+      else
+      {
+        m_t << "\\par";
+        m_t << "}\n";
+      }
+      m_lastIsPara=TRUE;
+      break;
+    case DocStyleChange::Summary: /* emulation of the <summary> tag inside a <details> tag */
+      if (s->enable()) m_t << "{\\b ";      else m_t << "} ";
+      break;
   }
 }
 

diff --git a/src/xmldocvisitor.cpp b/src/xmldocvisitor.cpp
@@ -239,6 +239,12 @@ void XmlDocVisitor::visit(DocStyleChange *s)
       break;
     case DocStyleChange::Div:  /* HTML only */ break;
     case DocStyleChange::Span: /* HTML only */ break;
+    case DocStyleChange::Details:
+      if (s->enable()) m_t << "<details>";  else m_t << "</details>";
+      break;
+    case DocStyleChange::Summary:
+      if (s->enable()) m_t << "<summary>";  else m_t << "</summary>";
+      break;
   }
 }
 

diff --git a/templates/xml/compound.xsd b/templates/xml/compound.xsd
@@ -429,6 +429,8 @@
       <xsd:element name="small" type="docMarkupType" />
       <xsd:element name="del" type="docMarkupType" />
       <xsd:element name="ins" type="docMarkupType" />
+      <xsd:element name="details" type="docMarkupType" />
+      <xsd:element name="summary" type="docMarkupType" />
       <xsd:element name="htmlonly" type="docHtmlOnlyType" />
       <xsd:element name="manonly" type="xsd:string" />
       <xsd:element name="xmlonly" type="xsd:string" />