Markdown indented code blocks (#20473)

* Implement Markdown indented code blocks

Additional indentation of 4 spaces makes a block an "indented code block"
(monospaced text without syntax highlighting).
Also `::` RST syntax for code blocks is disabled.

So instead of
```rst
see::

  Some code
```

the code block should be written as
```markdown
see:

    Some code
```

* Migrate RST literal blocks :: to Markdown's ones

lib/packages/docutils/dochelpers.nim

@@ -75,10 +75,10 @@ proc toLangSymbol*(linkText: PRstNode): LangSymbol =
   ## Parses `linkText` into a more structured form using a state machine.
   ##
   ## This proc is designed to allow link syntax with operators even
-  ## without escaped backticks inside::
+  ## without escaped backticks inside:
   ##   
-  ##   `proc *`_
-  ##   `proc []`_
+  ##     `proc *`_
+  ##     `proc []`_
   ##
   ## This proc should be kept in sync with the `renderTypes` proc from
   ## ``compiler/typesrenderer.nim``.

lib/packages/docutils/rst.nim

@@ -2172,7 +2172,7 @@ proc whichSection(p: RstParser): RstNodeKind =
     # for punctuation sequences that can be both tkAdornment and tkPunct
     if isMarkdownCodeBlock(p):
       return rnCodeBlock
-    elif currentTok(p).symbol == "::":
+    elif isRst(p) and currentTok(p).symbol == "::":
       return rnLiteralBlock
     elif currentTok(p).symbol == ".."  and
        nextTok(p).kind in {tkWhite, tkIndent}:
@@ -2362,8 +2362,10 @@ proc parseParagraph(p: var RstParser, result: PRstNode) =
     of tkIndent:
       if nextTok(p).kind == tkIndent:
         inc p.idx
-        break
-      elif currentTok(p).ival == currInd(p):
+        break  # blank line breaks paragraph for both Md & Rst
+      elif currentTok(p).ival == currInd(p) or (
+          isMd(p) and currentTok(p).ival > currInd(p)):
+          # (Md allows adding additional indentation inside paragraphs)
         inc p.idx
         case whichSection(p)
         of rnParagraph, rnLeaf, rnHeadline, rnMarkdownHeadline,
@@ -2377,7 +2379,8 @@ proc parseParagraph(p: var RstParser, result: PRstNode) =
       else:
         break
     of tkPunct:
-      if (let literalBlockKind = whichRstLiteralBlock(p);
+      if isRst(p) and (
+          let literalBlockKind = whichRstLiteralBlock(p);
           literalBlockKind != lbNone):
         result.add newLeaf(":")
         inc p.idx            # skip '::'
@@ -2932,11 +2935,11 @@ proc parseSection(p: var RstParser, result: PRstNode) =
       elif currentTok(p).ival > currInd(p):
         if roPreferMarkdown in p.s.options:  # Markdown => normal paragraphs
           if currentTok(p).ival - currInd(p) >= 4:
-            rstMessage(p, mwRstStyle,
-                       "Markdown indented code not implemented")
-          pushInd(p, currentTok(p).ival)
-          parseSection(p, result)
-          popInd(p)
+            result.add parseLiteralBlock(p)
+          else:
+            pushInd(p, currentTok(p).ival)
+            parseSection(p, result)
+            popInd(p)
         else:  # RST mode => block quotes
           pushInd(p, currentTok(p).ival)
           var a = newRstNodeA(p, rnBlockQuote)

lib/packages/docutils/rstast.nim

@@ -377,13 +377,13 @@ proc renderRstToJsonNode(node: PRstNode): JsonNode =
 
 proc renderRstToJson*(node: PRstNode): string =
   ## Writes the given RST node as JSON that is in the form
-  ## ::
-  ##   {
-  ##     "kind":string node.kind,
-  ##     "text":optional string node.text,
-  ##     "level":optional int node.level,
-  ##     "sons":optional node array
-  ##   }
+  ##
+  ##     {
+  ##       "kind":string node.kind,
+  ##       "text":optional string node.text,
+  ##       "level":optional int node.level,
+  ##       "sons":optional node array
+  ##     }
   renderRstToJsonNode(node).pretty
 
 proc renderRstToText*(node: PRstNode): string =

lib/posix/posix_utils.nim

@@ -57,9 +57,10 @@ proc memoryLock*(a1: pointer, a2: int) =
 proc memoryLockAll*(flags: int) =
   ## Locks all memory for the running process to prevent swapping.
   ##
-  ## example::
-  ##
+  ## example:
+  ##   ```nim
   ##   memoryLockAll(MCL_CURRENT or MCL_FUTURE)
+  ##   ```
   if mlockall(flags.cint) != 0:
     raise newException(OSError, $strerror(errno))
 

lib/pure/distros.nim

@@ -9,12 +9,12 @@
 
 ## This module implements the basics for Linux distribution ("distro")
 ## detection and the OS's native package manager. Its primary purpose is to
-## produce output for Nimble packages, like::
+## produce output for Nimble packages, like:
 ##
-##   To complete the installation, run:
+##     To complete the installation, run:
 ##
-##   sudo apt-get install libblas-dev
-##   sudo apt-get install libvoodoo
+##     sudo apt-get install libblas-dev
+##     sudo apt-get install libvoodoo
 ##
 ## The above output could be the result of a code snippet like:
 ##

lib/pure/htmlgen.nim

@@ -34,9 +34,9 @@
 ##   var nim = "Nim"
 ##   echo h1(a(href="https://nim-lang.org", nim))
 ##
-## Writes the string::
+## Writes the string:
 ##
-##   <h1><a href="https://nim-lang.org">Nim</a></h1>
+##     <h1><a href="https://nim-lang.org">Nim</a></h1>
 ##
 
 import

lib/pure/os.nim

@@ -2294,11 +2294,12 @@ iterator walkDir*(dir: string; relative = false, checkDir = false):
   ##
   ## **Example:**
   ##
-  ## This directory structure::
-  ##   dirA / dirB / fileB1.txt
-  ##        / dirC
-  ##        / fileA1.txt
-  ##        / fileA2.txt
+  ## This directory structure:
+  ##
+  ##     dirA / dirB / fileB1.txt
+  ##          / dirC
+  ##          / fileA1.txt
+  ##          / fileA2.txt
   ##
   ## and this code:
   runnableExamples("-r:off"):

lib/pure/pegs.nim

@@ -2058,9 +2058,9 @@ func parsePeg*(pattern: string, filename = "pattern", line = 1, col = 0): Peg =
 
 func peg*(pattern: string): Peg =
   ## constructs a Peg object from the `pattern`. The short name has been
-  ## chosen to encourage its use as a raw string modifier::
+  ## chosen to encourage its use as a raw string modifier:
   ##
-  ##   peg"{\ident} \s* '=' \s* {.*}"
+  ##     peg"{\ident} \s* '=' \s* {.*}"
   result = parsePeg(pattern, "pattern")
 
 func escapePeg*(s: string): string =

lib/pure/strformat.nim

@@ -171,9 +171,9 @@ For strings and numeric types the optional argument is a so-called
 
 # Standard format specifiers for strings, integers and floats
 
-The general form of a standard format specifier is::
+The general form of a standard format specifier is:
 
-  [[fill]align][sign][#][0][minimumwidth][.precision][type]
+    [[fill]align][sign][#][0][minimumwidth][.precision][type]
 
 The square brackets `[]` indicate an optional element.
 
@@ -423,9 +423,9 @@ proc formatInt(n: SomeNumber; radix: int; spec: StandardFormatSpecifier): string
 proc parseStandardFormatSpecifier*(s: string; start = 0;
                                    ignoreUnknownSuffix = false): StandardFormatSpecifier =
   ## An exported helper proc that parses the "standard format specifiers",
-  ## as specified by the grammar::
+  ## as specified by the grammar:
   ##
-  ##   [[fill]align][sign][#][0][minimumwidth][.precision][type]
+  ##     [[fill]align][sign][#][0][minimumwidth][.precision][type]
   ##
   ## This is only of interest if you want to write a custom `format` proc that
   ## should support the standard format specifiers. If `ignoreUnknownSuffix` is true,

lib/pure/xmltree.nim

@@ -778,8 +778,8 @@ macro `<>`*(x: untyped): untyped =
   ## .. code-block:: nim
   ##   <>a(href="http://nim-lang.org", newText("Nim rules."))
   ##
-  ## Produces an XML tree for::
+  ## Produces an XML tree for:
   ##
-  ##  <a href="http://nim-lang.org">Nim rules.</a>
+  ##     <a href="http://nim-lang.org">Nim rules.</a>
   ##
   result = xmlConstructor(x)

lib/system/channels_builtin.nim

@@ -91,14 +91,15 @@
 ## Sample output
 ## -------------
 ## The program should output something similar to this, but keep in mind that
-## exact results may vary in the real world::
-##   Hello World!
-##   Pretend I'm doing useful work...
-##   Pretend I'm doing useful work...
-##   Pretend I'm doing useful work...
-##   Pretend I'm doing useful work...
-##   Pretend I'm doing useful work...
-##   Another message
+## exact results may vary in the real world:
+##
+##     Hello World!
+##     Pretend I'm doing useful work...
+##     Pretend I'm doing useful work...
+##     Pretend I'm doing useful work...
+##     Pretend I'm doing useful work...
+##     Pretend I'm doing useful work...
+##     Another message
 ##
 ## Passing Channels Safely
 ## -----------------------