Highlight functions and variables in :ncode blocks. #2746
Conversation
aartaka
force-pushed
the
doc-syntax-highlight
branch
2 times, most recently
from
201d59a
to
65b1ebc
Compare
|
Look! It highlights special forms now (
|
aartaka
force-pushed
the
doc-syntax-highlight
branch
from
cde5b54
to
7cb8bd8
Compare
|
Okay, now I'm fully satisfied with what's there:
|
|
It's impressive work! But before we get down to further discussion, the original issue #1480 mentioned https://prismjs.com/, which may already contain a CL highlighter. There are also pure CL libraries like https://github.com/kingcons/colorize. |
Indeed, PrismJS has CL highlighting, but we agreed to not include any JS into Nyxt distribution unless strictly necessary. In our case, it's not strictly necessary at all, as compiler/language gives us enough leverage for even a more meaningful highlighting than PrismJS can ever give.
Right, this one is good in being a Lisp library. But still, it's the same paradygm as PrismJS: it treats the code as a mere text, a mere thing to colorize based on pre-set rules and sets of symbols. It links ANSI CL symbols to CLHS, but no more linking/interactiveness beyond that. This PR is different in that it inspects the image to infer the highlighting information. Importantly, it distinguishes functions, macros, and special forms from each other, and may thus highlight them differently. It also provides links to all the functions/macros used in the given code. This approach is quite demanding on compiler/distribution, but we're hard-set on making Nyxt a self-introspecting program anyway, so it should be more than relevant. |
|
OK, thanks for investigating. That said, aren't there any other library that do just that? |
|
Do we want to have links in code snippets? |
Yes, because those allow to immediately look at the docs/sources of the function/macro/whatever used in the code. And links are so nice and fidgety as code highlighting elements too :P |
I'm afraid I'm not convinced. I think visually it'd look too cluttered (syntax highlighting + link style). |
aartaka
force-pushed
the
doc-syntax-highlight
branch
from
696bdf5
to
b3058e9
Compare
Fair point. As a totally-not-a-fan-of-angry-fruit-salad, I concur. 348a1cf introduces a much more neutral highlight for functions and variables, making it much less cluttered (see the attached image). Should be much better now. |
aartaka
force-pushed
the
doc-syntax-highlight
branch
from
2a6e8b3
to
841c054
Compare
|
So I've enabled code highlighting in |
|
I can test if you ping me on email :-D otherwise i may forget! |
|
I did test, and it is fucking awesome! I did encounter a bug though :-O. Can't do |
aartaka
force-pushed
the
doc-syntax-highlight
branch
from
116b711
to
0945220
Compare
To allow using :nxref inside :ncode.
command-key-p allows ignoring the keybinding part for commands, if it's not relevant.
Now that we recognize more of forms, there will at least be less false variables.
This way, copying, RELP-editing, and config appending use the printed code, while display is the HTMLized one.
So that progn is resolved as itself, and not as prog with "n" appended.
This shortens the code while retaining its purpose.
This way, it feels less angry-fruit-salad to the eye.
aartaka
force-pushed
the
doc-syntax-highlight
branch
from
0945220
to
5dc541e
Compare
Fixed on master and rebased here. Shoud be fixed now, it the error you're (not) referring to is the same as mine :) |
|
Well, I fixed the bug that I encountered :-) |
aartaka
force-pushed
the
doc-syntax-highlight
branch
from
d257294
to
e8c7e8d
Compare
|
Yep, I allowed myself a liberty to edit it some. Need to refactor the whole macro before merging (is it OK to merge then?) |
|
It is OK :-) |
|
Feel free to refactor the macro on master, that is orthogonal to this PR, this PR is OK to merge, thus I merged :-D |
|
@jmercouris, you didn't merge this according to our standards - it should have been merged with a merge commit. This is extremely important. Also, the commits should probably have been squashed. |
|
Sorry Andre, I had totally forgotten about this. Old habits! |
|
No big deal, thanks. |
Description
This adds a rudimentary syntax highlighting to all our :ncode blocks, which means: all code examples in
manualanddescribe-*pages. This is a prototype, but a working one (see screenshots below).Fixes #1480.
At this stage I'm interested in what all y'all have to say about this. Am I going the right way here? @aadcg, @jmercouris, @Ambrevar.
Discussion
let-bindings are highlighted as functions, due to primitiveness of the code walker (resolve-linkable-symbols). We have to fix that. Anyone aware of some package/CL function that gets us to the body of the macro/special form, ignoring the arguments/bindings/special symbols? Swank should have something like that, but I can't find it. How does SLY do syntax highlighting then?Checklist:
Everything in this checklist is required for each PR. Please do not approve a PR that does not have all of these items.
cd /path/to/nyxt/checkout git submodule add https://gitlab.common-lisp.net/nyxt/py-configparser _build/py-configparser:documentations written in the aforementioned style. (It's OK to skip the docstring for really trivial parts.)changelog.lispwith my changes if it's anything user-facing (new features, important bug fix, compatibility breakage).migration.lispentry for all compatibility-breaking changes.