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

doc/basicopt.txt

@@ -1,4 +1,3 @@
-::
 
     nim command [options] [projectfile] [arguments]
 

doc/contributing.md

@@ -314,12 +314,12 @@ To avoid accidental highlighting follow this rule in ``*.nim`` files:
   programming languages, including identifiers, in ``*.nim`` files.
 
   For languages other than Nim add a role after final backtick,
-  e.g. for C++ inline highlighting::
+  e.g. for C++ inline highlighting:
 
       `#include <stdio.h>`:cpp:
 
   For a currently unsupported language add the `:code:` role,
-  like for SQL in this example::
+  like for SQL in this example:
 
       `SELECT * FROM <table_name>;`:code:
 
@@ -336,7 +336,7 @@ To avoid accidental highlighting follow this rule in ``*.nim`` files:
 
 .. Note:: ``*.rst`` files have ``:literal:`` as their default role.
   So for them the rule above is only applicable if the ``:nim:`` role
-          is set up manually as the default \[*]::
+  is set up manually as the default \[*]:
 
       .. role:: nim(code)
          :language: nim
@@ -489,7 +489,7 @@ General commit rules
      git diff --check --cached || exit $?
      ```
 5. Describe your commit and use your common sense.
-   Example commit message::
+   Example commit message:
 
        Fixes #123; refs #124
 
@@ -581,8 +581,6 @@ Code reviews
 3. In addition, you can view GitHub-like diffs locally to identify what was changed
    within a code block using `diff-highlight`:cmd: or `diff-so-fancy`:cmd:, e.g.:
 
-   ::
-
         # put this in ~/.gitconfig:
         [core]
           pager = "diff-so-fancy | less -R" # or: use: `diff-highlight`

doc/destructors.md

@@ -358,7 +358,6 @@ Rewrite rules
 The current implementation follows strategy (2). This means that resources are
 destroyed at the scope exit.
 
-::
 
     var x: T; stmts
     ---------------             (destroy-var)

doc/docgen.md

@@ -64,7 +64,8 @@ Example:
     age: int
   ```
 
-Outputs::
+Outputs:
+
     Person* = object
       name: string
       age: int
@@ -133,7 +134,8 @@ The `doc`:option: command:
   nim doc docgen_sample.nim
   ```
 
-Partial Output::
+Partial Output:
+
     ...
     proc helloWorld(times: int) {.raises: [], tags: [].}
     ...
@@ -179,7 +181,8 @@ The `jsondoc`:option: command:
   nim jsondoc docgen_sample.nim
   ```
 
