mirror of
https://github.com/nim-lang/Nim.git
synced 2026-01-04 12:07:51 +00:00
cde6b2aab8
* 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
214 lines
4.9 KiB
Nim
214 lines
4.9 KiB
Nim
##[
|
|
|
|
.. include:: ./utils_overview.rst
|
|
|
|
# This is now a header
|
|
|
|
## Next header
|
|
|
|
### And so on
|
|
|
|
# More headers
|
|
|
|
###### Up to level 6
|
|
|
|
|
|
#. An enumeration
|
|
#. Second idea here.
|
|
|
|
More text.
|
|
|
|
1. Other case value
|
|
2. Second case.
|
|
|
|
Ref group fn2_ or specific function like `fn2()`_
|
|
or `fn2( int )`_ or `fn2(int,
|
|
float)`_.
|
|
|
|
Ref generics like this: binarySearch_ or `binarySearch(openArray[T], K,
|
|
proc (T, K))`_ or `proc binarySearch(openArray[T], K, proc (T, K))`_ or
|
|
in different style: `proc binarysearch(openarray[T], K, proc(T, K))`_.
|
|
Can be combined with export symbols and type parameters:
|
|
`binarysearch*[T, K](openArray[T], K, proc (T, K))`_.
|
|
With spaces `binary search`_.
|
|
|
|
Note that `proc` can be used in postfix form: `binarySearch proc`_.
|
|
|
|
Ref. type like G_ and `type G`_ and `G[T]`_ and `type G*[T]`_.
|
|
|
|
Group ref. with capital letters works: fN11_ or fn11_
|
|
]##
|
|
|
|
include ./utils_helpers
|
|
|
|
type
|
|
SomeType* = enum
|
|
enumValueA,
|
|
enumValueB,
|
|
enumValueC
|
|
G*[T] = object
|
|
val: T
|
|
|
|
proc someType*(): SomeType =
|
|
## constructor.
|
|
SomeType(2)
|
|
|
|
|
|
proc fn2*() = discard ## comment
|
|
proc fn2*(x: int) =
|
|
## fn2 comment
|
|
discard
|
|
proc fn2*(x: int, y: float) =
|
|
discard
|
|
proc binarySearch*[T, K](a: openArray[T]; key: K;
|
|
cmp: proc (x: T; y: K): int {.closure.}): int =
|
|
discard
|
|
proc fn3*(): auto = 1 ## comment
|
|
proc fn4*(): auto = 2 * 3 + 4 ## comment
|
|
proc fn5*() ## comment
|
|
proc fn5*() = discard
|
|
proc fn6*() =
|
|
## comment
|
|
proc fn7*() =
|
|
## comment
|
|
discard
|
|
proc fn8*(): auto =
|
|
## comment
|
|
1+1
|
|
func fn9*(a: int): int = 42 ## comment
|
|
func fn10*(a: int): int = a ## comment
|
|
|
|
# Note capital letter N will be handled correctly in
|
|
# group references like fN11_ or fn11_
|
|
# (or [fN11] or [fn11] in Markdown Syntax):
|
|
|
|
func fN11*() = discard
|
|
func fN11*(x: int) = discard
|
|
|
|
# bug #9235
|
|
|
|
template aEnum*(): untyped =
|
|
type
|
|
A* {.inject.} = enum ## The enum A.
|
|
aA
|
|
|
|
template bEnum*(): untyped =
|
|
type
|
|
B* {.inject.} = enum ## The enum B.
|
|
bB
|
|
|
|
func someFunc*() =
|
|
## My someFunc.
|
|
## Stuff in `quotes` here.
|
|
## [Some link](https://nim-lang.org)
|
|
discard
|
|
|
|
template fromUtilsGen*(): untyped =
|
|
## should be shown in utils.html only
|
|
runnableExamples:
|
|
discard "should be in utils.html only, not in module that calls fromUtilsGen"
|
|
## ditto
|
|
|
|
iterator fromUtils1*(): int =
|
|
runnableExamples:
|
|
# ok1
|
|
assert 1 == 1
|
|
# ok2
|
|
yield 15
|
|
|
|
template fromUtils2*() =
|
|
## ok3
|
|
runnableExamples:
|
|
discard """should be shown as examples for fromUtils2
|
|
in module calling fromUtilsGen"""
|
|
|
|
proc fromUtils3*() =
|
|
## came form utils but should be shown where `fromUtilsGen` is called
|
|
runnableExamples: discard """should be shown as examples for fromUtils3
|
|
in module calling fromUtilsGen"""
|
|
|
|
proc f*(x: G[int]) =
|
|
## There is also variant `f(G[string])`_
|
|
discard
|
|
proc f*(x: G[string]) =
|
|
## See also `f(G[int])`_.
|
|
discard
|
|
|
|
## Ref. `[]`_ is the same as `proc \`[]\`(G[T])`_ because there are no
|
|
## overloads. The full form: `proc \`[]\`*[T](x: G[T]): T`_
|
|
|
|
proc `[]`*[T](x: G[T]): T = x.val
|
|
|
|
## Ref. `[]=`_ aka `\`[]=\`(G[T], int, T)`_.
|
|
|
|
proc `[]=`*[T](a: var G[T], index: int, value: T) = discard
|
|
|
|
## Ref. `$`_ aka `proc $`_ or `proc \`$\``_.
|
|
|
|
proc `$`*[T](a: G[T]): string = ""
|
|
|
|
## Ref. `$(a: ref SomeType)`_.
|
|
|
|
proc `$`*[T](a: ref SomeType): string = ""
|
|
|
|
## Ref. foo_bar_ aka `iterator foo_bar_`_.
|
|
|
|
iterator fooBar*(a: seq[SomeType]): int = discard
|
|
|
|
## Ref. `fn[T; U,V: SomeFloat]()`_.
|
|
|
|
proc fn*[T; U, V: SomeFloat]() = discard
|
|
|
|
## Ref. `'big`_ or `func \`'big\``_ or `\`'big\`(string)`_.
|
|
|
|
func `'big`*(a: string): SomeType = discard
|
|
|
|
##[
|
|
|
|
Pandoc Markdown
|
|
===============
|
|
|
|
Now repeat all the auto links of above in Pandoc Markdown Syntax.
|
|
|
|
Ref group [fn2] or specific function like [fn2()]
|
|
or [fn2( int )] or [fn2(int,
|
|
float)].
|
|
|
|
Ref generics like this: [binarySearch] or [binarySearch(openArray[T], K,
|
|
proc (T, K))] or [proc binarySearch(openArray[T], K, proc (T, K))] or
|
|
in different style: [proc binarysearch(openarray[T], K, proc(T, K))].
|
|
Can be combined with export symbols and type parameters:
|
|
[binarysearch*[T, K](openArray[T], K, proc (T, K))].
|
|
With spaces [binary search].
|
|
|
|
Note that `proc` can be used in postfix form: [binarySearch proc].
|
|
|
|
Ref. type like [G] and [type G] and [G[T]] and [type G*[T]].
|
|
|
|
Group ref. with capital letters works: [fN11] or [fn11]
|
|
|
|
Ref. [`[]`] is the same as [proc `[]`(G[T])] because there are no
|
|
overloads. The full form: [proc `[]`*[T](x: G[T]): T]
|
|
Ref. [`[]=`] aka [`[]=`(G[T], int, T)].
|
|
Ref. [$] aka [proc $] or [proc `$`].
|
|
Ref. [$(a: ref SomeType)].
|
|
Ref. [foo_bar] aka [iterator foo_bar_].
|
|
Ref. [fn[T; U,V: SomeFloat]()].
|
|
Ref. ['big] or [func `'big`] or [`'big`(string)].
|
|
|
|
Link name syntax
|
|
----------------
|
|
|
|
Pandoc Markdown has synax for changing text of links:
|
|
Ref. [this proc][`[]`] or [another symbol][G[T]].
|
|
|
|
Symbols documentation
|
|
---------------------
|
|
|
|
Let us repeat auto links from symbols section below:
|
|
|
|
There is also variant [f(G[string])].
|
|
See also [f(G[int])].
|
|
|
|
]##
|