follow-up #18013 - inline syntax highlighting (#18166)

20 files changed, 183 insertions, 164 deletions

diff --git a/doc/destructors.rst b/doc/destructors.rst
index 3cd4cd925..c99606b95 100644
--- a/doc/destructors.rst
+++ b/doc/destructors.rst
@@ -5,8 +5,8 @@ Nim Destructors and Move Semantics
 :Authors: Andreas Rumpf
 :Version: |nimversion|
 
+.. default-role:: code
 .. include:: rstcommon.rst
-.. default-role:: nim
 .. contents::
 
 
diff --git a/doc/docgen.rst b/doc/docgen.rst
index 86352a989..e9ff7f1e3 100644
--- a/doc/docgen.rst
+++ b/doc/docgen.rst
@@ -5,8 +5,8 @@
 :Author: Erik O'Leary
 :Version: |nimversion|
 
+.. default-role:: code
 .. include:: rstcommon.rst
-.. default-role:: Nim
 .. contents::
 
 
diff --git a/doc/drnim.rst b/doc/drnim.rst
index 08de7cd6d..070cd1787 100644
--- a/doc/drnim.rst
+++ b/doc/drnim.rst
@@ -5,8 +5,8 @@
 :Author: Andreas Rumpf
 :Version: |nimversion|
 
+.. default-role:: code
 .. include:: rstcommon.rst
-.. default-role:: Nim
 .. contents::
 
 
@@ -43,7 +43,7 @@ your code.
 Installation
 ============
 
-Run `koch drnim`:option:, the executable will afterwards be
+Run `koch drnim`:cmd:, the executable will afterwards be
 in ``$nim/bin/drnim``.
 
 
diff --git a/doc/estp.rst b/doc/estp.rst
index 43128bef7..550194d2d 100644
--- a/doc/estp.rst
+++ b/doc/estp.rst
@@ -2,8 +2,8 @@
   Embedded Stack Trace Profiler (ESTP) User Guide
 ===================================================
 
+.. default-role:: code
 .. include:: rstcommon.rst
-.. default-role:: Nim
 
 :Author: Andreas Rumpf
 :Version: |nimversion|
diff --git a/doc/hcr.rst b/doc/hcr.rst
index 574c4f39d..dd25e39b3 100644
--- a/doc/hcr.rst
+++ b/doc/hcr.rst
@@ -1,9 +1,10 @@
-.. default-role:: code
-
 ===================================
       Hot code reloading
 ===================================
 
+.. default-role:: code
+.. include:: rstcommon.rst
+
 The `hotCodeReloading`:idx: option enables special compilation mode where
 changes in the code can be applied automatically to a running program.
 The code reloading happens at the granularity of an individual module.
@@ -22,7 +23,7 @@ during development resides.
 
 In this example, we use SDL2 to create a window and we reload the logic
 code when `F9` is pressed. The important lines are marked with `#***`.
-To install SDL2 you can use `nimble install sdl2`.
+To install SDL2 you can use `nimble install sdl2`:cmd:.
 
 
 .. code-block:: nim
@@ -98,34 +99,40 @@ To install SDL2 you can use `nimble install sdl2`.
   main()
 
 
-Compile this example via::
+Compile this example via:
 
+```cmd
   nim c --hotcodereloading:on mymain.nim
+```
 
 Now start the program and KEEP it running!
 
-::
-
+.. code:: cmd
   # Unix:
   mymain &
   # or Windows (click on the .exe)
   mymain.exe
   # edit
 
-For example, change the line::
+For example, change the line:
 
+```nim
   discard renderer.setDrawColor(255, 128, 128, 0)
+```
 
-into::
+into:
 
+```nim
   discard renderer.setDrawColor(255, 255, 128, 0)
+```
 
 (This will change the color of the rectangle.)
 
 Then recompile the project, but do not restart or quit the mymain.exe program!
-::
 
+```cmd
   nim c --hotcodereloading:on mymain.nim
+```
 
 Now give the `mymain` SDL window the focus, press F9, and watch the
 updated version of the program.
@@ -188,15 +195,15 @@ Native code targets
 ===================
 
 Native projects using the hot code reloading option will be implicitly
-compiled with the `-d:useNimRtl` option and they will depend on both
+compiled with the `-d:useNimRtl`:option: option and they will depend on both
 the `nimrtl` library and the `nimhcr` library which implements the
 hot code reloading run-time. Both libraries can be found in the `lib`
 folder of Nim and can be compiled into dynamic libraries to satisfy
 runtime demands of the example code above. An example of compiling
-`nimhcr.nim` and `nimrtl.nim` when the source dir of Nim is installed
+``nimhcr.nim`` and ``nimrtl.nim`` when the source dir of Nim is installed
 with choosenim follows.
 
-::
+.. code:: console
 
   # Unix/MacOS
   # Make sure you are in the directory containing your .nim files
diff --git a/doc/intern.rst b/doc/intern.rst
index 2f83e0d06..ab74c4a3a 100644
--- a/doc/intern.rst
+++ b/doc/intern.rst
@@ -6,8 +6,8 @@
 :Author: Andreas Rumpf
 :Version: |nimversion|
 
+.. default-role:: code
 .. include:: rstcommon.rst