-Output::
+Output:
+
     {
       "orig": "docgen_sample.nim",
       "nimble": "",
@@ -205,7 +208,8 @@ The `jsondoc0`:option: command:
   nim jsondoc0 docgen_sample.nim
   ```
 
-Output::
+Output:
+
     [
       {
         "comment": "This module is a sample."
@@ -247,9 +251,12 @@ If you have a constant:
 
 then it should be referenced in one of the 2 forms:
 
-A. non-qualified (no symbol kind specification)::
+A. non-qualified (no symbol kind specification):
+
        pi_
-B. qualified (with symbol kind specification)::
+
+B. qualified (with symbol kind specification):
+
        `const pi`_
 
 For routine kinds there are more options. Consider this definition:
@@ -262,11 +269,11 @@ Generally following syntax is allowed for referencing `foo`:
 
 *  short (without parameters):
 
-   A. non-qualified::
+   A. non-qualified:
 
           foo_
 
-   B. qualified::
+   B. qualified:
 
           `proc foo`_
 
@@ -274,29 +281,29 @@ Generally following syntax is allowed for referencing `foo`:
 
    A. non-qualified:
 
-      1) specifying parameters names::
+      1) specifying parameters names:
 
              `foo(a, b)`_
 
-      2) specifying parameters types::
+      2) specifying parameters types:
 
              `foo(int, float)`_
 
-      3) specifying both names and types::
+      3) specifying both names and types:
 
              `foo(a: int, b: float)`_
 
-      4) output parameter can also be specified if you wish::
+      4) output parameter can also be specified if you wish:
 
              `foo(a: int, b: float): string`_
 
    B. qualified: all 4 options above are valid.
-      Particularly you can use the full format::
+      Particularly you can use the full format:
 
           `proc foo(a: int, b: float): string`_
 
 .. Tip:: Avoid cluttering your text with extraneous information by using
-   one of shorter forms::
+   one of shorter forms:
 
        binarySearch_
        `binarySearch(a, key, cmp)`_
@@ -304,7 +311,7 @@ Generally following syntax is allowed for referencing `foo`:
    Brevity is better for reading! If you use a short form and have an
    ambiguity problem (see below) then just add some additional info.
 
-Symbol kind like `proc` can also be specified in the postfix form::
+Symbol kind like `proc` can also be specified in the postfix form:
 
     `foo proc`_
     `walkDir(d: string) iterator`_
@@ -320,7 +327,7 @@ Symbol kind like `proc` can also be specified in the postfix form::
         `proc` and `template`. In this case they are split between their
         corresponding sections in output file. Qualified references are
         useful in this case -- just disambiguate by referring to these
-        sections explicitly::
+        sections explicitly:
 
             See `foo proc`_ and `foo template`_.
 
@@ -334,7 +341,7 @@ Symbol kind like `proc` can also be specified in the postfix form::
    (while procs have higher priority than other Nim symbol kinds).
 
 Generic parameters can also be used. All in all, this long form will be
-recognized fine::
+recognized fine:
 
     `proc binarySearch*[T; K](a: openArray[T], key: K, cmp: proc(T, K)): int`_
 
@@ -351,14 +358,14 @@ recognized fine::
       ```
 
    you cannot use names underlined by `~~` so it must be referenced with
-   ``cmp: proc(T, K)``. Hence these forms are valid::
+   ``cmp: proc(T, K)``. Hence these forms are valid:
 
        `binarySearch(a: openArray[T], key: K, cmp: proc(T, K))`_
        `binarySearch(openArray[T], K, proc(T, K))`_
        `binarySearch(a, key, cmp)`_
 2. Default values in routine parameters are not recognized, one needs to
    specify the type and/or name instead. E.g. for referencing `proc f(x = 7)`
-   use one of the mentioned forms::
+   use one of the mentioned forms:
 
        `f(int)`_ or `f(x)`_ or `f(x: int)`_.
 3. Generic parameters must be given the same way as in the
@@ -376,7 +383,7 @@ recognized fine::
       func `[]`*[T](x: openArray[T]): T
       ```
 
-   A short form works without additional backticks::
+   A short form works without additional backticks:
 
        `$`_
        `[]`_
@@ -384,7 +391,7 @@ recognized fine::
    However for fully-qualified reference copy-pasting backticks (`) into other
    backticks will not work in our RST parser (because we use Markdown-like
    inline markup rules). You need either to delete backticks or keep
-   them and escape with backslash \\::
+   them and escape with backslash \\:
 
        no backticks: `func $`_
        escaped:  `func \`$\``_
@@ -392,7 +399,7 @@ recognized fine::
        escaped:  `func \`[]\`[T](x: openArray[T]): T`_
 
 .. Note:: Types that defined as `enum`, or `object`, or `tuple` can also be
-   referenced with those names directly (instead of `type`)::
+   referenced with those names directly (instead of `type`):
 
        type CopyFlag = enum
          ...

doc/drnim.md

