From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Neil Jerram Newsgroups: gmane.lisp.guile.user Subject: Re: Proposal: Deep Dive into the Guile Docs & Makeover Proposal Date: Sat, 19 Feb 2022 12:17:40 +0000 Message-ID: References: <871r01sa4a.fsf@nonconstructivism.com> Mime-Version: 1.0 Content-Type: text/plain; charset="UTF-8" Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="35513"; mail-complaints-to="usenet@ciao.gmane.io" Cc: guix-user@gnu.org, guile-user , guix-days@gnu.org To: Blake Shaw Original-X-From: guile-user-bounces+guile-user=m.gmane-mx.org@gnu.org Sat Feb 19 13:19:32 2022 Return-path: Envelope-to: guile-user@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1nLOi4-00094G-EV for guile-user@m.gmane-mx.org; Sat, 19 Feb 2022 13:19:32 +0100 Original-Received: from localhost ([::1]:58940 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1nLOi2-0000LU-6U for guile-user@m.gmane-mx.org; Sat, 19 Feb 2022 07:19:31 -0500 Original-Received: from eggs.gnu.org ([209.51.188.92]:60250) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1nLOh7-0000LJ-Uv for guile-user@gnu.org; Sat, 19 Feb 2022 07:18:34 -0500 Original-Received: from [2607:f8b0:4864:20::22e] (port=44856 helo=mail-oi1-x22e.google.com) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1nLOgV-0007hu-7e; Sat, 19 Feb 2022 07:18:32 -0500 Original-Received: by mail-oi1-x22e.google.com with SMTP id j24so3758924oii.11; Sat, 19 Feb 2022 04:17:52 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=mime-version:references:in-reply-to:from:date:message-id:subject:to :cc; bh=74/2oHdhVFvEgWtjKE+MoZyk0TUnX/RxiJHuj6iR8Fs=; b=Jo9nCIrF9IL1EP6C0ze1DnLahUZJiO1PHlR7myCYgzSf+rYGj05GTmgboI5/GDOPhb c0uIRBAXUyO6dHIVjs3LBCZVbTTWKfphOUE5ZTtm5oNICL58trL2VoRQwL4Tc/FG2QCX afrT82IZtf/tb85lvUdfg1mTjThC/L0OTDAcAUEzPCjY3lF6zhR5+3kpLtCd3klKFUXB +BLM7enP6H2xUsqVn+lkdNfjLUPycquxkgFh0vTcTlLQov1+dBciGROoS+hWRGAkOw5r dKxcBZXrfYFPHy62RPGZKyrSVL2CM9IQxXNBy8nCDRmi23usIxa8tAUhmtRu0aQdudPx 0Xtw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:mime-version:references:in-reply-to:from:date :message-id:subject:to:cc; bh=74/2oHdhVFvEgWtjKE+MoZyk0TUnX/RxiJHuj6iR8Fs=; b=zSONYQ8xHoc5cE0HtzuSddC/Uec4MOKZLDA4KcRVzN6yCJxlulJiJYVhw+lvn6G/mn l+WFTMiwKtUryo8jEkqAfUYHbV8z1TaPlaBoRSfej/PsAiArhAcZgBV8RSJf2RdY67sF W59MIWuSDZfSK1sao7XkhZaW6L9cpbb03dtnUArEguFka9FD2e3EuWHrC923v9S6F8UZ qHjTRyqzQ+xRgqYmphyHDXipCrAjRiSeyfolkraVUN4T6Vw3GMPlv2iAkJs3ox5ZEd+k GsShxPZjGO2XHo4CJMfl7f4tVEMpmXtjFg1RHW0CLD3CowJiN6gMSXiFbru0v4uYkVPu 6ejA== X-Gm-Message-State: AOAM532CX6sDJO0acRVp9vpa5EbkKfgqWPytZz1LhAYYQlBogSr7iPge 6waxIF6K6iuDHANkAbdEQYnsfKcESyE05QuwnNB9PbYv X-Google-Smtp-Source: ABdhPJx+Vh4UjwaF7Abbl//fIPmsArmyIH8zlDKL4e9C7+lTZBUTFS9UoIOFLkLxS7YUqVUinMA4ldYdARbAd5hHDtY= X-Received: by 2002:a05:6808:10d6:b0:2cf:992a:fd8d with SMTP id s22-20020a05680810d600b002cf992afd8dmr6549115ois.145.1645273071646; Sat, 19 Feb 2022 04:17:51 -0800 (PST) In-Reply-To: <871r01sa4a.fsf@nonconstructivism.com> X-Host-Lookup-Failed: Reverse DNS lookup failed for 2607:f8b0:4864:20::22e (failed) Received-SPF: pass client-ip=2607:f8b0:4864:20::22e; envelope-from=neiljerram@gmail.com; helo=mail-oi1-x22e.google.com X-Spam_score_int: -6 X-Spam_score: -0.7 X-Spam_bar: / X-Spam_report: (-0.7 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, FREEMAIL_FROM=0.001, PDS_HP_HELO_NORDNS=0.659, RCVD_IN_DNSWL_NONE=-0.0001, RDNS_NONE=0.793, SPF_HELO_NONE=0.001, SPF_PASS=-0.001, T_SCC_BODY_TEXT_LINE=-0.01 autolearn=no autolearn_force=no X-Spam_action: no action X-BeenThere: guile-user@gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: General Guile related discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: guile-user-bounces+guile-user=m.gmane-mx.org@gnu.org Original-Sender: "guile-user" Xref: news.gmane.io gmane.lisp.guile.user:18106 Archived-At: On Thu, 17 Feb 2022 at 16:59, Blake Shaw 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