-.. default-role:: Nim
 .. contents::
 
   "Abstraction is layering ignorance on top of reality." -- Richard Gabriel
diff --git a/doc/koch.rst b/doc/koch.rst
index 1eb02d785..b8d85dff4 100644
--- a/doc/koch.rst
+++ b/doc/koch.rst
@@ -1,11 +1,11 @@
-.. default-role:: code
-
 ===============================
    Nim maintenance script
 ===============================
 
 :Version: |nimversion|
 
+.. default-role:: code
+.. include:: rstcommon.rst
 .. contents::
 
 .. raw:: html
@@ -19,7 +19,7 @@ Introduction
 
 The `koch`:idx: program is Nim's maintenance script. It is a replacement
 for make and shell scripting with the advantage that it is much more portable.
-The word *koch* means *cook* in German. `koch` is used mainly to build the
+The word *koch* means *cook* in German. `koch`:cmd: is used mainly to build the
 Nim compiler, but it can also be used for other tasks. This document
 describes the supported commands and their options.
 
@@ -33,12 +33,11 @@ boot command
 The `boot`:idx: command bootstraps the compiler, and it accepts different
 options:
 
--d:release
-  By default a debug version is created, passing this option will
+-d:release    By default a debug version is created, passing this option will
   force a release build, which is much faster and should be preferred
   unless you are debugging the compiler.
--d:nimUseLinenoise
-  Use the linenoise library for interactive mode (not needed on Windows).
+-d:nimUseLinenoise     Use the linenoise library for interactive mode
+                       (not needed on Windows).
 
 After compilation is finished you will hopefully end up with the nim
 compiler in the `bin` directory. You can add Nim's `bin` directory to
@@ -56,16 +55,16 @@ temp command
 ------------
 
 The temp command builds the Nim compiler but with a different final name
-(`nim_temp`), so it doesn't overwrite your normal compiler. You can use
+(`nim_temp`:cmd:), so it doesn't overwrite your normal compiler. You can use
 this command to test different options, the same you would issue for the `boot
 command <#commands-boot-command>`_.
 
 test command
 ------------
 
-The `test`:idx: command can also be invoked with the alias `tests`. This
-command will compile and run `testament/tester.nim`, which is the main
-driver of Nim's test suite. You can pass options to the `test` command,
+The `test`:idx: command can also be invoked with the alias `tests`:option:. This
+command will compile and run ``testament/tester.nim``, which is the main
+driver of Nim's test suite. You can pass options to the `test`:option: command,
 they will be forwarded to the tester. See its source code for available
 options.
 
@@ -74,13 +73,13 @@ web command
 
 The `web`:idx: command converts the documentation in the `doc` directory
 from rst to HTML. It also repeats the same operation but places the result in
-the `web/upload` which can be used to update the website at
+the ``web/upload`` which can be used to update the website at
 https://nim-lang.org.
 
 By default, the documentation will be built in parallel using the number of
 available CPU cores. If any documentation build sub-commands fail, they will
 be rerun in serial fashion so that meaningful error output can be gathered for
-inspection. The `--parallelBuild:n` switch or configuration option can be
+inspection. The `--parallelBuild:n`:option: switch or configuration option can be
 used to force a specific number of parallel jobs or run everything serially
 from the start (`n == 1`).
 
@@ -89,4 +88,4 @@ pdf command
 
 The `pdf`:idx: command builds PDF versions of Nim documentation: Manual,
 Tutorial and a few other documents. To run it one needs to
-`install Latex/pdflatex <https://www.latex-project.org/get>`_ first.
+`install Latex/xelatex <https://www.latex-project.org/get>`_ first.
diff --git a/doc/lib.rst b/doc/lib.rst
index f09fe16b2..988fbf6f0 100644
--- a/doc/lib.rst
+++ b/doc/lib.rst
@@ -1,5 +1,3 @@
-.. default-role:: code
-
 ====================
 Nim Standard Library
 ====================
@@ -7,11 +5,13 @@ Nim Standard Library
 :Author: Andreas Rumpf
 :Version: |nimversion|
 
+.. default-role:: code
+.. include:: rstcommon.rst
 .. contents::
 
 Nim's library is divided into *pure libraries*, *impure libraries*, and *wrappers*.
 
-Pure libraries do not depend on any external `*.dll` or `lib*.so` binary
+Pure libraries do not depend on any external ``*.dll`` or ``lib*.so`` binary
 while impure libraries do. A wrapper is an impure library that is a very
 low-level interface to a C library.
 
@@ -39,11 +39,11 @@ Automatic imports
 
 * `threads <threads.html>`_
   Basic Nim thread support. **Note:** This is part of the system module. Do not
-  import it explicitly. Enabled with `--threads:on`.
+  import it explicitly. Enabled with `--threads:on`:option:.
 
 * `channels <channels_builtin.html>`_
   Nim message passing support for threads. **Note:** This is part of the
-  system module. Do not import it explicitly. Enabled with `--threads:on`.
+  system module. Do not import it explicitly. Enabled with `--threads:on`:option:.
 
 
 Core
@@ -366,7 +366,7 @@ Parsers
 
 * `parsecfg <parsecfg.html>`_
   The `parsecfg` module implements a high-performance configuration file