@@ -66,7 +66,7 @@ without additional annotations:
   ```
 
 This program contains a famous "index out of bounds" bug. DrNim
-detects it and produces the following error message::
+detects it and produces the following error message:
 
     cannot prove: i <= len(a) + -1; counter example: i -> 0 a.len -> 0 [IndexCheck]
 
@@ -146,7 +146,7 @@ Example: insertionSort
 Unfortunately, the invariants required to prove that this code is correct take more
 code than the imperative instructions. However, this effort can be compensated
 by the fact that the result needs very little testing. Be aware though that
-DrNim only proves that after `insertionSort` this condition holds::
+DrNim only proves that after `insertionSort` this condition holds:
 
     forall(i in 1..<a.len, a[i-1] <= a[i])
 
@@ -170,7 +170,7 @@ Syntax of propositions
 ======================
 
 The basic syntax is `ensures|requires|invariant: <prop>`.
-A `prop` is either a comparison or a compound::
+A `prop` is either a comparison or a compound:
 
     prop = nim_bool_expression
          | prop 'and' prop

doc/estp.md

@@ -70,7 +70,6 @@ the trace acts like an explanation; in traditional profilers you can only find
 expensive leaf functions easily but the *reason* why they are invoked
 often remains mysterious.
 
-::
     total executions of each stack trace:
     Entry: 0/3391 Calls: 84/4160 = 2.0% [sum: 84; 84/4160 = 2.0%]
       newCrcFromRopeAux

doc/filters.md

@@ -10,7 +10,7 @@ A `Source Code Filter (SCF)`  transforms the input character stream to an in-mem
 output stream before parsing. A filter can be used to provide templating
 systems or preprocessors.
 
-To use a filter for a source file the `#?` notation is used::
+To use a filter for a source file the `#?` notation is used:
 
     #? stdtmpl(subsChar = '$', metaChar = '#')
     #proc generateXML(name, age: string): string =
@@ -50,7 +50,7 @@ In your `main.nim`:
 Pipe operator
 =============
 
-Filters can be combined with the `|` pipe operator::
+Filters can be combined with the `|` pipe operator:
 
     #? strip(startswith="<") | stdtmpl
     #proc generateXML(name, age: string): string =
@@ -123,7 +123,7 @@ Parameters and their defaults:
 * `toString: string = "$"`
   : the operation that is applied to each expression
 
-Example::
+Example:
 
     #? stdtmpl | standard
     #proc generateHTMLPage(title, currentTab, content: string,
@@ -183,7 +183,7 @@ whitespace) is converted to a string literal that is added to `result`.
 The substitution character introduces a Nim expression *e* within the
 string literal. *e* is converted to a string with the *toString* operation
 which defaults to `$`. For strong type checking, set `toString` to the
-empty string. *e* must match this PEG pattern::
+empty string. *e* must match this PEG pattern:
 
     e <- [a-zA-Z\128-\255][a-zA-Z0-9\128-\255_.]* / '{' x '}'
     x <- '{' x+ '}' / [^}]*
@@ -192,7 +192,7 @@ To produce a single substitution character it has to be doubled: `$$`
 produces `$`.
 
 The template engine is quite flexible. It is easy to produce a procedure that
-writes the template code directly to a file::
+writes the template code directly to a file:
 
     #? stdtmpl(emit="f.write") | standard
     #proc writeHTMLPage(f: File, title, currentTab, content: string,

doc/idetools.md

@@ -36,13 +36,17 @@ Specifying the location of the query
 
 All of the available idetools commands require you to specify a
 query location through the `--track` or `--trackDirty` switches.
-The general idetools invocations are::
+The general idetools invocations are:
 
+  ```cmd
   nim idetools --track:FILE,LINE,COL <switches> proj.nim
+  ```
 
-Or::
+Or:
 
+  ```cmd
   nim idetools --trackDirty:DIRTY_FILE,FILE,LINE,COL <switches> proj.nim
+  ```
 
 `proj.nim`
 :   This is the main *project* filename. Most of the time you will
@@ -178,14 +182,18 @@ results of the compilation, and subsequent queries should be fast
 in the millisecond range, thus being responsive enough for IDEs.
 
 If you want to start the server using stdin/stdout as communication
-you need to type::
+you need to type:
 
+  ```cmd
   nim serve --server.type:stdin proj.nim
+  ```
 
-If you want to start the server using tcp and a port, you need to type::
+If you want to start the server using tcp and a port, you need to type:
 
+  ```cmd
   nim serve --server.type:tcp --server.port:6000 \
       --server.address:hostname proj.nim
+  ```
 
 In both cases the server will start up and await further commands.
 The syntax of the commands you can now send to the server is
@@ -542,10 +550,12 @@ Running the test suite
 
 At the moment idetools support is still in development so the test
 suite is not integrated with the main test suite and you have to
-run it manually. First you have to compile the tester::
+run it manually. First you have to compile the tester:
 
