search

hinkelman / chez-docs

Access Chez Scheme documentation from the REPL
https://akkuscm.org/packages/chez-docs/
Other
26 stars 1 forks source link

Geiser integration #3

Open logc opened 4 years ago

logc commented 4 years ago

Thank you so much for this project! I have been looking for something like this for some time ...

Do you think that either your scraped data or this project could be integrated with Geiser, so that the documentation opens in Emacs when typing a function's name?

hinkelman commented 4 years ago

That would be great, but beyond my current skill level. If you know how to do that, feel free to use to any part of this repo to try to make it happen. If not, then I will spend more time trying to understand how the Geiser integration might work.

logc commented 4 years ago

I am not super sure how to do it either, but I can look into it. Could you please tell me a bit more about how the data is used by the library?

I see that if 'open-link' is selected, it opens the URL via the command line (e.g.openin MacOS), but when'display-form` is specified, is only the function signature shown?

hinkelman commented 4 years ago

The data are scraped from the Summary of Forms, which includes an HTML table with 3 columns: Form, Category, and Page (which contains the anchored link). The links in the table point to one of two documents as indicated by the page number. A t in the page number indicates The Scheme Programming Language. That is probably the first barrier to Geiser integration. There isn't a single source to pull from. In chez-docs, if there is a procedure with documentation in both sources (e.g., <), then I just launch both pages.

The HTML table does not provide a procedure column so I just extracted the characters before the first space in the form and used it as the procedure name (even though they are not all procedures). This is the structure of the data in Scheme:

'((csug ("proc1" "form1" "url1")
        ("proc2" "form2" "url2"))
  (tspl ("proc1" "form1" "url1")
        ("proc2" "form2" "url2")))

The procedure doc requires an exact match of the proc strings. I added find-proc to give more flexibility in search the proc strings in the data. That work presumably involved reinventing the wheel as the autocomplete functionality available through emacs would be a big improvement over find-proc.

I'm not sure if any of this is helpful, but I'm happy to continue the discussion.

jaor commented 2 years ago

hi. geiser's main maintainer here :) i didn't know about akka and this package in particular until now! yes, this should be integrable in geiser, and, if nobody is working on it already, i'll give it a try... eventually (i'm particularly interested in improving geiser-chez, as it's becoming one of my most used schemes, but don't have much time, so help would be appreciated).

thanks!

hinkelman commented 2 years ago

That's great! I've made very little (essentially no) progress on trying to extract more of the text from the web pages for display in the REPL. I'm open to suggestions about the best way to incorporate Chez documentation into geiser and I'm happy to help where I can.

jaor commented 2 years ago

On Sat, Oct 08 2022, Travis Hinkelman wrote:

That's great! I've made very little (essentially no) progress on trying to extract more of the text from the web pages for display in the REPL.

Ah, i had missed chez-docs-scrape. That's excellent.

I'm open to suggestions about the best way to incorporate Chez documentation into geiser and I'm happy to help where I can.

I have yet to start using Akku in earnest, but i very much like its concept and hope it's as good as it looks, so having an indirect dependency on Akku for using geiser-chez is not necessarily a bad thing.

That said, if a significant proportion of Chez users don't usually have Akku in their systems, an alternative could be to use the results of chez-docs-scrape directly in geiser, where one could also massage them using elisp (and avoid the traffic between the repl and emacs). Since we're going to need some elisp gluing in geiser anyway, that might also be more efficient in the end.

(i also see chez-docs expanding in the future in directions orthogonal to geiser, like providing terminal embellishments for its outputs.)

hinkelman commented 1 year ago

@jaor, I finally made the time to process the Chez Scheme documentation. Hopefully, you can repurpose chez-docs-data.scm and summary-data.scm into something useful for geiser. The way I use those two files is to look up the procedure in summary-data.scm to get the anchor (2nd item in each sublist), which is used as a keyword to get the documentation (as a lists of strings) associated with that anchor on the documentation website.