Implement Pandoc Markdown concise link extension (#20304)
* Implement Pandoc Markdown concise link extension This implements https://github.com/nim-lang/Nim/issues/20127. Besides reference to headings we also support doing references to Nim symbols inside Nim modules. Markdown: ``` Some heading ------------ Ref. [Some heading]. ``` Nim: ``` proc someFunction*() ... ... ## Ref. [someFunction] ``` This is substitution for RST syntax like `` `target`_ ``. All 3 syntax variants of extension from Pandoc Markdown are supported: `[target]`, `[target][]`, `[description][target]`. This PR also fixes clashes in existing files, particularly conflicts with RST footnote feature, which does not work with this PR (but there is a plan to adopt a popular [Markdown footnote extension](https://pandoc.org/MANUAL.html#footnotes) to make footnotes work). Also the PR fixes a bug that Markdown links did not work when `[...]` section had a line break. The implementation is straightforward since link resolution did not change w.r.t. RST implementation, it's almost only about new syntax addition. The only essential difference is a possibility to add a custom link description: form `[description][target]` which does not have an RST equivalent. * fix nim 1.0 gotcha
This commit is contained in:
Andrey Makarov
GitHub
parent
b931e74a59
commit
cde6b2aab8
23 changed files with 325 additions and 152 deletions
|
|
@ -4,7 +4,7 @@
|
|||
|
||||
Command:
|
||||
//compile, c compile project with default code generator (C)
|
||||
//r compile to $nimcache/projname, run with [arguments]
|
||||
//r compile to $nimcache/projname, run with `arguments`
|
||||
using backend specified by `--backend` (default: c)
|
||||
//doc generate the documentation for inputfile for
|
||||
backend specified by `--backend` (default: c)
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
@ -345,7 +345,7 @@ To avoid accidental highlighting follow this rule in ``*.nim`` files:
|
|||
The first 2 lines are for other RST implementations,
|
||||
including Github one.
|
||||
|
||||
.. [*] this is fulfilled when ``doc/rstcommon.rst`` is included.
|
||||
\[*] this is fulfilled when ``doc/rstcommon.rst`` is included.
|
||||
|
||||
Best practices
|
||||
==============
|
||||
|
|
@ -431,7 +431,7 @@ including prepending location info, writing to log files, etc.).
|
|||
```
|
||||
|
||||
.. _use_Option:
|
||||
[Ongoing debate] Consider using Option instead of return bool + var argument,
|
||||
(Ongoing debate) Consider using Option instead of return bool + var argument,
|
||||
unless stack allocation is needed (e.g. for efficiency).
|
||||
|
||||
```nim
|
||||
|
|
|
|||
|
|
@ -245,9 +245,9 @@ underscore `_` to a *link text*.
|
|||
Link text is either one word or a group of words enclosed by backticks `\``
|
||||
(for a one word case backticks are usually omitted).
|
||||
Link text will be displayed *as is* while *link target* will be set to
|
||||
the anchor [*]_ of Nim symbol that corresponds to link text.
|
||||
the anchor \[*] of Nim symbol that corresponds to link text.
|
||||
|
||||
.. [*] anchors' format is described in `HTML anchor generation`_ section below.
|
||||
[*] anchors' format is described in `HTML anchor generation`_ section below.
|
||||
|
||||
If you have a constant:
|
||||
|
||||
|
|
|
|||
|
|
@ -239,7 +239,7 @@ symbol for which idetools returns valid output.
|
|||
skConst
|
||||
-------
|
||||
|
||||
| **Third column**: module + [n scope nesting] + const name.
|
||||
| **Third column**: module + \[n scope nesting] + const name.
|
||||
| **Fourth column**: the type of the const value.
|
||||
| **Docstring**: always the empty string.
|
||||
|
||||
|
|
@ -254,7 +254,7 @@ skConst
|
|||
skEnumField
|
||||
-----------
|
||||
|
||||
| **Third column**: module + [n scope nesting] + enum type + enum field name.
|
||||
| **Third column**: module + \[n scope nesting] + enum type + enum field name.
|
||||
| **Fourth column**: enum type grouping other enum fields.
|
||||
| **Docstring**: always the empty string.
|
||||
|
||||
|
|
@ -269,7 +269,7 @@ skEnumField
|
|||
skForVar
|
||||
--------
|
||||
|
||||
| **Third column**: module + [n scope nesting] + var name.
|
||||
| **Third column**: module + \[n scope nesting] + var name.
|
||||
| **Fourth column**: type of the var.
|
||||
| **Docstring**: always the empty string.
|
||||
|
||||
|
|
@ -291,7 +291,7 @@ defined, since at that point in the file the parser hasn't processed
|
|||
the full line yet. The signature will be returned complete in
|
||||
posterior instances of the iterator.
|
||||
|
||||
| **Third column**: module + [n scope nesting] + iterator name.
|
||||
| **Third column**: module + \[n scope nesting] + iterator name.
|
||||
| **Fourth column**: signature of the iterator including return type.
|
||||
| **Docstring**: docstring if available.
|
||||
|
||||
|
|
@ -308,7 +308,7 @@ posterior instances of the iterator.
|
|||
skLabel
|
||||
-------
|
||||
|
||||
| **Third column**: module + [n scope nesting] + name.
|
||||
| **Third column**: module + \[n scope nesting] + name.
|
||||
| **Fourth column**: always the empty string.
|
||||
| **Docstring**: always the empty string.
|
||||
|
||||
|
|
@ -325,7 +325,7 @@ skLabel
|
|||
skLet
|
||||
-----
|
||||
|
||||
| **Third column**: module + [n scope nesting] + let name.
|
||||
| **Third column**: module + \[n scope nesting] + let name.
|
||||
| **Fourth column**: the type of the let variable.
|
||||
| **Docstring**: always the empty string.
|
||||
|
||||
|
|
@ -346,7 +346,7 @@ defined, since at that point in the file the parser hasn't processed
|
|||
the full line yet. The signature will be returned complete in
|
||||
posterior instances of the macro.
|
||||
|
||||
| **Third column**: module + [n scope nesting] + macro name.
|
||||
| **Third column**: module + \[n scope nesting] + macro name.
|
||||
| **Fourth column**: signature of the macro including return type.
|
||||
| **Docstring**: docstring if available.
|
||||
|
||||
|
|
@ -384,7 +384,7 @@ Note that at the moment the word `proc` is returned for the
|
|||
signature of the found method instead of the expected `method`.
|
||||
This may change in the future.
|
||||
|
||||
| **Third column**: module + [n scope nesting] + method name.
|
||||
| **Third column**: module + \[n scope nesting] + method name.
|
||||
| **Fourth column**: signature of the method including return type.
|
||||
| **Docstring**: docstring if available.
|
||||
|
||||
|
|
@ -402,7 +402,7 @@ This may change in the future.
|
|||
skParam
|
||||
-------
|
||||
|
||||
| **Third column**: module + [n scope nesting] + param name.
|
||||
| **Third column**: module + \[n scope nesting] + param name.
|
||||
| **Fourth column**: the type of the parameter.
|
||||
| **Docstring**: always the empty string.
|
||||
|
||||
|
|
@ -427,7 +427,7 @@ While at the language level a proc is differentiated from others
|
|||
by the parameters and return value, the signature of the proc
|
||||
returned by idetools returns also the pragmas for the proc.
|
||||
|
||||
| **Third column**: module + [n scope nesting] + proc name.
|
||||
| **Third column**: module + \[n scope nesting] + proc name.
|
||||
| **Fourth column**: signature of the proc including return type.
|
||||
| **Docstring**: docstring if available.
|
||||
|
||||
|
|
@ -446,7 +446,7 @@ returned by idetools returns also the pragmas for the proc.
|
|||
skResult
|
||||
--------
|
||||
|
||||
| **Third column**: module + [n scope nesting] + result.
|
||||
| **Third column**: module + \[n scope nesting] + result.
|
||||
| **Fourth column**: the type of the result.
|
||||
| **Docstring**: always the empty string.
|
||||
|
||||
|
|
@ -467,7 +467,7 @@ defined, since at that point in the file the parser hasn't processed
|
|||
the full line yet. The signature will be returned complete in
|
||||
posterior instances of the template.
|
||||
|
||||
| **Third column**: module + [n scope nesting] + template name.
|
||||
| **Third column**: module + \[n scope nesting] + template name.
|
||||
| **Fourth column**: signature of the template including return type.
|
||||
| **Docstring**: docstring if available.
|
||||
|
||||
|
|
@ -496,7 +496,7 @@ posterior instances of the template.
|
|||
skType
|
||||
------
|
||||
|
||||
| **Third column**: module + [n scope nesting] + type name.
|
||||
| **Third column**: module + \[n scope nesting] + type name.
|
||||
| **Fourth column**: the type.
|
||||
| **Docstring**: always the empty string.
|
||||
|
||||
|
|
@ -512,7 +512,7 @@ skType
|
|||
skVar
|
||||
-----
|
||||
|
||||
| **Third column**: module + [n scope nesting] + var name.
|
||||
| **Third column**: module + \[n scope nesting] + var name.
|
||||
| **Fourth column**: the type of the var.
|
||||
| **Docstring**: always the empty string.
|
||||
|
||||
|
|
|
|||
|
|
@ -328,7 +328,7 @@ Coding Guidelines
|
|||
* Max line length is 100 characters.
|
||||
* Provide spaces around binary operators if that enhances readability.
|
||||
* Use a space after a colon, but not before it.
|
||||
* [deprecated] Start types with a capital `T`, unless they are
|
||||
* (deprecated) Start types with a capital `T`, unless they are
|
||||
pointers/references which start with `P`.
|
||||
* Prefer `import package`:nim: over `from package import symbol`:nim:.
|
||||
|
||||
|
|
|
|||
|
|
@ -2862,11 +2862,11 @@ ref or pointer type nil
|
|||
procedural type nil
|
||||
sequence `@[]`
|
||||
string `""`
|
||||
tuple[x: A, y: B, ...] (default(A), default(B), ...)
|
||||
`tuple[x: A, y: B, ...]` (default(A), default(B), ...)
|
||||
(analogous for objects)
|
||||
array[0..., T] [default(T), ...]
|
||||
range[T] default(T); this may be out of the valid range
|
||||
T = enum cast[T]\(0); this may be an invalid value
|
||||
`array[0..., T]` `[default(T), ...]`
|
||||
`range[T]` default(T); this may be out of the valid range
|
||||
T = enum `cast[T](0)`; this may be an invalid value
|
||||
============================ ==============================================
|
||||
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue