Skip to content

Commit

Permalink
Implement Pandoc Markdown concise link extension
Browse files Browse the repository at this point in the history
This implements nim-lang#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.
  • Loading branch information
a-mr committed Sep 4, 2022
1 parent b931e74 commit 1bdb83c
Show file tree
Hide file tree
Showing 23 changed files with 318 additions and 144 deletions.
2 changes: 1 addition & 1 deletion doc/basicopt.txt
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
6 changes: 3 additions & 3 deletions doc/contributing.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
==============
Expand Down Expand Up @@ -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
Expand Down
4 changes: 2 additions & 2 deletions doc/docgen.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand Down
28 changes: 14 additions & 14 deletions doc/idetools.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand All @@ -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.

Expand All @@ -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.

Expand All @@ -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.

Expand All @@ -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.

Expand All @@ -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.

Expand All @@ -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.

Expand Down Expand Up @@ -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.

Expand All @@ -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.

Expand All @@ -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.

Expand All @@ -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.

Expand All @@ -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.

Expand Down Expand Up @@ -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.

Expand All @@ -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.

Expand Down
2 changes: 1 addition & 1 deletion doc/intern.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:.

Expand Down
8 changes: 4 additions & 4 deletions doc/manual.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
============================ ==============================================


Expand Down
2 changes: 1 addition & 1 deletion lib/core/macros.nim
Original file line number Diff line number Diff line change
Expand Up @@ -182,7 +182,7 @@ template `^^`(n: NimNode, i: untyped): untyped =

proc `[]`*[T, U: Ordinal](n: NimNode, x: HSlice[T, U]): seq[NimNode] =
## Slice operation for NimNode.
## Returns a seq of child of `n` who inclusive range [n[x.a], n[x.b]].
## Returns a seq of child of `n` who inclusive range `[n[x.a], n[x.b]]`.
let xa = n ^^ x.a
let L = (n ^^ x.b) - xa + 1
result = newSeq[NimNode](L)
Expand Down
6 changes: 3 additions & 3 deletions lib/impure/db_mysql.nim
Original file line number Diff line number Diff line change
Expand Up @@ -180,7 +180,7 @@ iterator fastRows*(db: DbConn, query: SqlQuery,
## if you require **ALL** the rows.
##
## Breaking the fastRows() iterator during a loop will cause the next
## database query to raise an [EDb] exception `Commands out of sync`.
## database query to raise an `EDb` exception `Commands out of sync`.
rawExec(db, query, args)
var sqlres = mysql.useResult(PMySQL db)
if sqlres != nil:
Expand All @@ -203,7 +203,7 @@ iterator instantRows*(db: DbConn, query: SqlQuery,
args: varargs[string, `$`]): InstantRow
{.tags: [ReadDbEffect].} =
## Same as fastRows but returns a handle that can be used to get column text
## on demand using []. Returned handle is valid only within the iterator body.
## on demand using `[]`. Returned handle is valid only within the iterator body.
rawExec(db, query, args)
var sqlres = mysql.useResult(PMySQL db)
if sqlres != nil:
Expand Down Expand Up @@ -283,7 +283,7 @@ proc setColumnInfo(columns: var DbColumns; res: PRES; L: int) =
iterator instantRows*(db: DbConn; columns: var DbColumns; query: SqlQuery;
args: varargs[string, `$`]): InstantRow =
## Same as fastRows but returns a handle that can be used to get column text
## on demand using []. Returned handle is valid only within the iterator body.
## on demand using `[]`. Returned handle is valid only within the iterator body.
rawExec(db, query, args)
var sqlres = mysql.useResult(PMySQL db)
if sqlres != nil:
Expand Down
4 changes: 2 additions & 2 deletions lib/impure/db_odbc.nim
Original file line number Diff line number Diff line change
Expand Up @@ -168,7 +168,7 @@ proc dbError*(db: var DbConn) {.
raise e

proc sqlCheck(db: var DbConn, resVal: TSqlSmallInt) {.raises: [DbError]} =
## Wrapper that raises [EDb] if `resVal` is neither SQL_SUCCESS or SQL_NO_DATA
## Wrapper that raises `EDb` if `resVal` is neither SQL_SUCCESS or SQL_NO_DATA
if resVal notIn [SQL_SUCCESS, SQL_NO_DATA]: dbError(db)

proc sqlGetDBMS(db: var DbConn): string {.
Expand Down Expand Up @@ -304,7 +304,7 @@ iterator instantRows*(db: var DbConn, query: SqlQuery,
args: varargs[string, `$`]): InstantRow
{.tags: [ReadDbEffect, WriteDbEffect].} =
## Same as fastRows but returns a handle that can be used to get column text
## on demand using []. Returned handle is valid only within the iterator body.
## on demand using `[]`. Returned handle is valid only within the iterator body.
var
rowRes: Row = @[]
sz: TSqlLen = 0
Expand Down
4 changes: 2 additions & 2 deletions lib/impure/db_postgres.nim
Original file line number Diff line number Diff line change
Expand Up @@ -271,15 +271,15 @@ iterator instantRows*(db: DbConn, query: SqlQuery,
args: varargs[string, `$`]): InstantRow
{.tags: [ReadDbEffect].} =
## same as fastRows but returns a handle that can be used to get column text
## on demand using []. Returned handle is valid only within iterator body.
## on demand using `[]`. Returned handle is valid only within iterator body.
setupSingeRowQuery(db, query, args)
fetchinstantRows(db)

iterator instantRows*(db: DbConn, stmtName: SqlPrepared,
args: varargs[string, `$`]): InstantRow
{.tags: [ReadDbEffect].} =
## same as fastRows but returns a handle that can be used to get column text
## on demand using []. Returned handle is valid only within iterator body.
## on demand using `[]`. Returned handle is valid only within iterator body.
setupSingeRowQuery(db, stmtName, args)
fetchinstantRows(db)

Expand Down
2 changes: 1 addition & 1 deletion lib/packages/docutils/dochelpers.nim
Original file line number Diff line number Diff line change
Expand Up @@ -82,7 +82,7 @@ proc toLangSymbol*(linkText: PRstNode): LangSymbol =
##
## This proc should be kept in sync with the `renderTypes` proc from
## ``compiler/typesrenderer.nim``.
assert linkText.kind in {rnRef, rnInner}
assert linkText.kind in {rnRstRef, rnInner}

const NimDefs = ["proc", "func", "macro", "method", "iterator",
"template", "converter", "const", "type", "var",
Expand Down
Loading

0 comments on commit 1bdb83c

Please sign in to comment.