Menu
▾
▴
Re: [Sbcl-devel] SB-MANUAL contrib prototype
|
From: Jesse B. <jes...@pr...> - 2026-06-04 16:07:29
|
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...> 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... >> https://lists.sourceforge.net/lists/listinfo/sbcl-devel |