-  parser. The configuration file's syntax is similar to the Windows `.ini`
+  parser. The configuration file's syntax is similar to the Windows ``.ini``
   format, but much more powerful, as it is not a line based parser. String
   literals, raw string literals, and triple quote string literals are supported
   as in the Nim programming language.
diff --git a/doc/manual.rst b/doc/manual.rst
index ff34b62ca..867db245b 100644
--- a/doc/manual.rst
+++ b/doc/manual.rst
@@ -572,7 +572,8 @@ In the following examples, `-1` is a single token:
 
   "abc";-1
 
-In the following examples, `-1` is parsed as two separate tokens (as `- 1`):
+In the following examples, `-1` is parsed as two separate tokens
+(as `-`:tok: `1`:tok:):
 
 .. code-block:: nim
 
@@ -2509,7 +2510,7 @@ of the argument.
    range.
 3. Generic match: `f` is a generic type and `a` matches, for
    instance `a` is `int` and `f` is a generic (constrained) parameter
-   type (like in `[T]` or `[T: int|char]`.
+   type (like in `[T]` or `[T: int|char]`).
 4. Subrange or subtype match: `a` is a `range[T]` and `T`
    matches `f` exactly. Or: `a` is a subtype of `f`.
 5. Integral conversion match: `a` is convertible to `f` and `f` and `a`
@@ -3840,7 +3841,7 @@ Type bound operators currently include:
 (some of which are still implementation defined and not yet documented).
 
 For more details on some of those procs, see
-`lifetimeminustracking-hooks <destructors.html#lifetimeminustracking-hooks>`_.
+`Lifetime-tracking hooks <destructors.html#lifetimeminustracking-hooks>`_.
 
 Nonoverloadable builtins
 ------------------------
@@ -5283,7 +5284,7 @@ instantiations cross multiple different modules:
 
 In module B has an `init` proc from module C in its scope that is not
 taken into account when `genericB` is instantiated which leads to the
-instantiation of `genericA`. The solution is to `forward`:idx these
+instantiation of `genericA`. The solution is to `forward`:idx: these
 symbols by a `bind` statement inside `genericB`.
 
 
@@ -7305,19 +7306,19 @@ Produces:
   supplied pattern to denote the concrete type parameters of the generic type.
   See the usage of the apostrophe operator in proc patterns for more details.
 
-.. code-block:: nim
+  .. code-block:: nim
 
-  type
-    VectorIterator {.importcpp: "std::vector<'0>::iterator".} [T] = object
+    type
+      VectorIterator {.importcpp: "std::vector<'0>::iterator".} [T] = object
 
-  var x: VectorIterator[cint]
+    var x: VectorIterator[cint]
 
 
-Produces:
+  Produces:
 
-.. code-block:: C
+  .. code-block:: C
 
-  std::vector<int>::iterator x;
+    std::vector<int>::iterator x;
 
 
 ImportJs pragma
@@ -7444,7 +7445,7 @@ compile-time define pragmas
 ---------------------------
 
 The pragmas listed here can be used to optionally accept values from
-the -d/--define option at compile time.
+the `-d/--define`:option: option at compile time.
 
 The implementation currently provides the following possible options (various
 others may be added later).
@@ -7461,7 +7462,7 @@ pragma             description
    const FooBar {.intdefine.}: int = 5
    echo FooBar
 
-::
+.. code:: cmd
    nim c -d:FooBar=42 foobar.nim
 
 In the above example, providing the `-d`:option: flag causes the symbol
@@ -7480,7 +7481,8 @@ pragma pragma
 -------------
 
 The `pragma` pragma can be used to declare user-defined pragmas. This is
-useful because Nim's templates and macros do not affect pragmas. User-defined pragmas are in a different module-wide scope than all other symbols.
+useful because Nim's templates and macros do not affect pragmas.
+User-defined pragmas are in a different module-wide scope than all other symbols.
 They cannot be imported from a module.
 
 Example:
@@ -7553,18 +7555,18 @@ More examples with custom pragmas:
 
 - Better serialization/deserialization control:
 
-.. code-block:: nim
-  type MyObj = object
-    a {.dontSerialize.}: int
-    b {.defaultDeserialize: 5.}: int
-    c {.serializationKey: "_c".}: string
+  .. code-block:: nim
+    type MyObj = object
+      a {.dontSerialize.}: int
+      b {.defaultDeserialize: 5.}: int
+      c {.serializationKey: "_c".}: string
 
 - Adopting type for gui inspector in a game engine:
 
-.. code-block:: nim
-  type MyComponent = object
-    position {.editable, animatable.}: Vector3
-    alpha {.editRange: [0.0..1.0], animatable.}: float32
+  .. code-block:: nim
+    type MyComponent = object
+      position {.editable, animatable.}: Vector3
+      alpha {.editRange: [0.0..1.0], animatable.}: float32
 
 
 Macro pragmas
diff --git a/doc/manual_experimental.rst b/doc/manual_experimental.rst
index 51037b509..2c1043ecb 100644
--- a/doc/manual_experimental.rst
+++ b/doc/manual_experimental.rst
@@ -1,5 +1,3 @@
-.. default-role:: code
-
 =========================
 Nim Experimental Features
 =========================
@@ -7,6 +5,8 @@ Nim Experimental Features
 :Authors: Andreas Rumpf
 :Version: |nimversion|
 
+.. default-role:: code
+.. include:: rstcommon.rst
 .. contents::
 
 
@@ -15,7 +15,7 @@ About this document
 
 This document describes features of Nim that are to be considered experimental.
 Some of these are not covered by the `.experimental` pragma or
-`--experimental` switch because they are already behind a special syntax and
+`--experimental`:option: switch because they are already behind a special syntax and
 one may want to use Nim libraries using these features without using them
 oneself.
 
@@ -1109,7 +1109,7 @@ The `parameter constraint`:idx: expression can use the operators `|` (or),
 Predicate                Meaning
 ===================      =====================================================
 `atom`                   The matching node has no children.
-`lit`                    The matching node is a literal like "abc", 12.
+`lit`                    The matching node is a literal like `"abc"`, `12`.
 `sym`                    The matching node must be a symbol (a bound
                          identifier).
 `ident`                  The matching node must be an identifier (an unbound
@@ -1185,7 +1185,7 @@ constant folding, so the following does not work:
 
 The reason is that the compiler already transformed the 1 into "1" for
 the `echo` statement. However, a term rewriting macro should not change the
-semantics anyway. In fact they can be deactivated with the `--patterns:off`
+semantics anyway. In fact they can be deactivated with the `--patterns:off`:option:
 command line option or temporarily with the `patterns` pragma.
 
 
@@ -1779,7 +1779,7 @@ Noalias annotation
 ==================
 
 Since version 1.4 of the Nim compiler, there is a `.noalias` annotation for variables
-and parameters. It is mapped directly to C/C++'s `restrict` keyword and means that
+and parameters. It is mapped directly to C/C++'s `restrict`:c: keyword and means that
 the underlying pointer is pointing to a unique location in memory, no other aliases to
 this location exist. It is *unchecked* that this alias restriction is followed, if the
 restriction is violated, the backend optimizer is free to miscompile the code.
@@ -1832,8 +1832,8 @@ the `view types section <#view-types-algorithm>`_.
 View types
 ==========
 
-**Note**:  `--experimental:views` is more effective
-with `--experimental:strictFuncs`.
+**Note**:  `--experimental:views`:option: is more effective
+with `--experimental:strictFuncs`:option:.
 
 A view type is a type that is or contains one of the following types:
 
@@ -1981,8 +1981,8 @@ The scope of the view does not matter:
 
 The analysis requires as much precision about mutations as is reasonably obtainable,
 so it is more effective with the experimental `strict funcs <#strict-funcs>`_
-feature. In other words `--experimental:views` works better
-with `--experimental:strictFuncs`.
+feature. In other words `--experimental:views`:option: works better
+with `--experimental:strictFuncs`:option:.
 
 The analysis is currently control flow insensitive:
 
diff --git a/doc/manual_experimental_strictnotnil.rst b/doc/manual_experimental_strictnotnil.rst
index cb3bfeca9..b14e5f9f3 100644
--- a/doc/manual_experimental_strictnotnil.rst
+++ b/doc/manual_experimental_strictnotnil.rst
@@ -1,8 +1,9 @@
-.. default-role:: code
-
 Strict not nil checking
 =========================
 
+.. default-role:: code
+.. include:: rstcommon.rst
+
 **Note:** This feature is experimental, you need to enable it with
 
 .. code-block:: nim
@@ -10,7 +11,7 @@ Strict not nil checking
 
 or 
 
-.. code-block:: bash
+.. code-block:: cmd
   nim c --experimental:strictNotNil <program>
 
 In the second case it would check builtin and imported modules as well.
@@ -60,14 +61,16 @@ You can annotate a type where nil isn't a valid value with `not nil`.
 
 
 If a type can include `nil` as a valid value, dereferencing values of the type
-is checked by the compiler: if a value which might be nil is derefenced, this produces a warning by default, you can turn this into an error using the compiler options `--warningAsError:strictNotNil`
+is checked by the compiler: if a value which might be nil is derefenced, this
+produces a warning by default, you can turn this into an error using
+the compiler options `--warningAsError:strictNotNil`:option:.
 
 If a type is nilable, you should dereference its values only after a `isNil` or equivalent check.
 
 local turn on/off
 ---------------------
 
-You can still turn off nil checking on function/module level by using a `{.strictNotNil: off}.` pragma.
+You can still turn off nil checking on function/module level by using a `{.strictNotNil: off.}` pragma.
 Note: test that/TODO for code/manual.
 
 nilability state
@@ -75,11 +78,14 @@ nilability state
 
 Currently a nilable value can be `Safe`, `MaybeNil` or `Nil` : we use internally `Parent` and `Unreachable` but this is an implementation detail(a parent layer has the actual nilability).
 
-`Safe` means it shouldn't be nil at that point: e.g. after assignment to a non-nil value or `not a.isNil` check
-`MaybeNil` means it might be nil, but it might not be nil: e.g. an argument, a call argument or a value after an `if` and `else`.
-`Nil` means it should be nil at that point; e.g. after an assignment to `nil` or a `.isNil` check.
-
-`Unreachable` means it shouldn't be possible to access this in this branch: so we do generate a warning as well.
+- `Safe` means it shouldn't be nil at that point: e.g. after assignment to
+  a non-nil value or `not a.isNil` check
+- `MaybeNil` means it might be nil, but it might not be nil: e.g. an argument,
+  a call argument or a value after an `if` and `else`.
+- `Nil` means it should be nil at that point; e.g. after an assignment to
+  `nil` or a `.isNil` check.
+- `Unreachable` means it shouldn't be possible to access this in this branch:
+  so we do generate a warning as well.
 
 We show an error for each dereference (`[]`, `.field`, `[index]` `()` etc) which is of a tracked expression which is
 in `MaybeNil` or `Nil` state.
diff --git a/doc/nep1.rst b/doc/nep1.rst
index 8687725bb..fc69bab69 100644
--- a/doc/nep1.rst
+++ b/doc/nep1.rst
@@ -1,11 +1,12 @@
-.. default-role:: code
-
 ==========================================================
 Nim Enhancement Proposal #1 - Standard Library Style Guide
 ==========================================================
+
 :Author: Clay Sweetser, Dominik Picheta
 :Version: |nimversion|
 
+.. default-role:: code
+.. include:: rstcommon.rst
 .. contents::
 
 
@@ -139,7 +140,7 @@ Naming Conventions
   - rotate and rotated
 
 - When the 'returns transformed copy' version already exists like `strutils.replace`
-  an in-place version should get an `-In` suffix (`replaceIn` for this example).
+  an in-place version should get an ``-In`` suffix (`replaceIn` for this example).
 
 
 - Use `subjectVerb`, not `verbSubject`, e.g.: `fileExists`, not `existsFile`.
@@ -225,8 +226,8 @@ indentation             indent
 Coding Conventions
 ------------------
 
-- The 'return' statement should ideally be used when its control-flow properties
-  are required. Use a procedure's implicit 'result' variable whenever possible.
+- The `return` statement should ideally be used when its control-flow properties
+  are required. Use a procedure's implicit `result` variable whenever possible.
   This improves readability.
 
   .. code-block:: nim
diff --git a/doc/nimgrep.rst b/doc/nimgrep.rst
index 52fc4d62a..6088a4c45 100644
--- a/doc/nimgrep.rst
+++ b/doc/nimgrep.rst
@@ -1,14 +1,11 @@
-.. default-role:: code
-
 =========================
   nimgrep User's manual
 =========================
 
-.. default-role:: literal
-
 :Author: Andreas Rumpf
 :Version: 1.6.0
 
+.. default-role:: option
 .. contents::
 
 Nimgrep is a command line tool for search and replace tasks. It can search for
@@ -23,11 +20,12 @@ Apart from that it is a generic text manipulation tool.
 Installation
 ============
 
-Compile nimgrep with the command::
+Compile nimgrep with the command:
 
+.. code:: cmd
   nim c -d:release tools/nimgrep.nim
 
-And copy the executable somewhere in your `$PATH`.
+And copy the executable somewhere in your ``$PATH``.
 
 
 Command line switches
@@ -40,31 +38,32 @@ Examples
 
 All examples below use default PCRE Regex patterns:
 
-+ To search recursively in Nim files using style-insensitive identifiers::
++ To search recursively in Nim files using style-insensitive identifiers:
 
-    --recursive --ext:'nim|nims' --ignoreStyle
+  .. code:: cmd
+    nimgrep --recursive --ext:'nim|nims' --ignoreStyle
     # short: -r --ext:'nim|nims' -y
 
   .. Note:: we used `'` quotes to avoid special treatment of `|` symbol
     for shells like Bash
 
 + To exclude version control directories (Git, Mercurial=hg, Subversion=svn)
-  from the search::
+  from the search:
 
-    --excludeDir:'^\.git$' --excludeDir:'^\.hg$' --excludeDir:'^\.svn$'
+  .. code:: cmd
+    nimgrep --excludeDir:'^\.git$' --excludeDir:'^\.hg$' --excludeDir:'^\.svn$'
     # short: --ed:'^\.git$' --ed:'^\.hg$' --ed:'^\.svn$'
 
 + To search only in paths containing the `tests` sub-directory recursively::
 
-    --recursive --includeDir:'(^|/)tests($|/)'
+  .. code:: cmd
+    nimgrep --recursive --includeDir:'(^|/)tests($|/)'
     # short: -r --id:'(^|/)tests($|/)'
 
-  .. Attention:: note the subtle difference between `--excludeDir` and
-    `--includeDir`: the former is applied to relative directory entries
+  .. Attention:: note the subtle difference between `--excludeDir`:option: and
+    `--includeDir`:option:\: the former is applied to relative directory entries
     and the latter is applied to the whole paths
 
 + Nimgrep can search multi-line, e.g. to find files containing `import`
-  and then `strutils` use::
-
-    'import(.|\n)*?strutils'
+  and then `strutils` use pattern `'import(.|\n)*?strutils'`:option:.
 
diff --git a/doc/niminst.rst b/doc/niminst.rst
index 3ccb47cc8..8fff1f0e8 100644
--- a/doc/niminst.rst
+++ b/doc/niminst.rst
@@ -1,5 +1,3 @@
-.. default-role:: code
-
 =========================
   niminst User's manual
 =========================
@@ -7,6 +5,8 @@
 :Author: Andreas Rumpf
 :Version: |nimversion|
 
+.. default-role:: code
+.. include:: rstcommon.rst
 .. contents::
 
 Introduction
@@ -34,7 +34,7 @@ configuration file. Here's an example of how the syntax looks like:
 
 The value of a key-value pair can reference user-defined variables via
 the `$variable` notation: They can be defined in the command line with the
-`--var:name=value` switch. This is useful to not hard-coding the
+`--var:name=value`:option: switch. This is useful to not hard-coding the
 program's version number into the configuration file, for instance.
 
 It follows a description of each possible section and how it affects the
@@ -91,10 +91,10 @@ Documentation section
 
 The `documentation` section supports the `files` key.
 Listed files will be installed into the OS's native documentation directory
-(which might be `$appdir/doc`).
+(which might be ``$appdir/doc``).
 
 There is a `start` key which determines whether the Windows installer
-generates a link to e.g. the `index.html` of your documentation.
+generates a link to e.g. the ``index.html`` of your documentation.
 
 
 Other section
@@ -125,9 +125,9 @@ Other possible options are:
 ====================   =======================================================
 Key                    description
 ====================   =======================================================
-`BinPath`            paths to add to the Windows `%PATH%` environment
+`BinPath`              paths to add to the Windows `%PATH%` environment
                        variable. Example: ``BinPath: r"bin;dist\mingw\bin"``
-`InnoSetup`          boolean flag whether an Inno Setup installer should be
+`InnoSetup`            boolean flag whether an Inno Setup installer should be
                        generated for Windows. Example: `InnoSetup: "Yes"`
 ====================   =======================================================
 
@@ -137,7 +137,7 @@ UnixBin section
 
 The `UnixBin` section currently only supports the `files` key.
 Listed files will be installed into the OS's native bin directory
-(e.g. `/usr/local/bin`). The exact location depends on the
+(e.g. ``/usr/local/bin``). The exact location depends on the
 installation path the user specifies when running the `install.sh` script.
 
 
@@ -165,9 +165,9 @@ Possible options are:
 ====================   =======================================================
 Key                    description
 ====================   =======================================================
-`path`               Path to Inno Setup.
+`path`                 Path to Inno Setup.
                        Example: ``path = r"c:\inno setup 5\iscc.exe"``
-`flags`              Flags to pass to Inno Setup.
+`flags`                Flags to pass to Inno Setup.
                        Example: `flags = "/Q"`
 ====================   =======================================================
 
@@ -180,8 +180,8 @@ Possible options are:
 ====================   =======================================================
 Key                    description
 ====================   =======================================================
-`path`               Path to the C compiler.
-`flags`              Flags to pass to the C Compiler.
+`path`                 Path to the C compiler.
+`flags`                Flags to pass to the C Compiler.
                        Example: `flags = "-w"`
 ====================   =======================================================
 
diff --git a/doc/nims.rst b/doc/nims.rst
index f81637d73..5ae1d7baa 100644
--- a/doc/nims.rst
+++ b/doc/nims.rst
@@ -1,32 +1,33 @@
-.. default-role:: code
-
 ================================
           NimScript
 ================================
 
+.. default-role:: code
+.. include:: rstcommon.rst
+
 Strictly speaking, `NimScript` is the subset of Nim that can be evaluated
 by Nim's builtin virtual machine (VM). This VM is used for Nim's compiletime
 function evaluation features.
 
-The `nim` executable processes the `.nims` configuration files in
+The `nim`:cmd: executable processes the ``.nims`` configuration files in
 the following directories (in this order; later files overwrite
 previous settings):
 
 1) If environment variable `XDG_CONFIG_HOME` is defined,
-   `$XDG_CONFIG_HOME/nim/config.nims` or
-   `~/.config/nim/config.nims` (POSIX) or
-   `%APPDATA%/nim/config.nims` (Windows). This file can be skipped
-   with the `--skipUserCfg` command line option.
-2) `$parentDir/config.nims` where `$parentDir` stands for any
+   ``$XDG_CONFIG_HOME/nim/config.nims`` or
+   ``~/.config/nim/config.nims`` (POSIX) or
+   ``%APPDATA%/nim/config.nims`` (Windows). This file can be skipped
+   with the `--skipUserCfg`:option: command line option.
+2) ``$parentDir/config.nims`` where ``$parentDir`` stands for any
    parent directory of the project file's path. These files can be
