* Make rstgen work with gcsafe
Co-authored-by: Danil Yarantsev <tiberiumk12@gmail.com>
* add tests and fixes
* if nimHasWarningAsError
Co-authored-by: Danil Yarantsev <tiberiumk12@gmail.com>
* 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
The strutils `delete` func with signature
func delete*(s: var string, first, last: int)
was deprecated in adba5eb45e, in favor of one with signature
func delete*(s: var string, slice: Slice[int])
However, a few procedures still used the deprecated form. This commit
updates them, resolving these deprecation warnings:
rstgen.nim(766, 12) Warning: use `delete(s, first..last)`; delete is deprecated [Deprecated]
strutils.nim(1651, 19) Warning: use `delete(s, first..last)`; delete is deprecated [Deprecated]
strutils.nim(1679, 7) Warning: use `delete(s, first..last)`; delete is deprecated [Deprecated]
strutils.nim(2472, 7) Warning: use `delete(s, first..last)`; delete is deprecated [Deprecated]
Before this commit:
- `trimZeros` called `s.delete(i+1, i)` for an input that lacks a
trailing zero (like "1.23").
- `removePrefix*(s: var string, prefix: string)` called
`s.delete(0, -1)` when the prefix was the empty string.
which did not modify `s`, nor raise an error. But the newer slice
`delete` raises an `IndexDefect` when the start of the slice is greater
than the end, so we avoid calling the new `delete` for such a case.
Recall that exceptions inheriting from `system.Defect` are not tracked
with the `.raises: []` exception tracking mechanism [1], so this commit
does not break existing code like:
proc foo {.raises: [].} =
var s = "abc1.20"
s.removePrefix("abc")
s.trimZeros()
doAssert s == "1.2"
The `strutils.delete` deprecation was motivated by a problem with
`system.delete` [2][3]:
`system.delete` had surprising behavior when the index passed to it
was out of bounds (it would delete the last entry then). Compile
with `-d:nimStrictDelete` so that an index error is produced
instead.
Be aware however that your code might depend on this quirky behavior
so a review process is required on your part before you can use
`-d:nimStrictDelete`. To make this review easier, use the
`-d:nimAuditDelete` switch, which pretends that `system.delete` is
deprecated so that it is easier to see where it was used in your
code.
`-d:nimStrictDelete` will become the default in upcoming versions.
A similar deprecation happened with `sequtils.delete` [4], but that
deprecated form is already not used in this repo.
[1] https://github.com/nim-lang/Nim/blob/2dec69fe5aa6/doc/manual.md#exception-tracking
[2] https://github.com/nim-lang/Nim/blob/2dec69fe5aa6/changelogs/changelog_1_6_0.md#system
[3] https://github.com/nim-lang/Nim/commit/92cb76571432
[4] https://github.com/nim-lang/Nim/commit/1d6863a7899f
* Extract Markdown & Rst doc into separate file
This documentation should be extracted into separate file
as it's user's documentation, which can be used as a separate
utility for compiling `.md/.rst` files.
* Restructure: move markup info into markdown_rst.md
+Markdown link migration
Markdown link migration part 1
Also the warning is improved a bit.
Local links (targeting inside its document) which had had a full anchor
were turned into concise form.
The very fact that they existed may be due to the bug in
reference to subsections fixed https://github.com/nim-lang/Nim/pull/20279,
now they are working well (both in RST syntax and
new Pandoc Markdown syntax implemented in
https://github.com/nim-lang/Nim/pull/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
Fix links to subheader when TOC is present
It was observed (in https://github.com/nim-lang/Nim/pull/20112)
that links to 2nd- (and subsequent) -level headings
fail if TOC is present, e.g.:
```nim
.. contents::
Type relations
==============
Convertible relation
--------------------
Ref. `Convertible relation`_
```
The problem here is that links are resolved in `rst.nim` but later
`rstgen.nim` fixes ("fixes") anchors to make them unique so that
TOC always works (if e.g. there was another sub-section like
"Convertible relation").
The solution implemented in this PR is to move that fix-up of anchors
into `rst.nim`, so that link resolution could know final anchors.
The bug seems to be added in https://github.com/nim-lang/Nim/pull/2332
in 2015, that is it is present in Nim 1.0.
* Add `doctype: RST|Markdown|RstMarkdown` pragma
Implements https://github.com/nim-lang/RFCs/issues/68 ,
see also discussion in https://github.com/nim-lang/Nim/issues/17987
The permitted values:
* `markdown`, which is default. It still contains nearly all of
the RST supported but it is assumed that in time we will give up
most or all RST features in this mode
* `rst`, without any extensions
* `RstMarkdown` — compatibility with Nim 1.x. It's basically RST
with those Markdown features enabled that don't conflict with RST.
* Apply suggestions from code review
Co-authored-by: Clay Sweetser <Varriount@users.noreply.github.com>
* Additional fix in spirit of review
* Fix test after #20188
Co-authored-by: Clay Sweetser <Varriount@users.noreply.github.com>
- add additional parameters parsing (other implementations will just
ignore them). E.g. if in RST we have:
.. code:: nim
:test: "nim c $1"
...
then in Markdown that will be:
```nim test="nim c $1"
...
```
- implement Markdown interpretation of additional indentation which is
less than 4 spaces (>=4 spaces is a code block but it's not
implemented yet). RST interpretes it as quoted block, for Markdown it's
just normal paragraphs.
- add separate `md2html` and `md2tex` commands. This is to separate
Markdown behavior in cases when it diverges w.r.t. RST significantly —
most conspicously like in the case of additional indentation above, and
also currently the contradicting inline rule of Markdown is also turned
on only in `md2html` and `md2tex`. **Rationale:** mixing Markdown and
RST arbitrarily is a way to nowhere, we need to provide a way to fix the
particular behavior. Note that still all commands have **both** Markdown
and RST features **enabled**. In this PR `*.nim` files can be processed
only in Markdown mode, while `md2html` is for `*.md` files and
`rst2html` for `*.rst` files.
- rename `*.rst` files to `.*md` as our current default behavior is
already Markdown-ish
- convert code blocks in `docgen.rst` to Markdown style as an example.
Other code blocks will be converted in the follow-up PRs
- fix indentation inside Markdown code blocks — additional indentation
is preserved there
- allow more than 3 backticks open/close blocks (tildas \~ are still not
allowed to avoid conflict with RST adornment headings) see also
https://github.com/nim-lang/RFCs/issues/355
- better error messages
- (other) fix a bug that admonitions cannot be used in sandbox mode; fix
annoying warning on line 2711
Fixes silent disappearance of Markdown (pseudo-)link when it's detected as
unsafe protocol. Now it will be converted to plain text in spirit of
[the specification](https://spec.commonmark.org/0.30/#links).
For that sake the check for protocol is added to rst.nim also.
* fixes a possible 'javascript:' protocol exploit [backport:1.0]
* add tests
* Update tests/stdlib/trstgen.nim
* add the same logic for hyperlinks
* move the logic into a proc
Co-authored-by: narimiran <narimiran@disroot.org>
