On Tue, 08 Feb 2022, Blake Shaw <bl...@nonconstructivism.com> wrote: > * SUMMARY: Recent discussions on the Guix mailing list revealed that > many in the Guix community have found the Guile Reference Manual > difficult to navigate as newcomers. That should come as no surprise -- > in PDF form, the docs span approximately /850 pages/, making it a > quite hefty set of documents for an implementation of a minimal > programming language like Scheme, even when compared to the > documentation of relatively large PLs; the Racket Guide, for instannce, > is only 450 pages, while the Rust Book is approximately 550 pages.
Don't forget that Guile as a lot of legacy stuff in its manual. For example `catch/throw` -- the old way of doing exception, althought it's not clear what new projects should use -- is documented there. There's also the details of its implementation, indices, appendices, functions in C, many SRFI and modules. So it's true that scheme is a very simple language, but Guile is not only Scheme. I think there's certainly things that could be trim away to save some space, maybe some restructuration, but I think that overall the manual is great when you get use to it. In my opinion, the thing that lack in the manual is a complete "How to setup a project" example that is a more complex project than the tortoise tutorial. Having this section with condensed informations would be easier for newbies than sparsed informations across hundreds of pages. I had to learn that the hardway by reading multiple times the manual, and looking at Guix and Guile source code. -- Olivier Dion Polymtl