Markdown indented code blocks (#20473)
* Implement Markdown indented code blocks
Additional indentation of 4 spaces makes a block an "indented code block"
(monospaced text without syntax highlighting).
Also `::` RST syntax for code blocks is disabled.
So instead of
```rst
see::
Some code
```
the code block should be written as
```markdown
see:
Some code
```
* Migrate RST literal blocks :: to Markdown's ones
This commit is contained in:
Andrey Makarov
GitHub
parent
594e93a66b
commit
6505bd347d
33 changed files with 697 additions and 603 deletions
|
|
@ -1,4 +1,3 @@
|
|||
::
|
||||
|
||||
nim command [options] [projectfile] [arguments]
|
||||
|
||||
|
|
|
|||
|
|
@ -314,12 +314,12 @@ To avoid accidental highlighting follow this rule in ``*.nim`` files:
|
|||
programming languages, including identifiers, in ``*.nim`` files.
|
||||
|
||||
For languages other than Nim add a role after final backtick,
|
||||
e.g. for C++ inline highlighting::
|
||||
e.g. for C++ inline highlighting:
|
||||
|
||||
`#include <stdio.h>`:cpp:
|
||||
|
||||
For a currently unsupported language add the `:code:` role,
|
||||
like for SQL in this example::
|
||||
like for SQL in this example:
|
||||
|
||||
`SELECT * FROM <table_name>;`:code:
|
||||
|
||||
|
|
@ -336,7 +336,7 @@ To avoid accidental highlighting follow this rule in ``*.nim`` files:
|
|||
|
||||
.. Note:: ``*.rst`` files have ``:literal:`` as their default role.
|
||||
So for them the rule above is only applicable if the ``:nim:`` role
|
||||
is set up manually as the default \[*]::
|
||||
is set up manually as the default \[*]:
|
||||
|
||||
.. role:: nim(code)
|
||||
:language: nim
|
||||
|
|
@ -489,7 +489,7 @@ General commit rules
|
|||
git diff --check --cached || exit $?
|
||||
```
|
||||
5. Describe your commit and use your common sense.
|
||||
Example commit message::
|
||||
Example commit message:
|
||||
|
||||
Fixes #123; refs #124
|
||||
|
||||
|
|
@ -581,8 +581,6 @@ Code reviews
|
|||
3. In addition, you can view GitHub-like diffs locally to identify what was changed
|
||||
within a code block using `diff-highlight`:cmd: or `diff-so-fancy`:cmd:, e.g.:
|
||||
|
||||
::
|
||||
|
||||
# put this in ~/.gitconfig:
|
||||
[core]
|
||||
pager = "diff-so-fancy | less -R" # or: use: `diff-highlight`
|
||||
|
|
|
|||
|
|
@ -358,7 +358,6 @@ Rewrite rules
|
|||
The current implementation follows strategy (2). This means that resources are
|
||||
destroyed at the scope exit.
|
||||
|
||||
::
|
||||
|
||||
var x: T; stmts
|
||||
--------------- (destroy-var)
|
||||
|
|
|
|||
|
|
@ -64,7 +64,8 @@ Example:
|
|||
age: int
|
||||
```
|
||||
|
||||
Outputs::
|
||||
Outputs:
|
||||
|
||||
Person* = object
|
||||
name: string
|
||||
age: int
|
||||
|
|
@ -133,7 +134,8 @@ The `doc`:option: command:
|
|||
nim doc docgen_sample.nim
|
||||
```
|
||||
|
||||
Partial Output::
|
||||
Partial Output:
|
||||
|
||||
...
|
||||
proc helloWorld(times: int) {.raises: [], tags: [].}
|
||||
...
|
||||
|
|
@ -179,7 +181,8 @@ The `jsondoc`:option: command:
|
|||
nim jsondoc docgen_sample.nim
|
||||
```
|
||||
|
||||
Output::
|
||||
Output:
|
||||
|
||||
{
|
||||
"orig": "docgen_sample.nim",
|
||||
"nimble": "",
|
||||
|
|
@ -205,7 +208,8 @@ The `jsondoc0`:option: command:
|
|||
nim jsondoc0 docgen_sample.nim
|
||||
```
|
||||
|
||||
Output::
|
||||
Output:
|
||||
|
||||
[
|
||||
{
|
||||
"comment": "This module is a sample."
|
||||
|
|
@ -247,9 +251,12 @@ If you have a constant:
|
|||
|
||||
then it should be referenced in one of the 2 forms:
|
||||
|
||||
A. non-qualified (no symbol kind specification)::
|
||||
A. non-qualified (no symbol kind specification):
|
||||
|
||||
pi_
|
||||
B. qualified (with symbol kind specification)::
|
||||
|
||||
B. qualified (with symbol kind specification):
|
||||
|
||||
`const pi`_
|
||||
|
||||
For routine kinds there are more options. Consider this definition:
|
||||
|
|
@ -262,11 +269,11 @@ Generally following syntax is allowed for referencing `foo`:
|
|||
|
||||
* short (without parameters):
|
||||
|
||||
A. non-qualified::
|
||||
A. non-qualified:
|
||||
|
||||
foo_
|
||||
|
||||
B. qualified::
|
||||
B. qualified:
|
||||
|
||||
`proc foo`_
|
||||
|
||||
|
|
@ -274,29 +281,29 @@ Generally following syntax is allowed for referencing `foo`:
|
|||
|
||||
A. non-qualified:
|
||||
|
||||
1) specifying parameters names::
|
||||
1) specifying parameters names:
|
||||
|
||||
`foo(a, b)`_
|
||||
|
||||
2) specifying parameters types::
|
||||
2) specifying parameters types:
|
||||
|
||||
`foo(int, float)`_
|
||||
|
||||
3) specifying both names and types::
|
||||
3) specifying both names and types:
|
||||
|
||||
`foo(a: int, b: float)`_
|
||||
|
||||
4) output parameter can also be specified if you wish::
|
||||
4) output parameter can also be specified if you wish:
|
||||
|
||||
`foo(a: int, b: float): string`_
|
||||
|
||||
B. qualified: all 4 options above are valid.
|
||||
Particularly you can use the full format::
|
||||
Particularly you can use the full format:
|
||||
|
||||
`proc foo(a: int, b: float): string`_
|
||||
|
||||
.. Tip:: Avoid cluttering your text with extraneous information by using
|
||||
one of shorter forms::
|
||||
one of shorter forms:
|
||||
|
||||
binarySearch_
|
||||
`binarySearch(a, key, cmp)`_
|
||||
|
|
@ -304,7 +311,7 @@ Generally following syntax is allowed for referencing `foo`:
|
|||
Brevity is better for reading! If you use a short form and have an
|
||||
ambiguity problem (see below) then just add some additional info.
|
||||
|
||||
Symbol kind like `proc` can also be specified in the postfix form::
|
||||
Symbol kind like `proc` can also be specified in the postfix form:
|
||||
|
||||
`foo proc`_
|
||||
`walkDir(d: string) iterator`_
|
||||
|
|
@ -320,7 +327,7 @@ Symbol kind like `proc` can also be specified in the postfix form::
|
|||
`proc` and `template`. In this case they are split between their
|
||||
corresponding sections in output file. Qualified references are
|
||||
useful in this case -- just disambiguate by referring to these
|
||||
sections explicitly::
|
||||
sections explicitly:
|
||||
|
||||
See `foo proc`_ and `foo template`_.
|
||||
|
||||
|
|
@ -334,7 +341,7 @@ Symbol kind like `proc` can also be specified in the postfix form::
|
|||
(while procs have higher priority than other Nim symbol kinds).
|
||||
|
||||
Generic parameters can also be used. All in all, this long form will be
|
||||
recognized fine::
|
||||
recognized fine:
|
||||
|
||||
`proc binarySearch*[T; K](a: openArray[T], key: K, cmp: proc(T, K)): int`_
|
||||
|
||||
|
|
@ -351,14 +358,14 @@ recognized fine::
|
|||
```
|
||||
|
||||
you cannot use names underlined by `~~` so it must be referenced with
|
||||
``cmp: proc(T, K)``. Hence these forms are valid::
|
||||
``cmp: proc(T, K)``. Hence these forms are valid:
|
||||
|
||||
`binarySearch(a: openArray[T], key: K, cmp: proc(T, K))`_
|
||||
`binarySearch(openArray[T], K, proc(T, K))`_
|
||||
`binarySearch(a, key, cmp)`_
|
||||
2. Default values in routine parameters are not recognized, one needs to
|
||||
specify the type and/or name instead. E.g. for referencing `proc f(x = 7)`
|
||||
use one of the mentioned forms::
|
||||
use one of the mentioned forms:
|
||||
|
||||
`f(int)`_ or `f(x)`_ or `f(x: int)`_.
|
||||
3. Generic parameters must be given the same way as in the
|
||||
|
|
@ -376,7 +383,7 @@ recognized fine::
|
|||
func `[]`*[T](x: openArray[T]): T
|
||||
```
|
||||
|
||||
A short form works without additional backticks::
|
||||
A short form works without additional backticks:
|
||||
|
||||
`$`_
|
||||
`[]`_
|
||||
|
|
@ -384,7 +391,7 @@ recognized fine::
|
|||
However for fully-qualified reference copy-pasting backticks (`) into other
|
||||
backticks will not work in our RST parser (because we use Markdown-like
|
||||
inline markup rules). You need either to delete backticks or keep
|
||||
them and escape with backslash \\::
|
||||
them and escape with backslash \\:
|
||||
|
||||
no backticks: `func $`_
|
||||
escaped: `func \`$\``_
|
||||
|
|
@ -392,7 +399,7 @@ recognized fine::
|
|||
escaped: `func \`[]\`[T](x: openArray[T]): T`_
|
||||
|
||||
.. Note:: Types that defined as `enum`, or `object`, or `tuple` can also be
|
||||
referenced with those names directly (instead of `type`)::
|
||||
referenced with those names directly (instead of `type`):
|
||||
|
||||
type CopyFlag = enum
|
||||
...
|
||||
|
|
|
|||
|
|
@ -66,7 +66,7 @@ without additional annotations:
|
|||
```
|
||||
|
||||
This program contains a famous "index out of bounds" bug. DrNim
|
||||
detects it and produces the following error message::
|
||||
detects it and produces the following error message:
|
||||
|
||||
cannot prove: i <= len(a) + -1; counter example: i -> 0 a.len -> 0 [IndexCheck]
|
||||
|
||||
|
|
@ -146,7 +146,7 @@ Example: insertionSort
|
|||
Unfortunately, the invariants required to prove that this code is correct take more
|
||||
code than the imperative instructions. However, this effort can be compensated
|
||||
by the fact that the result needs very little testing. Be aware though that
|
||||
DrNim only proves that after `insertionSort` this condition holds::
|
||||
DrNim only proves that after `insertionSort` this condition holds:
|
||||
|
||||
forall(i in 1..<a.len, a[i-1] <= a[i])
|
||||
|
||||
|
|
@ -170,7 +170,7 @@ Syntax of propositions
|
|||
======================
|
||||
|
||||
The basic syntax is `ensures|requires|invariant: <prop>`.
|
||||
A `prop` is either a comparison or a compound::
|
||||
A `prop` is either a comparison or a compound:
|
||||
|
||||
prop = nim_bool_expression
|
||||
| prop 'and' prop
|
||||
|
|
|
|||
|
|
@ -70,7 +70,6 @@ the trace acts like an explanation; in traditional profilers you can only find
|
|||
expensive leaf functions easily but the *reason* why they are invoked
|
||||
often remains mysterious.
|
||||
|
||||
::
|
||||
total executions of each stack trace:
|
||||
Entry: 0/3391 Calls: 84/4160 = 2.0% [sum: 84; 84/4160 = 2.0%]
|
||||
newCrcFromRopeAux
|
||||
|
|
|
|||
|
|
@ -10,7 +10,7 @@ A `Source Code Filter (SCF)` transforms the input character stream to an in-mem
|
|||
output stream before parsing. A filter can be used to provide templating
|
||||
systems or preprocessors.
|
||||
|
||||
To use a filter for a source file the `#?` notation is used::
|
||||
To use a filter for a source file the `#?` notation is used:
|
||||
|
||||
#? stdtmpl(subsChar = '$', metaChar = '#')
|
||||
#proc generateXML(name, age: string): string =
|
||||
|
|
@ -50,7 +50,7 @@ In your `main.nim`:
|
|||
Pipe operator
|
||||
=============
|
||||
|
||||
Filters can be combined with the `|` pipe operator::
|
||||
Filters can be combined with the `|` pipe operator:
|
||||
|
||||
#? strip(startswith="<") | stdtmpl
|
||||
#proc generateXML(name, age: string): string =
|
||||
|
|
@ -123,7 +123,7 @@ Parameters and their defaults:
|
|||
* `toString: string = "$"`
|
||||
: the operation that is applied to each expression
|
||||
|
||||
Example::
|
||||
Example:
|
||||
|
||||
#? stdtmpl | standard
|
||||
#proc generateHTMLPage(title, currentTab, content: string,
|
||||
|
|
@ -183,7 +183,7 @@ whitespace) is converted to a string literal that is added to `result`.
|
|||
The substitution character introduces a Nim expression *e* within the
|
||||
string literal. *e* is converted to a string with the *toString* operation
|
||||
which defaults to `$`. For strong type checking, set `toString` to the
|
||||
empty string. *e* must match this PEG pattern::
|
||||
empty string. *e* must match this PEG pattern:
|
||||
|
||||
e <- [a-zA-Z\128-\255][a-zA-Z0-9\128-\255_.]* / '{' x '}'
|
||||
x <- '{' x+ '}' / [^}]*
|
||||
|
|
@ -192,7 +192,7 @@ To produce a single substitution character it has to be doubled: `$$`
|
|||
produces `$`.
|
||||
|
||||
The template engine is quite flexible. It is easy to produce a procedure that
|
||||
writes the template code directly to a file::
|
||||
writes the template code directly to a file:
|
||||
|
||||
#? stdtmpl(emit="f.write") | standard
|
||||
#proc writeHTMLPage(f: File, title, currentTab, content: string,
|
||||
|
|
|
|||
|
|
@ -36,13 +36,17 @@ Specifying the location of the query
|
|||
|
||||
All of the available idetools commands require you to specify a
|
||||
query location through the `--track` or `--trackDirty` switches.
|
||||
The general idetools invocations are::
|
||||
The general idetools invocations are:
|
||||
|
||||
```cmd
|
||||
nim idetools --track:FILE,LINE,COL <switches> proj.nim
|
||||
```
|
||||
|
||||
Or::
|
||||
Or:
|
||||
|
||||
```cmd
|
||||
nim idetools --trackDirty:DIRTY_FILE,FILE,LINE,COL <switches> proj.nim
|
||||
```
|
||||
|
||||
`proj.nim`
|
||||
: This is the main *project* filename. Most of the time you will
|
||||
|
|
@ -178,14 +182,18 @@ results of the compilation, and subsequent queries should be fast
|
|||
in the millisecond range, thus being responsive enough for IDEs.
|
||||
|
||||
If you want to start the server using stdin/stdout as communication
|
||||
you need to type::
|
||||
you need to type:
|
||||
|
||||
```cmd
|
||||
nim serve --server.type:stdin proj.nim
|
||||
```
|
||||
|
||||
If you want to start the server using tcp and a port, you need to type::
|
||||
If you want to start the server using tcp and a port, you need to type:
|
||||
|
||||
```cmd
|
||||
nim serve --server.type:tcp --server.port:6000 \
|
||||
--server.address:hostname proj.nim
|
||||
```
|
||||
|
||||
In both cases the server will start up and await further commands.
|
||||
The syntax of the commands you can now send to the server is
|
||||
|
|
@ -542,10 +550,12 @@ Running the test suite
|
|||
|
||||
At the moment idetools support is still in development so the test
|
||||
suite is not integrated with the main test suite and you have to
|
||||
run it manually. First you have to compile the tester::
|
||||
run it manually. First you have to compile the tester:
|
||||
|
||||
```cmd
|
||||
$ cd my/nim/checkout/tests
|
||||
$ nim c testament/caasdriver.nim
|
||||
```
|
||||
|
||||
Running the `caasdriver` without parameters will attempt to process
|
||||
all the test cases in all three operation modes. If a test succeeds
|
||||
|
|
@ -567,9 +577,11 @@ If you don't want to run all the test case files you can pass any
|
|||
substring as a parameter to `caasdriver`. Only files matching the
|
||||
passed substring will be run. The filtering doesn't use any globbing
|
||||
metacharacters, it's a plain match. For example, to run only
|
||||
`*-compile*.txt` tests in verbose mode::
|
||||
`*-compile*.txt` tests in verbose mode:
|
||||
|
||||
```cmd
|
||||
./caasdriver verbose -compile
|
||||
```
|
||||
|
||||
|
||||
Test case file format
|
||||
|
|
|
|||
|
|
@ -593,14 +593,14 @@ Integer literals
|
|||
In Nim, there is a redundant way to specify the type of an
|
||||
integer literal. First, it should be unsurprising that every
|
||||
node has a node kind. The node of an integer literal can be any of the
|
||||
following values::
|
||||
following values:
|
||||
|
||||
nkIntLit, nkInt8Lit, nkInt16Lit, nkInt32Lit, nkInt64Lit,
|
||||
nkUIntLit, nkUInt8Lit, nkUInt16Lit, nkUInt32Lit, nkUInt64Lit
|
||||
|
||||
On top of that, there is also the `typ` field for the type. The
|
||||
kind of the `typ` field can be one of the following ones, and it
|
||||
should be matching the literal kind::
|
||||
should be matching the literal kind:
|
||||
|
||||
tyInt, tyInt8, tyInt16, tyInt32, tyInt64, tyUInt, tyUInt8,
|
||||
tyUInt16, tyUInt32, tyUInt64
|
||||
|
|
@ -656,7 +656,6 @@ pointing back to the integer literal node in the ast containing the
|
|||
integer value. These are the properties that hold true for integer
|
||||
literal types.
|
||||
|
||||
::
|
||||
n.kind == nkIntLit
|
||||
n.typ.kind == tyInt
|
||||
n.typ.n == n
|
||||
|
|
|
|||
|
|
@ -47,14 +47,14 @@ is not ambiguous.
|
|||
|
||||
Non-terminals start with a lowercase letter, abstract terminal symbols are in
|
||||
UPPERCASE. Verbatim terminal symbols (including keywords) are quoted
|
||||
with `'`. An example::
|
||||
with `'`. An example:
|
||||
|
||||
ifStmt = 'if' expr ':' stmts ('elif' expr ':' stmts)* ('else' stmts)?
|
||||
|
||||
The binary `^*` operator is used as a shorthand for 0 or more occurrences
|
||||
separated by its second argument; likewise `^+` means 1 or more
|
||||
occurrences: `a ^+ b` is short for `a (b a)*`
|
||||
and `a ^* b` is short for `(a (b a)*)?`. Example::
|
||||
and `a ^* b` is short for `(a (b a)*)?`. Example:
|
||||
|
||||
arrayConstructor = '[' expr ^* ',' ']'
|
||||
|
||||
|
|
@ -190,7 +190,7 @@ is another pseudo terminal that describes the *action* of popping a value
|
|||
from the stack, `IND{>}` then implies to push onto the stack.
|
||||
|
||||
With this notation we can now easily define the core of the grammar: A block of
|
||||
statements (simplified example)::
|
||||
statements (simplified example):
|
||||
|
||||
ifStmt = 'if' expr ':' stmt
|
||||
(IND{=} 'elif' expr ':' stmt)*
|
||||
|
|
@ -409,7 +409,7 @@ ending of the string literal is defined by the pattern `"""[^"]`, so this:
|
|||
""""long string within quotes""""
|
||||
```
|
||||
|
||||
Produces::
|
||||
Produces:
|
||||
|
||||
"long string within quotes"
|
||||
|
||||
|
|
@ -434,7 +434,7 @@ To produce a single `"` within a raw string literal, it has to be doubled:
|
|||
r"a""b"
|
||||
```
|
||||
|
||||
Produces::
|
||||
Produces:
|
||||
|
||||
a"b
|
||||
|
||||
|
|
@ -513,7 +513,7 @@ See also [custom numeric literals].
|
|||
Numeric literals
|
||||
----------------
|
||||
|
||||
Numeric literals have the form::
|
||||
Numeric literals have the form:
|
||||
|
||||
hexdigit = digit | 'A'..'F' | 'a'..'f'
|
||||
octdigit = '0'..'7'
|
||||
|
|
@ -674,7 +674,7 @@ Operators
|
|||
---------
|
||||
|
||||
Nim allows user defined operators. An operator is any combination of the
|
||||
following characters::
|
||||
following characters:
|
||||
|
||||
= + - * / < >
|
||||
@ $ ~ & % |
|
||||
|
|
@ -698,7 +698,7 @@ as `a(not b)`, not as `(a) not (b)`.
|
|||
Unicode Operators
|
||||
-----------------
|
||||
|
||||
These Unicode operators are also parsed as operators::
|
||||
These Unicode operators are also parsed as operators:
|
||||
|
||||
∙ ∘ × ★ ⊗ ⊘ ⊙ ⊛ ⊠ ⊡ ∩ ∧ ⊓ # same priority as * (multiplication)
|
||||
± ⊕ ⊖ ⊞ ⊟ ∪ ∨ ⊔ # same priority as + (addition)
|
||||
|
|
@ -714,7 +714,7 @@ No Unicode normalization step is performed.
|
|||
Other tokens
|
||||
------------
|
||||
|
||||
The following strings denote other tokens::
|
||||
The following strings denote other tokens:
|
||||
|
||||
` ( ) { } [ ] , ; [. .] {. .} (. .) [:
|
||||
|
||||
|
|
@ -1207,9 +1207,11 @@ The boolean type is named `bool`:idx: in Nim and can be one of the two
|
|||
pre-defined values `true` and `false`. Conditions in `while`,
|
||||
`if`, `elif`, `when`-statements need to be of type `bool`.
|
||||
|
||||
This condition holds::
|
||||
This condition holds:
|
||||
|
||||
```nim
|
||||
ord(false) == 0 and ord(true) == 1
|
||||
```
|
||||
|
||||
The operators `not, and, or, xor, <, <=, >, >=, !=, ==` are defined
|
||||
for the bool type. The `and` and `or` operators perform short-cut
|
||||
|
|
@ -1248,8 +1250,9 @@ specified. The values are ordered. Example:
|
|||
```
|
||||
|
||||
|
||||
Now the following holds::
|
||||
Now the following holds:
|
||||
|
||||
```nim
|
||||
ord(north) == 0
|
||||
ord(east) == 1
|
||||
ord(south) == 2
|
||||
|
|
@ -1257,6 +1260,7 @@ Now the following holds::
|
|||
|
||||
# Also allowed:
|
||||
ord(Direction.west) == 3
|
||||
```
|
||||
|
||||
The implied order is: north < east < south < west. The comparison operators can be used
|
||||
with enumeration types. Instead of `north` etc., the enum value can also
|
||||
|
|
@ -2568,8 +2572,9 @@ literal match and that is better than a generic match etc. In the following,
|
|||
for the routine `p`.
|
||||
|
||||
A routine `p` matches better than a routine `q` if the following
|
||||
algorithm returns true::
|
||||
algorithm returns true:
|
||||
|
||||
```nim
|
||||
for each matching category m in ["exact match", "literal match",
|
||||
"generic match", "subtype match",
|
||||
"integral match", "conversion match"]:
|
||||
|
|
@ -2579,6 +2584,7 @@ algorithm returns true::
|
|||
else:
|
||||
return false
|
||||
return "ambiguous"
|
||||
```
|
||||
|
||||
|
||||
Some examples:
|
||||
|
|
@ -4061,7 +4067,7 @@ Nonoverloadable builtins
|
|||
------------------------
|
||||
|
||||
The following built-in procs cannot be overloaded for reasons of implementation
|
||||
simplicity (they require specialized semantic checking)::
|
||||
simplicity (they require specialized semantic checking):
|
||||
|
||||
declared, defined, definedInScope, compiles, sizeof,
|
||||
is, shallowCopy, getAst, astToStr, spawn, procCall
|
||||
|
|
@ -4071,7 +4077,7 @@ keyword however, a redefinition may `shadow`:idx: the definition in
|
|||
the [system](system.html) 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
|
||||
to `f`::
|
||||
to `f`:
|
||||
|
||||
declared, defined, definedInScope, compiles, getAst, astToStr
|
||||
|
||||
|
|
@ -8291,7 +8297,7 @@ The `dynlib` import mechanism supports a versioning scheme:
|
|||
importc, dynlib: "libtcl(|8.5|8.4|8.3).so.(1|0)".}
|
||||
```
|
||||
|
||||
At runtime, the dynamic library is searched for (in this order)::
|
||||
At runtime, the dynamic library is searched for (in this order):
|
||||
|
||||
libtcl.so.1
|
||||
libtcl.so.0
|
||||
|
|
|
|||
|
|
@ -790,7 +790,7 @@ be part of a single graph.
|
|||
Assignments like `a = b` "connect" two variables, both variables end up in the
|
||||
same graph `{a, b} = G(a) = G(b)`. Unfortunately, the pattern to look for is
|
||||
much more complex than that and can involve multiple assignment targets
|
||||
and sources::
|
||||
and sources:
|
||||
|
||||
f(x, y) = g(a, b)
|
||||
|
||||
|
|
@ -1586,7 +1586,7 @@ all the arguments, but also the matched operators in reverse polish notation:
|
|||
```
|
||||
|
||||
This passes the expression `x + y * z - x` to the `optM` macro as
|
||||
an `nnkArgList` node containing::
|
||||
an `nnkArgList` node containing:
|
||||
|
||||
Arglist
|
||||
Sym "x"
|
||||
|
|
|
|||
|
|
@ -22,7 +22,8 @@ Usage (to convert Markdown into HTML):
|
|||
nim md2html markdown_rst.md
|
||||
```
|
||||
|
||||
Output::
|
||||
Output:
|
||||
|
||||
You're reading it!
|
||||
|
||||
The `md2tex`:option: command is invoked identically to `md2html`:option:,
|
||||
|
|
@ -132,7 +133,7 @@ Additional Nim-specific features
|
|||
* ``:idx:`` role for \`interpreted text\` to include the link to this
|
||||
text into an index (example: [Nim index]).
|
||||
* double slash `//` in option lists serves as a prefix for any option that
|
||||
starts from a word (without any leading symbols like `-`, `--`, `/`)::
|
||||
starts from a word (without any leading symbols like `-`, `--`, `/`):
|
||||
|
||||
//compile compile the project
|
||||
//doc generate documentation
|
||||
|
|
@ -152,7 +153,7 @@ Optional additional features, by default turned on:
|
|||
* Markdown tables
|
||||
* Markdown code blocks. For them the same additional arguments as for RST
|
||||
code blocks can be provided (e.g. `test` or `number-lines`) but with
|
||||
a one-line syntax like this::
|
||||
a one-line syntax like this:
|
||||
|
||||
```nim test number-lines=10
|
||||
echo "ok"
|
||||
|
|
@ -189,7 +190,7 @@ This parser has 2 modes for inline markup:
|
|||
does escape so that we can always input a single backtick ` in
|
||||
inline code. However that makes impossible to input code with
|
||||
``\`` at the end in *single* backticks, one must use *double*
|
||||
backticks::
|
||||
backticks:
|
||||
|
||||
`\` -- WRONG
|
||||
``\`` -- GOOD
|
||||
|
|
@ -204,8 +205,6 @@ This parser has 2 modes for inline markup:
|
|||
- interpretation of Markdown block quotes is also slightly different,
|
||||
e.g. case
|
||||
|
||||
::
|
||||
|
||||
>>> foo
|
||||
> bar
|
||||
>>baz
|
||||
|
|
|
|||
|
|
@ -241,7 +241,7 @@ found an ambiguity error is produced.
|
|||
|
||||
However before the PATH is used the current directory is checked for the
|
||||
file's existence. So if PATH contains ``$lib`` and ``$lib/bar`` and the
|
||||
directory structure looks like this::
|
||||
directory structure looks like this:
|
||||
|
||||
$lib/x.nim
|
||||
$lib/bar/x.nim
|
||||
|
|
@ -319,7 +319,7 @@ Another way is to make Nim invoke a cross compiler toolchain:
|
|||
For cross compilation, the compiler invokes a C compiler named
|
||||
like `$cpu.$os.$cc` (for example arm.linux.gcc) and the configuration
|
||||
system is used to provide meaningful defaults. For example for `ARM` your
|
||||
configuration file should contain something like::
|
||||
configuration file should contain something like:
|
||||
|
||||
arm.linux.gcc.path = "/usr/bin"
|
||||
arm.linux.gcc.exe = "arm-linux-gcc"
|
||||
|
|
@ -435,7 +435,7 @@ and `passL`:option: command line switches to something like:
|
|||
--passL="-specs=$DEVKITPRO/libnx/switch.specs -L$DEVKITPRO/libnx/lib -lnx"
|
||||
```
|
||||
|
||||
or setup a ``nim.cfg`` file like so::
|
||||
or setup a ``nim.cfg`` file like so:
|
||||
|
||||
#nim.cfg
|
||||
--mm:orc
|
||||
|
|
|
|||
|
|
@ -28,21 +28,28 @@ system by this day and age, your project is already in big trouble.
|
|||
Installation
|
||||
------------
|
||||
|
||||
Nimfix is part of the compiler distribution. Compile via::
|
||||
Nimfix is part of the compiler distribution. Compile via:
|
||||
|
||||
```cmd
|
||||
nim c compiler/nimfix/nimfix.nim
|
||||
mv compiler/nimfix/nimfix bin
|
||||
```
|
||||
|
||||
Or on windows::
|
||||
Or on windows:
|
||||
|
||||
```cmd
|
||||
nim c compiler\nimfix\nimfix.nim
|
||||
move compiler\nimfix\nimfix.exe bin
|
||||
```
|
||||
|
||||
Usage
|
||||
-----
|
||||
|
||||
Usage:
|
||||
|
||||
```cmd
|
||||
nimfix [options] projectfile.nim
|
||||
```
|
||||
|
||||
Options:
|
||||
|
||||
|
|
|
|||
|
|
@ -1,11 +1,16 @@
|
|||
|
||||
Usage:
|
||||
|
||||
* To search::
|
||||
* To search:
|
||||
|
||||
nimgrep [options] PATTERN [(FILE/DIRECTORY)*/-]
|
||||
* To replace::
|
||||
|
||||
* To replace:
|
||||
|
||||
nimgrep [options] PATTERN --replace REPLACEMENT (FILE/DIRECTORY)*/-
|
||||
* To list file names::
|
||||
|
||||
* To list file names:
|
||||
|
||||
nimgrep [options] --filenames [PATTERN] [(FILE/DIRECTORY)*]
|
||||
|
||||
Positional arguments, from left to right:
|
||||
|
|
@ -42,7 +47,8 @@ Options:
|
|||
to abort any time without touching the file
|
||||
--filenames just list filenames. Provide a PATTERN to find it in
|
||||
the filenames (not in the contents of a file) or run
|
||||
with empty pattern to just list all files::
|
||||
with empty pattern to just list all files:
|
||||
|
||||
nimgrep --filenames # In current dir
|
||||
nimgrep --filenames "" DIRECTORY
|
||||
# Note empty pattern "", lists all files in DIRECTORY
|
||||
|
|
|
|||
|
|
@ -72,7 +72,7 @@ Key description
|
|||
Many sections support the `files` key. Listed filenames
|
||||
can be separated by semicolon or the `files` key can be repeated. Wildcards
|
||||
in filenames are supported. If it is a directory name, all files in the
|
||||
directory are used::
|
||||
directory are used:
|
||||
|
||||
[Config]
|
||||
Files: "configDir"
|
||||
|
|
|
|||
|
|
@ -131,7 +131,7 @@ notation meaning
|
|||
Supported PEG grammar
|
||||
---------------------
|
||||
|
||||
The PEG parser implements this grammar (written in PEG syntax)::
|
||||
The PEG parser implements this grammar (written in PEG syntax):
|
||||
|
||||
# Example grammar of PEG in PEG syntax.
|
||||
# Comments start with '#'.
|
||||
|
|
|
|||
|
|
@ -56,7 +56,7 @@ backslashes are interpreted by the regular expression engine:
|
|||
A regular expression is a pattern that is matched against a subject string
|
||||
from left to right. Most characters stand for themselves in a pattern, and
|
||||
match the corresponding characters in the subject. As a trivial example,
|
||||
the pattern::
|
||||
the pattern:
|
||||
|
||||
The quick brown fox
|
||||
|
||||
|
|
@ -130,7 +130,7 @@ in patterns in a visible manner. There is no restriction on the appearance of
|
|||
non-printing characters, apart from the binary zero that terminates a pattern,
|
||||
but when a pattern is being prepared by text editing, it is usually easier to
|
||||
use one of the following escape sequences than the binary character it
|
||||
represents::
|
||||
represents:
|
||||
|
||||
============== ============================================================
|
||||
character meaning
|
||||
|
|
@ -246,7 +246,7 @@ The fourth use of backslash is for certain `simple assertions`:idx:. An
|
|||
assertion specifies a condition that has to be met at a particular point in
|
||||
a match, without consuming any characters from the subject string. The use of
|
||||
subpatterns for more complicated assertions is described below. The
|
||||
backslashed assertions are::
|
||||
backslashed assertions are:
|
||||
|
||||
============== ============================================================
|
||||
assertion meaning
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
..
|
||||
Usage of this file:
|
||||
Add this in the beginning of *.rst file::
|
||||
Add this in the beginning of *.rst file:
|
||||
|
||||
.. default-role:: code
|
||||
.. include:: rstcommon.rst
|
||||
|
|
|
|||
20
doc/tut1.md
20
doc/tut1.md
|
|
@ -45,24 +45,28 @@ We start the tour with a modified "hello world" program:
|
|||
```
|
||||
|
||||
|
||||
Save this code to the file "greetings.nim". Now compile and run it::
|
||||
|
||||
Save this code to the file "greetings.nim". Now compile and run it:
|
||||
```cmd
|
||||
nim compile --run greetings.nim
|
||||
```
|
||||
|
||||
With the ``--run`` [switch](nimc.html#compiler-usage-commandminusline-switches) Nim
|
||||
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:
|
||||
```cmd
|
||||
nim compile --run greetings.nim arg1 arg2
|
||||
```
|
||||
|
||||
Commonly used commands and switches have abbreviations, so you can also use::
|
||||
|
||||
Commonly used commands and switches have abbreviations, so you can also use:
|
||||
```cmd
|
||||
nim c -r greetings.nim
|
||||
```
|
||||
|
||||
This is a **debug version**.
|
||||
To compile a release version use::
|
||||
|
||||
To compile a release version use:
|
||||
```cmd
|
||||
nim c -d:release greetings.nim
|
||||
```
|
||||
|
||||
By default, the Nim compiler generates a large number of runtime checks
|
||||
aiming for your debugging pleasure. With ``-d:release`` some checks are
|
||||
|
|
|
|||
|
|
@ -75,7 +75,7 @@ proc toLangSymbol*(linkText: PRstNode): LangSymbol =
|
|||
## Parses `linkText` into a more structured form using a state machine.
|
||||
##
|
||||
## This proc is designed to allow link syntax with operators even
|
||||
## without escaped backticks inside::
|
||||
## without escaped backticks inside:
|
||||
##
|
||||
## `proc *`_
|
||||
## `proc []`_
|
||||
|
|
|
|||
|
|
@ -2172,7 +2172,7 @@ proc whichSection(p: RstParser): RstNodeKind =
|
|||
# for punctuation sequences that can be both tkAdornment and tkPunct
|
||||
if isMarkdownCodeBlock(p):
|
||||
return rnCodeBlock
|
||||
elif currentTok(p).symbol == "::":
|
||||
elif isRst(p) and currentTok(p).symbol == "::":
|
||||
return rnLiteralBlock
|
||||
elif currentTok(p).symbol == ".." and
|
||||
nextTok(p).kind in {tkWhite, tkIndent}:
|
||||
|
|
@ -2362,8 +2362,10 @@ proc parseParagraph(p: var RstParser, result: PRstNode) =
|
|||
of tkIndent:
|
||||
if nextTok(p).kind == tkIndent:
|
||||
inc p.idx
|
||||
break
|
||||
elif currentTok(p).ival == currInd(p):
|
||||
break # blank line breaks paragraph for both Md & Rst
|
||||
elif currentTok(p).ival == currInd(p) or (
|
||||
isMd(p) and currentTok(p).ival > currInd(p)):
|
||||
# (Md allows adding additional indentation inside paragraphs)
|
||||
inc p.idx
|
||||
case whichSection(p)
|
||||
of rnParagraph, rnLeaf, rnHeadline, rnMarkdownHeadline,
|
||||
|
|
@ -2377,7 +2379,8 @@ proc parseParagraph(p: var RstParser, result: PRstNode) =
|
|||
else:
|
||||
break
|
||||
of tkPunct:
|
||||
if (let literalBlockKind = whichRstLiteralBlock(p);
|
||||
if isRst(p) and (
|
||||
let literalBlockKind = whichRstLiteralBlock(p);
|
||||
literalBlockKind != lbNone):
|
||||
result.add newLeaf(":")
|
||||
inc p.idx # skip '::'
|
||||
|
|
@ -2932,8 +2935,8 @@ proc parseSection(p: var RstParser, result: PRstNode) =
|
|||
elif currentTok(p).ival > currInd(p):
|
||||
if roPreferMarkdown in p.s.options: # Markdown => normal paragraphs
|
||||
if currentTok(p).ival - currInd(p) >= 4:
|
||||
rstMessage(p, mwRstStyle,
|
||||
"Markdown indented code not implemented")
|
||||
result.add parseLiteralBlock(p)
|
||||
else:
|
||||
pushInd(p, currentTok(p).ival)
|
||||
parseSection(p, result)
|
||||
popInd(p)
|
||||
|
|
|
|||
|
|
@ -377,7 +377,7 @@ proc renderRstToJsonNode(node: PRstNode): JsonNode =
|
|||
|
||||
proc renderRstToJson*(node: PRstNode): string =
|
||||
## Writes the given RST node as JSON that is in the form
|
||||
## ::
|
||||
##
|
||||
## {
|
||||
## "kind":string node.kind,
|
||||
## "text":optional string node.text,
|
||||
|
|
|
|||
|
|
@ -57,9 +57,10 @@ proc memoryLock*(a1: pointer, a2: int) =
|
|||
proc memoryLockAll*(flags: int) =
|
||||
## Locks all memory for the running process to prevent swapping.
|
||||
##
|
||||
## example::
|
||||
##
|
||||
## example:
|
||||
## ```nim
|
||||
## memoryLockAll(MCL_CURRENT or MCL_FUTURE)
|
||||
## ```
|
||||
if mlockall(flags.cint) != 0:
|
||||
raise newException(OSError, $strerror(errno))
|
||||
|
||||
|
|
|
|||
|
|
@ -9,7 +9,7 @@
|
|||
|
||||
## This module implements the basics for Linux distribution ("distro")
|
||||
## detection and the OS's native package manager. Its primary purpose is to
|
||||
## produce output for Nimble packages, like::
|
||||
## produce output for Nimble packages, like:
|
||||
##
|
||||
## To complete the installation, run:
|
||||
##
|
||||
|
|
|
|||
|
|
@ -34,7 +34,7 @@
|
|||
## var nim = "Nim"
|
||||
## echo h1(a(href="https://nim-lang.org", nim))
|
||||
##
|
||||
## Writes the string::
|
||||
## Writes the string:
|
||||
##
|
||||
## <h1><a href="https://nim-lang.org">Nim</a></h1>
|
||||
##
|
||||
|
|
|
|||
|
|
@ -2294,7 +2294,8 @@ iterator walkDir*(dir: string; relative = false, checkDir = false):
|
|||
##
|
||||
## **Example:**
|
||||
##
|
||||
## This directory structure::
|
||||
## This directory structure:
|
||||
##
|
||||
## dirA / dirB / fileB1.txt
|
||||
## / dirC
|
||||
## / fileA1.txt
|
||||
|
|
|
|||
|
|
@ -2058,7 +2058,7 @@ func parsePeg*(pattern: string, filename = "pattern", line = 1, col = 0): Peg =
|
|||
|
||||
func peg*(pattern: string): Peg =
|
||||
## constructs a Peg object from the `pattern`. The short name has been
|
||||
## chosen to encourage its use as a raw string modifier::
|
||||
## chosen to encourage its use as a raw string modifier:
|
||||
##
|
||||
## peg"{\ident} \s* '=' \s* {.*}"
|
||||
result = parsePeg(pattern, "pattern")
|
||||
|
|
|
|||
|
|
@ -171,7 +171,7 @@ For strings and numeric types the optional argument is a so-called
|
|||
|
||||
# Standard format specifiers for strings, integers and floats
|
||||
|
||||
The general form of a standard format specifier is::
|
||||
The general form of a standard format specifier is:
|
||||
|
||||
[[fill]align][sign][#][0][minimumwidth][.precision][type]
|
||||
|
||||
|
|
@ -423,7 +423,7 @@ proc formatInt(n: SomeNumber; radix: int; spec: StandardFormatSpecifier): string
|
|||
proc parseStandardFormatSpecifier*(s: string; start = 0;
|
||||
ignoreUnknownSuffix = false): StandardFormatSpecifier =
|
||||
## An exported helper proc that parses the "standard format specifiers",
|
||||
## as specified by the grammar::
|
||||
## as specified by the grammar:
|
||||
##
|
||||
## [[fill]align][sign][#][0][minimumwidth][.precision][type]
|
||||
##
|
||||
|
|
|
|||
|
|
@ -778,7 +778,7 @@ macro `<>`*(x: untyped): untyped =
|
|||
## .. code-block:: nim
|
||||
## <>a(href="http://nim-lang.org", newText("Nim rules."))
|
||||
##
|
||||
## Produces an XML tree for::
|
||||
## Produces an XML tree for:
|
||||
##
|
||||
## <a href="http://nim-lang.org">Nim rules.</a>
|
||||
##
|
||||
|
|
|
|||
|
|
@ -91,7 +91,8 @@
|
|||
## Sample output
|
||||
## -------------
|
||||
## The program should output something similar to this, but keep in mind that
|
||||
## exact results may vary in the real world::
|
||||
## exact results may vary in the real world:
|
||||
##
|
||||
## Hello World!
|
||||
## Pretend I'm doing useful work...
|
||||
## Pretend I'm doing useful work...
|
||||
|
|
|
|||
|
|
@ -7,6 +7,8 @@ discard """
|
|||
|
||||
[Suite] RST indentation
|
||||
|
||||
[Suite] Markdown indentation
|
||||
|
||||
[Suite] Warnings
|
||||
|
||||
[Suite] RST include directive
|
||||
|
|
@ -124,12 +126,12 @@ suite "RST parsing":
|
|||
check(dedent"""
|
||||
Paragraph::
|
||||
|
||||
>x""".toAst == expected)
|
||||
>x""".toAst(rstOptions = preferRst) == expected)
|
||||
|
||||
check(dedent"""
|
||||
Paragraph::
|
||||
|
||||
>x""".toAst == expected)
|
||||
>x""".toAst(rstOptions = preferRst) == expected)
|
||||
|
||||
test "RST quoted literal blocks, :: at a separate line":
|
||||
let expected =
|
||||
|
|
@ -148,7 +150,7 @@ suite "RST parsing":
|
|||
::
|
||||
|
||||
>x
|
||||
>>y""".toAst == expected)
|
||||
>>y""".toAst(rstOptions = preferRst) == expected)
|
||||
|
||||
check(dedent"""
|
||||
Paragraph
|
||||
|
|
@ -156,7 +158,7 @@ suite "RST parsing":
|
|||
::
|
||||
|
||||
>x
|
||||
>>y""".toAst == expected)
|
||||
>>y""".toAst(rstOptions = preferRst) == expected)
|
||||
|
||||
test "Markdown quoted blocks":
|
||||
check(dedent"""
|
||||
|
|
@ -779,7 +781,7 @@ suite "RST parsing":
|
|||
|
||||
code
|
||||
|
||||
""".toAst ==
|
||||
""".toAst(rstOptions = preferRst) ==
|
||||
dedent"""
|
||||
rnInner
|
||||
rnLeaf 'Check'
|
||||
|
|
@ -788,6 +790,32 @@ suite "RST parsing":
|
|||
rnLeaf 'code'
|
||||
""")
|
||||
|
||||
test "Markdown indented code blocks":
|
||||
check(dedent"""
|
||||
See
|
||||
|
||||
some code""".toAst ==
|
||||
dedent"""
|
||||
rnInner
|
||||
rnInner
|
||||
rnLeaf 'See'
|
||||
rnLiteralBlock
|
||||
rnLeaf 'some code'
|
||||
""")
|
||||
|
||||
# not a code block -- no blank line before:
|
||||
check(dedent"""
|
||||
See
|
||||
some code""".toAst ==
|
||||
dedent"""
|
||||
rnInner
|
||||
rnLeaf 'See'
|
||||
rnLeaf ' '
|
||||
rnLeaf 'some'
|
||||
rnLeaf ' '
|
||||
rnLeaf 'code'
|
||||
""")
|
||||
|
||||
suite "RST tables":
|
||||
|
||||
test "formatting in tables works":
|
||||
|
|
@ -1238,6 +1266,31 @@ suite "RST indentation":
|
|||
rnLeaf 'term3definition2'
|
||||
""")
|
||||
|
||||
suite "Markdown indentation":
|
||||
test "Markdown paragraph indentation":
|
||||
# Additional spaces (<=3) of indentation does not break the paragraph.
|
||||
# TODO: in 2nd case de-indentation causes paragraph to break, this is
|
||||
# reasonable but does not seem to conform the Markdown spec.
|
||||
check(dedent"""
|
||||
Start1
|
||||
stop1
|
||||
|
||||
Start2
|
||||
stop2
|
||||
""".toAst ==
|
||||
dedent"""
|
||||
rnInner
|
||||
rnParagraph
|
||||
rnLeaf 'Start1'
|
||||
rnLeaf ' '
|
||||
rnLeaf 'stop1'
|
||||
rnParagraph
|
||||
rnLeaf 'Start2'
|
||||
rnParagraph
|
||||
rnLeaf 'stop2'
|
||||
rnLeaf ' '
|
||||
""")
|
||||
|
||||
suite "Warnings":
|
||||
test "warnings for broken footnotes/links/substitutions":
|
||||
let input = dedent"""
|
||||
|
|
|
|||
|
|
@ -632,7 +632,7 @@ Test literal block
|
|||
::
|
||||
|
||||
check """
|
||||
let output1 = input1.toHtml
|
||||
let output1 = input1.toHtml(preferRst)
|
||||
doAssert "<pre>" in output1
|
||||
|
||||
test "Markdown code block":
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue