jyapayne/Nim
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

turn on syntax highlighting in Manual & Tutorial (#17692)

Browse source 
* turn on syntax highlighting in Manual & Tutorial

* avoid highlighting of "method"

* use relative path

* 2 more changes
This commit is contained in:
Andrey Makarov 2021-04-11 11:23:08 +03:00 • committed by GitHub
commit 3aaec0647b
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
7 changed files with 149 additions and 137 deletions
Download patch file Download diff file Expand all files Collapse all files

192
doc/manual.rst
View file

@ -1,5 +1,3 @@
.. default-role:: code
========== ==========
Nim Manual Nim Manual
========== ==========
@ -7,6 +5,8 @@ Nim Manual
:Authors: Andreas Rumpf, Zahary Karadjov :Authors: Andreas Rumpf, Zahary Karadjov
:Version: |nimversion| :Version: |nimversion|
.. default-role:: code
.. include:: rstcommon.rst
.. contents:: .. contents::
@ -127,9 +127,9 @@ compiler may instead choose to allow the program to die with a fatal error.
echo "invalid index" echo "invalid index"
The current implementation allows to switch between these different behaviors The current implementation allows to switch between these different behaviors
via `--panics:on|off`. When panics are turned on, the program dies with a via ``--panics:on|off``. When panics are turned on, the program dies with a
panic, if they are turned off the runtime errors are turned into panic, if they are turned off the runtime errors are turned into
exceptions. The benefit of `--panics:on` is that it produces smaller binary exceptions. The benefit of ``--panics:on`` is that it produces smaller binary
code and the compiler has more freedom to optimize the code. code and the compiler has more freedom to optimize the code.
An `unchecked runtime error`:idx: is an error that is not guaranteed to be An `unchecked runtime error`:idx: is an error that is not guaranteed to be
@ -490,7 +490,7 @@ Rationale: It enables the efficient support of `array[char, int]` or
The `Rune` type can represent any Unicode character. The `Rune` type can represent any Unicode character.
`Rune` is declared in the `unicode module <unicode.html>`_. `Rune` is declared in the `unicode module <unicode.html>`_.
A character literal that does not end in ``'`` is interpreted as ``'`` if there A character literal that does not end in `'` is interpreted as `'` if there
is a preceeding backtick token. There must be no whitespace between the preceeding is a preceeding backtick token. There must be no whitespace between the preceeding
backtick token and the character literal. This special case ensures that a declaration backtick token and the character literal. This special case ensures that a declaration
like ``proc `'customLiteral`(s: string)`` is valid. ``proc `'customLiteral`(s: string)`` like ``proc `'customLiteral`(s: string)`` is valid. ``proc `'customLiteral`(s: string)``
@ -752,7 +752,7 @@ Otherwise, precedence is determined by the first character.
Precedence level Operators First character Terminal symbol Precedence level Operators First character Terminal symbol
================ ======================================================= ================== =============== ================ ======================================================= ================== ===============
10 (highest) `$ ^` OP10 10 (highest) `$ ^` OP10
9 `* / div mod shl shr %` ``* % \ /`` OP9 9 `* / div mod shl shr %` `* % \ /` OP9
8 `+ -` `+ - ~ |` OP8 8 `+ -` `+ - ~ |` OP8
7 `&` `&` OP7 7 `&` `&` OP7
6 `..` `.` OP6 6 `..` `.` OP6
@ -1008,7 +1008,7 @@ These integer types are pre-defined:
literal that has no type suffix is of this type if it is in the range literal that has no type suffix is of this type if it is in the range
`low(int32)..high(int32)` otherwise the literal's type is `int64`. `low(int32)..high(int32)` otherwise the literal's type is `int64`.
intXX `int`\ XX
additional signed integer types of XX bits use this naming scheme additional signed integer types of XX bits use this naming scheme
(example: int16 is a 16-bit wide integer). (example: int16 is a 16-bit wide integer).
The current implementation supports `int8`, `int16`, `int32`, `int64`. The current implementation supports `int8`, `int16`, `int32`, `int64`.
@ -1019,7 +1019,7 @@ intXX
has the same size as a pointer. An integer literal with the type has the same size as a pointer. An integer literal with the type
suffix `'u` is of this type. suffix `'u` is of this type.
uintXX `uint`\ XX
additional unsigned integer types of XX bits use this naming scheme additional unsigned integer types of XX bits use this naming scheme
(example: uint16 is a 16-bit wide unsigned integer). (example: uint16 is a 16-bit wide unsigned integer).
The current implementation supports `uint8`, `uint16`, `uint32`, The current implementation supports `uint8`, `uint16`, `uint32`,
@ -1039,22 +1039,22 @@ the `%` suffix as convention:
====================== ====================================================== ====================== ======================================================
operation meaning operation meaning
====================== ====================================================== ====================== ======================================================
`a +% b` unsigned integer addition `a +% b` unsigned integer addition
`a -% b` unsigned integer subtraction `a -% b` unsigned integer subtraction
`a *% b` unsigned integer multiplication `a *% b` unsigned integer multiplication
`a /% b` unsigned integer division `a /% b` unsigned integer division
`a %% b` unsigned integer modulo operation `a %% b` unsigned integer modulo operation
`a <% b` treat `a` and `b` as unsigned and compare `a <% b` treat `a` and `b` as unsigned and compare
`a <=% b` treat `a` and `b` as unsigned and compare `a <=% b` treat `a` and `b` as unsigned and compare
`ze(a)` extends the bits of `a` with zeros until it has the `ze(a)` extends the bits of `a` with zeros until it has the
width of the `int` type width of the `int` type
`toU8(a)` treats `a` as unsigned and converts it to an `toU8(a)` treats `a` as unsigned and converts it to an
unsigned integer of 8 bits (but still the unsigned integer of 8 bits (but still the
`int8` type) `int8` type)
`toU16(a)` treats `a` as unsigned and converts it to an `toU16(a)` treats `a` as unsigned and converts it to an
unsigned integer of 16 bits (but still the unsigned integer of 16 bits (but still the
`int16` type) `int16` type)
`toU32(a)` treats `a` as unsigned and converts it to an `toU32(a)` treats `a` as unsigned and converts it to an
unsigned integer of 32 bits (but still the unsigned integer of 32 bits (but still the
`int32` type) `int32` type)
====================== ====================================================== ====================== ======================================================
@ -1117,9 +1117,9 @@ The following floating-point types are pre-defined:
but now it is always mapped to `float64`. but now it is always mapped to `float64`.
This type should be used in general. This type should be used in general.
floatXX `float`\ XX
an implementation may define additional floating-point types of XX bits using an implementation may define additional floating-point types of XX bits using
this naming scheme (example: float64 is a 64-bit wide float). The current this naming scheme (example: `float64` is a 64-bit wide float). The current
implementation supports `float32` and `float64`. Literals of these types implementation supports `float32` and `float64`. Literals of these types
have the suffix 'fXX. have the suffix 'fXX.
@ -1459,7 +1459,7 @@ The notation `x[i]` can be used to access the i-th element of `x`.
Arrays are always bounds checked (statically or at runtime). These Arrays are always bounds checked (statically or at runtime). These
checks can be disabled via pragmas or invoking the compiler with the checks can be disabled via pragmas or invoking the compiler with the
`--boundChecks:off` command-line switch. ``--boundChecks:off`` command-line switch.
An array constructor can have explicit indexes for readability: An array constructor can have explicit indexes for readability:
@ -1946,7 +1946,8 @@ memory manually:
dealloc(d) dealloc(d)
Without the `reset` call the memory allocated for the `d.s` string would Without the `reset` call the memory allocated for the `d.s` string would
never be freed. The example also demonstrates two important features for low-level programming: the `sizeof` proc returns the size of a type or value never be freed. The example also demonstrates two important features for
low-level programming: the `sizeof` proc returns the size of a type or value
in bytes. The `cast` operator can circumvent the type system: the compiler in bytes. The `cast` operator can circumvent the type system: the compiler
is forced to treat the result of the `alloc0` call (which returns an untyped is forced to treat the result of the `alloc0` call (which returns an untyped
pointer) as if it would have the type `ptr Data`. Casting should only be pointer) as if it would have the type `ptr Data`. Casting should only be
@ -2045,7 +2046,7 @@ Nim supports these `calling conventions`:idx:\:
C++ class member functions on the x86 architecture. C++ class member functions on the x86 architecture.
`syscall`:idx: `syscall`:idx:
The syscall convention is the same as `__syscall` in C. It is used for The syscall convention is the same as `__syscall`:c: in C. It is used for
interrupts. interrupts.
`noconv`:idx: `noconv`:idx:
@ -3217,7 +3218,7 @@ Assembler statement
The direct embedding of assembler code into Nim code is supported The direct embedding of assembler code into Nim code is supported
by the unsafe `asm` statement. Identifiers in the assembler code that refer to by the unsafe `asm` statement. Identifiers in the assembler code that refer to
Nim identifiers shall be enclosed in a special character which can be Nim identifiers shall be enclosed in a special character which can be
specified in the statement's pragmas. The default special character is ``'`'``: specified in the statement's pragmas. The default special character is `'\`'`:
.. code-block:: nim .. code-block:: nim
{.push stackTrace:off.} {.push stackTrace:off.}
@ -3261,7 +3262,7 @@ Instead of:
Using statement Using statement
--------------- ---------------
The using statement provides syntactic convenience in modules where The `using` statement provides syntactic convenience in modules where
the same parameter names and types are used over and over. Instead of: the same parameter names and types are used over and over. Instead of:
.. code-block:: nim .. code-block:: nim
@ -3301,8 +3302,8 @@ that are explicitly typed is possible and requires a semicolon between them.
If expression If expression
------------- -------------
An `if expression` is almost like an if statement, but it is an expression. An `if` expression is almost like an if statement, but it is an expression.
This feature is similar to `ternary operators` in other languages. This feature is similar to *ternary operators* in other languages.
Example: Example:
.. code-block:: nim .. code-block:: nim
@ -3314,12 +3315,12 @@ required. `Elif` parts are also allowed.
When expression When expression
--------------- ---------------
Just like an `if expression`, but corresponding to the when statement. Just like an `if` expression, but corresponding to the `when` statement.
Case expression Case expression
--------------- ---------------
The `case expression` is again very similar to the case statement: The `case` expression is again very similar to the case statement:
.. code-block:: nim .. code-block:: nim
var favoriteFood = case animal var favoriteFood = case animal
@ -3337,7 +3338,7 @@ the last expression as the result value.
Block expression Block expression
---------------- ----------------
A `block expression` is almost like a block statement, but it is an expression A `block` expression is almost like a block statement, but it is an expression
that uses the last expression under the block as the value. that uses the last expression under the block as the value.
It is similar to the statement list expression, but the statement list expression It is similar to the statement list expression, but the statement list expression
does not open a new block scope. does not open a new block scope.
@ -3434,7 +3435,7 @@ Type casts should not be confused with *type conversions,* as mentioned in the
prior section. Unlike type conversions, a type cast cannot change the underlying prior section. Unlike type conversions, a type cast cannot change the underlying
bit pattern of the data being casted (aside from that the size of the target type bit pattern of the data being casted (aside from that the size of the target type
may differ from the source type). Casting resembles *type punning* in other may differ from the source type). Casting resembles *type punning* in other
languages or C++'s `reinterpret_cast` and `bit_cast` features. languages or C++'s `reinterpret_cast`:cpp: and `bit_cast`:cpp: features.
The addr operator The addr operator
----------------- -----------------
@ -3562,7 +3563,7 @@ the operator's position within an expression.) There is no way to declare
postfix operators: all postfix operators are built-in and handled by the postfix operators: all postfix operators are built-in and handled by the
grammar explicitly. grammar explicitly.
Any operator can be called like an ordinary proc with the '`opr`' Any operator can be called like an ordinary proc with the \`opr\`
notation. (Thus an operator can have more than two parameters): notation. (Thus an operator can have more than two parameters):
.. code-block:: nim .. code-block:: nim
@ -3596,9 +3597,9 @@ current module:
Method call syntax Method call syntax
------------------ ------------------
For object-oriented programming, the syntax `obj.method(args)` can be used For object-oriented programming, the syntax `obj.methodName(args)` can be used
instead of `method(obj, args)`. The parentheses can be omitted if there are no instead of `methodName(obj, args)`. The parentheses can be omitted if
remaining arguments: `obj.len` (instead of `len(obj)`). there are no remaining arguments: `obj.len` (instead of `len(obj)`).
This method call syntax is not restricted to objects, it can be used This method call syntax is not restricted to objects, it can be used
to supply any type of first argument for procedures: to supply any type of first argument for procedures:
@ -3813,7 +3814,7 @@ simplicity (they require specialized semantic checking)::
Thus they act more like keywords than like ordinary identifiers; unlike a Thus they act more like keywords than like ordinary identifiers; unlike a
keyword however, a redefinition may `shadow`:idx: the definition in keyword however, a redefinition may `shadow`:idx: the definition in
the `system` module. From this list the following should not be written in dot the system_ 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 notation `x.f` since `x` cannot be type-checked before it gets passed
to `f`:: to `f`::
@ -4059,7 +4060,7 @@ Multi-methods
-------------- --------------
**Note:** Starting from Nim 0.20, to use multi-methods one must explicitly pass **Note:** Starting from Nim 0.20, to use multi-methods one must explicitly pass
`--multimethods:on` when compiling. ``--multimethods:on`` when compiling.
In a multi-method, all parameters that have an object type are used for the In a multi-method, all parameters that have an object type are used for the
dispatching: dispatching:
@ -4768,7 +4769,7 @@ And so is:
The reason for this is that `DivByZeroDefect` inherits from `Defect` and The reason for this is that `DivByZeroDefect` inherits from `Defect` and
with `--panics:on` Defects become unrecoverable errors. with ``--panics:on`` Defects become unrecoverable errors.
(Since version 1.4 of the language.) (Since version 1.4 of the language.)
@ -5567,7 +5568,7 @@ However, this means that the method call syntax is not available for
**Note**: The Nim compiler prior to version 1 was more lenient about this **Note**: The Nim compiler prior to version 1 was more lenient about this
requirement. Use the `--useVersion:0.19` switch for a transition period. requirement. Use the ``--useVersion:0.19`` switch for a transition period.
@ -6022,7 +6023,7 @@ A module may gain access to symbols of another module by the `import`:idx:
statement. `Recursive module dependencies`:idx: are allowed, but are slightly statement. `Recursive module dependencies`:idx: are allowed, but are slightly
subtle. Only top-level symbols that are marked with an asterisk (`*`) are subtle. Only top-level symbols that are marked with an asterisk (`*`) are
exported. A valid module name can only be a valid Nim identifier (and thus its exported. A valid module name can only be a valid Nim identifier (and thus its
filename is `identifier.nim`). filename is ``identifier.nim``).
The algorithm for compiling modules is: The algorithm for compiling modules is:
@ -6484,7 +6485,7 @@ asmNoStackFrame pragma
A proc can be marked with the `asmNoStackFrame` pragma to tell the compiler A proc can be marked with the `asmNoStackFrame` pragma to tell the compiler
it should not generate a stack frame for the proc. There are also no exit it should not generate a stack frame for the proc. There are also no exit
statements like `return result;` generated and the generated C function is statements like `return result;` generated and the generated C function is
declared as `__declspec(naked)` or `__attribute__((naked))` (depending on declared as `__declspec(naked)`:c: or `__attribute__((naked))`:c: (depending on
the used C compiler). the used C compiler).
**Note**: This pragma should only be used by procs which consist solely of **Note**: This pragma should only be used by procs which consist solely of
@ -6879,7 +6880,7 @@ This pragma has no effect on the JS backend.
Volatile pragma Volatile pragma
--------------- ---------------
The `volatile` pragma is for variables only. It declares the variable as The `volatile` pragma is for variables only. It declares the variable as
`volatile`, whatever that means in C/C++ (its semantics are not well defined `volatile`:c:, whatever that means in C/C++ (its semantics are not well defined
in C/C++). in C/C++).
**Note**: This pragma will not exist for the LLVM backend. **Note**: This pragma will not exist for the LLVM backend.
@ -6906,7 +6907,7 @@ Header pragma
------------- -------------
The `header` pragma is very similar to the `nodecl` pragma: It can be The `header` pragma is very similar to the `nodecl` pragma: It can be
applied to almost any symbol and specifies that it should not be declared applied to almost any symbol and specifies that it should not be declared
and instead, the generated code should contain an `#include`: and instead, the generated code should contain an `#include`:c:\:
.. code-block:: Nim .. code-block:: Nim
type type
@ -6915,8 +6916,8 @@ and instead, the generated code should contain an `#include`:
The `header` pragma always expects a string constant. The string constant The `header` pragma always expects a string constant. The string constant
contains the header file: As usual for C, a system header file is enclosed contains the header file: As usual for C, a system header file is enclosed
in angle brackets: `<>`. If no angle brackets are given, Nim in angle brackets: `<>`:c:. If no angle brackets are given, Nim
encloses the header file in `""` in the generated C code. encloses the header file in `""`:c: in the generated C code.
**Note**: This will not work for the LLVM backend. **Note**: This will not work for the LLVM backend.
@ -6924,7 +6925,7 @@ encloses the header file in `""` in the generated C code.
IncompleteStruct pragma IncompleteStruct pragma
----------------------- -----------------------
The `incompleteStruct` pragma tells the compiler to not use the The `incompleteStruct` pragma tells the compiler to not use the
underlying C `struct` in a `sizeof` expression: underlying C `struct`:c: in a `sizeof` expression:
.. code-block:: Nim .. code-block:: Nim
type type
@ -6941,8 +6942,8 @@ with the project:
{.compile: "myfile.cpp".} {.compile: "myfile.cpp".}
**Note**: Nim computes a SHA1 checksum and only recompiles the file if it **Note**: Nim computes a SHA1 checksum and only recompiles the file if it
has changed. One can use the `-f` command-line option to force the recompilation has changed. One can use the ``-f`` command-line option to force
of the file. the recompilation of the file.
Since 1.4 the `compile` pragma is also available with this syntax: Since 1.4 the `compile` pragma is also available with this syntax:
@ -6964,7 +6965,7 @@ The `link` pragma can be used to link an additional file with the project:
PassC pragma PassC pragma
------------ ------------
The `passc` pragma can be used to pass additional parameters to the C The `passc` pragma can be used to pass additional parameters to the C
compiler like one would using the command-line switch `--passc`: compiler like one would using the command-line switch ``--passc``:
.. code-block:: Nim .. code-block:: Nim
{.passc: "-Wall -Werror".} {.passc: "-Wall -Werror".}
@ -6992,7 +6993,7 @@ the pragma resides in:
PassL pragma PassL pragma
------------ ------------
The `passL` pragma can be used to pass additional parameters to the linker The `passL` pragma can be used to pass additional parameters to the linker
like one would be using the command-line switch `--passL`: like one would be using the command-line switch ``--passL``:
.. code-block:: Nim .. code-block:: Nim
{.passL: "-lSDLmain -lSDL".} {.passL: "-lSDLmain -lSDL".}
@ -7029,7 +7030,7 @@ Example:
embedsC() embedsC()
`nimbase.h` defines `NIM_EXTERNC` C macro that can be used for `nimbase.h` defines `NIM_EXTERNC` C macro that can be used for
`extern "C"` code to work with both `nim c` and `nim cpp`, e.g.: `extern "C"`:cpp: code to work with both `nim c` and `nim cpp`, e.g.:
.. code-block:: Nim .. code-block:: Nim
proc foobar() {.importc:"$1".} proc foobar() {.importc:"$1".}
@ -7044,8 +7045,8 @@ Example:
This usage is however deprecated. This usage is however deprecated.
For a top-level emit statement, the section where in the generated C/C++ file For a top-level emit statement, the section where in the generated C/C++ file
the code should be emitted can be influenced via the the code should be emitted can be influenced via the prefixes
prefixes `/*TYPESECTION*/` or `/*VARSECTION*/` or `/*INCLUDESECTION*/`: `/*TYPESECTION*/`:c: or `/*VARSECTION*/`:c: or `/*INCLUDESECTION*/`:c:\:
.. code-block:: Nim .. code-block:: Nim
{.emit: """/*TYPESECTION*/ {.emit: """/*TYPESECTION*/
@ -7075,7 +7076,7 @@ Similar to the `importc pragma for C
<#foreign-function-interface-importc-pragma>`_, the <#foreign-function-interface-importc-pragma>`_, the
`importcpp` pragma can be used to import `C++`:idx: methods or C++ symbols `importcpp` pragma can be used to import `C++`:idx: methods or C++ symbols
in general. The generated code then uses the C++ method calling in general. The generated code then uses the C++ method calling
syntax: `obj->method(arg)`. In combination with the `header` and `emit` syntax: `obj->method(arg)`:cpp:. In combination with the `header` and `emit`
pragmas this allows *sloppy* interfacing with libraries written in C++: pragmas this allows *sloppy* interfacing with libraries written in C++:
.. code-block:: Nim .. code-block:: Nim
@ -7105,16 +7106,16 @@ pragmas this allows *sloppy* interfacing with libraries written in C++:
proc run(device: IrrlichtDevice): bool {. proc run(device: IrrlichtDevice): bool {.
header: irr, importcpp: "#.run(@)".} header: irr, importcpp: "#.run(@)".}
The compiler needs to be told to generate C++ (command `cpp`) for The compiler needs to be told to generate C++ (command ``cpp``) for
this to work. The conditional symbol `cpp` is defined when the compiler this to work. The conditional symbol `cpp` is defined when the compiler
emits C++ code. emits C++ code.
Namespaces Namespaces
~~~~~~~~~~ ~~~~~~~~~~
The *sloppy interfacing* example uses `.emit` to produce `using namespace` The *sloppy interfacing* example uses `.emit` to produce `using namespace`:cpp:
declarations. It is usually much better to instead refer to the imported name declarations. It is usually much better to instead refer to the imported name
via the `namespace::identifier` notation: via the `namespace::identifier`:cpp: notation:
.. code-block:: nim .. code-block:: nim
type type
@ -7126,7 +7127,8 @@ Importcpp for enums
~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~
When `importcpp` is applied to an enum type the numerical enum values are When `importcpp` is applied to an enum type the numerical enum values are
annotated with the C++ enum type, like in this example: `((TheCppEnum)(3))`. annotated with the C++ enum type, like in this example:
`((TheCppEnum)(3))`:cpp:.
(This turned out to be the simplest way to implement it.) (This turned out to be the simplest way to implement it.)
@ -7136,10 +7138,11 @@ Importcpp for procs
Note that the `importcpp` variant for procs uses a somewhat cryptic pattern Note that the `importcpp` variant for procs uses a somewhat cryptic pattern
language for maximum flexibility: language for maximum flexibility:
- A hash `#` symbol is replaced by the first or next argument. - A hash ``#`` symbol is replaced by the first or next argument.
- A dot following the hash `#.` indicates that the call should use C++'s dot - A dot following the hash ``#.`` indicates that the call should use C++'s dot
or arrow notation. or arrow notation.
- An at symbol `@` is replaced by the remaining arguments, separated by commas. - An at symbol ``@`` is replaced by the remaining arguments,
separated by commas.
For example: For example:
@ -7155,7 +7158,7 @@ Produces:
As a special rule to keep backward compatibility with older versions of the As a special rule to keep backward compatibility with older versions of the
`importcpp` pragma, if there is no special pattern `importcpp` pragma, if there is no special pattern
character (any of `# ' @`) at all, C++'s character (any of ``# ' @``) at all, C++'s
dot or arrow notation is assumed, so the above example can also be written as: dot or arrow notation is assumed, so the above example can also be written as:
.. code-block:: nim .. code-block:: nim
@ -7169,11 +7172,11 @@ capabilities:
proc dictLookup(a: Dict, k: Key): Value {.importcpp: "#[#]".} proc dictLookup(a: Dict, k: Key): Value {.importcpp: "#[#]".}
- An apostrophe `'` followed by an integer `i` in the range 0..9 - An apostrophe ``'`` followed by an integer ``i`` in the range 0..9
is replaced by the i'th parameter *type*. The 0th position is the result is replaced by the i'th parameter *type*. The 0th position is the result
type. This can be used to pass types to C++ function templates. Between type. This can be used to pass types to C++ function templates. Between
the `'` and the digit, an asterisk can be used to get to the base type the ``'`` and the digit, an asterisk can be used to get to the base type
of the type. (So it "takes away a star" from the type; `T*` becomes `T`.) of the type. (So it "takes away a star" from the type; `T*`:c: becomes `T`.)
Two stars can be used to get to the element type of the element type etc. Two stars can be used to get to the element type of the element type etc.
For example: For example:
@ -7191,12 +7194,12 @@ Produces:
x = SystemManager::getSubsystem<System::Input>() x = SystemManager::getSubsystem<System::Input>()
- `#@` is a special case to support a `cnew` operation. It is required so - ``#@`` is a special case to support a `cnew` operation. It is required so
that the call expression is inlined directly, without going through a that the call expression is inlined directly, without going through a
temporary location. This is only required to circumvent a limitation of the temporary location. This is only required to circumvent a limitation of the
current code generator. current code generator.
For example C++'s `new` operator can be "imported" like this: For example C++'s `new`:cpp: operator can be "imported" like this:
.. code-block:: nim .. code-block:: nim
proc cnew*[T](x: T): ptr T {.importcpp: "(new '*0#@)", nodecl.} proc cnew*[T](x: T): ptr T {.importcpp: "(new '*0#@)", nodecl.}
@ -7211,7 +7214,7 @@ Produces:
.. code-block:: C .. code-block:: C
x = new Foo(3, 4) x = new Foo(3, 4)
However, depending on the use case `new Foo` can also be wrapped like this However, depending on the use case `new Foo`:cpp: can also be wrapped like this
instead: instead:
.. code-block:: nim .. code-block:: nim
@ -7224,7 +7227,8 @@ Wrapping constructors
~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~
Sometimes a C++ class has a private copy constructor and so code like Sometimes a C++ class has a private copy constructor and so code like
`Class c = Class(1,2);` must not be generated but instead `Class c(1,2);`. `Class c = Class(1,2);`:cpp: must not be generated but instead
`Class c(1,2);`:cpp:.
For this purpose the Nim proc that wraps a C++ constructor needs to be For this purpose the Nim proc that wraps a C++ constructor needs to be
annotated with the `constructor`:idx: pragma. This pragma also helps to generate annotated with the `constructor`:idx: pragma. This pragma also helps to generate
faster C++ code since construction then doesn't invoke the copy constructor: faster C++ code since construction then doesn't invoke the copy constructor:
@ -7298,7 +7302,7 @@ ImportJs pragma
Similar to the `importcpp pragma for C++ <#implementation-specific-pragmas-importcpp-pragma>`_, Similar to the `importcpp pragma for C++ <#implementation-specific-pragmas-importcpp-pragma>`_,
the `importjs` pragma can be used to import Javascript methods or the `importjs` pragma can be used to import Javascript methods or
symbols in general. The generated code then uses the Javascript method symbols in general. The generated code then uses the Javascript method
calling syntax: `obj.method(arg)`. calling syntax: ``obj.method(arg)``.
ImportObjC pragma ImportObjC pragma
@ -7306,7 +7310,7 @@ ImportObjC pragma
Similar to the `importc pragma for C Similar to the `importc pragma for C
<#foreign-function-interface-importc-pragma>`_, the `importobjc` pragma can <#foreign-function-interface-importc-pragma>`_, the `importobjc` pragma can
be used to import `Objective C`:idx: methods. The generated code then uses the be used to import `Objective C`:idx: methods. The generated code then uses the
Objective C method calling syntax: `[obj method param1: arg]`. Objective C method calling syntax: ``[obj method param1: arg]``.
In addition with the `header` and `emit` pragmas this In addition with the `header` and `emit` pragmas this
allows *sloppy* interfacing with libraries written in Objective C: allows *sloppy* interfacing with libraries written in Objective C:
@ -7346,8 +7350,8 @@ allows *sloppy* interfacing with libraries written in Objective C:
g.greet(12, 34) g.greet(12, 34)
g.free() g.free()
The compiler needs to be told to generate Objective C (command `objc`) for The compiler needs to be told to generate Objective C (command ``objc``) for
this to work. The conditional symbol `objc` is defined when the compiler this to work. The conditional symbol ``objc`` is defined when the compiler
emits Objective C code. emits Objective C code.
@ -7392,7 +7396,7 @@ will generate this code:
The `.cppNonPod` pragma should be used for non-POD `importcpp` types so that they The `.cppNonPod` pragma should be used for non-POD `importcpp` types so that they
work properly (in particular regarding constructor and destructor) for work properly (in particular regarding constructor and destructor) for
`.threadvar` variables. This requires `--tlsEmulation:off`. `.threadvar` variables. This requires ``--tlsEmulation:off``.
.. code-block:: nim .. code-block:: nim
type Foo {.cppNonPod, importcpp, header: "funs.h".} = object type Foo {.cppNonPod, importcpp, header: "funs.h".} = object
@ -7436,12 +7440,12 @@ pragma description
:: ::
nim c -d:FooBar=42 foobar.nim nim c -d:FooBar=42 foobar.nim
In the above example, providing the -d flag causes the symbol In the above example, providing the ``-d`` flag causes the symbol
`FooBar` to be overwritten at compile-time, printing out 42. If the `FooBar` to be overwritten at compile-time, printing out 42. If the
`-d:FooBar=42` were to be omitted, the default value of 5 would be ``-d:FooBar=42`` were to be omitted, the default value of 5 would be
used. To see if a value was provided, `defined(FooBar)` can be used. used. To see if a value was provided, `defined(FooBar)` can be used.
The syntax `-d:flag` is actually just a shortcut for `-d:flag=true`. The syntax ``-d:flag`` is actually just a shortcut for ``-d:flag=true``.
User-defined pragmas User-defined pragmas
==================== ====================
@ -7604,7 +7608,7 @@ spelled*:
proc printf(formatstr: cstring) {.header: "<stdio.h>", importc: "printf", varargs.} proc printf(formatstr: cstring) {.header: "<stdio.h>", importc: "printf", varargs.}
When `importc` is applied to a `let` statement it can omit its value which When `importc` is applied to a `let` statement it can omit its value which
will then be expected to come from C. This can be used to import a C `const`: will then be expected to come from C. This can be used to import a C `const`:c:\:
.. code-block:: .. code-block::
{.emit: "const int cconst = 42;".} {.emit: "const int cconst = 42;".}
@ -7625,8 +7629,8 @@ is not set to C, other pragmas are available:
.. code-block:: Nim .. code-block:: Nim
proc p(s: cstring) {.importc: "prefix$1".} proc p(s: cstring) {.importc: "prefix$1".}
In the example, the external name of `p` is set to `prefixp`. Only `$1` In the example, the external name of `p` is set to `prefixp`. Only ``$1``
is available and a literal dollar sign must be written as `$$`. is available and a literal dollar sign must be written as ``$$``.
Exportc pragma Exportc pragma
@ -7648,8 +7652,8 @@ The string literal passed to `exportc` can be a format string:
proc p(s: string) {.exportc: "prefix$1".} = proc p(s: string) {.exportc: "prefix$1".} =
echo s echo s
In the example, the external name of `p` is set to `prefixp`. Only `$1` In the example, the external name of `p` is set to `prefixp`. Only ``$1``
is available and a literal dollar sign must be written as `$$`. is available and a literal dollar sign must be written as ``$$``.
If the symbol should also be exported to a dynamic library, the `dynlib` If the symbol should also be exported to a dynamic library, the `dynlib`
pragma should be used in addition to the `exportc` pragma. See pragma should be used in addition to the `exportc` pragma. See
@ -7665,8 +7669,8 @@ mangling. The string literal passed to `extern` can be a format string:
proc p(s: string) {.extern: "prefix$1".} = proc p(s: string) {.extern: "prefix$1".} =
echo s echo s
In the example, the external name of `p` is set to `prefixp`. Only `$1` In the example, the external name of `p` is set to `prefixp`. Only ``$1``
is available and a literal dollar sign must be written as `$$`. is available and a literal dollar sign must be written as ``$$``.
Bycopy pragma Bycopy pragma
@ -7704,8 +7708,8 @@ strings automatically:
Union pragma Union pragma
------------ ------------
The `union` pragma can be applied to any `object` type. It means all The `union` pragma can be applied to any `object` type. It means all
of the object's fields are overlaid in memory. This produces a `union` of the object's fields are overlaid in memory. This produces a `union`:c:
instead of a `struct` in the generated C/C++ code. The object declaration instead of a `struct`:c: in the generated C/C++ code. The object declaration
then must not use inheritance or any GC'ed memory but this is currently not then must not use inheritance or any GC'ed memory but this is currently not
checked. checked.
@ -7728,7 +7732,7 @@ a static error. Usage with inheritance should be defined and documented.
Dynlib pragma for import Dynlib pragma for import
------------------------ ------------------------
With the `dynlib` pragma, a procedure or a variable can be imported from With the `dynlib` pragma, a procedure or a variable can be imported from
a dynamic library (`.dll` files for Windows, `lib*.so` files for UNIX). a dynamic library (``.dll`` files for Windows, ``lib*.so`` files for UNIX).
The non-optional argument has to be the name of the dynamic library: The non-optional argument has to be the name of the dynamic library:
.. code-block:: Nim .. code-block:: Nim
@ -7771,14 +7775,14 @@ string expressions in general:
proc myImport(s: cstring) {.cdecl, importc, dynlib: getDllName().} proc myImport(s: cstring) {.cdecl, importc, dynlib: getDllName().}
**Note**: Patterns like `libtcl(|8.5|8.4).so` are only supported in constant **Note**: Patterns like ``libtcl(|8.5|8.4).so`` are only supported in constant
strings, because they are precompiled. strings, because they are precompiled.
**Note**: Passing variables to the `dynlib` pragma will fail at runtime **Note**: Passing variables to the `dynlib` pragma will fail at runtime
because of order of initialization problems. because of order of initialization problems.
**Note**: A `dynlib` import can be overridden with **Note**: A `dynlib` import can be overridden with
the `--dynlibOverride:name` command-line option. The the ``--dynlibOverride:name`` command-line option. The
`Compiler User Guide <nimc.html>`_ contains further information. `Compiler User Guide <nimc.html>`_ contains further information.
@ -7793,15 +7797,15 @@ conjunction with the `exportc` pragma:
proc exportme(): int {.cdecl, exportc, dynlib.} proc exportme(): int {.cdecl, exportc, dynlib.}
This is only useful if the program is compiled as a dynamic library via the This is only useful if the program is compiled as a dynamic library via the
`--app:lib` command-line option. ``--app:lib`` command-line option.
Threads Threads
======= =======
To enable thread support the `--threads:on` command-line switch needs to To enable thread support the ``--threads:on`` command-line switch needs to
be used. The `system` module then contains several threading primitives. be used. The system_ module then contains several threading primitives.
See the `threads <threads.html>`_ and `channels <channels.html>`_ modules See the `threads <threads.html>`_ and `channels <channels.html>`_ modules
for the low-level thread API. There are also high-level parallelism constructs for the low-level thread API. There are also high-level parallelism constructs
available. See `spawn <manual_experimental.html#parallel-amp-spawn>`_ for available. See `spawn <manual_experimental.html#parallel-amp-spawn>`_ for
@ -7842,7 +7846,7 @@ any of its parameters contain a `ref` or `closure` type. This enforces
the *no heap sharing restriction*. the *no heap sharing restriction*.
Routines that are imported from C are always assumed to be `gcsafe`. Routines that are imported from C are always assumed to be `gcsafe`.
To disable the GC-safety checking the `--threadAnalysis:off` command-line To disable the GC-safety checking the ``--threadAnalysis:off`` command-line
switch can be used. This is a temporary workaround to ease the porting effort switch can be used. This is a temporary workaround to ease the porting effort
from old code to the new threading model. from old code to the new threading model.

1
doc/manual/var_t_return.rst
View file

@ -1,4 +1,5 @@
.. default-role:: code .. default-role:: code
.. include:: ../rstcommon.rst
Memory safety for returning by `var T` is ensured by a simple borrowing Memory safety for returning by `var T` is ensured by a simple borrowing
rule: If `result` does not refer to a location pointing to the heap rule: If `result` does not refer to a location pointing to the heap

6
doc/rstcommon.rst Normal file
View file

@ -0,0 +1,6 @@
.. role:: nim(code)
:language: nim
.. default-role:: nim

38
doc/sets_fragment.txt
View file

@ -1,13 +1,13 @@
The set type models the mathematical notion of a set. The set's basetype can The set type models the mathematical notion of a set. The set's basetype can
only be an ordinal type of a certain size, namely: only be an ordinal type of a certain size, namely:
* ``int8``-``int16`` * `int8`-`int16`
* ``uint8``/``byte``-``uint16`` * `uint8`/`byte`-`uint16`
* ``char`` * `char`
* ``enum`` * `enum`
or equivalent. For signed integers the set's base type is defined to be in the or equivalent. For signed integers the set's base type is defined to be in the
range ``0 .. MaxSetElements-1`` where ``MaxSetElements`` is currently always range `0 .. MaxSetElements-1` where `MaxSetElements` is currently always
2^16. 2^16.
The reason is that sets are implemented as high performance bit vectors. The reason is that sets are implemented as high performance bit vectors.
@ -17,7 +17,7 @@ Attempting to declare a set with a larger type will result in an error:
var s: set[int64] # Error: set is too large var s: set[int64] # Error: set is too large
Sets can be constructed via the set constructor: ``{}`` is the empty set. The Sets can be constructed via the set constructor: `{}` is the empty set. The
empty set is type compatible with any concrete set type. The constructor empty set is type compatible with any concrete set type. The constructor
can also be used to include elements (and ranges of elements): can also be used to include elements (and ranges of elements):
@ -35,18 +35,18 @@ These operations are supported by sets:
================== ======================================================== ================== ========================================================
operation meaning operation meaning
================== ======================================================== ================== ========================================================
``A + B`` union of two sets `A + B` union of two sets
``A * B`` intersection of two sets `A * B` intersection of two sets
``A - B`` difference of two sets (A without B's elements) `A - B` difference of two sets (A without B's elements)
``A == B`` set equality `A == B` set equality
``A <= B`` subset relation (A is subset of B or equal to B) `A <= B` subset relation (A is subset of B or equal to B)
``A < B`` strict subset relation (A is a proper subset of B) `A < B` strict subset relation (A is a proper subset of B)
``e in A`` set membership (A contains element e) `e in A` set membership (A contains element e)
``e notin A`` A does not contain element e `e notin A` A does not contain element e
``contains(A, e)`` A contains element e `contains(A, e)` A contains element e
``card(A)`` the cardinality of A (number of elements in A) `card(A)` the cardinality of A (number of elements in A)
``incl(A, elem)`` same as ``A = A + {elem}`` `incl(A, elem)` same as `A = A + {elem}`
``excl(A, elem)`` same as ``A = A - {elem}`` `excl(A, elem)` same as `A = A - {elem}`
================== ======================================================== ================== ========================================================
Bit fields Bit fields
@ -54,7 +54,7 @@ Bit fields
Sets are often used to define a type for the *flags* of a procedure. Sets are often used to define a type for the *flags* of a procedure.
This is a cleaner (and type safe) solution than defining integer This is a cleaner (and type safe) solution than defining integer
constants that have to be ``or``'ed together. constants that have to be `or`'ed together.
Enum, sets and casting can be used together as in: Enum, sets and casting can be used together as in:

34
doc/tut1.rst
View file

@ -1,5 +1,3 @@
.. default-role:: code
===================== =====================
Nim Tutorial (Part I) Nim Tutorial (Part I)
===================== =====================
@ -7,6 +5,8 @@ Nim Tutorial (Part I)
:Author: Andreas Rumpf :Author: Andreas Rumpf
:Version: |nimversion| :Version: |nimversion|
.. default-role:: code
.. include:: rstcommon.rst
.. contents:: .. contents::
Introduction Introduction
@ -48,7 +48,7 @@ Save this code to the file "greetings.nim". Now compile and run it::
nim compile --run greetings.nim nim compile --run greetings.nim
With the `--run` `switch <nimc.html#compiler-usage-commandminusline-switches>`_ Nim With the ``--run`` `switch <nimc.html#compiler-usage-commandminusline-switches>`_ Nim
executes the file automatically after compilation. You can give your program 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::
@ -63,12 +63,12 @@ To compile a release version use::
nim c -d:release greetings.nim nim c -d:release greetings.nim
By default, the Nim compiler generates a large number of runtime checks By default, the Nim compiler generates a large number of runtime checks
aiming for your debugging pleasure. With `-d:release` some checks are aiming for your debugging pleasure. With ``-d:release`` some checks are
`turned off and optimizations are turned on `turned off and optimizations are turned on
<nimc.html#compiler-usage-compileminustime-symbols>`_. <nimc.html#compiler-usage-compileminustime-symbols>`_.
For benchmarking or production code, use the `-d:release` switch. For benchmarking or production code, use the ``-d:release`` switch.
For comparing the performance with unsafe languages like C, use the `-d:danger` switch For comparing the performance with unsafe languages like C, use the ``-d:danger`` switch
in order to get meaningful, comparable results. Otherwise Nim might be handicapped in order to get meaningful, comparable results. Otherwise Nim might be handicapped
by checks that are **not even available** for C. by checks that are **not even available** for C.
@ -535,7 +535,7 @@ differences:
that belong to the first condition that evaluates to `true`. that belong to the first condition that evaluates to `true`.
The `when` statement is useful for writing platform-specific code, similar to The `when` statement is useful for writing platform-specific code, similar to
the `#ifdef` construct in the C programming language. the `#ifdef`:c: construct in the C programming language.
Statements and indentation Statements and indentation
@ -596,7 +596,7 @@ Procedures
To define new commands like `echo <system.html#echo,varargs[typed,]>`_ To define new commands like `echo <system.html#echo,varargs[typed,]>`_
and `readLine <io.html#readLine,File>`_ in the examples, the concept of a and `readLine <io.html#readLine,File>`_ in the examples, the concept of a
`procedure` is needed. (Some languages call them *methods* or *functions*.) *procedure* is needed. (Some languages call them *methods* or *functions*.)
In Nim new procedures are defined with the `proc` keyword: In Nim new procedures are defined with the `proc` keyword:
.. code-block:: nim .. code-block:: nim
@ -802,7 +802,7 @@ Operators
--------- ---------
The Nim library makes heavy use of overloading - one reason for this is that The Nim library makes heavy use of overloading - one reason for this is that
each operator like `+` is just an overloaded proc. The parser lets you each operator like `+` is just an overloaded proc. The parser lets you
use operators in `infix notation` (`a + b`) or `prefix notation` (`+ a`). use operators in *infix notation* (`a + b`) or *prefix notation* (`+ a`).
An infix operator always receives two arguments, a prefix operator always one. An infix operator always receives two arguments, a prefix operator always one.
(Postfix operators are not possible, because this would be ambiguous: does (Postfix operators are not possible, because this would be ambiguous: does
`a @ @ b` mean `(a) @ (@b)` or `(a@) @ (b)`? It always means `a @ @ b` mean `(a) @ (@b)` or `(a@) @ (b)`? It always means
@ -810,7 +810,7 @@ An infix operator always receives two arguments, a prefix operator always one.
Apart from a few built-in keyword operators such as `and`, `or`, `not`, Apart from a few built-in keyword operators such as `and`, `or`, `not`,
operators always consist of these characters: operators always consist of these characters:
``+ - * \ / < > = @ $ ~ & % ! ? ^ . |`` `+ - * \ / < > = @ $ ~ & % ! ? ^ . |`
User-defined operators are allowed. Nothing stops you from defining your own User-defined operators are allowed. Nothing stops you from defining your own
`@!?+~` operator, but doing so may reduce readability. `@!?+~` operator, but doing so may reduce readability.
@ -952,7 +952,7 @@ evaluation. For example:
Characters Characters
---------- ----------
The `character type` is called `char`. Its size is always one byte, so The *character type* is called `char`. Its size is always one byte, so
it cannot represent most UTF-8 characters, but it *can* represent one of the bytes it cannot represent most UTF-8 characters, but it *can* represent one of the bytes
that makes up a multi-byte UTF-8 character. that makes up a multi-byte UTF-8 character.
The reason for this is efficiency: for the overwhelming majority of use-cases, The reason for this is efficiency: for the overwhelming majority of use-cases,
@ -1220,7 +1220,7 @@ Arrays can be constructed using `[]`:
The notation `x[i]` is used to access the i-th element of `x`. The notation `x[i]` is used to access the i-th element of `x`.
Array access is always bounds checked (at compile-time or at runtime). These Array access is always bounds checked (at compile-time or at runtime). These
checks can be disabled via pragmas or invoking the compiler with the checks can be disabled via pragmas or invoking the compiler with the
`--bound_checks:off` command line switch. ``--bound_checks:off`` command line switch.
Arrays are value types, like any other Nim type. The assignment operator Arrays are value types, like any other Nim type. The assignment operator
copies the whole array contents. copies the whole array contents.
@ -1620,11 +1620,11 @@ variables! For example:
path = "usr/local/nimc.html" path = "usr/local/nimc.html"
(dir, name, ext) = splitFile(path) (dir, name, ext) = splitFile(path)
baddir, badname, badext = splitFile(path) baddir, badname, badext = splitFile(path)
echo dir # outputs `usr/local` echo dir # outputs "usr/local"
echo name # outputs `nimc` echo name # outputs "nimc"
echo ext # outputs `.html` echo ext # outputs ".html"
# All the following output the same line: # All the following output the same line:
# `(dir: usr/local, name: nimc, ext: .html)` # "(dir: usr/local, name: nimc, ext: .html)"
echo baddir echo baddir
echo badname echo badname
echo badext echo badext
@ -1711,7 +1711,7 @@ Examples are provided in the `manual <manual.html#types-distinct-type>`_.
Modules Modules
======= =======
Nim supports splitting a program into pieces with a module concept. Nim supports splitting a program into pieces with a *module* concept.
Each module is in its own file. Modules enable `information hiding`:idx: and Each module is in its own file. Modules enable `information hiding`:idx: and
`separate compilation`:idx:. A module may gain access to the symbols of another `separate compilation`:idx:. A module may gain access to the symbols of another
module by using the `import`:idx: statement. Only top-level symbols that are marked module by using the `import`:idx: statement. Only top-level symbols that are marked

11
doc/tut2.rst
View file

@ -1,5 +1,3 @@
.. default-role:: code
====================== ======================
Nim Tutorial (Part II) Nim Tutorial (Part II)
====================== ======================
@ -7,6 +5,8 @@ Nim Tutorial (Part II)
:Author: Andreas Rumpf :Author: Andreas Rumpf
:Version: |nimversion| :Version: |nimversion|
.. default-role:: code
.. include:: rstcommon.rst
.. contents:: .. contents::
@ -175,7 +175,8 @@ Method call syntax
------------------ ------------------
There is a syntactic sugar for calling routines: There is a syntactic sugar for calling routines:
The syntax `obj.method(args)` can be used instead of `method(obj, args)`. The syntax `obj.methodName(args)` can be used
instead of `methodName(obj, args)`.
If there are no remaining arguments, the parentheses can be omitted: If there are no remaining arguments, the parentheses can be omitted:
`obj.len` (instead of `len(obj)`). `obj.len` (instead of `len(obj)`).
@ -296,7 +297,7 @@ because it makes more sense for them to use static binding, but `eval` is a
method because it requires dynamic binding. method because it requires dynamic binding.
**Note:** Starting from Nim 0.20, to use multi-methods one must explicitly pass **Note:** Starting from Nim 0.20, to use multi-methods one must explicitly pass
`--multimethods:on` when compiling. ``--multimethods:on`` when compiling.
In a multi-method all parameters that have an object type are used for the In a multi-method all parameters that have an object type are used for the
dispatching: dispatching:
@ -459,7 +460,7 @@ If you want to add the `{.raises.}` pragma to existing code, the compiler can
also help you. You can add the `{.effects.}` pragma statement to your proc and also help you. You can add the `{.effects.}` pragma statement to your proc and
the compiler will output all inferred effects up to that point (exception the compiler will output all inferred effects up to that point (exception
tracking is part of Nim's effect system). Another more roundabout way to tracking is part of Nim's effect system). Another more roundabout way to
find out the list of exceptions raised by a proc is to use the Nim `doc` find out the list of exceptions raised by a proc is to use the Nim ``doc``
command which generates documentation for a whole module and decorates all command which generates documentation for a whole module and decorates all
procs with the list of raised exceptions. You can read more about Nim's procs with the list of raised exceptions. You can read more about Nim's
`effect system and related pragmas in the manual <manual.html#effect-system>`_. `effect system and related pragmas in the manual <manual.html#effect-system>`_.

4
doc/tut3.rst
View file

@ -1,5 +1,3 @@
.. default-role:: code
======================= =======================
Nim Tutorial (Part III) Nim Tutorial (Part III)
======================= =======================
@ -7,6 +5,8 @@ Nim Tutorial (Part III)
:Author: Arne Döring :Author: Arne Döring
:Version: |nimversion| :Version: |nimversion|
.. default-role:: code
.. include:: rstcommon.rst
.. contents:: .. contents::