Re: [PATCH] Implement efficient 'scm_unget_bytes' and 'unget-bytevector'

[Mark H Weaver <mhw@netris.org>]

Hi Ludovic,

ludo@gnu.org (Ludovic Courtès) writes:

> Mark H Weaver <mhw@netris.org> skribis:
>
>> Here's an improved patch that also exports 'unget-bytevector' from
>> (ice-9 binary-ports).
>
> LGTM.

Excellent :)

>> I've used it to unget 15 megabytes, and it was quite fast.
>> Unfortunately, I'm at a bit of a loss of where to document it in the
>> manual.
>
> What about adding a sentence to mention (ice-9 bytevectors) under
> “Bytevectors”, and then ‘unget-bytevector’ under “R6RS Binary Input”?

The problem is that "R6RS Binary Input" describes procedures exported
from (rnrs io ports), but 'unget-bytevector' is not exported from that
module, nor should it be.

'unget-bytevector' is exported only from (ice-9 binary-ports), and there
is no section of the manual that describes that module.  It is only
mentioned briefly at the end of 6.14.10 (R6RS I/O Ports) as follows:

   A subset of the `(rnrs io ports)' module is provided by the `(ice-9
   binary-ports)' module.  It contains binary input/output procedures
   and does not rely on R6RS support.

Unfortunately, this patch invalidates the above claim that (ice-9
binary-ports) is a subset of (rnrs io ports).

I see no easy fix.  Maybe the documentation for the procedures exported
from (ice-9 binary-ports) should be moved into a separate "Binary I/O"
subsection of 6.14 (Input and Output), and the corresponding procedure
entries in 6.14.10 (R6RS I/O Ports) should cross-reference the new
subsection?

What do you think?

    Thanks!
      Mark