unofficial mirror of guile-user@gnu.org 
 help / color / mirror / Atom feed
From: Neil Jerram <neiljerram@gmail.com>
To: Blake Shaw <blake@nonconstructivism.com>
Cc: guix-user@gnu.org, guile-user <guile-user@gnu.org>, guix-days@gnu.org
Subject: Re: Proposal: Deep Dive into the Guile Docs & Makeover Proposal
Date: Sat, 19 Feb 2022 12:17:40 +0000	[thread overview]
Message-ID: <CAKuG=vspPanMiS58WV+ibsNDVemcG-shk9eGp3O00WK6L8kLLQ@mail.gmail.com> (raw)
In-Reply-To: <871r01sa4a.fsf@nonconstructivism.com>

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



  parent reply	other threads:[~2022-02-19 12:17 UTC|newest]

Thread overview: 20+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2022-02-17 16:58 Proposal: Deep Dive into the Guile Docs & Makeover Proposal Blake Shaw
2022-02-18 17:48 ` Olivier Dion via General Guile related discussions
2022-02-19 12:17 ` Neil Jerram [this message]
2022-02-19 15:33   ` Olivier Dion via General Guile related discussions
2022-02-19 17:35     ` adriano
  -- strict thread matches above, loose matches on Subject: below --
2022-02-18 18:05 Blake Shaw
2022-02-16 22:06 Blake Shaw
2022-02-08 16:59 Blake Shaw
2022-02-08 17:28 ` Daniel Tornabene
2022-02-08 15:21 Blake Shaw
2022-02-08 13:06 Blake Shaw
2022-02-08  7:36 Blake Shaw
2022-02-08  9:07 ` Neil Jerram
2022-02-08 11:46   ` Blake Shaw
2022-02-08 15:22     ` Daniel Tornabene
2022-02-08 10:16 ` Jérémy Korwin-Zmijowski
2022-02-08 14:45 ` james
2022-02-08 15:08 ` Olivier Dion via General Guile related discussions
2022-02-08 17:25   ` Daniel Tornabene
2022-02-10 17:20 ` Christine Lemmer-Webber

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

  List information: https://www.gnu.org/software/guile/

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to='CAKuG=vspPanMiS58WV+ibsNDVemcG-shk9eGp3O00WK6L8kLLQ@mail.gmail.com' \
    --to=neiljerram@gmail.com \
    --cc=blake@nonconstructivism.com \
    --cc=guile-user@gnu.org \
    --cc=guix-days@gnu.org \
    --cc=guix-user@gnu.org \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).