[bugfix] document the norewrite pragma (#11453)

* fixes #9454
* Peer review feedback, wording, move to experimental manual

doc/manual.rst

@@ -6020,7 +6020,6 @@ In the example a new pragma named ``rtl`` is introduced that either imports
 a symbol from a dynamic library or exports the symbol for dynamic library
 generation.
 
-
 Disabling certain messages
 --------------------------
 Nim generates some warnings and hints ("line too long") that may annoy the

doc/manual_experimental.rst

@@ -1589,6 +1589,26 @@ having unknown lock level as well:
       g.memberProc()
 
 
+noRewrite pragma
+----------------
+
+Term rewriting macros and templates are currently greedy and
+they will rewrite as long as there is a match.
+There was no way to ensure some rewrite happens only once,
+eg. when rewriting term to same term plus extra content.
+
+``noRewrite`` pragma can actually prevent further rewriting on marked code,
+e.g. with given example ``echo("ab")`` will be rewritten just once:
+
+.. code-block:: nim
+  template pwnEcho{echo(x)}(x: expr) =
+    {.noRewrite.}: echo("pwned!")
+
+  echo "ab"
+
+``noRewrite`` pragma can be useful to control term-rewriting macros recursion.
+
+
 Taint mode
 ==========