From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Daniel Tornabene Newsgroups: gmane.lisp.guile.user Subject: Re: Proposal: Deep Dive into the Guile Docs & Makeover Proposal Date: Tue, 8 Feb 2022 11:25:05 -0600 Message-ID: References: <87tud9olma.fsf@nonconstructivism.com> <87mtj15rax.fsf@laura> 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="37983"; mail-complaints-to="usenet@ciao.gmane.io" Cc: guix-user@gnu.org, guile-user , guix-days@gnu.org To: Olivier Dion Original-X-From: guile-user-bounces+guile-user=m.gmane-mx.org@gnu.org Tue Feb 08 20:19:42 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 1nHW1e-0009hk-BN for guile-user@m.gmane-mx.org; Tue, 08 Feb 2022 20:19:42 +0100 Original-Received: from localhost ([::1]:52914 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1nHW1d-00088E-9a for guile-user@m.gmane-mx.org; Tue, 08 Feb 2022 14:19:41 -0500 Original-Received: from eggs.gnu.org ([209.51.188.92]:51802) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1nHUF2-0000f0-Rz for guile-user@gnu.org; Tue, 08 Feb 2022 12:25:25 -0500 Original-Received: from [2a00:1450:4864:20::12d] (port=39699 helo=mail-lf1-x12d.google.com) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1nHUEy-00043N-So; Tue, 08 Feb 2022 12:25:23 -0500 Original-Received: by mail-lf1-x12d.google.com with SMTP id b9so34627926lfq.6; Tue, 08 Feb 2022 09:25:18 -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=3AZ//63n+3vYRFzouqfVxN/9niIhh9LvwRbKufB8L+g=; b=HtvC5mTEHl3gCL6YCcU11YP0NfOJnoszmGJxb4GXNy/Q9uAlbix0p8TqrVynbjS1yy MuTvJOGdW9VM25ranEb47o0+DCjFge4dNX41J5hKZ7pvgJm7b2t4Ef23cnNGPn4LC2m8 hdhtH+8XGAwTwJZ5dFCqmRVKOOb/PYoX0/QAkeb4zEOUoG8ZSP5TGQ1HBv+koZ2xOoFw FGakXcc+B2kREXgDdgcZQoToIVcDmB9TakTYQfzJQIizJp23Hr3mhUAqd/jdKiIIJ563 1+SxXAuFySXo9jxjwFM2GsCQblyrnCCfdSZqx4vZmjumSooK9n2iZZrD480GyjWtYwsv HcLw== 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=3AZ//63n+3vYRFzouqfVxN/9niIhh9LvwRbKufB8L+g=; b=KQFMoDK/sHjnTJMU99VW++RP6wGyxxwkzH29aXaTUOaTK4yqt4CtWmoKLpytFWYWQk bU3iEDpL/MZFjV1RH8ih++twgv7pQc+BZrMsrhADm1Od38TxuSJ716akBYXzW9KHj/TW uMtl4SPvZNm5F0b/ksDaItAJ+ia78IMixEOMRTrKPBXlEZX+AjnV4OjtomlCJiDKInZi g12FDiz1h+vXXWv5Bt+nxcYqTTiqch89RUeaCqNMLmT4GObinv2voUtCk1ENVddxq3jE ZClH8EiRvE4HpcmQQSXItCLqE7u+6hQ5oDI7EW+Tomvi9s6/eLZSj5H5knAPNDcfYCl1 Roeg== X-Gm-Message-State: AOAM532iVUteH5F+wyUwsE9nT7jMsIpj5WbgrLHnjVWn4DDdEI4RKI/K 02HZvkGz3VVVKOlZHz9o3aD/Mk+Qyp/CN/Zr7bk= X-Google-Smtp-Source: ABdhPJzsyf4OnYAKOnyPfw2wfsC23YR2Hh479B+QPQjn+sPRE3tVuZs5+pa0/UQzkK5JIuuuesiJvZoGV8fOgTTFMnc= X-Received: by 2002:ac2:4f8b:: with SMTP id z11mr3689965lfs.90.1644341117183; Tue, 08 Feb 2022 09:25:17 -0800 (PST) In-Reply-To: <87mtj15rax.fsf@laura> X-Host-Lookup-Failed: Reverse DNS lookup failed for 2a00:1450:4864:20::12d (failed) Received-SPF: pass client-ip=2a00:1450:4864:20::12d; envelope-from=d.t.peters777@gmail.com; helo=mail-lf1-x12d.google.com X-Spam_score_int: -10 X-Spam_score: -1.1 X-Spam_bar: - X-Spam_report: (-1.1 / 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_ENVFROM_END_DIGIT=0.25, FREEMAIL_FROM=0.001, HTML_MESSAGE=0.001, PDS_HP_HELO_NORDNS=0.001, 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-Content-Filtered-By: Mailman/MimeDel 2.1.29 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:18042 Archived-At: 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 wrote: > On Tue, 08 Feb 2022, Blake Shaw 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 > >