Skip to content
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

inline triple backtick foo.bar in doc comment incorrectly identifies foo as lang, stripping it in docs #17314

Open
timotheecour opened this issue Mar 10, 2021 · 1 comment
Labels
Documentation Generation Related to documentation generation (but not content).

Comments

@timotheecour
Copy link
Member

timotheecour commented Mar 10, 2021

Example

when true:
  ##[
  a1 ```foo.bar```

  a2
  ```foo
  bar
  ```
  ]##

Current Output

doc comment in nim code:

same code as comment but in rst file:

Expected Output

current output (stripping foo in the 1st foo.bar is incorrect; it looks like it's interpretting foo as the language of a markdown block but that seems incorrect (eg stackoverflow doesn't do that)

the question is whether to treat this case as markdown emulation or rst:

  • if treating as markdown emulation, it should render
foo.bar
  • if treating as rst, it should render with backticks, using double backticks `` as delimiters:
`foo.bar`

We should do what's best for nim here if there's an ambiguity.
This ties into how to escape single backticks /cc @a-mr refs #17260:

  • if we use rst interpretation, this gives a way to render backticks
  • if we use markdown interpretation, then to render backticks we'd need to do as follows:
## ``` `foo.bar` ```

(the leading and trailing space are stripped out; it's a markdown feature)

Additional Information

pip3 install rst2html
cat t11956d.rst | rst2html.py > /tmp/z01.html
generates:

image

1.5.1 2f213db

@timotheecour timotheecour changed the title a1 foo.bar in doc comment incorrectly identifies foo as lang, stripping it in docs inline triple backtick foo.bar in doc comment incorrectly identifies foo as lang, stripping it in docs Mar 10, 2021
@timotheecour timotheecour added the Documentation Generation Related to documentation generation (but not content). label Mar 10, 2021
@timotheecour
Copy link
Member Author

nim-lang/RFCs#355 would fix this (and other issues)

@a-mr a-mr mentioned this issue Jun 1, 2021
28 tasks
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Documentation Generation Related to documentation generation (but not content).
Projects
None yet
Development

No branches or pull requests

1 participant