issued #7589 Add Markdown todo list

Adding check boxes available by means of indicators `- [ ]` /  `- [x]` / `- [X]`.
Adding checkbox possibilities to the different output formats
Updating documentation

Small example: [example.tar.gz](https://github.com/doxygen/doxygen/files/4226518/example.tar.gz)

This actually the same implementation as with the original proposed pull request #7602 though due to changes in time it was not easy (possible) to merge the original against  master

Author: albert-github

addon/doxmlparser/doxmlparser/compound.py

@@ -989,6 +989,11 @@ class DoxBool(str, Enum):
     NO='no'
 
 
+class DoxCheck(str, Enum):
+    CHECKED='checked'
+    UNCHECKED='unchecked'
+
+
 class DoxCompoundKind(str, Enum):
     CLASS='class'
     STRUCT='struct'
@@ -17381,12 +17386,14 @@ class docListItemType(GeneratedsSuper):
     __hash__ = GeneratedsSuper.__hash__
     subclass = None
     superclass = None
-    def __init__(self, value=None, para=None, gds_collector_=None, **kwargs_):
+    def __init__(self, override=None, value=None, para=None, gds_collector_=None, **kwargs_):
         self.gds_collector_ = gds_collector_
         self.gds_elementtree_node_ = None
         self.original_tagname_ = None
         self.parent_object_ = kwargs_.get('parent_object_')
         self.ns_prefix_ = None
+        self.override = _cast(None, override)
+        self.override_nsprefix_ = None
         self.value = _cast(int, value)
         self.value_nsprefix_ = None
         if para is None:
@@ -17419,10 +17426,27 @@ def insert_para_at(self, index, value):
         self.para.insert(index, value)
     def replace_para_at(self, index, value):
         self.para[index] = value
+    def get_override(self):
+        return self.override
+    def set_override(self, override):
+        self.override = override
     def get_value(self):
         return self.value
     def set_value(self, value):
         self.value = value
+    def validate_DoxCheck(self, value):
+        # Validate type DoxCheck, a restriction on xsd:string.
+        if value is not None and Validate_simpletypes_ and self.gds_collector_ is not None:
+            if not isinstance(value, str):
+                lineno = self.gds_get_node_lineno_()
+                self.gds_collector_.add_message('Value "%(value)s"%(lineno)s is not of the correct base simple type (str)' % {"value": value, "lineno": lineno, })
+                return False
+            value = value
+            enumerations = ['checked', 'unchecked']
+            if value not in enumerations:
+                lineno = self.gds_get_node_lineno_()
+                self.gds_collector_.add_message('Value "%(value)s"%(lineno)s does not match xsd enumeration restriction on DoxCheck' % {"value" : encode_str_2_3(value), "lineno": lineno} )
+                result = False
     def hasContent_(self):
         if (
             self.para
@@ -17454,6 +17478,9 @@ def export(self, outfile, level, namespaceprefix_='', namespacedef_='', name_='d
         else:
             outfile.write('/>%s' % (eol_, ))
     def exportAttributes(self, outfile, level, already_processed, namespaceprefix_='', name_='docListItemType'):
+        if self.override is not None and 'override' not in already_processed:
+            already_processed.add('override')
+            outfile.write(' override=%s' % (self.gds_encode(self.gds_format_string(quote_attrib(self.override), input_name='override')), ))
         if self.value is not None and 'value' not in already_processed:
             already_processed.add('value')
             outfile.write(' value="%s"' % self.gds_format_integer(self.value, input_name='value'))
@@ -17477,6 +17504,11 @@ def build(self, node, gds_collector_=None):
             self.buildChildren(child, node, nodeName_, gds_collector_=gds_collector_)
         return self
     def buildAttributes(self, node, attrs, already_processed):
+        value = find_attr_value_('override', node)
+        if value is not None and 'override' not in already_processed:
+            already_processed.add('override')
+            self.override = value
+            self.validate_DoxCheck(self.override)    # validate type DoxCheck
         value = find_attr_value_('value', node)
         if value is not None and 'value' not in already_processed:
             already_processed.add('value')

doc/lists.dox

@@ -11,6 +11,10 @@ sign also plus (`+`) or asterisk (`*`) can be used.
 Numbered lists can also be generated by using a minus followed by a hash (`#`)
 or by using a number followed by a dot.
 
+Lists with as indicator a checked or unchecked check box are possible when having
+a minus followed by optional spaces and followed by `[ ]` for an unchecked
+check box and `[x]` or `[X]` for a checked check box.
+
 Nesting of lists is allowed and is based on indentation of the items.<p>
 Here is an example:
 
@@ -25,6 +29,9 @@ Here is an example:
    *    - keyboard events
    *         1. key down event
    *         2. key up event
+   *    - checbox list
+   *         - [ ] unchecked
+   *         - [x] checked
    *
    *  More text here.
    */
@@ -40,6 +47,9 @@ Here is an example:
        - keyboard events
             1. key down event
             2. key up event
+       - checbox list
+            - [ ] unchecked
+            - [x] checked
 
      More text here.
 

doc/markdown.dox

@@ -724,6 +724,12 @@ lists by using `-#` markers:
 
     -# item1
     -# item2
+Lists with as indicator a checked or unchecked check box are by using
+`- [ ]` or `- [x]` or `- [X]` as markers:
+
+    - [ ] unchecked
+    - [x] checked
+
 
 \subsection mddox_stars Use of asterisks
 

src/docbookvisitor.cpp

@@ -619,7 +619,19 @@ void DocbookDocVisitor::operator()(const DocAutoListItem &li)
 {
 DB_VIS_C
   if (m_hide) return;
-  m_t << "<listitem>";
+  switch (li.itemNumber())
+  {
+    case DocAutoList::Unchecked: // unchecked
+      m_t << "<listitem override=\"unchecked\">";
+      break;
+    case DocAutoList::Checked_x: // checked with x
+    case DocAutoList::Checked_X: // checked with X
+      m_t << "<listitem override=\"checked\">";
+      break;
+    default:
+      m_t << "<listitem>";
+      break;
+  }
   visitChildren(li);
   m_t << "</listitem>";
 }

src/docnode.cpp

@@ -2714,9 +2714,9 @@ int DocAutoListItem::parse()
 //--------------------------------------------------------------------------
 
 DocAutoList::DocAutoList(DocParser *parser,DocNodeVariant *parent,int indent,bool isEnumList,
-                         int depth) :
+                         int depth, bool isCheckedList):
       DocCompoundNode(parser,parent), m_indent(indent), m_isEnumList(isEnumList),
-      m_depth(depth)
+      m_depth(depth),m_isCheckedList(isCheckedList)
 {
 }
 
@@ -2730,10 +2730,20 @@ int DocAutoList::parse()
 	  // first item or sub list => create new list
   do
   {
-    if (parser()->context.token->id!=-1) // explicitly numbered list
+    switch (parser()->context.token->id)
     {
-      num=parser()->context.token->id;  // override num with real number given
+      case -1:
+        break;
+      case DocAutoList::Unchecked: // unchecked
+      case DocAutoList::Checked_x: // checked with x
+      case DocAutoList::Checked_X: // checked with X
+        num = parser()->context.token->id;
+        break;
+      default: // explicitly numbered list
+        num=parser()->context.token->id;  // override num with real number given
+        break;
     }
+
     children().append<DocAutoListItem>(parser(),thisVariant(),m_indent,num++);
     retval = children().get_last<DocAutoListItem>()->parse();
     //printf("DocAutoList::parse(): retval=0x%x parser()->context.token->indent=%d m_indent=%d "
@@ -2745,7 +2755,8 @@ int DocAutoList::parse()
   while (retval==TK_LISTITEM &&                // new list item
          m_indent==parser()->context.token->indent &&          // at same indent level
 	 m_isEnumList==parser()->context.token->isEnumList &&  // of the same kind
-         (parser()->context.token->id==-1 || parser()->context.token->id>=num)  // increasing number (or no number)
+         m_isCheckedList==parser()->context.token->isCheckedList &&  // of the same kind
+         (parser()->context.token->id==-1 || parser()->context.token->id>=num)  // increasing number (or no number or checked list)
         );
 
   parser()->tokenizer.endAutoList();
@@ -5344,7 +5355,8 @@ int DocPara::parse()
           {
             children().append<DocAutoList>(parser(),thisVariant(),
                                            parser()->context.token->indent,
-                                           parser()->context.token->isEnumList,depth);
+                                           parser()->context.token->isEnumList,depth,
+                                           parser()->context.token->isCheckedList);
             al = children().get_last<DocAutoList>();
             retval = children().get_last<DocAutoList>()->parse();
           } while (retval==TK_LISTITEM &&                   // new list

src/docnode.h

@@ -546,15 +546,23 @@ class DocIndexEntry : public DocNode
 class DocAutoList : public DocCompoundNode
 {
   public:
-    DocAutoList(DocParser *parser,DocNodeVariant *parent,int indent,bool isEnumList,int depth);
+    enum ListType
+    {
+       Unnumbered=1, Unchecked=-2, Checked_x=-3, Checked_X=-4 // positive numbers give the label
+    };
+    DocAutoList(DocParser *parser,DocNodeVariant *parent,int indent,bool isEnumList,
+                         int depth, bool isCheckedList);
+
     bool isEnumList() const    { return m_isEnumList; }
     int  indent() const        { return m_indent; }
+    bool isCheckedList() const { return m_isCheckedList; }
     int depth() const          { return m_depth; }
     int parse();
 
   private:
     int      m_indent = 0;
     bool     m_isEnumList = false;
+    bool     m_isCheckedList = false;
     int      m_depth = 0;
 };
 

src/doctokenizer.h

@@ -83,6 +83,7 @@ struct TokenInfo
 
   // list token info
   bool isEnumList = false;
+  bool isCheckedList = false;
   int indent = 0;
 
   // sections

src/doctokenizer.l

@@ -47,6 +47,7 @@ typedef yyguts_t *yyscan_t;
 #include "cite.h"
 #include "regex.h"
 #include "debug.h"
+#include "docnode.h"
 
 #define YY_NO_INPUT 1
 #define YY_NO_UNISTD_H 1
@@ -272,6 +273,7 @@ OPTSTARS  ("/""/"{BLANK}*)?"*"*{BLANK}*
 LISTITEM  {BLANK}*[-]("#")?{WS}
 MLISTITEM {BLANK}*[+*]{WS}
 OLISTITEM {BLANK}*[1-9][0-9]*"."{BLANK}
+CLISTITEM {BLANK}*[-]{BLANK}*"\["[ xX]"\]"
 ENDLIST   {BLANK}*"."{BLANK}*(\n|"\\ilinebr")
 ATTRNAME  [a-z_A-Z\x80-\xFF][:a-z_A-Z0-9\x80-\xFF\-]*
 ATTRIB    {ATTRNAME}{WS}*("="{WS}*(("\""[^\"]*"\"")|("'"[^\']*"'")|[^ \t\r\n'"><]+))?
@@ -414,10 +416,22 @@ SHOWDATE ([0-9]{4}"-"[0-9]{1,2}"-"[0-9]{1,2})?({WS}*[0-9]{1,2}":"[0-9]{1,2}(":"[
                          uint32_t dashPos = static_cast<uint32_t>(text.findRev('-'));
                          assert(dashPos!=static_cast<uint32_t>(-1));
                          yyextra->token.isEnumList = text.at(dashPos+1)=='#';
+                         yyextra->token.isCheckedList = false;
                          yyextra->token.id         = -1;
                          yyextra->token.indent     = computeIndent(yytext,dashPos);
                          return TK_LISTITEM;
                        }
+<St_Para>^{CLISTITEM}  { /* checkbox item */
+                         QCString text=yytext;
+                         int dashPos = text.findRev('-');
+                         yyextra->token.isEnumList = false;
+                         yyextra->token.isCheckedList = true;
+                         if (text.find('x') != -1) yyextra->token.id = DocAutoList::Checked_x;
+                         else if (text.find('X') != -1) yyextra->token.id = DocAutoList::Checked_X;
+                         else yyextra->token.id = DocAutoList::Unchecked;
+                         yyextra->token.indent     = computeIndent(yytext,dashPos);
+                         return TK_LISTITEM;
+                       }
 <St_Para>^{MLISTITEM}  { /* list item */
                          if (yyextra->insideHtmlLink || !yyextra->markdownSupport || yyextra->insidePre)
                          {
@@ -432,7 +446,8 @@ SHOWDATE ([0-9]{4}"-"[0-9]{1,2}"-"[0-9]{1,2})?({WS}*[0-9]{1,2}":"[0-9]{1,2}(":"[
                            reg::search(text,match,re);
                            size_t listPos = match.position();
                            assert(listPos!=std::string::npos);
-                           yyextra->token.isEnumList = FALSE;
+                           yyextra->token.isEnumList = false;
+                           yyextra->token.isCheckedList = false;
                            yyextra->token.id         = -1;
                            yyextra->token.indent     = computeIndent(yytext,listPos);
                            return TK_LISTITEM;
@@ -452,6 +467,7 @@ SHOWDATE ([0-9]{4}"-"[0-9]{1,2}"-"[0-9]{1,2})?({WS}*[0-9]{1,2}":"[0-9]{1,2}(":"[
                            size_t markPos = match.position();
                            assert(markPos!=std::string::npos);
                            yyextra->token.isEnumList = true;
+                           yyextra->token.isCheckedList = false;
                            bool ok = false;
                            int id = QCString(match.str()).toInt(&ok);
                            yyextra->token.id = ok ? id : -1;
@@ -470,10 +486,23 @@ SHOWDATE ([0-9]{4}"-"[0-9]{1,2}"-"[0-9]{1,2})?({WS}*[0-9]{1,2}":"[0-9]{1,2}(":"[
                          uint32_t dashPos = static_cast<uint32_t>(text.findRev('-'));
                          assert(dashPos!=static_cast<uint32_t>(-1));
                          yyextra->token.isEnumList = text.at(dashPos+1)=='#';
+                         yyextra->token.isCheckedList = false;
                          yyextra->token.id         = -1;
                          yyextra->token.indent     = computeIndent(text.data(),dashPos);
                          return TK_LISTITEM;
                        }
+<St_Para>{BLANK}*\n{CLISTITEM}   { /* checkbox item on next line */
+                         QCString text=yytext;
+                         text=text.right(text.length()-text.find('\n')-1);
+                         int dashPos = text.findRev('-');
+                         yyextra->token.isEnumList = false;
+                         yyextra->token.isCheckedList = true;
+                         if (text.find('x') != -1) yyextra->token.id = DocAutoList::Checked_x;
+                         else if (text.find('X') != -1) yyextra->token.id = DocAutoList::Checked_X;
+                         else yyextra->token.id = DocAutoList::Unchecked;
+                         yyextra->token.indent     = computeIndent(text.data(),dashPos);
+                         return TK_LISTITEM;
+                       }
 <St_Para>{BLANK}*(\n|"\\ilinebr"){MLISTITEM}     { /* list item on next line */
                          if (yyextra->insideHtmlLink || !yyextra->markdownSupport || yyextra->insidePre)
                          {
@@ -489,6 +518,7 @@ SHOWDATE ([0-9]{4}"-"[0-9]{1,2}"-"[0-9]{1,2})?({WS}*[0-9]{1,2}":"[0-9]{1,2}(":"[
                            size_t markPos = match.position();
                            assert(markPos!=std::string::npos);
                            yyextra->token.isEnumList = FALSE;
+                           yyextra->token.isCheckedList = false;
                            yyextra->token.id         = -1;
                            yyextra->token.indent     = computeIndent(text.c_str(),markPos);
                            return TK_LISTITEM;
@@ -509,6 +539,7 @@ SHOWDATE ([0-9]{4}"-"[0-9]{1,2}"-"[0-9]{1,2})?({WS}*[0-9]{1,2}":"[0-9]{1,2}(":"[
                            size_t markPos = match.position();
                            assert(markPos!=std::string::npos);
                            yyextra->token.isEnumList = true;
+                           yyextra->token.isCheckedList = false;
                            bool ok = false;
                            int id = QCString(match.str()).toInt(&ok);
                            yyextra->token.id = ok ? id : -1;
@@ -738,6 +769,12 @@ SHOWDATE ([0-9]{4}"-"[0-9]{1,2}"-"[0-9]{1,2})?({WS}*[0-9]{1,2}":"[0-9]{1,2}(":"[
                          }
                          lineCount(yytext,yyleng);
                        }
+<St_Para>({BLANK}*\n)+{BLANK}*\n/{CLISTITEM} { /* skip trailing paragraph followed by new checkbox item */
+                         if (yyextra->insidePre || yyextra->autoListLevel==0)
+                         {
+                           REJECT;
+                         }
+                       }
 <St_Para>({BLANK}*\n)+{BLANK}*\n/{MLISTITEM} { /* skip trailing paragraph followed by new list item */
                          if (!yyextra->markdownSupport || yyextra->insidePre || yyextra->autoListLevel==0)
                          {

src/htmldocvisitor.cpp

@@ -1028,7 +1028,14 @@ void HtmlDocVisitor::operator()(const DocAutoList &l)
   }
   else
   {
-    m_t << "<ul>";
+    if (l.isCheckedList())
+    {
+      m_t << "<ul class=\"check\">";
+    }
+    else
+    {
+      m_t << "<ul>";
+    }
   }
   if (!l.isPreformatted()) m_t << "\n";
   visitChildren(l);
@@ -1047,7 +1054,19 @@ void HtmlDocVisitor::operator()(const DocAutoList &l)
 void HtmlDocVisitor::operator()(const DocAutoListItem &li)
 {
   if (m_hide) return;
-  m_t << "<li>";
+  switch (li.itemNumber())
+  {
+    case DocAutoList::Unchecked: // unchecked
+      m_t << "<li class=\"unchecked\">";
+      break;
+    case DocAutoList::Checked_x: // checked with x
+    case DocAutoList::Checked_X: // checked with X
+      m_t << "<li class=\"checked\">";
+      break;
+    default:
+      m_t << "<li>";
+      break;
+  }
   visitChildren(li);
   m_t << "</li>";
   if (!li.isPreformatted()) m_t << "\n";

src/latexdocvisitor.cpp

@@ -754,7 +754,19 @@ void LatexDocVisitor::operator()(const DocAutoList &l)
 void LatexDocVisitor::operator()(const DocAutoListItem &li)
 {
   if (m_hide) return;
-  m_t << "\n\\item ";
+  switch (li.itemNumber())
+  {
+    case DocAutoList::Unchecked: // unchecked
+      m_t << "\n\\item[\\DoxyUnchecked] ";
+      break;
+    case DocAutoList::Checked_x: // checked with x
+    case DocAutoList::Checked_X: // checked with X
+      m_t << "\n\\item[\\DoxyChecked] ";
+      break;
+    default:
+      m_t << "\n\\item ";
+      break;
+  }
   incIndentLevel();
   visitChildren(li);
   decIndentLevel();