add RST highlighting for command line / shells (also fixes #16858) #17789
Conversation
a-mr
force-pushed
the
rst-shell-cmdline-highlighting
branch
from
7d774a4 to
6f3e1ff
Compare
| ============ | ||
| Contributing | ||
| ============ | ||
|
|
||
| .. default-role:: code | ||
| .. include:: rstcommon.rst |
There was a problem hiding this comment.
In that include file we have .. default-role:: nim. Do we need .. default-role:: code above it too?
There was a problem hiding this comment.
For nim rst2html we don't need .. default-role:: code. This is for compatibility with GitHub. Github doesn't seem to include files and it does not highlight Nim even if inserted directly to file (yet?). So effectively it sees only .. default-role:: code, which is satisfactory.
This trick was proposed by @timotheecour , see discussion around #17585 (comment)
|
|
||
| Not all the tests follow the convention here, feel free to change the ones | ||
| that don't. Always leave the code cleaner than you found it. | ||
|
|
||
| Stdlib | ||
| ------ | ||
|
|
||
| Each stdlib module (anything under `lib/`, e.g. `lib/pure/os.nim`) should | ||
| preferably have a corresponding separate test file, e.g. `tests/stdlib/tos.nim`. | ||
| Each stdlib module (anything under ``lib/``, e.g. ``lib/pure/os.nim``) should |
There was a problem hiding this comment.
Why are these single-backtick to double-backtick changes needed (at some (not all) places)?
There was a problem hiding this comment.
The rule was introduced in #17585 into contributing.rst.
It's simple in essence: we use double backticks where we don't want syntax highlighting. In the case of single backticks / and . would be highlighted as Nim operators. (Interestingly, Sphinx has a dedicated :file: role for files.)
Currently I selected the following uniform scheme:
- files/dir names are not highlighted in
:cmd:role - and they are not highlighted when using ``double backticks``
Of course this is still up to discussion, we can change our mind and remove/modify the rule, please share your thoughts...
| TokenClass* = enum | ||
| gtEof, gtNone, gtWhitespace, gtDecNumber, gtBinNumber, gtHexNumber, | ||
| gtOctNumber, gtFloatNumber, gtIdentifier, gtKeyword, gtStringLit, | ||
| gtLongStringLit, gtCharLit, gtEscapeSequence, # escape sequence like \xff | ||
| gtOperator, gtPunctuation, gtComment, gtLongComment, gtRegularExpression, | ||
| gtTagStart, gtTagEnd, gtKey, gtValue, gtRawData, gtAssembler, | ||
| gtPreprocessor, gtDirective, gtCommand, gtRule, gtHyperlink, gtLabel, | ||
| gtReference, gtOther | ||
| gtReference, gtProgram, gtOption, gtOther |
There was a problem hiding this comment.
how about using same approach as #15775 for these to simplify code:
TokenClass* = enum
gtEof = "Eof"
...
(the raw "gtEof" can always be had with enumutils.symbolName in the rare case it's needed)
There was a problem hiding this comment.
@timotheecour yes, that would be a better style.
A very generic cmdline tokenizer is implemented in
highlite.nim. It does not support programming constructs or escaping. But it can be used meaningfully for Unix shells, Powershell, even Windows cmd (mostly).Pseudo-language
cmdand role:cmd:is introduced for this highlighting. Here iscode-block:: cmdin black theme:Also added roles
:program:and:option:(borrowed from Sphinx) to input them separately:RST option list style/color is tweaked respectively:
Also a new RST node
rnCodeFragmentis used to revive highlighting for:tok:role (ref #16858 ):cc @narimiran