Menu
▾
▴
Re: [Sbcl-devel] SB-MANUAL contrib prototype
|
From: arthur m. <art...@li...> - 2026-06-04 17:14:39
|
I did send in patch. It was a year or couple of years ago perhaps, I don't remember to be honest. Yes, I am aware they prefer patches here. I have no problem with that :). But thanks for the advice anyway. -------- Originalmeddelande -------- Från: Jesse Bouwman <jes...@pr...> Datum: 2026-06-04 18:07 (GMT+01:00) Till: arthur miller <art...@li...> Kopia: Christoph Breitkopf <chb...@gm...>, Gábor Melis <me...@re...>, sbc...@li... Ämne: Re: [Sbcl-devel] SB-MANUAL contrib prototype Though the officially sanctioned submission route is still mailed patches, you could consider opening PRs on the github mirror for incremental beneficial patches like this, as I believe it's very easy for maintainers to review and apply them: https://github.com/sbcl/sbcl Cheers Jesse On Jun 4, 2026, at 8:25 AM, arthur miller <art...@li...> wrote: I read manual all the time, so I do care about it :). I do it in Emacs info mode though. There I can just 's' or 'm' (search or menu) and use completing read on menus or links so it is a bit better than reading in a web-browser. Especially with Helm and some extras to complete menus and search. But I would appreciate a more detailed and up to date manual. I have once sent in a patch to update the link to C. Rhodes paper about sequences. The link was broken in the manual, but since the patch was ignored I never bothered to send anything more related to the manual. It would be nice if the ansi draft was included and the standard functions or parts of the standard were linked to the draft, but I guess it would be a lot of work. -------- Originalmeddelande -------- Från: Christoph Breitkopf <chb...@gm...> Datum: 2026-06-04 13:15 (GMT+01:00) Till: Gábor Melis <me...@re...> Kopia: sbc...@li... Ämne: Re: [Sbcl-devel] SB-MANUAL contrib prototype Hi folks, can't help much, but I wanted to give feedback on this: "... This is especially so because no one seems to care about the user manual, which may be because it's a dead, neglected, offline thing ..." I look into the user manual about once a week, usually the online version I find from a search for "sbcl manual". With some luck, it's the current one. And I would appreciate more information in there. E.g. the parts of the cmucl manual that are linked could be updated to reflect the sbcl state and integrated. So there's at least one person who _does_ care about the manual. Any improvements and better find-ability would be greatly appreciated. - Chris On Thu, Jun 4, 2026 at 12:35 AM Gábor Melis <me...@re...<mailto:me...@re...>> wrote: Hello The SBCL user manual is not in great shape. I reckon it's because it is slow and cumbersome both to read and to write. For the reader -------------- - Finding the user manual in whatever form, opening it, finding the chapter or definition of interest is pure friction. It's not often worth it. - In the manual, there are very few links. If I see SB-EXT:EXIT mentioned in the text, I need to do text search and find the definition among the 8 hits. - The indices in the appendix do not help in a meaningful way (unless printed). - From the narrative part (coming from the doc/manual/*.texinfo chapter files), the vast majority of links go to sections. - The manual is incomplete and sometimes not up-to-date. - Going from documentation to the code it documents is also a manual process. This friction and low-usability combine to make the user manual decidedly unfun to read. I prefer staying in Slime because the docstrings are a M-. away. That's where most of the of the useful information is anyway. That said, I'd read the high-level discussions in the manual more often if I could more easily go to it. For the writer -------------- - Change a docstring, recompile SBCL, do make-doc.sh, check the result in a browser. Argh. - Docstrings are in a Markdown subset, but chapters are in Texinfo files with different capabilities. At least, changing a chapter file does not require recompiling SBCL. - It is demotivating that no one reads the user manual. Thus, working on the manual is quite painful. Addressing these issues ----------------------- For both the reader and writer, my main goal is to reduce the friction: opening, navigating, updating the documentation should be as interactive as working with code. It is unsurprising, of course, that I think this way considering that I wrote PAX for pretty much the same reasons (https://github.com/melisgl/mgl-pax/). SBCL is different from CL libraries though: it has no lisp library dependencies. So, using PAX is seemingly out of the question. This is a pity because PAX provides - live browsing (to greatly speed up the edit-compile-view cycle) - a way to switch between code and its documentation easily - auto- and explicit linking It's also a fairly mature system. So, PAX supports really nice, live and offline, cross-linked documentation in plain text, Markdown, HTML and PDF formats with better infrastructure than even in Emacs. But PAX is large with a few dependencies of its own, and I don't think people would appreciate if SBCL acquired a hard dependency even if only for building documentation instead of the very stable Texinfo. This is especially so because no one seems to care about the user manual, which may be because it's a dead, neglected, offline thing ... This prototype -------------- Since a full dependency on PAX is out of question, I implemented in a couple of hundred lines as much as was absolutely necessary to fake a PAX-like DEFSECTION macro and generate Texinfo from it: https://github.com/melisgl/sbcl/commit/f7f8251242696ed7a5d00f359bcb544af6023e73 (Eventually, when all chapter files are converted to lisp, doc/manual/*.lisp can be removed.) The generated Texinfo is somewhat close to the original: https://github.com/melisgl/sbcl/commit/0057f3ae2e49d40e927f2c4502848e57616c191e Here is the actual manual generated from this Texinfo (of which the first 6 chapters were generated from Lisp): - https://quotenil.com/blog-files/sbcl-pax-doc/texinfo/sbcl.html - https://quotenil.com/blog-files/sbcl-pax-doc/texinfo/sbcl.pdf The implementation is in the new SB-MANUAL contrib. When it's loaded, one can already M-. around, which provides a quick and dirty documentation browser. To actually view the documentation without recompiling the entire SBCL, we need the live documentation browser from the real PAX (w3m in Slime, or any browser via Hunchentoot): https://melisgl.github.io/mgl-pax-world/mgl-pax-manual.html#MGL-PAX:@BROWSING-LIVE-DOCUMENTATION%20MGL-PAX:SECTION To make switching from documentation to code faster, clicking on the locative (e.g. "[function]" in "- [function] sb-ext:exit") tells Slime to visit the definition. In this prototype, calling SB-MANUAL::SWITCH-TO-PAX will load PAX and patch up the data in the SB-MANUAL to make it as if PAX had been used all along. In addition, PAX can generate autolinked dead documentation: - https://quotenil.com/blog-files/sbcl-pax-doc/sbcl-manual.txt - https://quotenil.com/blog-files/sbcl-pax-doc/sbcl-manual.md - https://quotenil.com/blog-files/sbcl-pax-doc/sbcl.pdf - https://quotenil.com/blog-files/sbcl-pax-doc/html/sbcl-manual.html Note the autolinking in all formats but plain text. In dead documentation, clicking on the locative goes to definition in the sources on GitHub. Summary ------- In this setup, like SLIME, PAX is merely an optional development tool to make documentation truly interactive. It can also generate dead documentation with much better internal and external linking. Even without PAX, the lispification of chapter files provides minor M-. pleasures and makes linking to sections from definition docstrings possible. This is the best I could come up with to make the user manual a part of the live image within the constraints of SBCL. There is more to be done, but this should be a good time to give feedback. Cheers, Gábor PS: To play with SB-MANUAL::SWITCH-TO-PAX, you'll need the latest DRef, PAX and Autoload. Probably best to go with Ultralisp. _______________________________________________ Sbcl-devel mailing list Sbc...@li...<mailto:Sbc...@li...> https://lists.sourceforge.net/lists/listinfo/sbcl-devel |
