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

From: Taylan Kammer <[email-masked]>
Date: Thu, 26 Sep 2024 21:15:06 +0200

On 26.09.2024 15:35, Maxim Cournoyer wrote:
> Hi Tomas,
>
> Tomas Volf <[email-masked]> writes:
>
>> Maxim Cournoyer <[email-masked]> writes:
>>
>>> This is an import of the 'Abstract', 'Rationale', and 'Specification'
>>> sections from the upstream specification text, with some manual
>>> adjustment.
>>>
>>> * doc/ref/srfi-modules.texi (SRFI 64): New subsection.
>> I think important question to ask here is whether this manual section
>> documents SRFI-64 or what Guile ships as SRFI-64.  Current
>> implementation shipped by Guile has many quirks that do not conform to
>> the specification.
>>
>>> +@c This SRFI 64 documentation was "snarfed" from upstream specification
>>> +@c HTML document using the 'snarfi' script.
>> 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 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.
>
>> described by the manual does not match the implementation shipped).
> I'd consider different behavior in the implementation compared to the
> specification bugs.
>

Let me once again advertise my implementation of SRFI 64, found here:

    https://codeberg.org/taylan/scheme-srfis/

The code is more readable and better structured, has fewer bugs (obeys the specification), and adds a small number of useful extensions, as explained here:

    https://codeberg.org/taylan/scheme-srfis/#srfi-64

The output of the default test runner is also a lot more informative, and handles nested test groups. (Prints the entire "path" hierarchy of the current test.) It's also more verbose though, which may be a matter of taste: It prints something for every test executed, whereas the reference implementation (the one used by Guile) only prints something for failed tests.

Sadly, the patch I previously sent to Guile for switching to this implementation was ignored, and Guile's R7RS support is still insufficient to use the R7RS SRFI libraries "out of the box."

However, for the convenience of Guile users, the latest commit contains the directory "guile-srfi-64" in the repo's root, which contains a copy of the implementation with file naming and module boilerplate that should work with all recent Guile versions. So, you can use it by adding the following to your GUILE_LOAD_PATH:

    $scheme_srfis_repo_root/guile-srfi-64

E.g. I can start guile like this, to use it in lieu of the implementation that ships with Guile:

    GUILE_LOAD_PATH=/home/taylan/src/scheme-srfis/guile-srfi-64 guile

Maybe someone will want to try it out, and push for its inclusion in Guile if they agree that it's a superior implementation.

All the best,

Taylan