-
-
Notifications
You must be signed in to change notification settings - Fork 1.5k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
RST minor bugs #17340
Comments
that makes sense for nim files; for rst files, I needed to add wdyt ? |
For |
possible slight improvement: only issue the warning/hint if the rst contains at least one place where this would matter (eg: if user only has things like
it wouldn't trigger) |
@a-mr if you agree, can you add this item to the list above? ##
## .. warning:: Unsuitable for benchmarking (but still better than `now`),
## use `monotimes.getMonoTime` instead or `cpuTime`, depending on use cases. this should IMO generate a warning similar to #17257 ; users may expect this would render last line as part of the warning but it renders as regular text: it works if i add indentation (even 1 space) to that last line also, question: how much indentation is "canonical" ? |
yes, we should report a warning, added to the list. Canonical is certainly 3: all examples in the RST spec are written this way and its syntax diagrams are drawn assuming exactly 3 spaces. Generally, any indentation is allowed: the text just says "and any subsequent indented text". And rst2html.py allows any number of spaces. |
then can we produce at least a hint in case user has != 3? otherwise we'll surely end with different styles |
We already did :-) The more "natural" indentation would be the same as for code in this repository and most Nim projects, which is 2. I think it would be unnecessary complication to learn that in RST directives it "should" be 3. If we really have to proclaim some indentation as canonical then it had better be 2 IMHO. |
agreed. note that there's very little justification left for but for rst files, yes, we should canonicalize on 2 spaces and give a hint/warning when the indent is != 2. |
No, considering the ubiquity of 3 space indentation in RST world, even giving a Hint would be too much. So let us emit a warning only when indentation is exactly 0 after a directive (even when indentation is less than 0 seems like a perfectly valid use case). |
can you also add:
(refs future work mentioned in #17315 so it gets referenced here) |
@a-mr is this a bug, can we improve it or we have to use <> syntax when a link contains parens, eg: proc main*()=
##[
# these don't work:
https://en.wikipedia.org/wiki/APL_(programming_language)
[foo](https://en.wikipedia.org/wiki/APL_(programming_language))
[foo](https://en.wikipedia.org/wiki/APL_\(programming_language\))
[foo](https://en.wikipedia.org/wiki/APL_\(programming_language\))
# this works:
`bar <https://en.wikipedia.org/wiki/APL_(programming_language)>`_
]##
main() note: these work fine in gitub markdown: |
@timotheecour Yes, according to CommonMark that should be allowed. Added as bug 24. |
and a leftover bug: priority of option list inside definition list
rst: fix bug 20 from nim-lang#17340 (nim-lang#18360)
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 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 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.
…lang#17659) * further progress on rst roles & dir-s (fix nim-lang#17646) * fix documents according to the messages * fix bug 17 from nim-lang#17340
and a leftover bug: priority of option list inside definition list
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.
Let us track minor bugs in our RST implementation here.
default-role
does not do anything (see PR enable syntax highlighting for inline code #17585)code
default role (ref. PR: nim doc/rst2html renders\v
,\\
, etc incorrectly #17260, finished enable syntax highlighting for inline code #17585)\
does not work as expected in referencesinclude
does not work if:literal:
has indent < 3 (PR: rst indentation fixes (ref #17340) #17715 )\|
inside a table cell should render as|
not\|
=
should be allowed for borders in simple tables (PR: RST: improve simple tables #19859)..
not recognized (PR rst: allow comment to continue on second line #18338)Details
[x] 1. prefix role syntax doesn't work. Only postfix syntax does.
Should be (rst2html.py):
When started at the 1st column it's not even parsed:
:subscript:`some text`
[x] 2. directive
default-role
does not do anythingThis does not make text subscript:
rst2html.py:
[x] 3. make
code
default roleThis implies non-escaping backslashes between
` `
.Also we need to create a variable to track the default role in the first place :-)
[ ] 4. escape
\
does not work as expected in references(see also #17315 (comment))
This is not even parsed:
[x] 5. indentation bugs: some elements don't work on the first line when nested
:field: #. Item1 #. Item2
Should work (rst2html.py):
The same goes e.g. for bullet list as contents and admonitions as the container
Generally, indentation handling is not aligned/systematic in different body elements handlers.
[x] 6. directive
include
does not work if:literal:
has indent < 3E.g. indentation of
:literal:
is 2:Then contents of grammar.txt are not included and
literal:
appears as a block quote.[x] 7. simple tables with spanning cells are displayed wrongly
Should be (rst2html.py):
[ ] 8. wrong line in footnote reference and substitution reference
Consider this 2 mistakes:
The error reported is for line 6, which is EOF.
Solution: preserve original line of the references.
The same problem will be relevant for smart links
[ ] 9. no warning if no empty line after or before directive
Solution: report a warning like rst2html.py does:
When there is no empty line before directive the spec does not require anything. It silently parses as a normal paragraph both in rst.nim and rst2html.py. But it can be really confusing, we have to add a warning for this case also.
Also directive requires a blank line after it:
[x] 10. combining of bullet lists with option lists is sometimes broken
Consider an option list with more than 1 items and description on more than 1 lines. It's included into a bullet list.
The bullet list is broken.
Interesting, rst2html.py (v 0.14) is broken in another way: it complains about wrong indentation at
desc2
, the same option list without the bullet list parses OK.[ ] 11. some valid field lists are not parsed
It is probable that presence of non-alphanumeric symbols breaks them:
:(empty): current directory `.` is assumed (not with --replace) :-: read buffer once from stdin: pipe or terminal input;
[ ] 12. Markdown:
\|
inside a table cell should render as|
not\|
\|
outside a table cell should keep rendering as\|
(as it already does since #17315)13. Syntax for trailing whitespaces does not work
[x] 14. backslash + backtick escape does not work at the end of interpreted text
If
\`
is right before closing backtick then it fails to parse:Error: '`' expected
Interestingly, adding characters makes it compile:
[ ] 15. no warning when literal block has wrong indentation
rst2html.py gives a warning:
literalBlock.rst:3: (WARNING/2) Literal block expected; none found.
Nim silently ignores the mistake.
[x] 16. roles with valid refname symbols are not parsed
e.g.
:c++:
is not parsed:UPDATE:
c++
is not a valid name according to the spec, it's just that rst2html.py parses it. However, valid refnames are not recognized.[x] 17. two dots without space after them are recognized as a comment
disappears.
Found in #17671.
[x] 18. Only
=
should be allowed for borders in simple tablesOur implementation should not allow using
-
for borders in simple tables. It's against the spec and rst2html and Github don't parse such tables: https://github.com/nim-lang/Nim/blob/devel/doc/nep1.rst[x] 19. Multi-line comments starting from line of
..
not recognized[ ] 20. a blank line between options splits option list
e.g.
is parsed as 2 option lists.
[x] 21. code block with line indented after option disappears
Line
let a = 1
indented positively w.r.t.:number-lines:
option and the whole code block just disappears.[ ] 22. Markdown code blocks gobble up indentation on first line
```nim
discard 1
discard 2
```
May be related to #17314 .
[ ] 23. Markdown code blocks don't respect indentation rule
This
is displayed as
Note two spaces before
some code
and RST block quote quotation bar to the left of it.https://spec.commonmark.org/0.29/#fenced-code-block
Probably RST block quote feature should be turned off in default
nim
mode for that to work.[x] 24. Markdown links don't not allow balanced parentheses or escaped parentheses
According to the spec this should be allowed.
[ ] 25. docgen: multiple 1-level doc comments are glued without spacing
I would expect a blank line between "Main text" and "More text".
[ ] 26. Internal anchor cannot be set for enum.list/bullet list points
This is valid syntax for assigning an anchor to internal point of enumeration list or bullet list:
It works in
rst2html.py
but not inrst.nim
.[ ] 27. Text after 3rd backtick in code disappears
Found in #19058
[ ] 28. Still incorrect handling of indentation when text is wrapped
Current behavior:
Correct behavior by rst2html.py:
version
Nim 1.5.1, but all or almost all are applicable to stable versions.
cc @narimiran @timotheecour
The text was updated successfully, but these errors were encountered: