Shipping Sly with support for the Common Lisp "community spec"

[enzuru]

Hey @fonol, you may not remember me, but I responded to your post on Reddit a long time ago, noting for you that the GCL was a Common Lisp spec with a friendlier license than the HyperSpec.

Since then you've done amazing things and for the first time ever perhaps, we have a really good-looking and friendly Common Lisp "community spec" with a friendly license: https://cl-community-spec.github.io/

I would like to now open a ticket with @joaotavora so that we can discuss perhaps shipping Sly with community spec support, and not merely HyperSpec support. Obviously this "community spec" has a license that is more compatible with the GNU operating system.

The code most likely should be easy enough, seems to be https://cl-community-spec.github.io/pages/${symbol}.html in the vast majority of cases.

The community spec look OK in EWW, although you will always land on a screen filled with the table of contents, and not necessarily the symbol that you are looking for. A lot of Emacs users use EWW, so this will probably be important to address.

But perhaps there are other issues to consider? I suspect there might be some hesitation in swapping out the reliable 90s-esque HyperSpec for a relatively new project.

Although seemingly, as long as GitHub exists, this spec should continue to be online. I suspect LispWorks would sooner shutdown than GitHub.

[fonol]

Hi, glad that you find the project useful. I don't use Emacs, but I guess it could be nice to have support for the spec there. I would consider though that at the moment, the HyperSpec is certainly more complete and error-free. The CommunitySpec contains missing links, probably also some wrong links (e.g. stuff like "nil" sometimes linking on the wrong of the three pages about nil), wrong formatting, and also completely misses any images/figures (I think there are some in the HyperSpec?).

For the naming, it is mostly as you said that the symbol name is just the name of the HTML file. However, there are symbols not allowed in the URL which have to be escaped with their ASCII code, e.g. 002abreak_002don_002dsignals_002a.html. For convenience, there is a mapping of all the terms and pages here: https://github.com/fonol/cl-community-spec/blob/main/searchable_terms.json.

[charJe]

Even just opening the appropriate community spec page in the operating system default browser would be very nice.

[jgarte]

This would be a very nice and convenient feature to have in sly.

[jgarte]

@joaotavora

Do you think that this should be a sly contrib package instead and we should close this issue?

[joaotavora]

Do you think that this should be a sly contrib package instead and we should close this issue?

No, and sorry for not replying earlier (there wasn't a question until now, though).

I think you should attempt to do as many changes to lib/hyperspec.el as needed or possibly create a lib/cl-community-spec.el file so that the user can use this spec instead of the Hyperspec. Just make sure that the user can easily toggle between them (sly-documentation-function looks like it could do the job) and the interface to using them (say C-c C-d C-h) is the same.

browse-url should be used once an URL is computed. This ensures Emacs does the right thing (shows it in the in-editor browser if available and preferred, otherwise picks another browser).

BTW, this is unrelated, but Emacs CL emulation package (cl-lib.el) is "under attack" in the Emacs community (they're real fans of Greenpuns's 10th there) and one of the things they attack it with is the lack of good documentation. Having Lispworks' Hyperspec as a non-free resource or something that can be worked from didn't help. So I'm happy you're refreshing my memory on this great work.

[enzuru]

@joaotavora funny enough, I just finished reading that thread. Thanks for defending us cl-libbers

I am going to send an email to the mailing list to see what is the exact plant to document cl-lib proper is. I wouldn't mine pitching in.

Recently for Common Lisp docs in Emacs, I have been using sly-describe-symbol which produces OK documentation when used with SBCL. It's not as detailed as the HyperSpec or CommunitySpec though.

I think I am going to focus on my efforts on documenting cl-lib first, and then come back to this later. Anyone is free to get the Community Spec working though.

[jcguu95]

@enzuru The hardest part of this project is to create a hash-table that maps the symbols to url. It is done in hyperspec.el.

(mapc (lambda (entry)
    (common-lisp-hyperspec--insert (car entry) (cadr entry)))
      if common-lisp-hyperspec-symbol-table
      (common-lisp-hyperspec--parse-map-file
       common-lisp-hyperspec-symbol-table)
    '("&allow-other-keys" "03_da.htm")
      ("&aux" "03_da.htm")
      ("&body" "03_dd.htm")
      ("&environment" "03_dd.htm")
      ("&key" "03_da.htm")
      ("&optional" "03_da.htm")
      ("&rest" "03_da.htm")
      ("&whole" "03_dd.htm")
      ("*" "a_st.htm")
      ("**" "v__stst_.htm")
      ("***" "v__stst_.htm")
      ("*break-on-signals*" "v_break_.htm")
      ("*compile-file-pathname*" "v_cmp_fi.htm")
      ("*compile-file-truename*" "v_cmp_fi.htm")
      ("*compile-print*" "v_cmp_pr.htm")
      ("*compile-verbose*" "v_cmp_pr.htm")
      ("*debug-io*" "v_debug_.htm")
      ("*debugger-hook*" "v_debugg.htm")
      ("*default-pathname-defaults*" "v_defaul.htm")
      ("*error-output*" "v_debug_.htm")
      ("*features*" "v_featur.htm")
      ("*gensym-counter*" "v_gensym.htm")
      ("*load-pathname*" "v_ld_pns.htm")
      ("*load-print*" "v_ld_prs.htm")
      ("*load-truename*" "v_ld_pns.htm")

[elided..]

A possible and good enough workaround is to send search query to https://cl-community-spec.github.io/ and open up the searched results. Something like

https://cl-community-spec.github.io/MAH-OWN-INVENTED-API-for--search/unwind-protect

Either way, we need some insights from @fonol. If I get the relevant information, I can make a PR on this.