I recently started helping out as an additional maintainer of the Magic Racket project (a VS Code extension for Racket), and as part of this, I was curious about the state of Racket workflow features (editing, debugging, linting, etc.) across different tools.
I've started assembling a Racket workflow feature comparison to attempt to visualise the different features that are currently supported. I expect this will be quite helpful as I prioritise future Magic Racket features, and it may be useful for others to get an clearer picture of what's out there.
Let me know if you'd like to help out with this effort! I've already had several contributions via Discord. @benknoble added the Vim info, for example. Some cells are empty for things I wasn't sure about, so it would be great to know the status of those. There may also be additional tools that would be good to add, so do let me know about that as well. Feel free to leave comments in the doc, message me here or on Discord etc. if you have any feedback or corrections.
@jryans, that is a fantastic thing. Thank you for putting it together.
One thing that made me scratch my head is that I wasn't sure what some of the terms meant. Now I suspect that's partly a lack of knowledge on my part. But it did also make me want to find both definitions for the terms and links to the package docs so I could see them in action. Is there any way I can help annotate your document with that?
Ah, that's surely my fault for hastily summarising features and likely biasing my terminology towards the words VS Code would use.
It would be great to improve the naming and add cell notes to give longer explanations where needed. Let's talk about this more directly somewhere... Perhaps Discord, email, or private messaging here, whatever's best for you.
PS I’m struggling to work out what IDE features are enabled by the #lang protocol? I was expecting to find it in The Guide, DrRacket manual and Plugins manual, but I can’t quite work it out. Maybe I’m looking in the wrong places?
Ah yeah, it would be good to highlight that dimension in more detail somehow. At the moment there's only one row in the highlighting category ("General language identifiers (active #lang forms)") that covers a #lang-dependent feature, but many more features may or may not be working for all #langs vs. just Racket.
Thanks for the suggestion! I'll try to think about the best way to add in that additional info.
Source-Handling Configuration sort of hints at the language-specific features through #:info customisations. I am not aware of a straightforward list of editor features enabled by #lang, but perhaps we can write such a list once we've assembled a list of such features as part of the feature comparison here.
I think the two main features a #lang can surface in an editor are:
Token coloring. The lang-supplied lexer can say, for example, that certain spans are certain kind of tokens (e.g "string", "number", etc.). Then the editor can use a color for each kind, chosen by the user or a theme.
(On top of this basic "lexical" coloring, something like drracket/check-syntax could provide information for an editor to do additional, "semantic" coloring.)
(There's some excitement in Emacs world these days about tree-sitter, as a way to replace a lot of pile-of-regexp syntax highlighting. However AFAICT the tree-sitter tool chain seems intended for big/fixed/static languages. IIUC you define a grammar in a JS file, and build a tree-sitter lexer binary ahead of time. Probably someone smarter than me can see how to reconcile that with the more "dynamic" hash-lang concept.)
Also flavors of both commands for the REPL buffer; same key bindings in both buffers.
"Binding arrows". Emacs can't draw graphical arrows like in DrRacket, so if the feature must literally be arrows, it must be a "No".
However when the thing at point is a definition or a use, it is highlighted, as are its relations -- and there are commands to move among the related sites (even if not currently visible on screen). See commands starting here. So I feel like this is a "Yes", but I wouldn't be offended if you think it should be "Partial".
"Potential binding arrows". Same.
"Tail-position arrows". Same.
p.s. Those links are to the Racket Mode site page, which consists of a hand-written guide, plus a reference generated from the same per-command "doc strings" you can see live in Emacs.
So it's pretty good source of info about what's supported -- or at least attempted . But I'm also happy to answer questions, or point out anything that seems not quite right like the above. Hope this helps!
My $0.02: arrows drawn on the text and being able to navigate via the binding structure of the program are two separate things and while the first one is more discoverable the second one is a lot more useful!
It would be nice if, eventually, we got to the point where IDE services and IDEs are a bit more decoupled so that people using Emacs, magic racket, the lang server protocol, and DrRacket all had similar capabilities available to them, but just tailored to way those different editors usually do similar things. I think we're making progress in that direction, too!
I have almost certainly gotten some cells wrong, my apologies... I am not an Emacs user myself, so thus far the Racket Mode / Emacs value came from skimming your (quite thorough, well-written) documentation page and then correcting based on feedback from actual Emacs users.
I wasn't quite sure how to handle this case, since IIUC Emacs doesn't really support "mouse hover" like VS Code and DrRacket do (a free-floating mouse cursor overlapping something that is separate from the "text cursor" position). I don't fully understand the Emacs interaction model at the moment, so I may still have it wrong...
What triggers the documentation to appear and when does it appear? Moving the text cursor? Just when moving around or only while typing (which would make it more completion-focused)? I may need to tweak the naming in some rows properly convey this.
I believe the part that Racket Mode / Emacs are doing here is (meant to be) covered by the "Yes" values for "Highlighting: References to selected binding" and "Highlighting: Tail position".
The arrows are quite a unique DrRacket feature, so I think it's nice to list them separately via these "Hover" rows. I'll change them from "No" to "-" (out of scope) for non-DrRacket editors though, since I don't think any support drawing such arrows on top of the text area.
As mentioned above, your docs were the main source of info for my first attempt at the Racket Mode / Emacs features, so thanks for writing them! Please do continue to pass along any other corrections, as I'm sure there are still things to improve.
If you want to see documentation for the thing at point, you ask for it: You press some keys. It appears (in an external browser, or, in another Emacs "window" (pane) next to your code's "window" (pane)).
The on-command approach to docs is pretty typical for Emacs. Of course in Emacs it's also not unusual for people to configure things to happen automagically in whatever exact way they prefer.
There is also support for Emacs completion engines like company-mode, which can show you a snippet of the docs, while you're scrolling through completion candidates.
But. Much Racket documentation doesn't fit in one entire screen, much less a portion. And it often include links to other topics and tech terms, which you'd like to click. Finally, some is most comprehensible when you can scroll across multiple adjacent topics, as opposed to a "peephole" view of just one at a time.
In short, it was authored to be viewed in a web browser. When presented in a small non-interactive popup, sometimes it's OK... but sometimes it's not.
That's why I put so much work into making the documentation experience good, including rendering full Racket doc HTML pages in an Emacs text buffer with mostly reasonable formatting and live links to other topics.
That's why "Documentation: No" seemed not quite right IMHO.
I've moved "Documentation" out of the "Hover" category and up to a top-level item of its own, so now it can more properly be about just having some way of viewing documentation (regardless of how it's activated).
With that reorganisation in place, Racket Mode / Emacs now says "Yes" for that feature.
these google sheets allow linking- could the capability(feature) be linked to the documentation for the API? That way if someone decided they wanted a capability in their editor they would at least know where to find the API. e.g. say you want to add 'active #lang forms' to the Racket-Langserver
Add a column for GitHub - jeapostrophe/racket-langserver so it is clear what happens via the LSP and what is part of VSCcode. (I thought Vim used LSP? am I remembering wrong?)
Hmm, perhaps so, I'll need to keep thinking about it. Thanks for sharing your example sheet.
At the moment, I'm thinking both ways of organisation have utility, though perhaps for different audiences... I originally started building this sheet to get an idea of how editor features are used across different workflows, so that's why it currently categorised by editor feature and e.g. has multiple cells for given capabilities in different categories based on how the use editor features.
As an editor workflow maintainer, I want to be able to track each way of implementing a capability separately so I can clearly see the difference between each toolset. As a user though (which is of course most people), you probably just want to know what features exist regardless of their precise implementation.
Perhaps there's a way to support both organisation styles from the same data with e.g. separate tabs for each or something like that. I've added this to a backlog of ideas in the sheet while I think about this a bit more.
Yes, overall it sounds good to add links to more info on each feature. A lot of them are currently only documented by the one workflow that best supports them, but still linking to that for the feature overall is probably helpful.
Ah yeah, it does seem good to track the langserver features separately from the full workflow. AFAIK, at least VS Code and Vim use the langserver, but I'm sure there are others which do so as well. I've added this idea into the sheet as well as a future improvement.
