Very much agree with "How to setup a project" example, I should consider offering my own example at some point after Blake has worked through his approach. Really onboard with this comment overall, the fact that C interop is included directly in the manual is important, and something I've been meaning to write about myself from a different direction for some time now, and I wasn't even aware of the catch/throw change, a perfect thing to highlight or restructure.
On Tue, Feb 8, 2022 at 10:13 AM Olivier Dion via General Guile related discussions <guile-user@gnu.org> wrote: > 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 > >