From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Olivier Dion via General Guile related discussions Newsgroups: gmane.lisp.guile.user Subject: Re: Proposal: Deep Dive into the Guile Docs & Makeover Proposal Date: Tue, 08 Feb 2022 10:08:54 -0500 Message-ID: <87mtj15rax.fsf@laura> References: <87tud9olma.fsf@nonconstructivism.com> Reply-To: Olivier Dion Mime-Version: 1.0 Content-Type: text/plain Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="26848"; mail-complaints-to="usenet@ciao.gmane.io" Cc: guile-user@gnu.org, guix-user@gnu.org To: Blake Shaw , guix-days@gnu.org Original-X-From: guile-user-bounces+guile-user=m.gmane-mx.org@gnu.org Tue Feb 08 17:13:24 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 1nHT7M-0006rI-8T for guile-user@m.gmane-mx.org; Tue, 08 Feb 2022 17:13:24 +0100 Original-Received: from localhost ([::1]:49984 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1nHT7K-0004Z7-GM for guile-user@m.gmane-mx.org; Tue, 08 Feb 2022 11:13:22 -0500 Original-Received: from eggs.gnu.org ([209.51.188.92]:37876) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1nHS7K-0002ji-VY for guile-user@gnu.org; Tue, 08 Feb 2022 10:09:21 -0500 Original-Received: from smtp.polymtl.ca ([132.207.4.11]:42536) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1nHS7G-0006C1-S3; Tue, 08 Feb 2022 10:09:18 -0500 Original-Received: from localhost (modemcable094.169-200-24.mc.videotron.ca [24.200.169.94]) by smtp.polymtl.ca (8.14.7/8.14.7) with ESMTP id 218F8sXB002689 (version=TLSv1/SSLv3 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=NOT); Tue, 8 Feb 2022 10:08:59 -0500 DKIM-Filter: OpenDKIM Filter v2.11.0 smtp.polymtl.ca 218F8sXB002689 In-Reply-To: <87tud9olma.fsf@nonconstructivism.com> X-Poly-FromMTA: (modemcable094.169-200-24.mc.videotron.ca [24.200.169.94]) at Tue, 8 Feb 2022 15:08:54 +0000 Received-SPF: pass client-ip=132.207.4.11; envelope-from=olivier.dion@polymtl.ca; helo=smtp.polymtl.ca X-Spam_score_int: -41 X-Spam_score: -4.2 X-Spam_bar: ---- X-Spam_report: (-4.2 / 5.0 requ) BAYES_00=-1.9, RCVD_IN_DNSWL_MED=-2.3, RCVD_IN_MSPIKE_H3=0.001, RCVD_IN_MSPIKE_WL=0.001, SPF_HELO_PASS=-0.001, SPF_PASS=-0.001, T_SCC_BODY_TEXT_LINE=-0.01 autolearn=ham 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:18035 Archived-At: 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