Improve Markdown code blocks & start moving docs to Markdown style (#19954)

- add additional parameters parsing (other implementations will just
  ignore them). E.g. if in RST we have:

  .. code:: nim
     :test: "nim c $1"

     ...

  then in Markdown that will be:

  ```nim test="nim c $1"
  ...
  ```

- implement Markdown interpretation of additional indentation which is
  less than 4 spaces (>=4 spaces is a code block but it's not
implemented yet). RST interpretes it as quoted block, for Markdown it's
just normal paragraphs.
- add separate `md2html` and `md2tex` commands. This is to separate
  Markdown behavior in cases when it diverges w.r.t. RST significantly —
most conspicously like in the case of additional indentation above, and
also currently the contradicting inline rule of Markdown is also turned
on only in `md2html` and `md2tex`. **Rationale:** mixing Markdown and
RST arbitrarily is a way to nowhere, we need to provide a way to fix the
particular behavior. Note that still all commands have **both** Markdown
and RST features **enabled**. In this PR `*.nim` files can be processed
only in Markdown mode, while `md2html` is for `*.md` files and
`rst2html` for `*.rst` files.
- rename `*.rst` files to `.*md` as our current default behavior is
  already Markdown-ish
- convert code blocks in `docgen.rst` to Markdown style as an example.
  Other code blocks will be converted in the follow-up PRs
- fix indentation inside Markdown code blocks — additional indentation
  is preserved there
- allow more than 3 backticks open/close blocks (tildas \~ are still not
  allowed to avoid conflict with RST adornment headings) see also
https://github.com/nim-lang/RFCs/issues/355
- better error messages
- (other) fix a bug that admonitions cannot be used in sandbox mode; fix
  annoying warning on line 2711

doc/mm.md

@@ -0,0 +1,95 @@
+=======================
+Nim's Memory Management
+=======================
+
+.. default-role:: code
+.. include:: rstcommon.rst
+
+:Author: Andreas Rumpf
+:Version: |nimversion|
+
+..
+
+
+> "The road to hell is paved with good intentions."
+
+
+Multi-paradigm Memory Management Strategies
+===========================================
+
+.. default-role:: option
+
+Nim offers multiple different memory management strategies.
+To choose the memory management strategy use the `--mm:` switch.
+
+**The recommended switch for newly written Nim code is `--mm:orc`.**
+
+
+ARC/ORC
+-------
+
+`--mm:orc` is a memory management mode primarily based on reference counting. Cycles
+in the object graph are handled by a "cycle collector" which is based on "trial deletion".
+Since algorithms based on "tracing" are not used, the runtime behavior is oblivious to
+the involved heap sizes.
+
+The reference counting operations (= "RC ops") do not use atomic instructions and do not have to --
+instead entire subgraphs are *moved* between threads. The Nim compiler also aggressively
+optimizes away RC ops and exploits `move semantics <destructors.html#move-semantics>`_.
+
+Nim performs a fair share of optimizations for ARC/ORC; you can inspect what it did
+to your time critical function via `--expandArc:functionName`.
+
+`--mm:arc` uses the same mechanism as `--mm:orc`, but it leaves out the cycle collector.
+Both ARC and ORC offer deterministic performance for `hard realtime`:idx: systems, but
+ARC can be easier to reason about for people coming from Ada/C++/C -- roughly speaking
+the memory for a variable is freed when it goes "out of scope".
+
+We generally advise you to use the `acyclic` annotation in order to optimize away the
+cycle collector's overhead
+but `--mm:orc` also produces more machine code than `--mm:arc`, so if you're on a target
+where code size matters and you know that your code does not produce cycles, you can
+use `--mm:arc`. Notice that the default `async`:idx: implementation produces cycles
+and leaks memory with `--mm:arc`, in other words, for `async` you need to use `--mm:orc`.
+
+
+
+Other MM modes
+--------------
+
+.. note:: The default `refc` GC is incremental, thread-local and not "stop-the-world".
+
+--mm:refc    This is the default memory management strategy. It's a
+  deferred reference counting based garbage collector
+  with a simple Mark&Sweep backup GC in order to collect cycles. Heaps are thread-local.
+  `This document <refc.html>`_ contains further information.
+--mm:markAndSweep  Simple Mark-And-Sweep based garbage collector.
+  Heaps are thread-local.
+--mm:boehm    Boehm based garbage collector, it offers a shared heap.
+--mm:go    Go's garbage collector, useful for interoperability with Go.
+  Offers a shared heap.
+
+--mm:none    No memory management strategy nor a garbage collector. Allocated memory is
+  simply never freed. You should use `--mm:arc` instead.
+
+Here is a comparison of the different memory management modes:
+
+================== ======== ================= ============== ===================
+Memory Management  Heap     Reference Cycles  Stop-The-World Command line switch
+================== ======== ================= ============== ===================
+ORC                Shared   Cycle Collector   No             `--mm:orc`
+ARC                Shared   Leak              No             `--mm:arc`
+RefC               Local    Cycle Collector   No             `--mm:refc`
+Mark & Sweep       Local    Cycle Collector   No             `--mm:markAndSweep`
+Boehm              Shared   Cycle Collector   Yes            `--mm:boehm`
+Go                 Shared   Cycle Collector   Yes            `--mm:go`
+None               Manual   Manual            Manual         `--mm:none`
+================== ======== ================= ============== ===================
+
+.. default-role:: code
+.. include:: rstcommon.rst
+
+JavaScript's garbage collector is used for the `JavaScript and NodeJS
+<backends.html#backends-the-javascript-target>`_ compilation targets.
+The `NimScript <nims.html>`_ target uses the memory management strategy built into
+the Nim compiler.