+  ```cmd
   $ cd my/nim/checkout/tests
   $ nim c testament/caasdriver.nim
+  ```
 
 Running the `caasdriver` without parameters will attempt to process
 all the test cases in all three operation modes. If a test succeeds
@@ -567,9 +577,11 @@ If you don't want to run all the test case files you can pass any
 substring as a parameter to `caasdriver`. Only files matching the
 passed substring will be run. The filtering doesn't use any globbing
 metacharacters, it's a plain match. For example, to run only
-`*-compile*.txt` tests in verbose mode::
+`*-compile*.txt` tests in verbose mode:
 
+  ```cmd
   ./caasdriver verbose -compile
+  ```
 
 
 Test case file format

doc/intern.md

@@ -593,14 +593,14 @@ Integer literals
 In Nim, there is a redundant way to specify the type of an
 integer literal. First, it should be unsurprising that every
 node has a node kind. The node of an integer literal can be any of the
-following values::
+following values:
 
     nkIntLit, nkInt8Lit, nkInt16Lit, nkInt32Lit, nkInt64Lit,
     nkUIntLit, nkUInt8Lit, nkUInt16Lit, nkUInt32Lit, nkUInt64Lit
 
 On top of that, there is also the `typ` field for the type. The
 kind of the `typ` field can be one of the following ones, and it
-should be matching the literal kind::
+should be matching the literal kind:
 
     tyInt, tyInt8, tyInt16, tyInt32, tyInt64, tyUInt, tyUInt8,
     tyUInt16, tyUInt32, tyUInt64
@@ -656,7 +656,6 @@ pointing back to the integer literal node in the ast containing the
 integer value. These are the properties that hold true for integer
 literal types.
 
-::
     n.kind == nkIntLit
     n.typ.kind == tyInt
     n.typ.n == n

doc/manual.md

@@ -47,14 +47,14 @@ is not ambiguous.
 
 Non-terminals start with a lowercase letter, abstract terminal symbols are in
 UPPERCASE. Verbatim terminal symbols (including keywords) are quoted
-with `'`. An example::
+with `'`. An example:
 
     ifStmt = 'if' expr ':' stmts ('elif' expr ':' stmts)* ('else' stmts)?
 
 The binary `^*` operator is used as a shorthand for 0 or more occurrences
 separated by its second argument; likewise `^+` means 1 or more
 occurrences: `a ^+ b` is short for `a (b a)*`
-and `a ^* b` is short for `(a (b a)*)?`. Example::
+and `a ^* b` is short for `(a (b a)*)?`. Example:
 
     arrayConstructor = '[' expr ^* ',' ']'
 
@@ -190,7 +190,7 @@ is another pseudo terminal that describes the *action* of popping a value
 from the stack, `IND{>}` then implies to push onto the stack.
 
 With this notation we can now easily define the core of the grammar: A block of
-statements (simplified example)::
+statements (simplified example):
 
     ifStmt = 'if' expr ':' stmt
              (IND{=} 'elif' expr ':' stmt)*
