bug#71300: [PATCH v3] doc: Document SRFI 64.

Tomas Volf <[email protected]> Wed, 23 Oct 2024 02:29:34 +0200
Newsgroups	gmane.lisp.guile.bugs
Message-ID	<[email protected]>
Maxime Devos <[email protected]> writes:

>>> Based on this I believe it describes the specification.
>>
>>That's correct. It's been slightly modified in places where it said
>>things like "left to the implementation" and I was able to verify what
>>the current implementation in Guix does.
>
> I assume Guix->Guile.
>
> This modification of “left to the implementation” -> “what Guile does” is
> problematic, since it misleads readers into thinking this is the standard
> behaviour (it is after all named SRFI 64, not GRFI 64).
>
> “What Guile does” is also important information to have.
>
> To avoid this problem, when it documents a choice made by Guile, it should indicate in some way that this is Guile behaviour.
> (E.g.: “It is left to the implementation what happens when A. Guile chooses to
> B.”, or “It is left to the implementation what happens when A. Guile currently
> chooses to B, but may choose differently in future versions.”)
>
>>> I think either of those is fine (albeit describing the Guile's flavor
>>> would be preferred), but is should be stated (that the behavior
>>There's not really a Guile flavor; it's more like the reference
> implementation flavor ;-).  The one in Guile is pretty stock.
>
> Then Guile flavour is stock flavour, and stock flavour isn’t specification
> vanilla. From what I’ve heard, it’s not just sprinkles added to vanilla, it also
> has bugs (not the crunchy food kind).

Since Ludovic was so kind to merge my patch replacing the SRFI-64
implementation with a new version, to use your wording, Guile flavour is
no longer stock flavour, and should be pretty close to specification
vanilla.  I believe that should simplify documenting it.

I explicitly tried to stick as close as possible to the specification.
Those few implementation choices I made are described in the info manual
for my guile library.  For your convenience, HTML version can be found
here[0].  The next section (2.9.2) could possibly be of use as well.

0: https://files.wolfsden.cz/manuals/guile-wolfsden/guile-wolfsden-0.0.4.html#SRFI_002d64-implementation-choices

Have a nice day,
Tomas
signature.asc (application/pgp-signature, 853 B)