summary refs log tree commit diff stats
diff options
context:
space:
mode:
Diffstat
-rw-r--r--config/nimdoc.tex.cfg2
-rw-r--r--doc/destructors.rst15
-rw-r--r--doc/docgen.rst145
-rw-r--r--doc/drnim.rst7
-rw-r--r--doc/estp.rst22
-rw-r--r--doc/filelist.txt4
-rw-r--r--doc/filters.rst28
-rw-r--r--doc/intern.rst44
-rw-r--r--doc/nimdoc.css8
-rw-r--r--doc/testament.rst60
-rw-r--r--lib/packages/docutils/highlite.nim36
-rw-r--r--lib/packages/docutils/rst.nim11
-rw-r--r--nimdoc/testproject/expected/nimdoc.out.css8
-rw-r--r--tests/stdlib/thighlite.nim17
14 files changed, 252 insertions, 155 deletions
diff --git a/config/nimdoc.tex.cfg b/config/nimdoc.tex.cfg
index 471f20dc1..b1c02c5a0 100644
--- a/config/nimdoc.tex.cfg
+++ b/config/nimdoc.tex.cfg
@@ -137,6 +137,8 @@ bottomline=false}
 \newcommand{\spanReference}[1]{#1}
 \newcommand{\spanOther}[1]{#1}
 \newcommand{\spantok}[1]{\frame{#1}}
+\newcommand{\spanPrompt}[1]{\textcolor{red}{\textbf{#1}}}
+\newcommand{\spanProgramOutput}[1]{\textcolor{gray}{\textbf{#1}}}
 \newcommand{\spanprogram}[1]{\textbf{\underline{#1}}}
 \newcommand{\spanoption}[1]{\textbf{#1}}
 
diff --git a/doc/destructors.rst b/doc/destructors.rst
index c93fcabe1..3cd4cd925 100644
--- a/doc/destructors.rst
+++ b/doc/destructors.rst
@@ -1,5 +1,3 @@
-.. default-role:: code
-
 ==================================
 Nim Destructors and Move Semantics
 ==================================
@@ -7,6 +5,8 @@ Nim Destructors and Move Semantics
 :Authors: Andreas Rumpf
 :Version: |nimversion|
 
+.. include:: rstcommon.rst
+.. default-role:: nim
 .. contents::
 
 
@@ -273,7 +273,7 @@ Sink parameter inference
 ========================
 
 The current implementation can do a limited form of sink parameter
-inference. But it has to be enabled via `--sinkInference:on`, either
+inference. But it has to be enabled via `--sinkInference:on`:option:, either
 on the command line or via a `push` pragma.
 
 To enable it for a section of code, one can
@@ -496,10 +496,11 @@ for expressions of type `lent T` or of type `var T`.
 The .cursor annotation
 ======================
 
-Under the `--gc:arc|orc` modes Nim's `ref` type is implemented via the same runtime
-"hooks" and thus via reference counting. This means that cyclic structures cannot be freed
-immediately (`--gc:orc` ships with a cycle collector). With the `.cursor` annotation
-one can break up cycles declaratively:
+Under the `--gc:arc|orc`:option: modes Nim's `ref` type is implemented
+via the same runtime "hooks" and thus via reference counting.
+This means that cyclic structures cannot be freed
+immediately (`--gc:orc`:option: ships with a cycle collector).
+With the `.cursor` annotation one can break up cycles declaratively:
 
 .. code-block:: nim
 
diff --git a/doc/docgen.rst b/doc/docgen.rst
index c002ddb83..86352a989 100644
--- a/doc/docgen.rst
+++ b/doc/docgen.rst
@@ -1,5 +1,3 @@
-.. default-role:: code
-
 ===================================
    Nim DocGen Tools Guide
 ===================================
@@ -7,6 +5,8 @@
 :Author: Erik O'Leary
 :Version: |nimversion|
 
+.. include:: rstcommon.rst
+.. default-role:: Nim
 .. contents::
 
 
@@ -17,20 +17,22 @@ This document describes the `documentation generation tools`:idx: built into
 the `Nim compiler <nimc.html>`_, which can generate HTML and JSON output
 from input .nim files and projects, as well as HTML and LaTeX from input RST
 (reStructuredText) files. The output documentation will include the module
-dependencies (`import`), any top-level documentation comments (##), and
-exported symbols (*), including procedures, types, and variables.
+dependencies (`import`), any top-level documentation comments (`##`), and
+exported symbols (`*`), including procedures, types, and variables.
 
 Quick start
 -----------
 
 Generate HTML documentation for a file:
 
-::
+.. code:: cmd
+
   nim doc <filename>.nim
 
 Generate HTML documentation for a whole project:
 
-::
+.. code:: cmd
+
   # delete any htmldocs/*.idx file before starting
   nim doc --project --index:on --git.url:<url> --git.commit:<tag> --outdir:htmldocs <main_filename>.nim
   # this will generate html files, a theindex.html index, css and js under `htmldocs`
@@ -39,15 +41,15 @@ Generate HTML documentation for a whole project:
   # CORS will prevent opening file:// urls; this works:
   python3 -m http.server 7029 --directory htmldocs
   # When --outdir is omitted it defaults to $projectPath/htmldocs,
-  or `$nimcache/htmldocs` with `--usenimcache` which avoids clobbering your sources;
-  and likewise without `--project`.
-  Adding `-r` will open in a browser directly.
+  # or `$nimcache/htmldocs` with `--usenimcache` which avoids clobbering your sources;
+  # and likewise without `--project`.
+  # Adding `-r` will open in a browser directly.
 
 
 Documentation Comments
 ----------------------
 
-Any comments which are preceded by a double-hash (##), are interpreted as
+Any comments which are preceded by a double-hash (`##`), are interpreted as
 documentation.  Comments are parsed as RST (see `reference
 <http://docutils.sourceforge.net/docs/user/rst/quickref.html>`_), providing
 Nim module authors the ability to easily generate richly formatted
@@ -66,7 +68,7 @@ Outputs::
     name: string
     age: int
 
-This type contains a description of a person
+  This type contains a description of a person
 
 Field documentation comments can be added to fields like so:
 
@@ -127,12 +129,15 @@ Document Types
 HTML
 ----
 
-The generation of HTML documents is done via the `doc` command. This command
-takes either a single .nim file, outputting a single .html file with the same
-base filename, or multiple .nim files, outputting multiple .html files and,
+The generation of HTML documents is done via the `doc`:option: command. This command
+takes either a single ``.nim`` file, outputting a single ``.html`` file with the same
+base filename, or multiple ``.nim`` files, outputting multiple ``.html`` files and,
 optionally, an index file.
 
-The `doc` command::
+The `doc`:option: command:
+
+.. code:: cmd
+
   nim doc sample
 
 Partial Output::
@@ -148,12 +153,16 @@ compiler.
 JSON
 ----
 
-The generation of JSON documents is done via the `jsondoc` command. This command
-takes in a .nim file and outputs a .json file with the same base filename. Note
-that this tool is built off of the `doc` command (previously `doc2`), and
-contains the same information.
+The generation of JSON documents is done via the `jsondoc`:option: command.
+This command takes in a ``.nim`` file and outputs a ``.json`` file with
+the same base filename.
+Note that this tool is built off of the `doc`:option: command
+(previously `doc2`:option:), and contains the same information.
+
+The `jsondoc`:option: command:
+
+.. code:: cmd
 
-The `jsondoc` command::
   nim jsondoc sample
 
 Output::
@@ -173,10 +182,13 @@ Output::
     ]
   }
 
-Similarly to the old `doc` command, the old `jsondoc` command has been
-renamed to `jsondoc0`.
+Similarly to the old `doc`:option: command, the old `jsondoc`:option: command has been
+renamed to `jsondoc0`:option:.
+
+The `jsondoc0`:option: command:
+
+.. code:: cmd
 
-The `jsondoc0` command::
   nim jsondoc0 sample
 
 Output::
@@ -192,8 +204,8 @@ Output::
     }
   ]
 
-Note that the `jsondoc` command outputs it's JSON without pretty-printing it,
-while `jsondoc0` outputs pretty-printed JSON.
+Note that the `jsondoc`:option: command outputs it's JSON without pretty-printing it,
+while `jsondoc0`:option: outputs pretty-printed JSON.
 
 Related Options
 ===============
@@ -201,22 +213,24 @@ Related Options
 Project switch
 --------------
 
-::
+.. code:: cmd
+
   nim doc --project filename.nim
 
 This will recursively generate documentation of all nim modules imported
-into the input module that belong to the Nimble package that `filename.nim`
+into the input module that belong to the Nimble package that ``filename.nim``
 belongs to.
 
 
 Index switch
 ------------
 
-::
+.. code:: cmd
+
   nim doc --index:on filename.nim
 
 This will generate an index of all the exported symbols in the input Nim
-module, and put it into a neighboring file with the extension of `.idx`. The
+module, and put it into a neighboring file with the extension of ``.idx``. The
 index file is line-oriented (newlines have to be escaped). Each line
 represents a tab-separated record of several columns, the first two mandatory,
 the rest optional. See the `Index (idx) file format`_ section for details.
@@ -229,31 +243,37 @@ file.
 See source switch
 -----------------
 
-::
+.. code:: cmd
+
   nim doc --git.url:<url> filename.nim
 
-With the `git.url` switch the *See source* hyperlink will appear below each
+With the `git.url`:option: switch the *See source* hyperlink will appear below each
 documented item in your source code pointing to the implementation of that
 item on a GitHub repository.
 You can click the link to see the implementation of the item.
 
-The `git.commit` switch overrides the hardcoded `devel` branch in config/nimdoc.cfg.
-This is useful to link to a different branch e.g. `--git.commit:master`,
-or to a tag e.g. `--git.commit:1.2.3` or a commit.
+The `git.commit`:option: switch overrides the hardcoded `devel` branch in config/nimdoc.cfg.
+This is useful to link to a different branch e.g. `--git.commit:master`:option:,
+or to a tag e.g. `--git.commit:1.2.3`:option: or a commit.
 
-Source URLs are generated as `href="${url}/tree/${commit}/${path}#L${line}"` by default and this compatible with GitHub but not with GitLab.
+Source URLs are generated as ``href="${url}/tree/${commit}/${path}#L${line}"``
+by default and this compatible with GitHub but not with GitLab.
 
-Similarly, `git.devel` switch overrides the hardcoded `devel` branch for the `Edit` link which is also useful if you have a different working branch than `devel` e.g. `--git.devel:master`.
+Similarly, `git.devel`:option: switch overrides the hardcoded `devel` branch
+for the `Edit` link which is also useful if you have a different working
+branch than `devel` e.g. `--git.devel:master`:option:.
 
-Edit URLs are generated as `href="${url}/tree/${devel}/${path}#L${line}"` by default.
+Edit URLs are generated as ``href="${url}/tree/${devel}/${path}#L${line}"``
+by default.
 
-You can edit `config/nimdoc.cfg` and modify the `doc.item.seesrc` value with a hyperlink to your own code repository.
+You can edit ``config/nimdoc.cfg`` and modify the ``doc.item.seesrc`` value
+with a hyperlink to your own code repository.
 
 In the case of Nim's own documentation, the `commit` value is just a commit
 hash to append to a formatted URL to https://github.com/nim-lang/Nim. The
-`tools/nimweb.nim` helper queries the current git commit hash during the doc
+``tools/nimweb.nim`` helper queries the current git commit hash during the doc
 generation, but since you might be working on an unpublished repository, it
-also allows specifying a `githash` value in `web/website.ini` to force a
+also allows specifying a `githash` value in ``web/website.ini`` to force a
 specific commit in the output.
 
 
@@ -261,28 +281,31 @@ Other Input Formats
 ===================
 
 The *Nim compiler* also has support for RST (reStructuredText) files with
-the `rst2html` and `rst2tex` commands. Documents like this one are
+the `rst2html`:option: and `rst2tex`:option: commands. Documents like this one are
 initially written in a dialect of RST which adds support for nim source code
-highlighting with the `.. code-block:: nim` prefix. `code-block` also
+highlighting with the ``.. code-block:: nim`` prefix. ``code-block`` also
 supports highlighting of C++ and some other c-like languages.
 
-Usage::
-  nim rst2html docgen.txt
+Usage:
+
+.. code:: cmd
+
+  nim rst2html docgen.rst
 
 Output::
   You're reading it!
 
-The `rst2tex` command is invoked identically to `rst2html`, but outputs
-a .tex file instead of .html.
+The `rst2tex`:option: command is invoked identically to `rst2html`:option:,
+but outputs a ``.tex`` file instead of ``.html``.
 
 
 HTML anchor generation
 ======================
 
-When you run the `rst2html` command, all sections in the RST document will
+When you run the `rst2html`:option: command, all sections in the RST document will
 get an anchor you can hyperlink to. Usually, you can guess the anchor lower
 casing the section title and replacing spaces with dashes, and in any case, you
-can get it from the table of contents. But when you run the `doc`
+can get it from the table of contents. But when you run the `doc`:option:
 command to generate API documentation, some symbol get one or two anchors at
 the same time: a numerical identifier, or a plain name plus a complex name.
 
@@ -314,15 +337,15 @@ suffix may be added depending on the type of the callable:
 Callable type   Suffix
 -------------   --------------
 proc            *empty string*
-macro           `.m`
-method          `.e`
-iterator        `.i`
-template        `.t`
-converter       `.c`
+macro           ``.m``
+method          ``.e``
+iterator        ``.i``
+template        ``.t``
+converter       ``.c``
 -------------   --------------
 
 The relationship of type to suffix is made by the proc `complexName` in the
-`compiler/docgen.nim` file. Here are some examples of complex names for
+``compiler/docgen.nim`` file. Here are some examples of complex names for
 symbols in the `system module <system.html>`_.
 
 * `type SomeSignedInt = int | int8 | int16 | int32 | int64` **=>**
@@ -346,7 +369,7 @@ symbols in the `system module <system.html>`_.
 Index (idx) file format
 =======================
 
-Files with the `.idx` extension are generated when you use the `Index
+Files with the ``.idx`` extension are generated when you use the `Index
 switch <#related-options-index-switch>`_ along with commands to generate
 documentation from source or text files. You can programmatically generate
 indices with the `setIndexTerm()
@@ -364,7 +387,7 @@ columns is:
 
 1. Mandatory term being indexed. Terms can include quoting according to
    Nim's rules (e.g. \`^\`).
-2. Base filename plus anchor hyperlink (e.g. `algorithm.html#*,int,SortOrder`).
+2. Base filename plus anchor hyperlink (e.g. ``algorithm.html#*,int,SortOrder``).
 3. Optional human-readable string to display as a hyperlink. If the value is not
    present or is the empty string, the hyperlink will be rendered
    using the term. Prefix whitespace indicates that this entry is
@@ -373,8 +396,8 @@ columns is:
    this as a tooltip after hovering a moment over the hyperlink.
 
 The index generation tools try to differentiate between documentation
-generated from `.nim` files and documentation generated from `.txt` or
-`.rst` files. The former are always closely related to source code and
+generated from ``.nim`` files and documentation generated from ``.txt`` or
+``.rst`` files. The former are always closely related to source code and
 consist mainly of API entries. The latter are generic documents meant for
 human reading.
 
@@ -393,7 +416,7 @@ the index file with their third column having as much prefix spaces as their
 level is in the TOC (at least 1 character). The prefix whitespace helps to
 filter TOC entries from API or text symbols. This is important because the
 amount of spaces is used to replicate the hierarchy for document TOCs in the
-final index, and TOC entries found in `.nim` files are discarded.
+final index, and TOC entries found in ``.nim`` files are discarded.
 
 
 Additional resources
@@ -404,8 +427,8 @@ Additional resources
 `RST Quick Reference
 <http://docutils.sourceforge.net/docs/user/rst/quickref.html>`_
 
-The output for HTML and LaTeX comes from the `config/nimdoc.cfg` and
-`config/nimdoc.tex.cfg` configuration files. You can add and modify these
+The output for HTML and LaTeX comes from the ``config/nimdoc.cfg`` and
+``config/nimdoc.tex.cfg`` configuration files. You can add and modify these
 files to your project to change the look of the docgen output.
 
 You can import the `packages/docutils/rstgen module <rstgen.html>`_ in your
diff --git a/doc/drnim.rst b/doc/drnim.rst
index d33a6066e..08de7cd6d 100644
--- a/doc/drnim.rst
+++ b/doc/drnim.rst
@@ -1,5 +1,3 @@
-.. default-role:: code
-
 ===================================
    DrNim User Guide
 ===================================
@@ -7,6 +5,8 @@
 :Author: Andreas Rumpf
 :Version: |nimversion|
 
+.. include:: rstcommon.rst
+.. default-role:: Nim
 .. contents::
 
 
@@ -43,7 +43,8 @@ your code.
 Installation
 ============
 
-Run `koch drnim`, the executable will afterwards be in `$nim/bin/drnim`.
+Run `koch drnim`:option:, the executable will afterwards be
+in ``$nim/bin/drnim``.
 
 
 Motivating Example
diff --git a/doc/estp.rst b/doc/estp.rst
index fa9977d44..43128bef7 100644
--- a/doc/estp.rst
+++ b/doc/estp.rst
@@ -1,9 +1,10 @@
-.. default-role:: code
-
 ===================================================
   Embedded Stack Trace Profiler (ESTP) User Guide
 ===================================================
 
+.. include:: rstcommon.rst
+.. default-role:: Nim
+
 :Author: Andreas Rumpf
 :Version: |nimversion|
 
@@ -12,7 +13,7 @@ Nim comes with a platform independent profiler -
 the Embedded Stack Trace Profiler (ESTP). The profiler
 is *embedded* into your executable. To activate the profiler you need to do:
 
-* compile your program with the `--profiler:on --stackTrace:on` command
+* compile your program with the `--profiler:on --stackTrace:on`:option: command
   line options
 * import the `nimprof` module
 * run your program as usual.
@@ -20,10 +21,10 @@ is *embedded* into your executable. To activate the profiler you need to do:
 You can in fact look at `nimprof`'s source code to see how to implement
 your own profiler.
 
-The setting `--profiler:on` defines the conditional symbol `profiler`.
+The setting `--profiler:on`:option: defines the conditional symbol `profiler`.
 You can use `when compileOption("profiler")` to make the switch seamless.
-If `profiler` is `off`, your program runs normally. Otherwise your program
-is profiled.
+If `profiler`:option: is `off`:option:, your program runs normally.
+Otherwise your program is profiled.
 
 ```nim
 when compileOption("profiler"):
@@ -31,10 +32,10 @@ when compileOption("profiler"):
 ```
 
 After your program has finished the profiler will create a
-file `profile_results.txt` containing the profiling results.
+file ``profile_results.txt`` containing the profiling results.
 
 Since the profiler works by examining stack traces, it's essential that
-the option `--stackTrace:on` is active! Unfortunately this means that a
+the option `--stackTrace:on`:option: is active! Unfortunately this means that a
 profiling build is much slower than a release build.
 
 
@@ -45,8 +46,9 @@ You can also use ESTP as a memory profiler to see which stack traces allocate
 the most memory and thus create the most GC pressure. It may also help to
 find memory leaks. To activate the memory profiler you need to do:
 
-* compile your program with the `--profiler:off --stackTrace:on -d:memProfiler`
-  command line options. Yes it's `--profiler:off`.
+* compile your program with the
+  `--profiler:off --stackTrace:on -d:memProfiler`:option:
+  command line options. Yes it's `--profiler:off`:option:.
 * import the `nimprof` module
 * run your program as usual.
 
diff --git a/doc/filelist.txt b/doc/filelist.txt
index c863ba0cf..74995f154 100644
--- a/doc/filelist.txt
+++ b/doc/filelist.txt
@@ -5,7 +5,7 @@ Short description of Nim's modules
 Module          Description
 ==============  ==========================================================
 nim             main module: parses the command line and calls
-                ``main.MainCommand``
+                `main.MainCommand`
 main            implements the top-level command dispatching
 nimconf         implements the config file reader
 syntaxes        dispatcher for the different parsers and filters
@@ -36,7 +36,7 @@ evals           contains an AST interpreter for compile time evaluation
 pragmas         semantic checking of pragmas
 
 idents          implements a general mapping from identifiers to an internal
-                representation (``PIdent``) that is used so that a simple
+                representation (`PIdent`) that is used so that a simple
                 id-comparison suffices to establish whether two Nim
                 identifiers are equivalent
 ropes           implements long strings represented as trees for
diff --git a/doc/filters.rst b/doc/filters.rst
index 52704411f..c6d436194 100644
--- a/doc/filters.rst
+++ b/doc/filters.rst
@@ -1,9 +1,9 @@
-.. default-role:: code
-
 ===================
 Source Code Filters
 ===================
 
+.. include:: rstcommon.rst
+.. default-role:: code
 .. contents::
 
 A `Source Code Filter (SCF)`  transforms the input character stream to an in-memory
@@ -25,8 +25,8 @@ just like an ordinary procedure call with named or positional arguments. The
 available parameters depend on the invoked filter. Before version 0.12.0 of
 the language `#!` was used instead of `#?`.
 
-**Hint:** With `--hint[codeBegin]:on` or `--verbosity:2`
-(or higher) while compiling or `nim check`, Nim lists the processed code after
+**Hint:** With `--hint[codeBegin]:on`:option: or `--verbosity:2`:option:
+(or higher) while compiling or `nim check`:cmd:, Nim lists the processed code after
 each filter application.
 
 Usage
@@ -70,10 +70,10 @@ The replace filter replaces substrings in each line.
 
 Parameters and their defaults:
 
-  `sub: string = ""`
+* `sub: string = ""`
     the substring that is searched for
 
-  `by: string = ""`
+* `by: string = ""`
     the string the substring is replaced with
 
 
@@ -85,14 +85,14 @@ each line.
 
 Parameters and their defaults:
 
-  `startswith: string = ""`
+* `startswith: string = ""`
     strip only the lines that start with *startswith* (ignoring leading
     whitespace). If empty every line is stripped.
 
-  `leading: bool = true`
+* `leading: bool = true`
     strip leading whitespace
 
-  `trailing: bool = true`
+* `trailing: bool = true`
     strip trailing whitespace
 
 
@@ -107,19 +107,19 @@ statements need `end X` delimiters.
 
 Parameters and their defaults:
 
-  `metaChar: char = '#'`
+* `metaChar: char = '#'`
     prefix for a line that contains Nim code
 
-  `subsChar: char = '$'`
+* `subsChar: char = '$'`
     prefix for a Nim expression within a template line
 
-  `conc: string = " & "`
+* `conc: string = " & "`
     the operation for concatenation
 
-  `emit: string = "result.add"`
+* `emit: string = "result.add"`
     the operation to emit a string literal
 
-  `toString: string = "$"`
+* `toString: string = "$"`
     the operation that is applied to each expression
 
 Example::
diff --git a/doc/intern.rst b/doc/intern.rst
index 3b1a48b41..2f83e0d06 100644
--- a/doc/intern.rst
+++ b/doc/intern.rst
@@ -1,5 +1,3 @@
-.. default-role:: code
-
 =========================================
     Internals of the Nim Compiler
 =========================================
@@ -8,6 +6,8 @@
 :Author: Andreas Rumpf
 :Version: |nimversion|
 
+.. include:: rstcommon.rst
+.. default-role:: Nim
 .. contents::
 
   "Abstraction is layering ignorance on top of reality." -- Richard Gabriel
@@ -38,25 +38,31 @@ Path           Purpose
 Bootstrapping the compiler
 ==========================
 
-**Note**: Add ``.`` to your PATH so that `koch` can be used without the `./`.
+**Note**: Add ``.`` to your PATH so that `koch`:cmd: can be used without the ``./``.
+
+Compiling the compiler is a simple matter of running:
 
-Compiling the compiler is a simple matter of running::
+.. code:: cmd
 
   nim c koch.nim
   koch boot -d:release
 
-For a debug version use::
+For a debug version use:
+
+.. code:: cmd
 
   nim c koch.nim
   koch boot
 
 
-And for a debug version compatible with GDB::
+And for a debug version compatible with GDB:
+
+.. code:: cmd
 
   nim c koch.nim
   koch boot --debuginfo --linedir:on
 
-The `koch` program is Nim's maintenance script. It is a replacement for
+The `koch`:cmd: program is Nim's maintenance script. It is a replacement for
 make and shell scripting with the advantage that it is much more portable.
 More information about its options can be found in the `koch <koch.html>`_
 documentation.
@@ -65,15 +71,17 @@ documentation.
 Developing the compiler
 =======================
 
-To create a new compiler for each run, use `koch temp`::
+To create a new compiler for each run, use `koch temp`:cmd:\:
+
+.. code:: cmd
 
   koch temp c test.nim
 
-`koch temp` creates a debug build of the compiler, which is useful
+`koch temp`:cmd: creates a debug build of the compiler, which is useful
 to create stacktraces for compiler debugging.
 
 You can of course use GDB or Visual Studio to debug the
-compiler (via `--debuginfo --lineDir:on`). However, there
+compiler (via `--debuginfo --lineDir:on`:option:). However, there
 are also lots of procs that aid in debugging:
 
 
@@ -136,16 +144,18 @@ examples how the AST represents each syntactic structure.
 Bisecting for regressions
 =========================
 
-`koch temp` returns 125 as the exit code in case the compiler
-compilation fails. This exit code tells `git bisect` to skip the
-current commit.::
+`koch temp`:cmd: returns 125 as the exit code in case the compiler
+compilation fails. This exit code tells `git bisect`:cmd: to skip the
+current commit:
+
+.. code:: cmd
 
   git bisect start bad-commit good-commit
   git bisect run ./koch temp -r c test-source.nim
 
 You can also bisect using custom options to build the compiler, for example if
 you don't need a debug version of the compiler (which runs slower), you can replace
-`./koch temp` by explicit compilation command, see `Rebuilding the compiler`_.
+`./koch temp`:cmd: by explicit compilation command, see `Rebuilding the compiler`_.
 
 
 Runtimes
@@ -182,7 +192,7 @@ check that the OS, System modules work and recompile Nim.
 
 The only case where things aren't as easy is when old runtime's garbage
 collectors need some assembler tweaking to work. The default
-implementation uses C's `setjmp` function to store all registers
+implementation uses C's `setjmp`:c: function to store all registers
 on the hardware stack. It may be necessary that the new platform needs to
 replace this generic code by some assembler code.
 
@@ -207,7 +217,7 @@ Complex assignments
 
 We already know the type information as a graph in the compiler.
 Thus we need to serialize this graph as RTTI for C code generation.
-Look at the file `lib/system/hti.nim` for more information.
+Look at the file ``lib/system/hti.nim`` for more information.
 
 
 Magics and compilerProcs
@@ -368,7 +378,7 @@ pass generates code to setup the environment and to pass it around. However,
 this pass does not change the types! So we have some kind of mismatch here; on
 the one hand the proc expression becomes an explicit tuple, on the other hand
 the tyProc(ccClosure) type is not changed. For C code generation it's also
-important the hidden formal param is `void*` and not something more
+important the hidden formal param is `void*`:c: and not something more
 specialized. However the more specialized env type needs to passed to the
 backend somehow. We deal with this by modifying `s.ast[paramPos]` to contain
 the formal hidden parameter, but not `s.typ`!
diff --git a/doc/nimdoc.css b/doc/nimdoc.css
index 6366d33dc..5c2bf2093 100644
--- a/doc/nimdoc.css
+++ b/doc/nimdoc.css
@@ -938,6 +938,14 @@ span.option {
   color: var(--option);

 }

 

+span.Prompt {

+  font-weight: bold;

+  color: red; }

+

+span.ProgramOutput {

+  font-weight: bold;

+  color: #808080; }

+

 span.program {

   font-weight: bold;

   color: var(--program);

diff --git a/doc/testament.rst b/doc/testament.rst
index 04c966ffe..ed1bd63a1 100644
--- a/doc/testament.rst
+++ b/doc/testament.rst
@@ -1,4 +1,10 @@
-.. default-role:: code
+===========
+ Testament
+===========
+
+.. 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,
 offers process isolation for your tests, it can generate statistics about test cases,
@@ -11,29 +17,34 @@ so can be useful to run your tests, even the most complex ones.
 Test files location
 ===================
 
-By default Testament looks for test files on `"./tests/*.nim"`.
-You can overwrite this pattern glob using `pattern <glob>`.
+By default Testament looks for test files on ``"./tests/*.nim"``.
+You can overwrite this pattern glob using `pattern <glob>`:option:.
 The default working directory path can be changed using
-`--directory:"folder/subfolder/"`.
+`--directory:"folder/subfolder/"`:option:.
 
-Testament uses the `nim` compiler on `PATH`.
-You can change that using `--nim:"folder/subfolder/nim"`.
-Running JavaScript tests with `--targets:"js"` requires a working NodeJS on
-`PATH`.
+Testament uses the `nim`:cmd: compiler on `PATH`.
+You can change that using `--nim:"folder/subfolder/nim"`:option:.
+Running JavaScript tests with `--targets:"js"`:option: requires
+a working NodeJS on `PATH`.
 
 
 Options
 =======
 
-* `--print`                   Also print results to the console
-* `--simulate`                See what tests would be run but don't run them (for debugging)
-* `--failing`                 Only show failing/ignored tests
-* `--targets:"c cpp js objc"` Run tests for specified targets (default: all)
-* `--nim:path`                Use a particular nim executable (default: `$PATH/nim`)
-* `--directory:dir`           Change to directory dir before reading the tests or doing anything else.
-* `--colors:on|off`           Turn messages coloring on|off.
-* `--backendLogging:on|off`   Disable or enable backend logging. By default turned on.
-* `--skipFrom:file`           Read tests to skip from `file` - one test per line, # comments ignored
+--print                   Also print results to the console
+--simulate                See what tests would be run but don't run them
+                          (for debugging)
+--failing                 Only show failing/ignored tests
+--targets:"c cpp js objc"
+                          Run tests for specified targets (default: all)
+--nim:path                Use a particular nim executable (default: $PATH/nim)
+--directory:dir           Change to directory dir before reading the tests
+                          or doing anything else.
+--colors:on|off           Turn messages coloring on|off.
+--backendLogging:on|off   Disable or enable backend logging.
+                          By default turned on.
+--skipFrom:file           Read tests to skip from ``file`` - one test per
+                          line, # comments ignored
 
 
 Running a single test
@@ -42,27 +53,26 @@ Running a single test
 This is a minimal example to understand the basics,
 not very useful for production, but easy to understand:
 
-.. code::
+.. code:: console
 
   $ mkdir tests
   $ echo "assert 42 == 42" > tests/test0.nim
   $ testament run test0.nim
-    PASS: tests/test0.nim C                                       ( 0.2 sec)
-
+  PASS: tests/test0.nim C                                    ( 0.2 sec)
   $ testament r test0
-    PASS: tests/test0.nim C                                       ( 0.2 sec)
+  PASS: tests/test0.nim C                                    ( 0.2 sec)
 
 
 Running all tests from a directory
 ==================================
 
-.. code::
+.. code:: console
 
   $ testament pattern "tests/*.nim"
 
 To search for tests deeper in a directory, use
 
-.. code::
+.. code:: console
 
   $ testament pattern "tests/**/*.nim"    # one level deeper
   $ testament pattern "tests/**/**/*.nim" # two levels deeper
@@ -70,10 +80,10 @@ To search for tests deeper in a directory, use
 HTML Reports
 ============
 
-Generate HTML Reports `testresults.html` from unittests,
+Generate HTML Reports ``testresults.html`` from unittests,
 you have to run at least 1 test *before* generating a report:
 
-.. code::
+.. code:: console
 
   $ testament html
 
diff --git a/lib/packages/docutils/highlite.nim b/lib/packages/docutils/highlite.nim
index d6ce274dd..014303837 100644
--- a/lib/packages/docutils/highlite.nim
+++ b/lib/packages/docutils/highlite.nim
@@ -49,6 +49,11 @@
 ## `nimgrep --ext:'nim|nims' file.name`:cmd: shows how to input ``|``.
 ## Any argument that contains ``.`` or ``/`` or ``\`` will be treated
 ## as a file or directory.
+##
+## In addition to `Cmd` there is also `Console` language for
+## displaying interactive sessions.
+## Lines with a command should start with ``$``, other lines are considered
+## as program output.
 
 import
   strutils
@@ -57,7 +62,7 @@ from algorithm import binarySearch
 type
   SourceLanguage* = enum
     langNone, langNim, langCpp, langCsharp, langC, langJava,
-    langYaml, langPython, langCmd
+    langYaml, langPython, langCmd, langConsole
   TokenClass* = enum
     gtEof, gtNone, gtWhitespace, gtDecNumber, gtBinNumber, gtHexNumber,
     gtOctNumber, gtFloatNumber, gtIdentifier, gtKeyword, gtStringLit,
@@ -65,7 +70,7 @@ type
     gtOperator, gtPunctuation, gtComment, gtLongComment, gtRegularExpression,
     gtTagStart, gtTagEnd, gtKey, gtValue, gtRawData, gtAssembler,
     gtPreprocessor, gtDirective, gtCommand, gtRule, gtHyperlink, gtLabel,
-    gtReference, gtProgram, gtOption, gtOther
+    gtReference, gtPrompt, gtProgramOutput, gtProgram, gtOption, gtOther
   GeneralTokenizer* = object of RootObj
     kind*: TokenClass
     start*, length*: int
@@ -76,14 +81,17 @@ type
 
 const
   sourceLanguageToStr*: array[SourceLanguage, string] = ["none",
-    "Nim", "C++", "C#", "C", "Java", "Yaml", "Python", "Cmd"]
+    "Nim", "C++", "C#", "C", "Java", "Yaml", "Python", "Cmd", "Console"]
+  sourceLanguageToAlpha*: array[SourceLanguage, string] = ["none",
+    "Nim", "cpp", "csharp", "C", "Java", "Yaml", "Python", "Cmd", "Console"]
+    ## list of languages spelled with alpabetic characters
   tokenClassToStr*: array[TokenClass, string] = ["Eof", "None", "Whitespace",
     "DecNumber", "BinNumber", "HexNumber", "OctNumber", "FloatNumber",
     "Identifier", "Keyword", "StringLit", "LongStringLit", "CharLit",
     "EscapeSequence", "Operator", "Punctuation", "Comment", "LongComment",
     "RegularExpression", "TagStart", "TagEnd", "Key", "Value", "RawData",
     "Assembler", "Preprocessor", "Directive", "Command", "Rule", "Hyperlink",
-    "Label", "Reference",
+    "Label", "Reference", "Prompt", "ProgramOutput",
     # start from lower-case if there is a corresponding RST role (see rst.nim)
     "program", "option",
     "Other"]
@@ -103,9 +111,11 @@ const
     "xor", "yield"]
 
 proc getSourceLanguage*(name: string): SourceLanguage =
-  for i in countup(succ(low(SourceLanguage)), high(SourceLanguage)):
+  for i in succ(low(SourceLanguage)) .. high(SourceLanguage):
     if cmpIgnoreStyle(name, sourceLanguageToStr[i]) == 0:
       return i
+    if cmpIgnoreStyle(name, sourceLanguageToAlpha[i]) == 0:
+      return i
   result = langNone
 
 proc initGeneralTokenizer*(g: var GeneralTokenizer, buf: cstring) =
@@ -915,17 +925,17 @@ proc pythonNextToken(g: var GeneralTokenizer) =
       "with", "yield"]
   nimNextToken(g, keywords)
 
-proc cmdNextToken(g: var GeneralTokenizer) =
+proc cmdNextToken(g: var GeneralTokenizer, dollarPrompt = false) =
   var pos = g.pos
   g.start = g.pos
   if g.state == low(TokenClass):
-    g.state = gtProgram
+    g.state = if dollarPrompt: gtPrompt else: gtProgram
   case g.buf[pos]
   of ' ', '\t'..'\r':
     g.kind = gtWhitespace
     while g.buf[pos] in {' ', '\t'..'\r'}:
       if g.buf[pos] == '\n':
-        g.state = gtProgram
+        g.state = if dollarPrompt: gtPrompt else: gtProgram
       inc(pos)
   of '\'', '"':
     g.kind = gtOption
@@ -955,6 +965,15 @@ proc cmdNextToken(g: var GeneralTokenizer) =
     g.kind = gtOperator
     inc(pos)
   of '\0': g.kind = gtEof
+  elif dollarPrompt and g.state == gtPrompt:
+    if g.buf[pos] == '$' and g.buf[pos+1] in {' ', '\t'}:
+      g.kind = gtPrompt
+      inc pos, 2
+      g.state = gtProgram
+    else:
+      g.kind = gtProgramOutput
+      while g.buf[pos] notin {'\n', '\0'}:
+        inc(pos)
   else:
     if g.state == gtProgram:
       g.kind = gtProgram
@@ -986,6 +1005,7 @@ proc getNextToken*(g: var GeneralTokenizer, lang: SourceLanguage) =
   of langYaml: yamlNextToken(g)
   of langPython: pythonNextToken(g)
   of langCmd: cmdNextToken(g)
+  of langConsole: cmdNextToken(g, dollarPrompt=true)
 
 proc tokenize*(text: string, lang: SourceLanguage): seq[(string, TokenClass)] =
   var g: GeneralTokenizer
diff --git a/lib/packages/docutils/rst.nim b/lib/packages/docutils/rst.nim
index 249c310b9..ea0d62e04 100644
--- a/lib/packages/docutils/rst.nim
+++ b/lib/packages/docutils/rst.nim
@@ -89,6 +89,8 @@
 ##
 ##   - generic command line highlighting roles:
 ##     - ``:cmd:`` for commands and common shells syntax
+##     - ``:console:`` the same  for interactive sessions
+##       (commands should be prepended by ``$``)
 ##     - ``:program:`` for executable names [cmp:Sphinx]_
 ##       (one can just use ``:cmd:`` on single word)
 ##     - ``:option:`` for command line options [cmp:Sphinx]_
@@ -168,6 +170,7 @@
 import
   os, strutils, rstast, std/enumutils, algorithm, lists, sequtils,
   std/private/miscdollars
+from highlite import SourceLanguage, getSourceLanguage
 
 type
   RstParseOption* = enum     ## options for the RST parser
@@ -549,10 +552,6 @@ proc defaultFindFile*(filename: string): string =
 proc defaultRole(options: RstParseOptions): string =
   if roNimFile in options: "nim" else: "literal"
 
-# mirror highlite.nim sourceLanguageToStr with substitutions c++ cpp, c# csharp
-const supportedLanguages = ["nim", "yaml", "python", "java", "c",
-                            "cpp", "csharp", "cmd"]
-
 proc whichRoleAux(sym: string): RstNodeKind =
   let r = sym.toLowerAscii
   case r
@@ -566,7 +565,7 @@ proc whichRoleAux(sym: string): RstNodeKind =
   of "code": result = rnInlineLiteral
   of "program", "option", "tok": result = rnCodeFragment
   # c++ currently can be spelled only as cpp, c# only as csharp
-  elif r in supportedLanguages:
+  elif getSourceLanguage(r) != langNone:
     result = rnInlineCode
   else:  # unknown role
     result = rnUnknownRole
@@ -2614,7 +2613,7 @@ proc dirRole(p: var RstParser): PRstNode =
   result = parseDirective(p, rnDirective, {hasArg, hasOptions}, nil)
   # just check that language is supported, TODO: real role association
   let lang = getFieldValue(result, "language").strip
-  if lang != "" and lang notin supportedLanguages:
+  if lang != "" and getSourceLanguage(lang) == langNone:
     rstMessage(p, mwUnsupportedLanguage, lang)
 
 proc dirRawAux(p: var RstParser, result: var PRstNode, kind: RstNodeKind,
diff --git a/nimdoc/testproject/expected/nimdoc.out.css b/nimdoc/testproject/expected/nimdoc.out.css
index 6366d33dc..5c2bf2093 100644
--- a/nimdoc/testproject/expected/nimdoc.out.css
+++ b/nimdoc/testproject/expected/nimdoc.out.css
@@ -938,6 +938,14 @@ span.option {
   color: var(--option);

 }

 

+span.Prompt {

+  font-weight: bold;

+  color: red; }

+

+span.ProgramOutput {

+  font-weight: bold;

+  color: #808080; }

+

 span.program {

   font-weight: bold;

   color: var(--program);

diff --git a/tests/stdlib/thighlite.nim b/tests/stdlib/thighlite.nim
index f26ea93e4..4113a6a80 100644
--- a/tests/stdlib/thighlite.nim
+++ b/tests/stdlib/thighlite.nim
@@ -1,8 +1,8 @@
 
-import unittest
+import unittest, strutils
 import ../../lib/packages/docutils/highlite
 
-block: # Nim tokenizing"
+block: # Nim tokenizing
   test "string literals and escape seq":
     check("\"ok1\\nok2\\nok3\"".tokenize(langNim) ==
        @[("\"ok1", gtStringLit), ("\\n", gtEscapeSequence), ("ok2", gtStringLit),
@@ -11,3 +11,16 @@ block: # Nim tokenizing"
     check("\"\"\"ok1\\nok2\\nok3\"\"\"".tokenize(langNim) ==
        @[("\"\"\"ok1\\nok2\\nok3\"\"\"", gtLongStringLit)
       ])
+
+block: # Cmd (shell) tokenizing
+  test "cmd with dollar and output":
+    check(
+      dedent"""
+        $ nim c file.nim
+        out: file [SuccessX]"""
+        .tokenize(langConsole) ==
+      @[("$ ", gtPrompt), ("nim", gtProgram),
+        (" ", gtWhitespace), ("c", gtOption), (" ", gtWhitespace),
+        ("file.nim", gtIdentifier), ("\n", gtWhitespace),
+        ("out: file [SuccessX]", gtProgramOutput)
+      ])
generated by cgit-pink 1.4.1-2-gfad0 (git 2.36.2.497.gbbea4dcf42) at 2025-06-14 13:40:07 +0000