Re: Proposal: Deep Dive into the Guile Docs & Makeover Proposal

[Neil Jerram]

On Thu, 17 Feb 2022 at 16:59, Blake Shaw <blake@nonconstructivism.com> wrote:
>
> https://tube.nocturlab.fr/videos/watch/2b55ca09-f0fd-4899-9cb0-9632cd90b3d1

Wow, what a great reminder of things past!  I mean "past" in the sense
that I used to be very strongly focused on this, but have not been for
some years.  The material is, happily, still very relevant in the
present, so well worth addressing how it can be improved.

I'm only about half way through the video so far, but already wanted
to mention a couple of points.

Firstly, about the Guile Recipes...  I had entirely forgotten about
that, but yes, it indicates that we were having the same kind of
conversation about a cookbook several years ago as we are now.
Undeniably the guidelines / contribution structure then did not work!
Let's hope someone can devise a better structure this time around.

Secondly, what I think is the overall reason the docs are such a
mess...  Guile has always has a central tension between Scheme-centric
and C-centric usage.

- Scheme-centric usage is:  Write your main program and most of its
code in Scheme.  When you need to use something from a C library, use
the FFI to do that, or dynamically load a shared object that exposes
function as Scheme objects and procedures.

- C-centric usage is:  You already have a big main program written in
C, and you only want to allow Scheme to get involved, at certain
points, as part of a config/customization-language-on-steroids model.
You expose some of your function as Scheme objects and procedures, and
call out to a user-configured Scheme file (which can use those objects
and procedures) at the relevant points in the C processing.

Personally, I am now a big fan of Scheme-centric + FFI, as it means
always writing Scheme and never having to hack C code.  If everyone
agreed on that, we could discard all the C-centric parts of the
manual, and focus the rest on a clearer use case.  But I very much
doubt that there is clear agreement on that.  In particular, the
C-centric usage is really Guile's original reason for existing: to act
as a universal extension language for lots of GNU programs that
already exist.

I think expressing that dichotomy, and arranging the docs as clearly
as possible while still allowing for both sides, is still our number 1
problem.

Best wishes,
     Neil