-   skipped with the `--skipParentCfg` command line option.
-3) `$projectDir/config.nims` where `$projectDir` stands for the
-   project's path. This file can be skipped with the `--skipProjCfg`
+   skipped with the `--skipParentCfg`:option: command line option.
+3) ``$projectDir/config.nims`` where ``$projectDir`` stands for the
+   project's path. This file can be skipped with the `--skipProjCfg`:option:
    command line option.
 4) A project can also have a project specific configuration file named
-   `$project.nims` that resides in the same directory as
-   `$project.nim`. This file can be skipped with the same
-   `--skipProjCfg` command line option.
+   ``$project.nims`` that resides in the same directory as
+   ``$project.nim``. This file can be skipped with the same
+   `--skipProjCfg`:option: command line option.
 
 For available procs and implementation details see `nimscript <nimscript.html>`_.
 
@@ -111,8 +112,8 @@ See also:
 NimScript as a configuration file
 =================================
 
-A command-line switch `--FOO` is written as `switch("FOO")` in
-NimScript. Similarly, command-line `--FOO:VAL` translates to
+A command-line switch `--FOO`:option: is written as `switch("FOO")` in
+NimScript. Similarly, command-line `--FOO:VAL`:option: translates to
 `switch("FOO", "VAL")`.
 
 Here are few examples of using the `switch` proc:
