Open timotheecour opened 3 years ago
How important/crucial is this? Shouldn't we focus on more important stuff than spending our time on implementing this and then fixing future bugs?
Thumb down from me, sorry.
I like the idea but ideally we should copy from some existing, well-known markdown or rst extension. If there are any...
maybe such extensions exist but I'm not awareof it, and people often complain about markdown/rst lacking such a feature. I don't like any of the workarounds mentioned in those links, which is why I ended up suggesting the simple solution in this RFC.
https://meta.stackexchange.com/questions/93581/how-can-we-display-additional-spaces-using-markdown
Use instead of space characters.
https://meta.stackexchange.com/questions/123584/markdown-code-snippets-dont-allow-trailing-spaces suggests using unicode Alt+0160, but typing it can be a pain and not obvious if you're reading some code and are unawaire it's using unicode, or if you copy paste it from the source instead of rendered output you'll get, well, unicode
https://meta.stackexchange.com/a/105363/223860 this one recommends zero-width unicode character, and has same caveats:
And then people copy-past zero-width characters in their code and wonder why it doesn't work... –
https://meta.stackoverflow.com/questions/363471/wrong-parsing-of-in-comments
Spaces are not allowed as the start or end character in inline code blocks now. Do not include them, or it won't work.
https://talk.commonmark.org/t/leading-and-trailing-white-spaces-in-code-blocks/628
the preservation of whitespace cannot be guaranteed. If the preservation of line breaks and/or other whitespace is important, literal blocks should be used
The end-string must be immediately preceded by non-whitespace.". So it looks like it's not possible per definition. This answer has introduced a custom role for accomplishing a similar task however it requires modifying the Sphinx code
There is already too much confusing syntax for adding even more.
Trailing/leading whitespace use cases are too marginal, let us leave it be.
For inline syntax highlighting we'd better focus on implementation of existing RST syntax:
See `def f(): return 3`:python:
or `def f(): return 3`:py:
(In rst2html.py it already works if such roles are defined:
.. role:: python(code)
:language: python
.. role:: py(code)
:language: python
)
@a-mr the existing syntax is the one that's confusing and limited, with lots of edge cases it cannot handle, and people complain about it (see links in https://github.com/nim-lang/RFCs/issues/355#issuecomment-806488730).
In rst2html.py it already works [...] Trailing/leading whitespace use cases are too marginal, let us leave it be.
are these too marginal too?
\
in syntax highlighted codeInstead of copying bad design, this RFC replaces it with something that's:
ie, it replaces something that sucks by something that doesn't suck.
eg, say I want inline block to represent these syntax-highlighted snippets for bash:
text before ```bash export MYPWD=`pwd`; ``` text after
or even this: ```bash export MYPWD=`pwd` ```
or this: ```cmd cd\``` (eg for windows cmd prompt to cd to root)
with rst2html how do you do that? say even the 1st case:
.. role:: bash(code)
:language: bash
can't work: backtick needs escaping:
`export MYPWD=`pwd`;`:bash:
can't work with double backticks: roles are for single backticks:
``export MYPWD=`pwd`;``:bash:
no syntax highlighting:
``export MYPWD=`pwd```
this doesn't render correctly in rst2html:
`export MYPWD=\`pwd\`;`:bash:
this doesn't render correctly in rst2html:
`export MYPWD=\`pwd\`;\\`:bash:
gives:
with this RFC, this is simply:
text before ```bash export MYPWD=`pwd`; ``` text after
text before ```bash export MYPWD=`pwd` ``` text after
text before ```cmd cd\ ``` text after
@timotheecour ,
Yes,
those are very minor use cases.
For them we can just advice users to use full .. code-block:: nim
or its normal Markdown counterpart.
A problem with trailing space looks completely artificial.
If you really have it then currently just explain it by a few English words :-)
/cc @a-mr
proposal
add a syntax for doc comments and rst files allowing writing arbitrary inline code blocks with optional syntax indicator, as follows:
the syntax is:
benefits
note
this proposal is simple (both to understand and to implement), allows encoding anything, and has 0 edge cases that I know of.
open question