@@ -409,7 +409,7 @@ ending of the string literal is defined by the pattern `"""[^"]`, so this:
   """"long string within quotes""""
   ```
 
-Produces::
+Produces:
 
     "long string within quotes"
 
@@ -434,7 +434,7 @@ To produce a single `"` within a raw string literal, it has to be doubled:
   r"a""b"
   ```
 
-Produces::
+Produces:
 
     a"b
 
@@ -513,7 +513,7 @@ See also [custom numeric literals].
 Numeric literals
 ----------------
 
-Numeric literals have the form::
+Numeric literals have the form:
 
     hexdigit = digit | 'A'..'F' | 'a'..'f'
     octdigit = '0'..'7'
@@ -674,7 +674,7 @@ Operators
 ---------
 
 Nim allows user defined operators. An operator is any combination of the
-following characters::
+following characters:
 
        =     +     -     *     /     <     >
        @     $     ~     &     %     |
@@ -698,7 +698,7 @@ as `a(not b)`, not as `(a) not (b)`.
 Unicode Operators
 -----------------
 
-These Unicode operators are also parsed as operators::
+These Unicode operators are also parsed as operators:
 
     ∙ ∘ × ★ ⊗ ⊘ ⊙ ⊛ ⊠ ⊡ ∩ ∧ ⊓   # same priority as * (multiplication)
     ± ⊕ ⊖ ⊞ ⊟ ∪ ∨ ⊔             # same priority as + (addition)
@@ -714,7 +714,7 @@ No Unicode normalization step is performed.
 Other tokens
 ------------
 
-The following strings denote other tokens::
+The following strings denote other tokens:
 
     `   (    )     {    }     [    ]    ,  ;   [.    .]  {.   .}  (.  .)  [:
 
@@ -1207,9 +1207,11 @@ The boolean type is named `bool`:idx: in Nim and can be one of the two
 pre-defined values `true` and `false`. Conditions in `while`,
 `if`, `elif`, `when`-statements need to be of type `bool`.
 
-This condition holds::
+This condition holds:
 
+  ```nim
   ord(false) == 0 and ord(true) == 1
+  ```
 
 The operators `not, and, or, xor, <, <=, >, >=, !=, ==` are defined
 for the bool type. The `and` and `or` operators perform short-cut
@@ -1248,8 +1250,9 @@ specified. The values are ordered. Example:
   ```
 
 
-Now the following holds::
+Now the following holds:
 
+  ```nim
   ord(north) == 0
   ord(east) == 1
   ord(south) == 2
@@ -1257,6 +1260,7 @@ Now the following holds::
 
   # Also allowed:
   ord(Direction.west) == 3
+  ```
 
 The implied order is: north < east < south < west. The comparison operators can be used
 with enumeration types. Instead of `north` etc., the enum value can also
@@ -2568,8 +2572,9 @@ literal match and that is better than a generic match etc. In the following,
 for the routine `p`.
 
 A routine `p` matches better than a routine `q` if the following
-algorithm returns true::
+algorithm returns true:
 
+  ```nim
   for each matching category m in ["exact match", "literal match",
                                   "generic match", "subtype match",
                                   "integral match", "conversion match"]:
@@ -2579,6 +2584,7 @@ algorithm returns true::
     else:
       return false
   return "ambiguous"
+  ```
 
 
 Some examples:
@@ -4061,7 +4067,7 @@ Nonoverloadable builtins
 ------------------------
 
 The following built-in procs cannot be overloaded for reasons of implementation
-simplicity (they require specialized semantic checking)::
+simplicity (they require specialized semantic checking):
 
     declared, defined, definedInScope, compiles, sizeof,
     is, shallowCopy, getAst, astToStr, spawn, procCall
@@ -4071,7 +4077,7 @@ keyword however, a redefinition may `shadow`:idx: the definition in
 the [system](system.html) module.
 From this list the following should not be written in dot
 notation `x.f` since `x` cannot be type-checked before it gets passed
-to `f`::
+to `f`:
 
     declared, defined, definedInScope, compiles, getAst, astToStr
 
@@ -8291,7 +8297,7 @@ The `dynlib` import mechanism supports a versioning scheme:
     importc, dynlib: "libtcl(|8.5|8.4|8.3).so.(1|0)".}
   ```
 
-At runtime, the dynamic library is searched for (in this order)::
+At runtime, the dynamic library is searched for (in this order):
 
     libtcl.so.1
     libtcl.so.0

doc/manual_experimental.md

@@ -790,7 +790,7 @@ be part of a single graph.
 Assignments like `a = b` "connect" two variables, both variables end up in the
 same graph `{a, b} = G(a) = G(b)`. Unfortunately, the pattern to look for is
 much more complex than that and can involve multiple assignment targets
-and sources::
+and sources:
 
     f(x, y) = g(a, b)
 
@@ -1586,7 +1586,7 @@ all the arguments, but also the matched operators in reverse polish notation:
   ```
 
 This passes the expression `x + y * z - x` to the `optM` macro as
-an `nnkArgList` node containing::
+an `nnkArgList` node containing:
 
     Arglist
       Sym "x"

doc/markdown_rst.md

@@ -22,7 +22,8 @@ Usage (to convert Markdown into HTML):
   nim md2html markdown_rst.md
   ```
 
-Output::
+Output:
+
     You're reading it!
 
 The `md2tex`:option: command is invoked identically to `md2html`:option:,
@@ -132,7 +133,7 @@ Additional Nim-specific features
 * ``:idx:`` role for \`interpreted text\` to include the link to this
   text into an index (example: [Nim index]).
 * double slash `//` in option lists serves as a prefix for any option that
-  starts from a word (without any leading symbols like `-`, `--`, `/`)::
+  starts from a word (without any leading symbols like `-`, `--`, `/`):
 
       //compile   compile the project
       //doc       generate documentation
@@ -152,7 +153,7 @@ Optional additional features, by default turned on:
 * Markdown tables
 * Markdown code blocks. For them the same additional arguments as for RST
   code blocks can be provided (e.g. `test` or `number-lines`) but with
-  a one-line syntax like this::
+  a one-line syntax like this:
 
       ```nim test number-lines=10
       echo "ok"
@@ -189,7 +190,7 @@ This parser has 2 modes for inline markup:
      does escape so that we can always input a single backtick ` in
      inline code. However that makes impossible to input code with
      ``\`` at the end in *single* backticks, one must use *double*
-     backticks::
+     backticks:
 
          `\`   -- WRONG
          ``\`` -- GOOD
@@ -204,8 +205,6 @@ This parser has 2 modes for inline markup:
    - interpretation of Markdown block quotes is also slightly different,
      e.g. case
 
-     ::
-
          >>> foo
          > bar
          >>baz

doc/nimc.md

@@ -241,7 +241,7 @@ found an ambiguity error is produced.
 
 However before the PATH is used the current directory is checked for the
 file's existence. So if PATH contains ``$lib`` and ``$lib/bar`` and the
-directory structure looks like this::
+directory structure looks like this:
 
     $lib/x.nim
     $lib/bar/x.nim
@@ -319,7 +319,7 @@ Another way is to make Nim invoke a cross compiler toolchain:
 For cross compilation, the compiler invokes a C compiler named
 like `$cpu.$os.$cc` (for example arm.linux.gcc) and the configuration
 system is used to provide meaningful defaults. For example for `ARM` your
-configuration file should contain something like::
+configuration file should contain something like:
 
     arm.linux.gcc.path = "/usr/bin"
     arm.linux.gcc.exe = "arm-linux-gcc"
@@ -435,7 +435,7 @@ and `passL`:option: command line switches to something like:
   --passL="-specs=$DEVKITPRO/libnx/switch.specs -L$DEVKITPRO/libnx/lib -lnx"
   ```
 
-or setup a ``nim.cfg`` file like so::
+or setup a ``nim.cfg`` file like so:
 
     #nim.cfg
     --mm:orc

doc/nimfix.md

@@ -28,21 +28,28 @@ system by this day and age, your project is already in big trouble.
 Installation
 ------------
 
-Nimfix is part of the compiler distribution. Compile via::
+Nimfix is part of the compiler distribution. Compile via:
 
+  ```cmd
   nim c compiler/nimfix/nimfix.nim
   mv compiler/nimfix/nimfix bin
+  ```
 
-Or on windows::
+Or on windows:
 
+  ```cmd
   nim c compiler\nimfix\nimfix.nim
   move compiler\nimfix\nimfix.exe bin
+  ```
 
 Usage
 -----
 
 Usage:
+
+  ```cmd
   nimfix [options] projectfile.nim
+  ```
 
 Options:
 

doc/nimgrep_cmdline.txt

@@ -1,11 +1,16 @@
 
 Usage:
 
-* To search::
+* To search:
+
       nimgrep [options] PATTERN [(FILE/DIRECTORY)*/-]
-* To replace::
+
+* To replace:
+
       nimgrep [options] PATTERN --replace REPLACEMENT (FILE/DIRECTORY)*/-
-* To list file names::
+
+* To list file names:
+
       nimgrep [options] --filenames [PATTERN] [(FILE/DIRECTORY)*]
 
 Positional arguments, from left to right:
@@ -42,7 +47,8 @@ Options:
                       to abort any time without touching the file
   --filenames         just list filenames. Provide a PATTERN to find it in
                       the filenames (not in the contents of a file) or run
-                      with empty pattern to just list all files::
+                      with empty pattern to just list all files:
+
                           nimgrep --filenames               # In current dir
                           nimgrep --filenames "" DIRECTORY
                            # Note empty pattern "", lists all files in DIRECTORY

doc/niminst.md

@@ -72,7 +72,7 @@ Key                    description
 Many sections support the `files` key. Listed filenames
 can be separated by semicolon or the `files` key can be repeated. Wildcards
 in filenames are supported. If it is a directory name, all files in the
-directory are used::
+directory are used:
 
     [Config]
     Files: "configDir"

doc/pegdocs.txt

@@ -131,7 +131,7 @@ notation           meaning
 Supported PEG grammar
 ---------------------
 
-The PEG parser implements this grammar (written in PEG syntax)::
+The PEG parser implements this grammar (written in PEG syntax):
 
     # Example grammar of PEG in PEG syntax.
     # Comments start with '#'.

doc/regexprs.txt

@@ -56,7 +56,7 @@ backslashes are interpreted by the regular expression engine:
 A regular expression is a pattern that is matched against a subject string
 from left to right. Most characters stand for themselves in a pattern, and
 match the corresponding characters in the subject. As a trivial example,
-the pattern::
+the pattern:
 
     The quick brown fox
 
@@ -130,7 +130,7 @@ in patterns in a visible manner. There is no restriction on the appearance of
 non-printing characters, apart from the binary zero that terminates a pattern,
 but when a pattern is being prepared by text editing, it is usually easier to
 use one of the following escape sequences than the binary character it
-represents::
+represents:
 
 ==============     ============================================================
 character          meaning
@@ -246,7 +246,7 @@ The fourth use of backslash is for certain `simple assertions`:idx:. An
 assertion specifies a condition that has to be met at a particular point in
 a match, without consuming any characters from the subject string. The use of
 subpatterns for more complicated assertions is described below. The
-backslashed assertions are::
+backslashed assertions are:
 
 ==============     ============================================================
 assertion          meaning

doc/rstcommon.rst

@@ -1,6 +1,6 @@
 ..
   Usage of this file:
-     Add this in the beginning of *.rst file::
+     Add this in the beginning of *.rst file:
 
          .. default-role:: code
          .. include:: rstcommon.rst

doc/tut1.md

@@ -45,24 +45,28 @@ We start the tour with a modified "hello world" program:
   ```
 
 
-Save this code to the file "greetings.nim". Now compile and run it::
+Save this code to the file "greetings.nim". Now compile and run it:
-
+  ```cmd
   nim compile --run greetings.nim
+  ```
 
 With the ``--run`` [switch](nimc.html#compiler-usage-commandminusline-switches) Nim
 executes the file automatically after compilation. You can give your program
-command-line arguments by appending them after the filename::
+command-line arguments by appending them after the filename:
-
+  ```cmd
   nim compile --run greetings.nim arg1 arg2
+  ```
 
-Commonly used commands and switches have abbreviations, so you can also use::
+Commonly used commands and switches have abbreviations, so you can also use:
-
+  ```cmd
   nim c -r greetings.nim
+  ```
 
 This is a **debug version**.
-To compile a release version use::
+To compile a release version use:
-
+  ```cmd
   nim c -d:release greetings.nim
+  ```
 
 By default, the Nim compiler generates a large number of runtime checks
 aiming for your debugging pleasure. With ``-d:release`` some checks are

lib/packages/docutils/dochelpers.nim

@@ -75,7 +75,7 @@ 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 []`_

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
+        break  # blank line breaks paragraph for both Md & Rst
-      elif currentTok(p).ival == currInd(p):
+      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,8 +2935,8 @@ 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,
+            result.add parseLiteralBlock(p)
-                       "Markdown indented code not implemented")
+          else:
             pushInd(p, currentTok(p).ival)
             parseSection(p, result)
             popInd(p)

lib/packages/docutils/rstast.nim

@@ -377,7 +377,7 @@ 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,

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,7 +9,7 @@
 
 ## 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:
 ##

lib/pure/htmlgen.nim

@@ -34,7 +34,7 @@
 ##   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>
 ##

lib/pure/os.nim

@@ -2294,7 +2294,8 @@ iterator walkDir*(dir: string; relative = false, checkDir = false):
   ##
   ## **Example:**
   ##
-  ## This directory structure::
+  ## This directory structure:
+  ##
   ##     dirA / dirB / fileB1.txt
   ##          / dirC
   ##          / fileA1.txt

lib/pure/pegs.nim

@@ -2058,7 +2058,7 @@ 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* {.*}"
   result = parsePeg(pattern, "pattern")

lib/pure/strformat.nim

@@ -171,7 +171,7 @@ 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]
 
@@ -423,7 +423,7 @@ 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]
   ##

lib/pure/xmltree.nim

@@ -778,7 +778,7 @@ 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>
   ##

lib/system/channels_builtin.nim

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

tests/stdlib/trst.nim

@@ -7,6 +7,8 @@ discard """
 
 [Suite] RST indentation
 
+[Suite] Markdown indentation
+
 [Suite] Warnings
 
 [Suite] RST include directive
@@ -124,12 +126,12 @@ suite "RST parsing":
     check(dedent"""
         Paragraph::
 
-        >x""".toAst == expected)
+        >x""".toAst(rstOptions = preferRst) == expected)
 
     check(dedent"""
         Paragraph::
 
-            >x""".toAst == expected)
+            >x""".toAst(rstOptions = preferRst) == expected)
 
   test "RST quoted literal blocks, :: at a separate line":
     let expected =
@@ -148,7 +150,7 @@ suite "RST parsing":
         ::
 
         >x
-        >>y""".toAst == expected)
+        >>y""".toAst(rstOptions = preferRst) == expected)
 
     check(dedent"""
         Paragraph
@@ -156,7 +158,7 @@ suite "RST parsing":
         ::
 
           >x
-          >>y""".toAst == expected)
+          >>y""".toAst(rstOptions = preferRst) == expected)
 
   test "Markdown quoted blocks":
     check(dedent"""
@@ -779,7 +781,7 @@ suite "RST parsing":
 
         code
 
-      """.toAst ==
+      """.toAst(rstOptions = preferRst) ==
       dedent"""
         rnInner
           rnLeaf  'Check'
@@ -788,6 +790,32 @@ suite "RST parsing":
             rnLeaf  'code'
       """)
 
+  test "Markdown indented code blocks":
+    check(dedent"""
+      See
+
+          some code""".toAst ==
+      dedent"""
+        rnInner
+          rnInner
+            rnLeaf  'See'
+          rnLiteralBlock
+            rnLeaf  'some code'
+      """)
+
+    # not a code block -- no blank line before:
+    check(dedent"""
+      See
+          some code""".toAst ==
+      dedent"""
+        rnInner
+          rnLeaf  'See'
+          rnLeaf  ' '
+          rnLeaf  'some'
+          rnLeaf  ' '
+          rnLeaf  'code'
+      """)
+
 suite "RST tables":
 
   test "formatting in tables works":
@@ -1238,6 +1266,31 @@ suite "RST indentation":
                 rnLeaf  'term3definition2'
       """)
 
+suite "Markdown indentation":
+  test "Markdown paragraph indentation":
+    # Additional spaces (<=3) of indentation does not break the paragraph.
+    # TODO: in 2nd case de-indentation causes paragraph to break, this is
+    # reasonable but does not seem to conform the Markdown spec.
+    check(dedent"""
+      Start1
+        stop1
+
+        Start2
+      stop2
+      """.toAst ==
+      dedent"""
+        rnInner
+          rnParagraph
+            rnLeaf  'Start1'
+            rnLeaf  ' '
+            rnLeaf  'stop1'
+          rnParagraph
+            rnLeaf  'Start2'
+          rnParagraph
+            rnLeaf  'stop2'
+            rnLeaf  ' '
+      """)
+
 suite "Warnings":
   test "warnings for broken footnotes/links/substitutions":
     let input = dedent"""

tests/stdlib/trstgen.nim

@@ -632,7 +632,7 @@ Test literal block
 ::
 
   check """
-    let output1 = input1.toHtml
+    let output1 = input1.toHtml(preferRst)
     doAssert "<pre>" in output1
 
   test "Markdown code block":