@@ -125,7 +126,7 @@ Here are few examples of using the `switch` proc:
   # command-line: --forceBuild
   switch("forceBuild")
 
-NimScripts also support `--` templates for convenience, which look
+NimScripts also support `--`:option: templates for convenience, which look
 like command-line switches written as-is in the NimScript file. So the
 above example can be rewritten as:
 
@@ -136,7 +137,7 @@ above example can be rewritten as:
 
 **Note**: In general, the *define* switches can also be set in
 NimScripts using `switch` or `--`, as shown in above
-examples. Only the `release` define (`-d:release`) cannot be set
+examples. Only the `release` define (`-d:release`:option:) cannot be set
 in NimScripts.
 
 
@@ -145,7 +146,7 @@ NimScript as a build tool
 
 The `task` template that the `system` module defines allows a NimScript
 file to be used as a build tool. The following example defines a
-task `build` that is an alias for the `c` command:
+task `build` that is an alias for the `c`:option: command:
 
 .. code-block:: nim
   task build, "builds an example":
@@ -159,7 +160,7 @@ Task          Description
 =========     ===================================================
 `help`        List all the available NimScript tasks along with their docstrings.
 `build`       Build the project with the required
-              backend (`c`, `cpp` or `js`).
+              backend (`c`:option:, `cpp`:option: or `js`:option:).
 `tests`       Runs the tests belonging to the project.
 `bench`       Runs benchmarks belonging to the project.
 =========     ===================================================
