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 2022-10-05 21:03:10 +03:00 • committed by GitHub
commit 6505bd347d
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
33 changed files with 697 additions and 603 deletions

View file

@ -10,15 +10,15 @@ 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 =
# result = ""
<xml>
<name>$name</name>
<age>$age</age>
</xml>
#? stdtmpl(subsChar = '$', metaChar = '#')
#proc generateXML(name, age: string): string =
# result = ""
<xml>
<name>$name</name>
<age>$age</age>
</xml>
As the example shows, passing arguments to a filter can be done
just like an ordinary procedure call with named or positional arguments. The
@ -50,15 +50,15 @@ 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 =
# result = ""
<xml>
<name>$name</name>
<age>$age</age>
</xml>
#? strip(startswith="<") | stdtmpl
#proc generateXML(name, age: string): string =
# result = ""
<xml>
<name>$name</name>
<age>$age</age>
</xml>
Available filters
@ -123,31 +123,31 @@ Parameters and their defaults:
* `toString: string = "$"`
: the operation that is applied to each expression
Example::
Example:
#? stdtmpl | standard
#proc generateHTMLPage(title, currentTab, content: string,
# tabs: openArray[string]): string =
# result = ""
<head><title>$title</title></head>
<body>
<div id="menu">
<ul>
#for tab in items(tabs):
#if currentTab == tab:
<li><a id="selected"
#else:
<li><a
#end if
href="${tab}.html">$tab</a></li>
#end for
</ul>
</div>
<div id="content">
$content
A dollar: $$.
</div>
</body>
#? stdtmpl | standard
#proc generateHTMLPage(title, currentTab, content: string,
# tabs: openArray[string]): string =
# result = ""
<head><title>$title</title></head>
<body>
<div id="menu">
<ul>
#for tab in items(tabs):
#if currentTab == tab:
<li><a id="selected"
#else:
<li><a
#end if
href="${tab}.html">$tab</a></li>
#end for
</ul>
</div>
<div id="content">
$content
A dollar: $$.
</div>
</body>
The filter transforms this into:
@ -183,36 +183,36 @@ 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+ '}' / [^}]*
e <- [a-zA-Z\128-\255][a-zA-Z0-9\128-\255_.]* / '{' x '}'
x <- '{' x+ '}' / [^}]*
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,
# tabs: openArray[string]) =
<head><title>$title</title></head>
<body>
<div id="menu">
<ul>
#for tab in items(tabs):
#if currentTab == tab:
<li><a id="selected"
#else:
<li><a
#end if
href="${tab}.html" title = "$title - $tab">$tab</a></li>
#end for
</ul>
</div>
<div id="content">
$content
A dollar: $$.
</div>
</body>
#? stdtmpl(emit="f.write") | standard
#proc writeHTMLPage(f: File, title, currentTab, content: string,
# tabs: openArray[string]) =
<head><title>$title</title></head>
<body>
<div id="menu">
<ul>
#for tab in items(tabs):
#if currentTab == tab:
<li><a id="selected"
#else:
<li><a
#end if
href="${tab}.html" title = "$title - $tab">$tab</a></li>
#end for
</ul>
</div>
<div id="content">
$content
A dollar: $$.
</div>
</body>