Great job outlining the client side of this :)
I would personally like to have a command line tool as well (similar to e.g. 'ri' for Ruby). And it would be nice to be able to look up the same stuff from a Scheme REPL even when the REPL is not running in a text editor.
- Instead of requiring an editor-specific implementation of relevant features, this requires an implementation of such features per each supported Scheme implementation.
- Also communication with the REPL is somewhat tricky, as there is no protocol, e.g. no safe way to identify whether REPL invocation has been completed.
This would be naturally implemented as a Scheme library to talk to the API, and the command line program would just be a simple wrapper around the library.
Any code that Scheme uses to talk to Emacs, VSCode and other editors could also use the library to provide extra functionality to the editor.
If someone wants to use the API from an editor without running a
Scheme REPL, there could also be an Emacs mode to talk to the API
directly. For easy HTTP queries there's e.g. https://github.com/tkf/emacs-request.
This should be quite easy to do if we have a rich API with lots of
endpoints and we don't care about getting maximum speed by caching
lots of data and parsing locally. That means we can let the server
do all the parsing.
Yet another alternative is for the Emacs extension to use the command line Scheme program to query the API when a REPL session is not running.
I don't really have a strong opinion on which method to use :)
But the Scheme library would probably be part of any reasonable
plan eventually. It would be really good if it could be used from
both R6RS and R7RS so this would be a good exercise in portable
coding and finding/making libraries to support that :) I don't
know if we need any support libraries other than a HTTP client
since the API can return S-expressions directly to the client.
5. Process the metadata (as S-expressions) already on the documentation web-server and directly communicate with that server from the editor.SLIME or Geiser probably has some solution we could use for introspection from Emacs. Maybe we should just integrate into Geiser at some point if that's ok with its author?
- Scheme-side implementation required only for the one Scheme we anyway use to build the server.
- No local Scheme client (server or REPL) required.
- No access to additional Scheme specific introspection and documentation features; we can only present what we can define as metadata.
- Performance will be worse than for the local client; whether this is noticeable for the highly interactive features (hovering, Emacs-eldoc) needs to be checked.
- I'm not sure whether all interesting features incl. those defined by LSP can be handled by HTTP and I might oversee a limitation that we have in the HTTP-case that we would not have in the local-socket case.
I would start with this since it's easiest and then look into the other alternatives (unless you are more excited about them, in which case you should do those :)
The LSP question is a good one. I don't know if anyone on this list is familiar with it yet. LSP/Geiser/the API client cover some of the same ground, so it would be good if some code can be re-used.
Lots to explore :)
So I took a first shot on processing the metadata that Lassi created here - code (for Gauche) is appended below. For now that's just picking to metadata values from an implementation-specific metadata file and using that information to build two Scheme functions - most simple thing to do was to just return the URL of the Scheme's index page plus one to query for documentation for symbol-at-point.Thanks for this, that was quick :)
We could do something to make it easier to download the metadata from that GitHub repo. I've previously used the handy URLs GitHub provides for downloading the files in a Git repo as a zip: e.g. <https://github.com/schemedoc/implementation-metadata/archive/master.zip>. If you download the zip, many languages can read the archive directly from the HTTP request instead of extracting to files. I've done this successfully in Racket and it's not that hard.
We could also change the format of each .scm file so one can just 'cat' them together to get one file with the metadata for all implementations. This would require wrapping the current contents of each file in a top-level form like:
<file contents here>)