Hi, following the discussion in IRC yesterday that made the point again that newcomers often don’t understand ice-9 I would suggest to start with the least invasive solution to that: mentioning ice-9 in the documentation more clearly.
Currently ice-9 is explained only in a single footnote in the chapter Using Modules, whics is very easy to miss. This patch adds four more mentions of ice-9 in places where I would have expected to see it:
From 2c61db75b2cbd32e8be52d4aedf469ca2cfed280 Mon Sep 17 00:00:00 2001 From: Arne Babenhauserheide <[email protected]> Date: Tue, 22 Sep 2026 08:38:11 +0200 Subject: [PATCH] Mention ice-9 more clearly in the documentation. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The reason for this change is that many users only understand ice-9 pretty late, and an obvous reason for that is that ice-9 was explained only in a single footnote in the chapter Using Modules. * doc/ref/intro.texi (Guile and Scheme): note that Guile expands upon the standard, usually with ice-9, but also with other namespaces. * doc/ref/api-modules.texi (General Information about Modules): note that ice-9 is the namespace for most extensions that Guile provides beyond the standard. * doc/ref/api-modules.texi (Using Guile Modules): mention that open-input-pipe comes from Guile’s extensions (ice-9 …). --- doc/ref/api-modules.texi | 8 +++++++- doc/ref/intro.texi | 13 +++++++++---- 2 files changed, 16 insertions(+), 5 deletions(-) diff --git a/doc/ref/api-modules.texi b/doc/ref/api-modules.texi index c8cb6413b..08b28392f 100644 --- a/doc/ref/api-modules.texi +++ b/doc/ref/api-modules.texi @@ -89,6 +89,11 @@ When Guile goes to use an interface from a module, for example yet, Guile searches a @dfn{load path} for a file that might define it, and loads that file. +@code{ice-9} is the namespace used for most modules that Guile provides on +top of the Scheme standards. The name refers to a seed crystal that +starts a crystallization process. Some larger groups of modules have +their own namespaces. + The following subsections go into more detail on using, creating, installing, and otherwise manipulating modules and the module system. @@ -114,7 +119,8 @@ interface is the one accessed. For example: Here, the interface specification is @code{(ice-9 popen)}, and the result is that the current module now has access to @code{open-pipe}, -@code{close-pipe}, @code{open-input-pipe}, and so on (@pxref{Pipes}). +@code{close-pipe}, @code{open-input-pipe}, and so on (@pxref{Pipes}) +from within Guile’s extensions (@code{ice-9}). Note in the previous example that if the current module had already defined @code{open-pipe}, that definition would be overwritten by the diff --git a/doc/ref/intro.texi b/doc/ref/intro.texi index dda330bdd..a9d017b66 100644 --- a/doc/ref/intro.texi +++ b/doc/ref/intro.texi @@ -84,6 +84,10 @@ practical needs, such as multithreaded programming and multidimensional arrays. Guile supports many SRFIs, as documented in detail in @ref{SRFI Support}. +On top of these standards, Guile provides its own library, mainly found +in @code{ice-9}, though some larger modules have their own namespace. They +are documented in @xref{Using Modules}. + The process that led to the R6RS standard brought a split in the Scheme community to the surface. The implementors that wrote R6RS considered that it was impossible to write useful, portable programs in R5RS, and @@ -104,10 +108,11 @@ communities: Racket, Clojure, Concurrent ML, and so on. In summary, Guile supports writing and running code written to the R5RS, R6RS, and R7RS Scheme standards, and also supports a number of SRFI -modules. However for most users, until a need for cross-implementation -portability has been identified, we recommend using the parts of Guile -that are useful in solving the problem at hand, regardless of whether -they proceed from a standard or whether they are Guile-specific. +modules and its own extensions in the @code{ice-9} namespace. For most users, +until a need for cross-implementation portability has been identified, +we recommend using the parts of Guile that are useful in solving the +problem at hand, regardless of whether they originate from a standard or +are Guile-specific. @node Combining with C -- 2.54.0
Best wishes, Arne -- Unpolitisch sein heißt politisch sein, ohne es zu merken. https://www.draketo.de
signature.asc
Description: PGP signature
