Re: [Sbcl-devel] SB-MANUAL contrib prototype

[Christoph B. <chb...@gm...>]

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
>