Re: [PATCH] Document R7RS bytevector functions

["Ludovic Courtès" <ludo@gnu.org>]

Hi Daniel,

lloda <lloda@sarc.name> skribis:

>> We should keep the manual in sync with docstrings in bytevectors.c.
>> 
>> Thus, my suggestion would be to not insert comments and footnotes about
>> R7RS in the existing sections, but instead to do that in the new section.
>
> Following this, I've removed the footnotes & references to R7RS in the main section.
>
> Patch aside:
>
> I still think the links are useful, so I'd like to find a way to put them back. I think someone who finds their way into the doc for r6rs bytevector-copy should be told that there are in fact different versions of this procedure. Just in general, I think there should be many more links in the doc.

Yes, I agree with that, I’m just not sure about the initial proposal.

> From 547bd47887d7096e5568c31edb0b1661b1ac23ec Mon Sep 17 00:00:00 2001
> From: Daniel Llorens <lloda@sarc.name>
> Date: Sun, 15 Jan 2023 22:41:48 +0100
> Subject: [PATCH] Document R7RS functions related to bytevectors
>
> * doc/ref/api-data.texi (Bytevectors): Document R7RS bytevector,
>   bytevector-copy, bytevector-copy!, bytevector-append.
>   Fix typo in (r6:bytevector-copy), index need not be positive.
>   Fix typos in bytevector-length, bytevector=, bytevector-fill!.
> * doc/ref/api-io.texi (Binary I/O): Document R7RS
>   open-output-bytevector, write-u8, read-u8, peek-u8,
>   get-output-bytevector, open-input-bytevector, read-bytevector!,
>   read-bytevector, write-bytevector.

[...]

> -A @dfn{bytevector} is a raw bit string.  The @code{(rnrs bytevectors)}
> +A @dfn{bytevector} is a raw byte string.  The @code{(rnrs bytevectors)}
>  module provides the programming interface specified by the
>  @uref{http://www.r6rs.org/, Revised^6 Report on the Algorithmic Language
>  Scheme (R6RS)}.  It contains procedures to manipulate bytevectors and
                  ^
Actually here we could insert something like:

  The R7RS also supports this interface with some additions and minor
  differences (@pxref{Bytevector Procedures in R7RS}).

> @@ -6799,6 +6804,86 @@ Return the length in bytes of bytevector @var{bv}.
>  Return a pointer to the contents of bytevector @var{bv}.
>  @end deftypefn
>  
> +@subsubheading Bytevector Procedures in R7RS

How about moving it at the bottom, after “Bytevectors as Uniform
Vectors”?

Also make sure to update the menu at the beginning of the “Bytevectors”
node (you can use ‘M-x texinfo-make-menu’ if you use Emacs).

OK for me with changes along these lines.

Thank you!

Ludo’.