docgen: sort symbols (fix #17910) (#18560)

* docgen: sort symbols (fix #17910)

* add workaround + change naming

* switch to a dedicated sort comparator

* fix numbers with unequal string lengths

* dedicated `sortName` instead of `plainNameEsc`:

* more compact names for non-overloaded symbols
* more predictable Ascii sort (e.g. `<` instead of `&lt;`)

3 files changed, 419 insertions, 349 deletions

diff --git a/compiler/docgen.nim b/compiler/docgen.nim
index f9e72850a..492668543 100644
--- a/compiler/docgen.nim
+++ b/compiler/docgen.nim
@@ -11,7 +11,7 @@
 # by knowing how the anchors are going to be named.
 
 import
-  ast, strutils, strtabs, options, msgs, os, idents,
+  ast, strutils, strtabs, algorithm, sequtils, options, msgs, os, idents,
   wordrecg, syntaxes, renderer, lexer,
   packages/docutils/rst, packages/docutils/rstgen,
   json, xmltree, trees, types,
@@ -43,11 +43,15 @@ type
     descRst: ItemPre     ## Description of the item (may contain
                          ## runnableExamples).
     substitutions: seq[string]    ## Variable names in `doc.item`...
+    sortName: string    ## The string used for sorting in output
   ModSection = object  ## Section like Procs, Types, etc.
     secItems: seq[Item]  ## Pre-processed items.
     finalMarkup: string  ## The items, after RST pass 2 and rendering.
   ModSections = array[TSymKind, ModSection]
-  TSections = array[TSymKind, string]
+  TocItem = object  ## HTML TOC item
+    content: string
+    sortName: string
+  TocSectionsFinal = array[TSymKind, string]
   ExampleGroup = ref object
     ## a group of runnableExamples with same rdoccmd
     rdoccmd: string ## from 1st arg in `runnableExamples(rdoccmd): body`
@@ -64,8 +68,13 @@ type
     module: PSym
     modDeprecationMsg: string
     section: ModSections     # entries of ``.nim`` file (for `proc`s, etc)
-    toc, toc2: TSections     # toc2 - grouped TOC
-    tocTable: array[TSymKind, Table[string, string]]
+    tocSimple: array[TSymKind, seq[TocItem]]
+      # TOC entries for non-overloadable symbols (e.g. types, constants)...
+    tocTable:  array[TSymKind, Table[string, seq[TocItem]]]
+      # ...otherwise (e.g. procs)
+    toc2: TocSectionsFinal  # TOC `content`, which is probably wrapped
+                            # in `doc.section.toc2`
+    toc: TocSectionsFinal  # final TOC (wrapped in `doc.section.toc`)
     indexValFilename: string
     analytics: string  # Google Analytics javascript, "" if doesn't exist
     seenSymbols: StringTableRef # avoids duplicate symbol generation for HTML.
@@ -88,6 +97,51 @@ type
 proc add(dest: var ItemPre, rst: PRstNode) = dest.add ItemFragment(isRst: true, rst: rst)
 proc add(dest: var ItemPre, str: string) = dest.add ItemFragment(isRst: false, str: str)
 
+proc cmpDecimalsIgnoreCase(a, b: string): int =
+  ## For sorting with correct handling of cases like 'uint8' and 'uint16'.
+  ## Also handles leading zeros well (however note that leading zeros are
+  ## significant when lengths of numbers mismatch, e.g. 'bar08' > 'bar8' !).
+  runnableExamples:
+    doAssert cmpDecimalsIgnoreCase("uint8", "uint16") < 0
+    doAssert cmpDecimalsIgnoreCase("val00032", "val16suffix") > 0
+    doAssert cmpDecimalsIgnoreCase("val16suffix", "val16") > 0
+    doAssert cmpDecimalsIgnoreCase("val_08_32", "val_08_8") > 0
+    doAssert cmpDecimalsIgnoreCase("val_07_32", "val_08_8") < 0
+    doAssert cmpDecimalsIgnoreCase("ab8", "ab08") < 0
+    doAssert cmpDecimalsIgnoreCase("ab8de", "ab08c") < 0 # sanity check
+  let aLen = a.len
+  let bLen = b.len
+  var
+    iA = 0
+    iB = 0
+  while iA < aLen and iB < bLen:
+    if isDigit(a[iA]) and isDigit(b[iB]):
+      var
+        limitA = iA  # index after the last (least significant) digit
+        limitB = iB
+      while limitA < aLen and isDigit(a[limitA]): inc limitA
+      while limitB < bLen and isDigit(b[limitB]): inc limitB
+      var pos = max(limitA-iA, limitB-iA)
+      while pos > 0:
+        if limitA-pos < iA:  # digit in `a` is 0 effectively
+          result = ord('0') - ord(b[limitB-pos])
+        elif limitB-pos < iB:  # digit in `b` is 0 effectively
+          result = ord(a[limitA-pos]) - ord('0')
+        else:
+          result = ord(a[limitA-pos]) - ord(b[limitB-pos])
+        if result != 0: return
+        dec pos
+      result = (limitA - iA) - (limitB - iB)  # consider 'bar08' > 'bar8'
+      if result != 0: return
+      iA = limitA
+      iB = limitB
+    else:
+      result = ord(toLowerAscii(a[iA])) - ord(toLowerAscii(b[iB]))
+      if result != 0: return
+      inc iA
+      inc iB
+  result = (aLen - iA) - (bLen - iB)
+
 proc prettyString(a: object): string =
   # xxx pending std/prettyprint refs https://github.com/nim-lang/RFCs/issues/203#issuecomment-602534906
   for k, v in fieldPairs(a):
@@ -862,6 +916,7 @@ proc genItem(d: PDoc, n, nameNode: PNode, k: TSymKind, docFlags: DocFlags) =
   let
     plainNameEsc = esc(d.target, plainName.strip)
     uniqueName = if k in routineKinds: plainNameEsc else: name
+    sortName = if k in routineKinds: plainName.strip else: name
     cleanPlainSymbol = renderPlainSymbolName(nameNode)
     complexSymbol = complexName(k, n, cleanPlainSymbol)
     plainSymbolEnc = encodeUrl(cleanPlainSymbol)
@@ -874,7 +929,10 @@ proc genItem(d: PDoc, n, nameNode: PNode, k: TSymKind, docFlags: DocFlags) =
 
   let seeSrc = genSeeSrc(d, toFullPath(d.conf, n.info), n.info.line.int)
 
-  d.section[k].secItems.add Item(descRst: comm, substitutions: @[
+  d.section[k].secItems.add Item(
+    descRst: comm,
+    sortName: sortName,
+    substitutions: @[
      "name", name, "uniqueName", uniqueName,
      "header", result, "itemID", $d.id,
      "header_plain", plainNameEsc, "itemSym", cleanPlainSymbol,
@@ -898,12 +956,15 @@ proc genItem(d: PDoc, n, nameNode: PNode, k: TSymKind, docFlags: DocFlags) =
       setIndexTerm(d[], external, symbolOrId, plain, nameNode.sym.name.s & '.' & plain,
         xmltree.escape(getPlainDocstring(e).docstringSummary))
 
-  d.toc[k].add(getConfigVar(d.conf, "doc.item.toc") % [
+  d.tocSimple[k].add TocItem(
+    sortName: sortName,
+    content: getConfigVar(d.conf, "doc.item.toc") % [
       "name", name, "header_plain", plainNameEsc,
       "itemSymOrIDEnc", symbolOrIdEnc])
 
-  d.tocTable[k].mgetOrPut(cleanPlainSymbol, "").add(
-    getConfigVar(d.conf, "doc.item.tocTable") % [
+  d.tocTable[k].mgetOrPut(cleanPlainSymbol, newSeq[TocItem]()).add TocItem(
+    sortName: sortName,
+    content: getConfigVar(d.conf, "doc.item.tocTable") % [
       "name", name, "header_plain", plainNameEsc,
       "itemSymOrID", symbolOrId.replace(",", ",<wbr>"),
       "itemSymOrIDEnc", symbolOrIdEnc])
@@ -1143,8 +1204,9 @@ proc finishGenerateDoc*(d: var PDoc) =
         var resolved = resolveSubs(d.sharedState, f.rst)
         renderRstToOut(d[], resolved, result)
       of false: result &= f.str
+  proc cmp(x, y: Item): int = cmpDecimalsIgnoreCase(x.sortName, y.sortName)
   for k in TSymKind:
-    for item in d.section[k].secItems:
+    for item in d.section[k].secItems.sorted(cmp):
       var itemDesc: string
       renderItemPre(d, item.descRst, itemDesc)
       d.section[k].finalMarkup.add(
@@ -1262,18 +1324,26 @@ proc genSection(d: PDoc, kind: TSymKind, groupedToc = false) =
       "sectionid", $ord(kind), "sectionTitle", title,
       "sectionTitleID", $(ord(kind) + 50), "content", d.section[kind].finalMarkup]
 
-  var tocSource = d.toc
+  proc cmp(x, y: TocItem): int = cmpDecimalsIgnoreCase(x.sortName, y.sortName)
   if groupedToc:
-    for p in d.tocTable[kind].keys:
+    let overloadableNames = toSeq(keys(d.tocTable[kind]))
+    for plainName in overloadableNames.sorted(cmpDecimalsIgnoreCase):
+      var overloadChoices = d.tocTable[kind][plainName]
+      overloadChoices.sort(cmp)
+      var content: string
+      for item in overloadChoices:
+        content.add item.content
       d.toc2[kind].add getConfigVar(d.conf, "doc.section.toc2") % [
           "sectionid", $ord(kind), "sectionTitle", title,
           "sectionTitleID", $(ord(kind) + 50),
-          "content", d.tocTable[kind][p], "plainName", p]
-    tocSource = d.toc2
+          "content", content, "plainName", plainName]
+  else:
+    for item in d.tocSimple[kind].sorted(cmp):
+      d.toc2[kind].add item.content
 
   d.toc[kind] = getConfigVar(d.conf, "doc.section.toc") % [
       "sectionid", $ord(kind), "sectionTitle", title,
-      "sectionTitleID", $(ord(kind) + 50), "content", tocSource[kind]]
+      "sectionTitleID", $(ord(kind) + 50), "content", d.toc2[kind]]
 
 proc relLink(outDir: AbsoluteDir, destFile: AbsoluteFile, linkto: RelativeFile): string =
   $relativeTo(outDir / linkto, destFile.splitFile().dir, '/')
diff --git a/nimdoc/testproject/expected/subdir/subdir_b/utils.html b/nimdoc/testproject/expected/subdir/subdir_b/utils.html
index 6aa71e8c2..939495ad1 100644
--- a/nimdoc/testproject/expected/subdir/subdir_b/utils.html
+++ b/nimdoc/testproject/expected/subdir/subdir_b/utils.html
@@ -131,16 +131,16 @@ window.addEventListener('DOMContentLoaded', main);
     title="aEnum(): untyped">aEnum(): untyped</a></li>
 
   </ul>
-  <ul class="simple nested-toc-section">fromUtilsGen
-      <li><a class="reference" href="#fromUtilsGen.t"
-    title="fromUtilsGen(): untyped">fromUtilsGen(): untyped</a></li>
-
-  </ul>
   <ul class="simple nested-toc-section">bEnum
       <li><a class="reference" href="#bEnum.t"
     title="bEnum(): untyped">bEnum(): untyped</a></li>
 
   </ul>
+  <ul class="simple nested-toc-section">fromUtilsGen
+      <li><a class="reference" href="#fromUtilsGen.t"
+    title="fromUtilsGen(): untyped">fromUtilsGen(): untyped</a></li>
+
+  </ul>
 
   </ul>
 </li>
diff --git a/nimdoc/testproject/expected/testproject.html b/nimdoc/testproject/expected/testproject.html
index 7e5a685d2..0f6289bbc 100644
--- a/nimdoc/testproject/expected/testproject.html
+++ b/nimdoc/testproject/expected/testproject.html
@@ -107,9 +107,7 @@ window.addEventListener('DOMContentLoaded', main);
 <li>
   <a class="reference reference-toplevel" href="#7" id="57">Types</a>
   <ul class="simple simple-toc-section">
-      <li><a class="reference" href="#FooBuzz"
-    title="FooBuzz {.deprecated: &quot;FooBuzz msg&quot;.} = int">FooBuzz</a></li>
-  <li><a class="reference" href="#A"
+      <li><a class="reference" href="#A"
     title="A {.inject.} = enum
   aA">A</a></li>
   <li><a class="reference" href="#B"
@@ -118,6 +116,8 @@ window.addEventListener('DOMContentLoaded', main);
   <li><a class="reference" href="#Foo"
     title="Foo = enum
   enumValueA2">Foo</a></li>
+  <li><a class="reference" href="#FooBuzz"
+    title="FooBuzz {.deprecated: &quot;FooBuzz msg&quot;.} = int">FooBuzz</a></li>
   <li><a class="reference" href="#Shapes"
     title="Shapes = enum
   Circle,                   ## A circle
@@ -129,10 +129,10 @@ window.addEventListener('DOMContentLoaded', main);
 <li>
   <a class="reference reference-toplevel" href="#8" id="58">Vars</a>
   <ul class="simple simple-toc-section">
-      <li><a class="reference" href="#someVariable"
-    title="someVariable: bool">someVariable</a></li>
-  <li><a class="reference" href="#aVariable"
+      <li><a class="reference" href="#aVariable"
     title="aVariable: array[1, int]">aVariable</a></li>
+  <li><a class="reference" href="#someVariable"
+    title="someVariable: bool">someVariable</a></li>
 
   </ul>
 </li>
@@ -153,19 +153,24 @@ window.addEventListener('DOMContentLoaded', main);
 <li>
   <a class="reference reference-toplevel" href="#12" id="62">Procs</a>
   <ul class="simple simple-toc-section">
-      <ul class="simple nested-toc-section">z10
-      <li><a class="reference" href="#z10"
-    title="z10()">z10()</a></li>
+      <ul class="simple nested-toc-section">addfBug14485
+      <li><a class="reference" href="#addfBug14485"
+    title="addfBug14485()">addfBug14485()</a></li>
 
   </ul>
-  <ul class="simple nested-toc-section">tripleStrLitTest
-      <li><a class="reference" href="#tripleStrLitTest"
-    title="tripleStrLitTest()">tripleStrLitTest()</a></li>
+  <ul class="simple nested-toc-section">anything
+      <li><a class="reference" href="#anything"
+    title="anything()">anything()</a></li>
 
   </ul>
-  <ul class="simple nested-toc-section">z17
-      <li><a class="reference" href="#z17"
-    title="z17()">z17()</a></li>
+  <ul class="simple nested-toc-section">asyncFun1
+      <li><a class="reference" href="#asyncFun1"
+    title="asyncFun1(): Future[int]">asyncFun1(): Future[int]</a></li>
+
+  </ul>
+  <ul class="simple nested-toc-section">asyncFun2
+      <li><a class="reference" href="#asyncFun2"
+    title="asyncFun2(): owned(Future[void])">asyncFun2(): owned(Future[void])</a></li>
 
   </ul>
   <ul class="simple nested-toc-section">asyncFun3
@@ -173,16 +178,33 @@ window.addEventListener('DOMContentLoaded', main);
     title="asyncFun3(): owned(Future[void])">asyncFun3(): owned(Future[void])</a></li>
 
   </ul>
-  <ul class="simple nested-toc-section">z2
-      <li><a class="reference" href="#z2"
-    title="z2()">z2()</a></li>
-
-  </ul>
   <ul class="simple nested-toc-section">bar
       <li><a class="reference" href="#bar%2CT%2CT"
     title="bar[T](a, b: T): T">bar[T](a, b: T): T</a></li>
 
   </ul>
+  <ul class="simple nested-toc-section">baz
+      <li><a class="reference" href="#baz"
+    title="baz()">baz()</a></li>
+  <li><a class="reference" href="#baz%2CT%2CT"
+    title="baz[T](a, b: T): T">baz[T](a, b: T): T</a></li>
+
+  </ul>
+  <ul class="simple nested-toc-section">buzz
+      <li><a class="reference" href="#buzz%2CT%2CT"
+    title="buzz[T](a, b: T): T">buzz[T](a, b: T): T</a></li>
+
+  </ul>
+  <ul class="simple nested-toc-section">c_nonexistent
+      <li><a class="reference" href="#c_nonexistent%2Ccstring"
+    title="c_nonexistent(frmt: cstring): cint">c_nonexistent(frmt: cstring): cint</a></li>
+
+  </ul>
+  <ul class="simple nested-toc-section">c_printf
+      <li><a class="reference" href="#c_printf%2Ccstring"
+    title="c_printf(frmt: cstring): cint">c_printf(frmt: cstring): cint</a></li>
+
+  </ul>
   <ul class="simple nested-toc-section">fromUtils3
       <li><a class="reference" href="#fromUtils3"
     title="fromUtils3()">fromUtils3()</a></li>
@@ -193,76 +215,39 @@ window.addEventListener('DOMContentLoaded', main);
     title="isValid[T](x: T): bool">isValid[T](x: T): bool</a></li>
 
   </ul>
-  <ul class="simple nested-toc-section">z6
-      <li><a class="reference" href="#z6"
-    title="z6(): int">z6(): int</a></li>
-
-  </ul>
-  <ul class="simple nested-toc-section">anything
-      <li><a class="reference" href="#anything"
-    title="anything()">anything()</a></li>
-
-  </ul>
   <ul class="simple nested-toc-section">low
       <li><a class="reference" href="#low%2CT"
     title="low[T: Ordinal | enum | range](x: T): T">low[T: Ordinal | enum | range](x: T): T</a></li>
 
   </ul>
-  <ul class="simple nested-toc-section">p1
-      <li><a class="reference" href="#p1"
-    title="p1()">p1()</a></li>
-
-  </ul>
-  <ul class="simple nested-toc-section">z11
-      <li><a class="reference" href="#z11"
-    title="z11()">z11()</a></li>
-
-  </ul>
-  <ul class="simple nested-toc-section">c_nonexistent
-      <li><a class="reference" href="#c_nonexistent%2Ccstring"
-    title="c_nonexistent(frmt: cstring): cint">c_nonexistent(frmt: cstring): cint</a></li>
-
-  </ul>
-  <ul class="simple nested-toc-section">buzz
-      <li><a class="reference" href="#buzz%2CT%2CT"
-    title="buzz[T](a, b: T): T">buzz[T](a, b: T): T</a></li>
-
-  </ul>
   <ul class="simple nested-toc-section">low2
       <li><a class="reference" href="#low2%2CT"
     title="low2[T: Ordinal | enum | range](x: T): T">low2[T: Ordinal | enum | range](x: T): T</a></li>
 
   </ul>
-  <ul class="simple nested-toc-section">z7
-      <li><a class="reference" href="#z7"
-    title="z7(): int">z7(): int</a></li>
-
-  </ul>
-  <ul class="simple nested-toc-section">z13
-      <li><a class="reference" href="#z13"
-    title="z13()">z13()</a></li>
+  <ul class="simple nested-toc-section">p1
+      <li><a class="reference" href="#p1"
+    title="p1()">p1()</a></li>
 
   </ul>
-  <ul class="simple nested-toc-section">baz
-      <li><a class="reference" href="#baz%2CT%2CT"
-    title="baz[T](a, b: T): T">baz[T](a, b: T): T</a></li>
-  <li><a class="reference" href="#baz"
-    title="baz()">baz()</a></li>
+  <ul class="simple nested-toc-section">someFunc
+      <li><a class="reference" href="#someFunc"
+    title="someFunc()">someFunc()</a></li>
 
   </ul>
-  <ul class="simple nested-toc-section">addfBug14485
-      <li><a class="reference" href="#addfBug14485"
-    title="addfBug14485()">addfBug14485()</a></li>
+  <ul class="simple nested-toc-section">tripleStrLitTest
+      <li><a class="reference" href="#tripleStrLitTest"
+    title="tripleStrLitTest()">tripleStrLitTest()</a></li>
 
   </ul>
-  <ul class="simple nested-toc-section">c_printf
-      <li><a class="reference" href="#c_printf%2Ccstring"
-    title="c_printf(frmt: cstring): cint">c_printf(frmt: cstring): cint</a></li>
+  <ul class="simple nested-toc-section">z1
+      <li><a class="reference" href="#z1"
+    title="z1(): Foo">z1(): Foo</a></li>
 
   </ul>
-  <ul class="simple nested-toc-section">z12
-      <li><a class="reference" href="#z12"
-    title="z12(): int">z12(): int</a></li>
+  <ul class="simple nested-toc-section">z2
+      <li><a class="reference" href="#z2"
+    title="z2()">z2()</a></li>
 
   </ul>
   <ul class="simple nested-toc-section">z3
@@ -270,19 +255,24 @@ window.addEventListener('DOMContentLoaded', main);
     title="z3()">z3()</a></li>
 
   </ul>
-  <ul class="simple nested-toc-section">z9
-      <li><a class="reference" href="#z9"
-    title="z9()">z9()</a></li>
-
-  </ul>
   <ul class="simple nested-toc-section">z4
       <li><a class="reference" href="#z4"
     title="z4()">z4()</a></li>
 
   </ul>
-  <ul class="simple nested-toc-section">someFunc
-      <li><a class="reference" href="#someFunc"
-    title="someFunc()">someFunc()</a></li>
+  <ul class="simple nested-toc-section">z5
+      <li><a class="reference" href="#z5"
+    title="z5(): int">z5(): int</a></li>
+
+  </ul>
+  <ul class="simple nested-toc-section">z6
+      <li><a class="reference" href="#z6"
+    title="z6(): int">z6(): int</a></li>
+
+  </ul>
+  <ul class="simple nested-toc-section">z7
+      <li><a class="reference" href="#z7"
+    title="z7(): int">z7(): int</a></li>
 
   </ul>
   <ul class="simple nested-toc-section">z8
@@ -290,24 +280,34 @@ window.addEventListener('DOMContentLoaded', main);
     title="z8(): int">z8(): int</a></li>
 
   </ul>
-  <ul class="simple nested-toc-section">z1
-      <li><a class="reference" href="#z1"
-    title="z1(): Foo">z1(): Foo</a></li>
+  <ul class="simple nested-toc-section">z9
+      <li><a class="reference" href="#z9"
+    title="z9()">z9()</a></li>
 
   </ul>
-  <ul class="simple nested-toc-section">z5
-      <li><a class="reference" href="#z5"
-    title="z5(): int">z5(): int</a></li>
+  <ul class="simple nested-toc-section">z10
+      <li><a class="reference" href="#z10"
+    title="z10()">z10()</a></li>
 
   </ul>
-  <ul class="simple nested-toc-section">asyncFun2
-      <li><a class="reference" href="#asyncFun2"
-    title="asyncFun2(): owned(Future[void])">asyncFun2(): owned(Future[void])</a></li>
+  <ul class="simple nested-toc-section">z11
+      <li><a class="reference" href="#z11"
+    title="z11()">z11()</a></li>
 
   </ul>
-  <ul class="simple nested-toc-section">asyncFun1
-      <li><a class="reference" href="#asyncFun1"
-    title="asyncFun1(): Future[int]">asyncFun1(): Future[int]</a></li>
+  <ul class="simple nested-toc-section">z12
+      <li><a class="reference" href="#z12"
+    title="z12(): int">z12(): int</a></li>
+
+  </ul>
+  <ul class="simple nested-toc-section">z13
+      <li><a class="reference" href="#z13"
+    title="z13()">z13()</a></li>
+
+  </ul>
+  <ul class="simple nested-toc-section">z17
+      <li><a class="reference" href="#z17"
+    title="z17()">z17()</a></li>
 
   </ul>
 
@@ -316,7 +316,12 @@ window.addEventListener('DOMContentLoaded', main);
 <li>
   <a class="reference reference-toplevel" href="#14" id="64">Methods</a>
   <ul class="simple simple-toc-section">
-      <ul class="simple nested-toc-section">method2
+      <ul class="simple nested-toc-section">method1
+      <li><a class="reference" href="#method1.e%2CMoo"
+    title="method1(self: Moo)">method1(self: Moo)</a></li>
+
+  </ul>
+  <ul class="simple nested-toc-section">method2
       <li><a class="reference" href="#method2.e%2CMoo"
     title="method2(self: Moo): int">method2(self: Moo): int</a></li>
 
@@ -326,23 +331,13 @@ window.addEventListener('DOMContentLoaded', main);
     title="method3(self: Moo): int">method3(self: Moo): int</a></li>
 
   </ul>
-  <ul class="simple nested-toc-section">method1
-      <li><a class="reference" href="#method1.e%2CMoo"
-    title="method1(self: Moo)">method1(self: Moo)</a></li>
-
-  </ul>
 
   </ul>
 </li>
 <li>
   <a class="reference reference-toplevel" href="#15" id="65">Iterators</a>
   <ul class="simple simple-toc-section">
-      <ul class="simple nested-toc-section">iter2
-      <li><a class="reference" href="#iter2.i%2Cint"
-    title="iter2(n: int): int">iter2(n: int): int</a></li>
-
-  </ul>
-  <ul class="simple nested-toc-section">fromUtils1
+      <ul class="simple nested-toc-section">fromUtils1
       <li><a class="reference" href="#fromUtils1.i"
     title="fromUtils1(): int">fromUtils1(): int</a></li>
 
@@ -352,6 +347,11 @@ window.addEventListener('DOMContentLoaded', main);
     title="iter1(n: int): int">iter1(n: int): int</a></li>
 
   </ul>
+  <ul class="simple nested-toc-section">iter2
+      <li><a class="reference" href="#iter2.i%2Cint"
+    title="iter2(n: int): int">iter2(n: int): int</a></li>
+
+  </ul>
 
   </ul>
 </li>
@@ -363,27 +363,42 @@ window.addEventListener('DOMContentLoaded', main);
     title="bar(): untyped">bar(): untyped</a></li>
 
   </ul>
-  <ul class="simple nested-toc-section">z18
-      <li><a class="reference" href="#z18.m"
-    title="z18(): int">z18(): int</a></li>
-
-  </ul>
   <ul class="simple nested-toc-section">z16
       <li><a class="reference" href="#z16.m"
     title="z16()">z16()</a></li>
 
   </ul>
+  <ul class="simple nested-toc-section">z18
+      <li><a class="reference" href="#z18.m"
+    title="z18(): int">z18(): int</a></li>
+
+  </ul>
 
   </ul>
 </li>
 <li>
   <a class="reference reference-toplevel" href="#18" id="68">Templates</a>
   <ul class="simple simple-toc-section">
-      <ul class="simple nested-toc-section">fromUtils2
+      <ul class="simple nested-toc-section">foo
+      <li><a class="reference" href="#foo.t%2CSomeType%2CSomeType"
+    title="foo(a, b: SomeType)">foo(a, b: SomeType)</a></li>
+
+  </ul>
+  <ul class="simple nested-toc-section">fromUtils2
       <li><a class="reference" href="#fromUtils2.t"
     title="fromUtils2()">fromUtils2()</a></li>
 
   </ul>
+  <ul class="simple nested-toc-section">myfn
+      <li><a class="reference" href="#myfn.t"
+    title="myfn()">myfn()</a></li>
+
+  </ul>
+  <ul class="simple nested-toc-section">testNimDocTrailingExample
+      <li><a class="reference" href="#testNimDocTrailingExample.t"
+    title="testNimDocTrailingExample()">testNimDocTrailingExample()</a></li>
+
+  </ul>
   <ul class="simple nested-toc-section">z6t
       <li><a class="reference" href="#z6t.t"
     title="z6t(): int">z6t(): int</a></li>
@@ -399,21 +414,6 @@ window.addEventListener('DOMContentLoaded', main);
     title="z15()">z15()</a></li>
 
   </ul>
-  <ul class="simple nested-toc-section">foo
-      <li><a class="reference" href="#foo.t%2CSomeType%2CSomeType"
-    title="foo(a, b: SomeType)">foo(a, b: SomeType)</a></li>
-
-  </ul>
-  <ul class="simple nested-toc-section">myfn
-      <li><a class="reference" href="#myfn.t"
-    title="myfn()">myfn()</a></li>
-
-  </ul>
-  <ul class="simple nested-toc-section">testNimDocTrailingExample
-      <li><a class="reference" href="#testNimDocTrailingExample.t"
-    title="testNimDocTrailingExample()">testNimDocTrailingExample()</a></li>
-
-  </ul>
 
   </ul>
 </li>
@@ -447,16 +447,6 @@ window.addEventListener('DOMContentLoaded', main);
 <div class="section" id="7">
 <h1><a class="toc-backref" href="#7">Types</a></h1>
 <dl class="item">
-<a id="FooBuzz"></a>
-<dt><pre><a href="testproject.html#FooBuzz"><span class="Identifier">FooBuzz</span></a> {.<span><span class="Other pragmadots">...</span></span><span class="pragmawrap"><span class="Identifier">deprecated</span><span class="Other">:</span> <span class="StringLit">&quot;FooBuzz msg&quot;</span></span>.} <span class="Other">=</span> <span class="Identifier">int</span></pre></dt>
-<dd>
-  <div class="deprecation-message">
-    <b>Deprecated:</b> FooBuzz msg
-  </div>
-
-
-
-</dd>
 <a id="A"></a>
 <dt><pre><a href="testproject.html#A"><span class="Identifier">A</span></a> {.<span class="Identifier">inject</span>.} <span class="Other">=</span> <span class="Keyword">enum</span>
   <span class="Identifier">aA</span></pre></dt>
@@ -481,6 +471,16 @@ The enum B.
 
 
 </dd>
+<a id="FooBuzz"></a>
+<dt><pre><a href="testproject.html#FooBuzz"><span class="Identifier">FooBuzz</span></a> {.<span><span class="Other pragmadots">...</span></span><span class="pragmawrap"><span class="Identifier">deprecated</span><span class="Other">:</span> <span class="StringLit">&quot;FooBuzz msg&quot;</span></span>.} <span class="Other">=</span> <span class="Identifier">int</span></pre></dt>
+<dd>
+  <div class="deprecation-message">
+    <b>Deprecated:</b> FooBuzz msg
+  </div>
+
+
+
+</dd>
 <a id="Shapes"></a>
 <dt><pre><a href="testproject.html#Shapes"><span class="Identifier">Shapes</span></a> <span class="Other">=</span> <span class="Keyword">enum</span>
   <span class="Identifier">Circle</span><span class="Other">,</span>                   <span class="Comment">## A circle</span>
@@ -496,18 +496,18 @@ Some shapes.
 <div class="section" id="8">
 <h1><a class="toc-backref" href="#8">Vars</a></h1>
 <dl class="item">
-<a id="someVariable"></a>
-<dt><pre><a href="testproject.html#someVariable"><span class="Identifier">someVariable</span></a><span class="Other">:</span> <span class="Identifier">bool</span></pre></dt>
+<a id="aVariable"></a>
+<dt><pre><a href="testproject.html#aVariable"><span class="Identifier">aVariable</span></a><span class="Other">:</span> <span class="Identifier">array</span><span class="Other">[</span><span class="DecNumber">1</span><span class="Other">,</span> <span class="Identifier">int</span><span class="Other">]</span></pre></dt>
 <dd>
 
-This should be visible.
+
 
 </dd>
-<a id="aVariable"></a>
-<dt><pre><a href="testproject.html#aVariable"><span class="Identifier">aVariable</span></a><span class="Other">:</span> <span class="Identifier">array</span><span class="Other">[</span><span class="DecNumber">1</span><span class="Other">,</span> <span class="Identifier">int</span><span class="Other">]</span></pre></dt>
+<a id="someVariable"></a>
+<dt><pre><a href="testproject.html#someVariable"><span class="Identifier">someVariable</span></a><span class="Other">:</span> <span class="Identifier">bool</span></pre></dt>
 <dd>
 
-
+This should be visible.
 
 </dd>
 
@@ -548,6 +548,56 @@ This should be visible.
 <div class="section" id="12">
 <h1><a class="toc-backref" href="#12">Procs</a></h1>
 <dl class="item">
+<a id="addfBug14485"></a>
+<dt><pre><span class="Keyword">proc</span> <a href="#addfBug14485"><span class="Identifier">addfBug14485</span></a><span class="Other">(</span><span class="Other">)</span> {.<span><span class="Other pragmadots">...</span></span><span class="pragmawrap"><span class="Identifier">raises</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span><span class="Other">,</span> <span class="Identifier">tags</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span></span>.}</pre></dt>
+<dd>
+
+Some proc
+<p><strong class="examples_text">Example:</strong></p>
+<pre class="listing"><span class="Keyword">discard</span> <span class="StringLit">&quot;foo() = &quot;</span> <span class="Operator">&amp;</span> <span class="Operator">$</span><span class="Punctuation">[</span><span class="DecNumber">1</span><span class="Punctuation">]</span>
+<span class="LongComment">#[
+0: let's also add some broken html to make sure this won't break in future
+1: &lt;/span&gt;
+2: &lt;/span&gt;
+3: &lt;/span
+4: &lt;/script&gt;
+5: &lt;/script
+6: &lt;/script
+7: end of broken html
+]#</span></pre>
+
+</dd>
+<a id="anything"></a>
+<dt><pre><span class="Keyword">proc</span> <a href="#anything"><span class="Identifier">anything</span></a><span class="Other">(</span><span class="Other">)</span> {.<span><span class="Other pragmadots">...</span></span><span class="pragmawrap"><span class="Identifier">raises</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span><span class="Other">,</span> <span class="Identifier">tags</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span></span>.}</pre></dt>
+<dd>
+
+There is no block quote after blank lines at the beginning.
+
+</dd>
+<a id="asyncFun1"></a>
+<dt><pre><span class="Keyword">proc</span> <a href="#asyncFun1"><span class="Identifier">asyncFun1</span></a><span class="Other">(</span><span class="Other">)</span><span class="Other">:</span> <span class="Identifier">Future</span><span class="Other">[</span><span class="Identifier">int</span><span class="Other">]</span> {.<span><span class="Other pragmadots">...</span></span><span class="pragmawrap"><span class="Identifier">raises</span><span class="Other">:</span> <span class="Other">[</span><span class="Identifier">Exception</span><span class="Other">,</span> <span class="Identifier">ValueError</span><span class="Other">]</span><span class="Other">,</span>
+                                <span class="Identifier">tags</span><span class="Other">:</span> <span class="Other">[</span><span class="Identifier">RootEffect</span><span class="Other">]</span></span>.}</pre></dt>
+<dd>
+
+ok1
+
+</dd>
+<a id="asyncFun2"></a>
+<dt><pre><span class="Keyword">proc</span> <a href="#asyncFun2"><span class="Identifier">asyncFun2</span></a><span class="Other">(</span><span class="Other">)</span><span class="Other">:</span> <span class="Identifier">owned</span><span class="Other">(</span><span class="Identifier">Future</span><span class="Other">[</span><span class="Identifier">void</span><span class="Other">]</span><span class="Other">)</span> {.<span><span class="Other pragmadots">...</span></span><span class="pragmawrap"><span class="Identifier">raises</span><span class="Other">:</span> <span class="Other">[</span><span class="Identifier">Exception</span><span class="Other">]</span><span class="Other">,</span> <span class="Identifier">tags</span><span class="Other">:</span> <span class="Other">[</span><span class="Identifier">RootEffect</span><span class="Other">]</span></span>.}</pre></dt>
+<dd>
+
+
+
+</dd>
+<a id="asyncFun3"></a>
+<dt><pre><span class="Keyword">proc</span> <a href="#asyncFun3"><span class="Identifier">asyncFun3</span></a><span class="Other">(</span><span class="Other">)</span><span class="Other">:</span> <span class="Identifier">owned</span><span class="Other">(</span><span class="Identifier">Future</span><span class="Other">[</span><span class="Identifier">void</span><span class="Other">]</span><span class="Other">)</span> {.<span><span class="Other pragmadots">...</span></span><span class="pragmawrap"><span class="Identifier">raises</span><span class="Other">:</span> <span class="Other">[</span><span class="Identifier">Exception</span><span class="Other">]</span><span class="Other">,</span> <span class="Identifier">tags</span><span class="Other">:</span> <span class="Other">[</span><span class="Identifier">RootEffect</span><span class="Other">]</span></span>.}</pre></dt>
+<dd>
+
+
+<p><strong class="examples_text">Example:</strong></p>
+<pre class="listing"><span class="Keyword">discard</span></pre>ok1
+
+</dd>
 <a id="bar,T,T"></a>
 <dt><pre><span class="Keyword">proc</span> <a href="#bar%2CT%2CT"><span class="Identifier">bar</span></a><span class="Other">[</span><span class="Identifier">T</span><span class="Other">]</span><span class="Other">(</span><span class="Identifier">a</span><span class="Other">,</span> <span class="Identifier">b</span><span class="Other">:</span> <span class="Identifier">T</span><span class="Other">)</span><span class="Other">:</span> <span class="Identifier">T</span></pre></dt>
 <dd>
@@ -555,6 +605,13 @@ This should be visible.
 
 
 </dd>
+<a id="baz"></a>
+<dt><pre><span class="Keyword">proc</span> <a href="#baz"><span class="Identifier">baz</span></a><span class="Other">(</span><span class="Other">)</span> {.<span><span class="Other pragmadots">...</span></span><span class="pragmawrap"><span class="Identifier">raises</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span><span class="Other">,</span> <span class="Identifier">tags</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span></span>.}</pre></dt>
+<dd>
+
+
+
+</dd>
 <a id="baz,T,T"></a>
 <dt><pre><span class="Keyword">proc</span> <a href="#baz%2CT%2CT"><span class="Identifier">baz</span></a><span class="Other">[</span><span class="Identifier">T</span><span class="Other">]</span><span class="Other">(</span><span class="Identifier">a</span><span class="Other">,</span> <span class="Identifier">b</span><span class="Other">:</span> <span class="Identifier">T</span><span class="Other">)</span><span class="Other">:</span> <span class="Identifier">T</span> {.<span><span class="Other pragmadots">...</span></span><span class="pragmawrap"><span class="Identifier">deprecated</span></span>.}</pre></dt>
 <dd>
@@ -575,11 +632,20 @@ This is deprecated without message.
 This is deprecated with a message.
 
 </dd>
-<a id="someFunc"></a>
-<dt><pre><span class="Keyword">func</span> <a href="#someFunc"><span class="Identifier">someFunc</span></a><span class="Other">(</span><span class="Other">)</span> {.<span><span class="Other pragmadots">...</span></span><span class="pragmawrap"><span class="Identifier">raises</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span><span class="Other">,</span> <span class="Identifier">tags</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span></span>.}</pre></dt>
+<a id="c_nonexistent,cstring"></a>
+<dt><pre><span class="Keyword">proc</span> <a href="#c_nonexistent%2Ccstring"><span class="Identifier">c_nonexistent</span></a><span class="Other">(</span><span class="Identifier">frmt</span><span class="Other">:</span> <span class="Identifier">cstring</span><span class="Other">)</span><span class="Other">:</span> <span class="Identifier">cint</span> {.<span class="Identifier">importc</span><span class="Other">:</span> <span class="StringLit">&quot;nonexistent&quot;</span><span class="Other">,</span>
+    <span class="Identifier">header</span><span class="Other">:</span> <span class="StringLit">&quot;&lt;stdio.h&gt;&quot;</span><span class="Other">,</span> <span class="Identifier">varargs</span><span class="Other">,</span> <span class="Identifier">discardable</span>.}</pre></dt>
 <dd>
 
-My someFunc. Stuff in <tt class="docutils literal"><span class="pre"><span class="Identifier">quotes</span></span></tt> here. <a class="reference external" href="https://nim-lang.org">Some link</a>
+
+
+</dd>
+<a id="c_printf,cstring"></a>
+<dt><pre><span class="Keyword">proc</span> <a href="#c_printf%2Ccstring"><span class="Identifier">c_printf</span></a><span class="Other">(</span><span class="Identifier">frmt</span><span class="Other">:</span> <span class="Identifier">cstring</span><span class="Other">)</span><span class="Other">:</span> <span class="Identifier">cint</span> {.<span class="Identifier">importc</span><span class="Other">:</span> <span class="StringLit">&quot;printf&quot;</span><span class="Other">,</span> <span class="Identifier">header</span><span class="Other">:</span> <span class="StringLit">&quot;&lt;stdio.h&gt;&quot;</span><span class="Other">,</span>
+                                     <span class="Identifier">varargs</span><span class="Other">,</span> <span class="Identifier">discardable</span>.}</pre></dt>
+<dd>
+
+the c printf. etc.
 
 </dd>
 <a id="fromUtils3"></a>
@@ -599,6 +665,103 @@ came form utils but should be shown where <tt class="docutils literal"><span cla
 
 
 </dd>
+<a id="low2,T"></a>
+<dt><pre><span class="Keyword">proc</span> <a href="#low2%2CT"><span class="Identifier">low2</span></a><span class="Other">[</span><span class="Identifier">T</span><span class="Other">:</span> <span class="Identifier">Ordinal</span> <span class="Operator">|</span> <span class="Keyword">enum</span> <span class="Operator">|</span> <span class="Identifier">range</span><span class="Other">]</span><span class="Other">(</span><span class="Identifier">x</span><span class="Other">:</span> <span class="Identifier">T</span><span class="Other">)</span><span class="Other">:</span> <span class="Identifier">T</span> {.<span class="Identifier">magic</span><span class="Other">:</span> <span class="StringLit">&quot;Low&quot;</span><span class="Other">,</span> <span class="Identifier">noSideEffect</span>.}</pre></dt>
+<dd>
+
+<p>Returns the lowest possible value of an ordinal value <tt class="docutils literal"><span class="pre"><span class="Identifier">x</span></span></tt>. As a special semantic rule, <tt class="docutils literal"><span class="pre"><span class="Identifier">x</span></span></tt> may also be a type identifier.</p>
+<p>See also:</p>
+<ul class="simple"><li><a class="reference external" href="#low,T">low(T)</a></li>
+</ul>
+<pre class="listing"><span class="Identifier">low2</span><span class="Punctuation">(</span><span class="DecNumber">2</span><span class="Punctuation">)</span> <span class="Comment"># =&gt; -9223372036854775808</span></pre>
+<p><strong class="examples_text">Example:</strong></p>
+<pre class="listing"><span class="Keyword">discard</span> <span class="StringLit">&quot;in low2&quot;</span></pre>
+
+</dd>
+<a id="low,T"></a>
+<dt><pre><span class="Keyword">proc</span> <a href="#low%2CT"><span class="Identifier">low</span></a><span class="Other">[</span><span class="Identifier">T</span><span class="Other">:</span> <span class="Identifier">Ordinal</span> <span class="Operator">|</span> <span class="Keyword">enum</span> <span class="Operator">|</span> <span class="Identifier">range</span><span class="Other">]</span><span class="Other">(</span><span class="Identifier">x</span><span class="Other">:</span> <span class="Identifier">T</span><span class="Other">)</span><span class="Other">:</span> <span class="Identifier">T</span> {.<span class="Identifier">magic</span><span class="Other">:</span> <span class="StringLit">&quot;Low&quot;</span><span class="Other">,</span> <span class="Identifier">noSideEffect</span>.}</pre></dt>
+<dd>
+
+<p>Returns the lowest possible value of an ordinal value <tt class="docutils literal"><span class="pre"><span class="Identifier">x</span></span></tt>. As a special semantic rule, <tt class="docutils literal"><span class="pre"><span class="Identifier">x</span></span></tt> may also be a type identifier.</p>
+<p>See also:</p>
+<ul class="simple"><li><a class="reference external" href="#low2,T">low2(T)</a></li>
+</ul>
+<pre class="listing"><span class="Identifier">low</span><span class="Punctuation">(</span><span class="DecNumber">2</span><span class="Punctuation">)</span> <span class="Comment"># =&gt; -9223372036854775808</span></pre>
+
+</dd>
+<a id="p1"></a>
+<dt><pre><span class="Keyword">proc</span> <a href="#p1"><span class="Identifier">p1</span></a><span class="Other">(</span><span class="Other">)</span> {.<span><span class="Other pragmadots">...</span></span><span class="pragmawrap"><span class="Identifier">raises</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span><span class="Other">,</span> <span class="Identifier">tags</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span></span>.}</pre></dt>
+<dd>
+
+cp1
+<p><strong class="examples_text">Example:</strong></p>
+<pre class="listing"><span class="Identifier">doAssert</span> <span class="DecNumber">1</span> <span class="Operator">==</span> <span class="DecNumber">1</span> <span class="Comment"># regular comments work here</span></pre>c4
+<p><strong class="examples_text">Example:</strong></p>
+<pre class="listing"><span class="Comment"># c5 regular comments before 1st token work</span>
+<span class="Comment"># regular comment</span>
+<span class="LongComment">#[
+nested regular comment
+]#</span>
+<span class="Identifier">doAssert</span> <span class="DecNumber">2</span> <span class="Operator">==</span> <span class="DecNumber">2</span> <span class="Comment"># c8</span>
+<span class="Comment">## this is a non-nested doc comment</span>
+
+<span class="LongComment">##[
+this is a nested doc comment
+]##</span>
+<span class="Keyword">discard</span> <span class="StringLit">&quot;c9&quot;</span>
+<span class="Comment"># also work after</span></pre>
+
+</dd>
+<a id="someFunc"></a>
+<dt><pre><span class="Keyword">func</span> <a href="#someFunc"><span class="Identifier">someFunc</span></a><span class="Other">(</span><span class="Other">)</span> {.<span><span class="Other pragmadots">...</span></span><span class="pragmawrap"><span class="Identifier">raises</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span><span class="Other">,</span> <span class="Identifier">tags</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span></span>.}</pre></dt>
+<dd>
+
+My someFunc. Stuff in <tt class="docutils literal"><span class="pre"><span class="Identifier">quotes</span></span></tt> here. <a class="reference external" href="https://nim-lang.org">Some link</a>
+
+</dd>
+<a id="tripleStrLitTest"></a>
+<dt><pre><span class="Keyword">proc</span> <a href="#tripleStrLitTest"><span class="Identifier">tripleStrLitTest</span></a><span class="Other">(</span><span class="Other">)</span> {.<span><span class="Other pragmadots">...</span></span><span class="pragmawrap"><span class="Identifier">raises</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span><span class="Other">,</span> <span class="Identifier">tags</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span></span>.}</pre></dt>
+<dd>
+
+
+<p><strong class="examples_text">Example: cmd: --hint:XDeclaredButNotUsed:off</strong></p>
+<pre class="listing"><span class="Comment">## mullitline string litterals are tricky as their indentation can span</span>
+<span class="Comment">## below that of the runnableExamples</span>
+<span class="Keyword">let</span> <span class="Identifier">s1a</span> <span class="Operator">=</span> <span class="LongStringLit">&quot;&quot;&quot;
+should appear at indent 0
+  at indent 2
+at indent 0
+&quot;&quot;&quot;</span>
+<span class="Comment"># make sure this works too</span>
+<span class="Keyword">let</span> <span class="Identifier">s1b</span> <span class="Operator">=</span> <span class="LongStringLit">&quot;&quot;&quot;start at same line
+  at indent 2
+at indent 0
+&quot;&quot;&quot;</span> <span class="Comment"># comment after</span>
+<span class="Keyword">let</span> <span class="Identifier">s2</span> <span class="Operator">=</span> <span class="LongStringLit">&quot;&quot;&quot;sandwich &quot;&quot;&quot;</span>
+<span class="Keyword">let</span> <span class="Identifier">s3</span> <span class="Operator">=</span> <span class="LongStringLit">&quot;&quot;&quot;&quot;&quot;&quot;</span>
+<span class="Keyword">when</span> <span class="Identifier">false</span><span class="Punctuation">:</span>
+  <span class="Keyword">let</span> <span class="Identifier">s5</span> <span class="Operator">=</span> <span class="LongStringLit">&quot;&quot;&quot;
+        in s5 &quot;&quot;&quot;</span>
+
+<span class="Keyword">let</span> <span class="Identifier">s3b</span> <span class="Operator">=</span> <span class="Punctuation">[</span><span class="LongStringLit">&quot;&quot;&quot;
+%!? #[...] # inside a multiline ...
+&quot;&quot;&quot;</span><span class="Punctuation">,</span> <span class="StringLit">&quot;foo&quot;</span><span class="Punctuation">]</span>
+
+<span class="Comment">## make sure handles trailing spaces</span>
+<span class="Keyword">let</span> <span class="Identifier">s4</span> <span class="Operator">=</span> <span class="LongStringLit">&quot;&quot;&quot; 
+&quot;&quot;&quot;</span>
+
+<span class="Keyword">let</span> <span class="Identifier">s5</span> <span class="Operator">=</span> <span class="LongStringLit">&quot;&quot;&quot; x
+&quot;&quot;&quot;</span>
+<span class="Keyword">let</span> <span class="Identifier">s6</span> <span class="Operator">=</span> <span class="LongStringLit">&quot;&quot;&quot; &quot;&quot;
+&quot;&quot;&quot;</span>
+<span class="Keyword">let</span> <span class="Identifier">s7</span> <span class="Operator">=</span> <span class="LongStringLit">&quot;&quot;&quot;&quot;&quot;&quot;&quot;&quot;&quot;&quot;</span>
+<span class="Keyword">let</span> <span class="Identifier">s8</span> <span class="Operator">=</span> <span class="Punctuation">[</span><span class="LongStringLit">&quot;&quot;&quot;&quot;&quot;&quot;&quot;&quot;&quot;&quot;</span><span class="Punctuation">,</span> <span class="LongStringLit">&quot;&quot;&quot;
+  &quot;&quot;&quot;</span> <span class="Punctuation">]</span>
+<span class="Keyword">discard</span>
+<span class="Comment"># should be in</span></pre>
+
+</dd>
 <a id="z1"></a>
 <dt><pre><span class="Keyword">proc</span> <a href="#z1"><span class="Identifier">z1</span></a><span class="Other">(</span><span class="Other">)</span><span class="Other">:</span> <a href="testproject.html#Foo"><span class="Identifier">Foo</span></a> {.<span><span class="Other pragmadots">...</span></span><span class="pragmawrap"><span class="Identifier">raises</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span><span class="Other">,</span> <span class="Identifier">tags</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span></span>.}</pre></dt>
 <dd>
@@ -702,13 +865,6 @@ cz13
 <pre class="listing"><span class="Keyword">discard</span></pre>
 
 </dd>
-<a id="baz"></a>
-<dt><pre><span class="Keyword">proc</span> <a href="#baz"><span class="Identifier">baz</span></a><span class="Other">(</span><span class="Other">)</span> {.<span><span class="Other pragmadots">...</span></span><span class="pragmawrap"><span class="Identifier">raises</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span><span class="Other">,</span> <span class="Identifier">tags</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span></span>.}</pre></dt>
-<dd>
-
-
-
-</dd>
 <a id="z17"></a>
 <dt><pre><span class="Keyword">proc</span> <a href="#z17"><span class="Identifier">z17</span></a><span class="Other">(</span><span class="Other">)</span> {.<span><span class="Other pragmadots">...</span></span><span class="pragmawrap"><span class="Identifier">raises</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span><span class="Other">,</span> <span class="Identifier">tags</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span></span>.}</pre></dt>
 <dd>
@@ -718,162 +874,6 @@ cz17 rest
 <pre class="listing"><span class="Keyword">discard</span> <span class="DecNumber">1</span></pre>rest
 
 </dd>
-<a id="p1"></a>
-<dt><pre><span class="Keyword">proc</span> <a href="#p1"><span class="Identifier">p1</span></a><span class="Other">(</span><span class="Other">)</span> {.<span><span class="Other pragmadots">...</span></span><span class="pragmawrap"><span class="Identifier">raises</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span><span class="Other">,</span> <span class="Identifier">tags</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span></span>.}</pre></dt>
-<dd>
-
-cp1
-<p><strong class="examples_text">Example:</strong></p>
-<pre class="listing"><span class="Identifier">doAssert</span> <span class="DecNumber">1</span> <span class="Operator">==</span> <span class="DecNumber">1</span> <span class="Comment"># regular comments work here</span></pre>c4
-<p><strong class="examples_text">Example:</strong></p>
-<pre class="listing"><span class="Comment"># c5 regular comments before 1st token work</span>
-<span class="Comment"># regular comment</span>
-<span class="LongComment">#[
-nested regular comment
-]#</span>
-<span class="Identifier">doAssert</span> <span class="DecNumber">2</span> <span class="Operator">==</span> <span class="DecNumber">2</span> <span class="Comment"># c8</span>
-<span class="Comment">## this is a non-nested doc comment</span>
-
-<span class="LongComment">##[
-this is a nested doc comment
-]##</span>
-<span class="Keyword">discard</span> <span class="StringLit">&quot;c9&quot;</span>
-<span class="Comment"># also work after</span></pre>
-
-</dd>
-<a id="addfBug14485"></a>
-<dt><pre><span class="Keyword">proc</span> <a href="#addfBug14485"><span class="Identifier">addfBug14485</span></a><span class="Other">(</span><span class="Other">)</span> {.<span><span class="Other pragmadots">...</span></span><span class="pragmawrap"><span class="Identifier">raises</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span><span class="Other">,</span> <span class="Identifier">tags</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span></span>.}</pre></dt>
-<dd>
-
-Some proc
-<p><strong class="examples_text">Example:</strong></p>
-<pre class="listing"><span class="Keyword">discard</span> <span class="StringLit">&quot;foo() = &quot;</span> <span class="Operator">&amp;</span> <span class="Operator">$</span><span class="Punctuation">[</span><span class="DecNumber">1</span><span class="Punctuation">]</span>
-<span class="LongComment">#[
-0: let's also add some broken html to make sure this won't break in future
-1: &lt;/span&gt;
-2: &lt;/span&gt;
-3: &lt;/span
-4: &lt;/script&gt;
-5: &lt;/script
-6: &lt;/script
-7: end of broken html
-]#</span></pre>
-
-</dd>
-<a id="c_printf,cstring"></a>
-<dt><pre><span class="Keyword">proc</span> <a href="#c_printf%2Ccstring"><span class="Identifier">c_printf</span></a><span class="Other">(</span><span class="Identifier">frmt</span><span class="Other">:</span> <span class="Identifier">cstring</span><span class="Other">)</span><span class="Other">:</span> <span class="Identifier">cint</span> {.<span class="Identifier">importc</span><span class="Other">:</span> <span class="StringLit">&quot;printf&quot;</span><span class="Other">,</span> <span class="Identifier">header</span><span class="Other">:</span> <span class="StringLit">&quot;&lt;stdio.h&gt;&quot;</span><span class="Other">,</span>
-                                     <span class="Identifier">varargs</span><span class="Other">,</span> <span class="Identifier">discardable</span>.}</pre></dt>
-<dd>
-
-the c printf. etc.
-
-</dd>
-<a id="c_nonexistent,cstring"></a>
-<dt><pre><span class="Keyword">proc</span> <a href="#c_nonexistent%2Ccstring"><span class="Identifier">c_nonexistent</span></a><span class="Other">(</span><span class="Identifier">frmt</span><span class="Other">:</span> <span class="Identifier">cstring</span><span class="Other">)</span><span class="Other">:</span> <span class="Identifier">cint</span> {.<span class="Identifier">importc</span><span class="Other">:</span> <span class="StringLit">&quot;nonexistent&quot;</span><span class="Other">,</span>
-    <span class="Identifier">header</span><span class="Other">:</span> <span class="StringLit">&quot;&lt;stdio.h&gt;&quot;</span><span class="Other">,</span> <span class="Identifier">varargs</span><span class="Other">,</span> <span class="Identifier">discardable</span>.}</pre></dt>
-<dd>
-
-
-
-</dd>
-<a id="low,T"></a>
-<dt><pre><span class="Keyword">proc</span> <a href="#low%2CT"><span class="Identifier">low</span></a><span class="Other">[</span><span class="Identifier">T</span><span class="Other">:</span> <span class="Identifier">Ordinal</span> <span class="Operator">|</span> <span class="Keyword">enum</span> <span class="Operator">|</span> <span class="Identifier">range</span><span class="Other">]</span><span class="Other">(</span><span class="Identifier">x</span><span class="Other">:</span> <span class="Identifier">T</span><span class="Other">)</span><span class="Other">:</span> <span class="Identifier">T</span> {.<span class="Identifier">magic</span><span class="Other">:</span> <span class="StringLit">&quot;Low&quot;</span><span class="Other">,</span> <span class="Identifier">noSideEffect</span>.}</pre></dt>
-<dd>
-
-<p>Returns the lowest possible value of an ordinal value <tt class="docutils literal"><span class="pre"><span class="Identifier">x</span></span></tt>. As a special semantic rule, <tt class="docutils literal"><span class="pre"><span class="Identifier">x</span></span></tt> may also be a type identifier.</p>
-<p>See also:</p>
-<ul class="simple"><li><a class="reference external" href="#low2,T">low2(T)</a></li>
-</ul>
-<pre class="listing"><span class="Identifier">low</span><span class="Punctuation">(</span><span class="DecNumber">2</span><span class="Punctuation">)</span> <span class="Comment"># =&gt; -9223372036854775808</span></pre>
-
-</dd>
-<a id="low2,T"></a>
-<dt><pre><span class="Keyword">proc</span> <a href="#low2%2CT"><span class="Identifier">low2</span></a><span class="Other">[</span><span class="Identifier">T</span><span class="Other">:</span> <span class="Identifier">Ordinal</span> <span class="Operator">|</span> <span class="Keyword">enum</span> <span class="Operator">|</span> <span class="Identifier">range</span><span class="Other">]</span><span class="Other">(</span><span class="Identifier">x</span><span class="Other">:</span> <span class="Identifier">T</span><span class="Other">)</span><span class="Other">:</span> <span class="Identifier">T</span> {.<span class="Identifier">magic</span><span class="Other">:</span> <span class="StringLit">&quot;Low&quot;</span><span class="Other">,</span> <span class="Identifier">noSideEffect</span>.}</pre></dt>
-<dd>
-
-<p>Returns the lowest possible value of an ordinal value <tt class="docutils literal"><span class="pre"><span class="Identifier">x</span></span></tt>. As a special semantic rule, <tt class="docutils literal"><span class="pre"><span class="Identifier">x</span></span></tt> may also be a type identifier.</p>
-<p>See also:</p>
-<ul class="simple"><li><a class="reference external" href="#low,T">low(T)</a></li>
-</ul>
-<pre class="listing"><span class="Identifier">low2</span><span class="Punctuation">(</span><span class="DecNumber">2</span><span class="Punctuation">)</span> <span class="Comment"># =&gt; -9223372036854775808</span></pre>
-<p><strong class="examples_text">Example:</strong></p>
-<pre class="listing"><span class="Keyword">discard</span> <span class="StringLit">&quot;in low2&quot;</span></pre>
-
-</dd>
-<a id="tripleStrLitTest"></a>
-<dt><pre><span class="Keyword">proc</span> <a href="#tripleStrLitTest"><span class="Identifier">tripleStrLitTest</span></a><span class="Other">(</span><span class="Other">)</span> {.<span><span class="Other pragmadots">...</span></span><span class="pragmawrap"><span class="Identifier">raises</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span><span class="Other">,</span> <span class="Identifier">tags</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span></span>.}</pre></dt>
-<dd>
-
-
-<p><strong class="examples_text">Example: cmd: --hint:XDeclaredButNotUsed:off</strong></p>
-<pre class="listing"><span class="Comment">## mullitline string litterals are tricky as their indentation can span</span>
-<span class="Comment">## below that of the runnableExamples</span>
-<span class="Keyword">let</span> <span class="Identifier">s1a</span> <span class="Operator">=</span> <span class="LongStringLit">&quot;&quot;&quot;
-should appear at indent 0
-  at indent 2
-at indent 0
-&quot;&quot;&quot;</span>
-<span class="Comment"># make sure this works too</span>
-<span class="Keyword">let</span> <span class="Identifier">s1b</span> <span class="Operator">=</span> <span class="LongStringLit">&quot;&quot;&quot;start at same line
-  at indent 2
-at indent 0
-&quot;&quot;&quot;</span> <span class="Comment"># comment after</span>
-<span class="Keyword">let</span> <span class="Identifier">s2</span> <span class="Operator">=</span> <span class="LongStringLit">&quot;&quot;&quot;sandwich &quot;&quot;&quot;</span>
-<span class="Keyword">let</span> <span class="Identifier">s3</span> <span class="Operator">=</span> <span class="LongStringLit">&quot;&quot;&quot;&quot;&quot;&quot;</span>
-<span class="Keyword">when</span> <span class="Identifier">false</span><span class="Punctuation">:</span>
-  <span class="Keyword">let</span> <span class="Identifier">s5</span> <span class="Operator">=</span> <span class="LongStringLit">&quot;&quot;&quot;
-        in s5 &quot;&quot;&quot;</span>
-
-<span class="Keyword">let</span> <span class="Identifier">s3b</span> <span class="Operator">=</span> <span class="Punctuation">[</span><span class="LongStringLit">&quot;&quot;&quot;
-%!? #[...] # inside a multiline ...
-&quot;&quot;&quot;</span><span class="Punctuation">,</span> <span class="StringLit">&quot;foo&quot;</span><span class="Punctuation">]</span>
-
-<span class="Comment">## make sure handles trailing spaces</span>
-<span class="Keyword">let</span> <span class="Identifier">s4</span> <span class="Operator">=</span> <span class="LongStringLit">&quot;&quot;&quot; 
-&quot;&quot;&quot;</span>
-
-<span class="Keyword">let</span> <span class="Identifier">s5</span> <span class="Operator">=</span> <span class="LongStringLit">&quot;&quot;&quot; x
-&quot;&quot;&quot;</span>
-<span class="Keyword">let</span> <span class="Identifier">s6</span> <span class="Operator">=</span> <span class="LongStringLit">&quot;&quot;&quot; &quot;&quot;
-&quot;&quot;&quot;</span>
-<span class="Keyword">let</span> <span class="Identifier">s7</span> <span class="Operator">=</span> <span class="LongStringLit">&quot;&quot;&quot;&quot;&quot;&quot;&quot;&quot;&quot;&quot;</span>
-<span class="Keyword">let</span> <span class="Identifier">s8</span> <span class="Operator">=</span> <span class="Punctuation">[</span><span class="LongStringLit">&quot;&quot;&quot;&quot;&quot;&quot;&quot;&quot;&quot;&quot;</span><span class="Punctuation">,</span> <span class="LongStringLit">&quot;&quot;&quot;
-  &quot;&quot;&quot;</span> <span class="Punctuation">]</span>
-<span class="Keyword">discard</span>
-<span class="Comment"># should be in</span></pre>
-
-</dd>
-<a id="asyncFun1"></a>
-<dt><pre><span class="Keyword">proc</span> <a href="#asyncFun1"><span class="Identifier">asyncFun1</span></a><span class="Other">(</span><span class="Other">)</span><span class="Other">:</span> <span class="Identifier">Future</span><span class="Other">[</span><span class="Identifier">int</span><span class="Other">]</span> {.<span><span class="Other pragmadots">...</span></span><span class="pragmawrap"><span class="Identifier">raises</span><span class="Other">:</span> <span class="Other">[</span><span class="Identifier">Exception</span><span class="Other">,</span> <span class="Identifier">ValueError</span><span class="Other">]</span><span class="Other">,</span>
-                                <span class="Identifier">tags</span><span class="Other">:</span> <span class="Other">[</span><span class="Identifier">RootEffect</span><span class="Other">]</span></span>.}</pre></dt>
-<dd>
-
-ok1
-
-</dd>
-<a id="asyncFun2"></a>
-<dt><pre><span class="Keyword">proc</span> <a href="#asyncFun2"><span class="Identifier">asyncFun2</span></a><span class="Other">(</span><span class="Other">)</span><span class="Other">:</span> <span class="Identifier">owned</span><span class="Other">(</span><span class="Identifier">Future</span><span class="Other">[</span><span class="Identifier">void</span><span class="Other">]</span><span class="Other">)</span> {.<span><span class="Other pragmadots">...</span></span><span class="pragmawrap"><span class="Identifier">raises</span><span class="Other">:</span> <span class="Other">[</span><span class="Identifier">Exception</span><span class="Other">]</span><span class="Other">,</span> <span class="Identifier">tags</span><span class="Other">:</span> <span class="Other">[</span><span class="Identifier">RootEffect</span><span class="Other">]</span></span>.}</pre></dt>
-<dd>
-
-
-
-</dd>
-<a id="asyncFun3"></a>
-<dt><pre><span class="Keyword">proc</span> <a href="#asyncFun3"><span class="Identifier">asyncFun3</span></a><span class="Other">(</span><span class="Other">)</span><span class="Other">:</span> <span class="Identifier">owned</span><span class="Other">(</span><span class="Identifier">Future</span><span class="Other">[</span><span class="Identifier">void</span><span class="Other">]</span><span class="Other">)</span> {.<span><span class="Other pragmadots">...</span></span><span class="pragmawrap"><span class="Identifier">raises</span><span class="Other">:</span> <span class="Other">[</span><span class="Identifier">Exception</span><span class="Other">]</span><span class="Other">,</span> <span class="Identifier">tags</span><span class="Other">:</span> <span class="Other">[</span><span class="Identifier">RootEffect</span><span class="Other">]</span></span>.}</pre></dt>
-<dd>
-
-
-<p><strong class="examples_text">Example:</strong></p>
-<pre class="listing"><span class="Keyword">discard</span></pre>ok1
-
-</dd>
-<a id="anything"></a>
-<dt><pre><span class="Keyword">proc</span> <a href="#anything"><span class="Identifier">anything</span></a><span class="Other">(</span><span class="Other">)</span> {.<span><span class="Other pragmadots">...</span></span><span class="pragmawrap"><span class="Identifier">raises</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span><span class="Other">,</span> <span class="Identifier">tags</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span></span>.}</pre></dt>
-<dd>
-
-There is no block quote after blank lines at the beginning.
-
-</dd>
 
 </dl></div>
 <div class="section" id="14">
@@ -967,6 +967,13 @@ cz18
 <div class="section" id="18">
 <h1><a class="toc-backref" href="#18">Templates</a></h1>
 <dl class="item">
+<a id="foo.t,SomeType,SomeType"></a>
+<dt><pre><span class="Keyword">template</span> <a href="#foo.t%2CSomeType%2CSomeType"><span class="Identifier">foo</span></a><span class="Other">(</span><span class="Identifier">a</span><span class="Other">,</span> <span class="Identifier">b</span><span class="Other">:</span> <a href="subdir/subdir_b/utils.html#SomeType"><span class="Identifier">SomeType</span></a><span class="Other">)</span></pre></dt>
+<dd>
+
+This does nothing 
+
+</dd>
 <a id="fromUtils2.t"></a>
 <dt><pre><span class="Keyword">template</span> <a href="#fromUtils2.t"><span class="Identifier">fromUtils2</span></a><span class="Other">(</span><span class="Other">)</span></pre></dt>
 <dd>
@@ -977,20 +984,6 @@ ok3
        in module calling fromUtilsGen&quot;&quot;&quot;</span></pre>
 
 </dd>
-<a id="z6t.t"></a>
-<dt><pre><span class="Keyword">template</span> <a href="#z6t.t"><span class="Identifier">z6t</span></a><span class="Other">(</span><span class="Other">)</span><span class="Other">:</span> <span class="Identifier">int</span></pre></dt>
-<dd>
-
-cz6t
-
-</dd>
-<a id="foo.t,SomeType,SomeType"></a>
-<dt><pre><span class="Keyword">template</span> <a href="#foo.t%2CSomeType%2CSomeType"><span class="Identifier">foo</span></a><span class="Other">(</span><span class="Identifier">a</span><span class="Other">,</span> <span class="Identifier">b</span><span class="Other">:</span> <a href="subdir/subdir_b/utils.html#SomeType"><span class="Identifier">SomeType</span></a><span class="Other">)</span></pre></dt>
-<dd>
-
-This does nothing 
-
-</dd>
 <a id="myfn.t"></a>
 <dt><pre><span class="Keyword">template</span> <a href="#myfn.t"><span class="Identifier">myfn</span></a><span class="Other">(</span><span class="Other">)</span></pre></dt>
 <dd>
@@ -1013,6 +1006,22 @@ bar
 <span class="Comment"># should be in</span></pre>should be still in
 
 </dd>
+<a id="testNimDocTrailingExample.t"></a>
+<dt><pre><span class="Keyword">template</span> <a href="#testNimDocTrailingExample.t"><span class="Identifier">testNimDocTrailingExample</span></a><span class="Other">(</span><span class="Other">)</span></pre></dt>
+<dd>
+
+
+<p><strong class="examples_text">Example:</strong></p>
+<pre class="listing"><span class="Keyword">discard</span> <span class="DecNumber">2</span></pre>
+
+</dd>
+<a id="z6t.t"></a>
+<dt><pre><span class="Keyword">template</span> <a href="#z6t.t"><span class="Identifier">z6t</span></a><span class="Other">(</span><span class="Other">)</span><span class="Other">:</span> <span class="Identifier">int</span></pre></dt>
+<dd>
+
+cz6t
+
+</dd>
 <a id="z14.t"></a>
 <dt><pre><span class="Keyword">template</span> <a href="#z14.t"><span class="Identifier">z14</span></a><span class="Other">(</span><span class="Other">)</span></pre></dt>
 <dd>
@@ -1039,15 +1048,6 @@ cz15
 <pre class="listing"><span class="Keyword">discard</span> <span class="DecNumber">1</span></pre>in or out?
 
 </dd>
-<a id="testNimDocTrailingExample.t"></a>
-<dt><pre><span class="Keyword">template</span> <a href="#testNimDocTrailingExample.t"><span class="Identifier">testNimDocTrailingExample</span></a><span class="Other">(</span><span class="Other">)</span></pre></dt>
-<dd>
-
-
-<p><strong class="examples_text">Example:</strong></p>
-<pre class="listing"><span class="Keyword">discard</span> <span class="DecNumber">2</span></pre>
-
-</dd>
 
 </dl></div>