Implement Markdown definition lists (+ migration) (#20333)

Implements definition lists Markdown extension adopted in a few
implementations including:
* [Pandoc](
  https://pandoc.org/MANUAL.html#definition-lists)
* [kramdown](
  https://kramdown.gettalong.org/quickref.html#definition-lists)
* [PHP extra Markdown](
  https://michelf.ca/projects/php-markdown/extra/#def-list)

Also affected files have been migrated.
RST definition lists are turned off for Markdown: this solves the
problem of broken formatting mentioned in
https://github.com/nim-lang/Nim/pull/20292.

1 files changed, 108 insertions, 28 deletions

diff --git a/tests/stdlib/trst.nim b/tests/stdlib/trst.nim
index f9150e02d..a92ab2daa 100644
--- a/tests/stdlib/trst.nim
+++ b/tests/stdlib/trst.nim
@@ -423,21 +423,21 @@ suite "RST parsing":
         .. Note:: deflist:
                     >> quote
                     continuation
-        """.toAst == expected)
+        """.toAst(rstOptions = preferRst) == expected)
 
     check(dedent"""
         .. Note::
            deflist:
              >> quote
              continuation
-        """.toAst == expected)
+        """.toAst(rstOptions = preferRst) == expected)
 
     check(dedent"""
         .. Note::
            deflist:
              >> quote
              >> continuation
-        """.toAst == expected)
+        """.toAst(rstOptions = preferRst) == expected)
 
     # spaces are not significant between `>`:
     check(dedent"""
@@ -445,7 +445,7 @@ suite "RST parsing":
            deflist:
              > > quote
              > > continuation
-        """.toAst == expected)
+        """.toAst(rstOptions = preferRst) == expected)
 
   test "Markdown quoted blocks: de-indent handled well":
     check(dedent"""
@@ -616,27 +616,28 @@ suite "RST parsing":
     check inputTilde.toAst == expected
 
   test "option list has priority over definition list":
-    check(dedent"""
-        --defusages
-                      file
-        -o            set
-        """.toAst ==
-      dedent"""
-        rnOptionList
-          rnOptionListItem  order=1
-            rnOptionGroup
-              rnLeaf  '--'
-              rnLeaf  'defusages'
-            rnDescription
-              rnInner
-                rnLeaf  'file'
-          rnOptionListItem  order=2
-            rnOptionGroup
-              rnLeaf  '-'
-              rnLeaf  'o'
-            rnDescription
-              rnLeaf  'set'
-        """)
+    for opt in [preferMarkdown, preferRst]:
+      check(dedent"""
+          --defusages
+                        file
+          -o            set
+          """.toAst(rstOptions = opt) ==
+        dedent"""
+          rnOptionList
+            rnOptionListItem  order=1
+              rnOptionGroup
+                rnLeaf  '--'
+                rnLeaf  'defusages'
+              rnDescription
+                rnInner
+                  rnLeaf  'file'
+            rnOptionListItem  order=2
+              rnOptionGroup
+                rnLeaf  '-'
+                rnLeaf  'o'
+              rnDescription
+                rnLeaf  'set'
+          """)
 
   test "items of 1 option list can be separated by blank lines":
     check(dedent"""
@@ -660,13 +661,13 @@ suite "RST parsing":
               rnLeaf  'desc2'
       """)
 
-  test "option list has priority over definition list":
+  test "definition list does not gobble up the following blocks":
     check(dedent"""
         defName
             defBody
 
         -b  desc2
-        """.toAst ==
+        """.toAst(rstOptions = preferRst) ==
       dedent"""
         rnInner
           rnDefList
@@ -1054,7 +1055,7 @@ suite "RST indentation":
          term2
            Definition2
     """
-    check(input.toAst == dedent"""
+    check(input.toAst(rstOptions = preferRst) == dedent"""
       rnEnumList  labelFmt=1)
         rnEnumItem
           rnAdmonition  adType=hint
@@ -1157,6 +1158,85 @@ suite "RST indentation":
     # "template..." should be parsed as a definition list attached to ":test:":
     check inputWrong.toAst != ast
 
+  test "Markdown definition lists work in conjunction with bullet lists":
+    check(dedent"""
+        * some term
+          : the definition
+
+        Paragraph.""".toAst ==
+      dedent"""
+        rnInner
+          rnBulletList
+            rnBulletItem
+              rnMdDefList
+                rnDefItem
+                  rnDefName
+                    rnLeaf  'some'
+                    rnLeaf  ' '
+                    rnLeaf  'term'
+                  rnDefBody
+                    rnInner
+                      rnLeaf  'the'
+                      rnLeaf  ' '
+                      rnLeaf  'definition'
+          rnParagraph
+            rnLeaf  'Paragraph'
+            rnLeaf  '.'
+      """)
+
+  test "Markdown definition lists work with blank lines and extra paragraphs":
+    check(dedent"""
+        Term1
+
+        :   Definition1
+
+        Term2 *inline markup*
+
+        :   Definition2
+
+            Paragraph2
+
+        Term3
+        : * point1
+          * point2
+        : term3definition2
+      """.toAst == dedent"""
+        rnMdDefList
+          rnDefItem
+            rnDefName
+              rnLeaf  'Term1'
+            rnDefBody
+              rnInner
+                rnLeaf  'Definition1'
+          rnDefItem
+            rnDefName
+              rnLeaf  'Term2'
+              rnLeaf  ' '
+              rnEmphasis
+                rnLeaf  'inline'
+                rnLeaf  ' '
+                rnLeaf  'markup'
+            rnDefBody
+              rnParagraph
+                rnLeaf  'Definition2'
+              rnParagraph
+                rnLeaf  'Paragraph2'
+          rnDefItem
+            rnDefName
+              rnLeaf  'Term3'
+            rnDefBody
+              rnBulletList
+                rnBulletItem
+                  rnInner
+                    rnLeaf  'point1'
+                rnBulletItem
+                  rnInner
+                    rnLeaf  'point2'
+            rnDefBody
+              rnInner
+                rnLeaf  'term3definition2'
+      """)
+
 suite "Warnings":
   test "warnings for broken footnotes/links/substitutions":
     let input = dedent"""