@@ -180,7 +181,7 @@ Standalone NimScript
 ====================
 
 NimScript can also be used directly as a portable replacement for Bash and
-Batch files. Use `nim myscript.nims` to run `myscript.nims`. For example,
+Batch files. Use `nim myscript.nims`:cmd: to run ``myscript.nims``. For example,
 installation of Nimble could be accomplished with this simple script:
 
 .. code-block:: nim
@@ -199,7 +200,7 @@ installation of Nimble could be accomplished with this simple script:
   mvFile "nimble" & $id & "/src/nimble".toExe, "bin/nimble".toExe
 
 On Unix, you can also use the shebang `#!/usr/bin/env nim`, as long as your filename
-ends with `.nims`:
+ends with ``.nims``:
 
 .. code-block:: nim
 
diff --git a/doc/nimsuggest.rst b/doc/nimsuggest.rst
index 509f72e8a..82693da0e 100644
--- a/doc/nimsuggest.rst
+++ b/doc/nimsuggest.rst
@@ -1,5 +1,3 @@
-.. default-role:: code
-
 ================================
   Nim IDE Integration Guide
 ================================
@@ -7,14 +5,16 @@
 :Author: Unknown
 :Version: |nimversion|
 
+.. default-role:: code
+.. include:: rstcommon.rst
 .. contents::
 
 
 Nim differs from many other compilers in that it is really fast,
 and being so fast makes it suited to provide external queries for
 text editors about the source code being written. Through the
-`nimsuggest` tool, any IDE
-can query a `.nim` source file and obtain useful information like
+`nimsuggest`:cmd: tool, any IDE
+can query a ``.nim`` source file and obtain useful information like
 definition of symbols or suggestions for completion.
 
 This document will guide you through the available options. If you
@@ -27,29 +27,30 @@ already available.
 Installation
 ============
 
-Nimsuggest is part of Nim's core. Build it via::
+Nimsuggest is part of Nim's core. Build it via:
 
+.. code:: cmd
   koch nimsuggest
 
 
 Nimsuggest invocation
 =====================
 
-Run it via `nimsuggest --stdin --debug myproject.nim`. Nimsuggest is a
+Run it via `nimsuggest --stdin --debug myproject.nim`:cmd:. Nimsuggest is a
 server that takes queries that are related to `myproject`. There is some
-support so that you can throw random `.nim` files which are not part
+support so that you can throw random ``.nim`` files which are not part
 of `myproject` at Nimsuggest too, but usually the query refer to modules/files
 that are part of `myproject`.
 
-`--stdin` means that Nimsuggest reads the query from `stdin`. This is great
+`--stdin`:option: means that Nimsuggest reads the query from `stdin`. This is great
 for testing things out and playing with it but for an editor communication
 via sockets is more reasonable so that is the default. It listens to port 6000
 by default.
 
-Nimsuggest is basically a frontend for the nim compiler so `--path` flags and
+Nimsuggest is basically a frontend for the nim compiler so `--path`:option: flags and
 `config files <https://nim-lang.org/docs/nimc.html#compiler-usage-configuration-files>`_
 can be used to specify additional dependencies like 
-`nimsuggest --stdin --debug --path:"dependencies" myproject.nim`. 
+`nimsuggest --stdin --debug --path:"dependencies" myproject.nim`:cmd:.
 
 
 Specifying the location of the query
@@ -60,25 +61,25 @@ cryptic 3 letter "command" `def` or `con` or `sug` or `use` followed by
 a location. A query location consists of:
 
 
-`file.nim`
+``file.nim``
     This is the name of the module or include file the query refers to.
 
-`dirtyfile.nim`
+``dirtyfile.nim``
     This is optional.
 
     The `file` parameter is enough for static analysis, but IDEs
     tend to have *unsaved buffers* where the user may still be in
     the middle of typing a line. In such situations the IDE can
     save the current contents to a temporary file and then use the
-    `dirtyfile.nim` option to tell Nimsuggest that `foobar.nim` should
-    be taken from `temporary/foobar.nim`.
+    ``dirtyfile.nim`` option to tell Nimsuggest that ``foobar.nim`` should
+    be taken from ``temporary/foobar.nim``.
 
 
-`line`
+``line``
     An integer with the line you are going to query. For the compiler
     lines start at **1**.
 
-`col`
+``col``
     An integer with the column you are going to query. For the
     compiler columns start at **0**.
 
@@ -149,9 +150,9 @@ tab characters (``\t``). The values of each column are:
 1. Three characters indicating the type of returned answer (e.g.
    `def` for definition, `sug` for suggestion, etc).
 2. Type of the symbol. This can be `skProc`, `skLet`, and just
-   about any of the enums defined in the module `compiler/ast.nim`.
+   about any of the enums defined in the module ``compiler/ast.nim``.
 3. Fully qualified path of the symbol. If you are querying a symbol
-   defined in the `proj.nim` file, this would have the form
+   defined in the ``proj.nim`` file, this would have the form
    `proj.symbolName`.
 4. Type/signature. For variables and enums this will contain the
    type of the symbol, for procs, methods and templates this will
diff --git a/doc/packaging.rst b/doc/packaging.rst
index ecde73f61..ecb17e482 100644
--- a/doc/packaging.rst
+++ b/doc/packaging.rst
@@ -45,7 +45,7 @@ The Debian package ships bash and ksh completion and manpages that can be reused
 
 Hints on the build process:
 
-::
+.. code:: cmd
 
    # build from C sources and then using koch
    ./build.sh --os $os_type --cpu $cpu_arch
diff --git a/doc/regexprs.txt b/doc/regexprs.txt
index 9ec08b810..f5544cc28 100644
--- a/doc/regexprs.txt
+++ b/doc/regexprs.txt
@@ -47,9 +47,11 @@ full documentation of Perl's regular expressions.
 Because the backslash ``\`` is a meta character both in the Nim
 programming language and in regular expressions, it is strongly
 recommended that one uses the *raw* strings of Nim, so that
-backslashes are interpreted by the regular expression engine::
+backslashes are interpreted by the regular expression engine:
 
+```nim
   r"\S"  # matches any character that is not whitespace
+```
 
 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
diff --git a/doc/testament.rst b/doc/testament.rst
index ed1bd63a1..5590cc6d7 100644
--- a/doc/testament.rst
+++ b/doc/testament.rst
@@ -2,8 +2,8 @@
  Testament
 ===========
 
+.. default-role:: code
 .. include:: rstcommon.rst
-.. default-role:: nim
 .. contents::
 
 Testament is an advanced automatic unittests runner for Nim tests, is used for the development of Nim itself,
diff --git a/doc/tools.rst b/doc/tools.rst
index e0044e1ca..0de4ac914 100644
--- a/doc/tools.rst
+++ b/doc/tools.rst
@@ -1,9 +1,10 @@
-.. default-role:: code
-
 ========================
 Tools available with Nim
 ========================
 
+.. default-role:: code
+.. include:: rstcommon.rst
+
 The standard distribution ships with the following tools:
 
 - | `Hot code reloading <hcr.html>`_
@@ -11,11 +12,11 @@ The standard distribution ships with the following tools:
     document explaining how it works.
 
 - | `Documentation generator <docgen.html>`_
-  | The builtin document generator `nim doc` generates HTML documentation
-    from `.nim` source files.
+  | The builtin document generator `nim doc`:cmd: generates HTML documentation
+    from ``.nim`` source files.
 
 - | `Nimsuggest for IDE support <nimsuggest.html>`_
-  | Through the `nimsuggest` tool, any IDE can query a `.nim` source file
+  | Through the `nimsuggest`:cmd: tool, any IDE can query a ``.nim`` source file
     and obtain useful information like the definition of symbols or suggestions for
     completion.
 
@@ -29,11 +30,11 @@ The standard distribution ships with the following tools:
   | Nim search and replace utility.
 
 - | nimpretty
-  | `nimpretty` is a Nim source code beautifier,
+  | `nimpretty`:cmd: is a Nim source code beautifier,
     to format code according to the official style guide.
 
 - | `testament <https://nim-lang.github.io/Nim/testament.html>`_
-  | `testament` is an advanced automatic *unittests runner* for Nim tests,
+  | `testament`:cmd: is an advanced automatic *unittests runner* for Nim tests,
     is used for the development of Nim itself, offers process isolation for your tests,
     it can generate statistics about test cases, supports multiple targets (C, JS, etc),
     `simulated Dry-Runs <https://en.wikipedia.org/wiki/Dry_run_(testing)>`_,