Re: [PATCH] Document R7RS bytevector functions

[Ludovic Courtès]

Hi Daniel,

lloda <lloda@sarc.name> skribis:

> Right now the manual just mentions (scheme base), but not the contents. This 
> patch at least makes sure that at least the bytevector-related R7RS functions 
> appear in the index.
>
> The patch documents a first group of purely bytevector functions and a second 
> group of binary I/O that are not elsewhere in Guile/R6RS or that exist but 
> have different definitions.

Nice.

> From 2b751615071aca023dac59db866fb09894fa2b57 Mon Sep 17 00:00:00 2001
> From: Daniel Llorens <lloda@sarc.name>
> Date: Fri, 13 Jan 2023 16:26:17 +0100
> Subject: [PATCH] Document R7RS functions related to bytevectors
>
> * doc/ref/api-data.texi: Document: bytevector bytevector-copy
>   bytevector-copy! bytevector-append
>   (r6:bytevector-copy): Index need not be positive (can be 0).
> * doc/ref/api-io.texi: Document: open-output-bytevector write-u8 read-u8 
> peek-u8
>   get-output-bytevector open-input-bytevector read-bytevector! read-bytevector
>   write-bytevector

Please specify the node names (see ‘git log’ for examples).

>  doc/ref/api-data.texi    | 102 ++++++++++++++++++++++++++++++---
>  doc/ref/api-io.texi      | 121 +++++++++++++++++++++++++++++++++++++++
>  lib/iconv_open-aix.h     |  68 +++++++++++-----------
>  lib/iconv_open-hpux.h    |  92 ++++++++++++++---------------
>  lib/iconv_open-irix.h    |  42 +++++++-------
>  lib/iconv_open-osf.h     |  80 +++++++++++++-------------
>  lib/iconv_open-solaris.h |  30 +++++-----

I guess the lib/ changes are unintended.  :-)

> +++ b/doc/ref/api-data.texi
> @@ -6188,9 +6188,9 @@ thus created is determined implicitly by the number of 
> arguments given.
>  Return a newly allocated vector composed of the
>  given arguments.  Analogous to @code{list}.
>  
> -@lisp
> +@example
>  (vector 'a 'b 'c) @result{} #(a b c)
> -@end lisp
> +@end example

Please keep @lisp as this gives information that can then be exploited
for syntax highlighting (‘texinfo --html’ doesn’t take advantage of it
so far, but in Guix we have machinery to do that.)

> +@ref{R7RS Support,R7RS} defines another set of bytevector functions in
> +the module @code{(scheme base)}. These functions are also described in this
> +section.

Please leave two spaces after and end-of-sentence period, to ease
navigation in Emacs and to please Texinfo (info "(texinfo) Ending a
Sentence").

Maybe these two sentences should go to the intro of the new subsection
(see below).

> @@ -6726,9 +6730,10 @@ procedures and C functions.
>  @deffnx {C Function} scm_c_make_bytevector (size_t len)
>  Return a new bytevector of @var{len} bytes.  Optionally, if @var{fill}
>  is given, fill it with @var{fill}; @var{fill} must be in the range
> -[-128,255].
> +[-128,255].@footnote{This function is defined both by R6RS in @code{(rnrs 
> bytevectors)} and by @ref{R7RS Standard Libraries,R7RS} in @code{(scheme 
> base)}.}.
>  @end deffn
>  
> +@anchor{x-bytevector?}
>  @deffn {Scheme Procedure} bytevector? obj
>  @deffnx {C Function} scm_bytevector_p (obj)
>  Return true if @var{obj} is a bytevector.
> @@ -6757,26 +6762,32 @@ length and contents.
>  @deffnx {C Function} scm_bytevector_fill_x (bv, fill)
>  Fill positions [@var{start} ... @var{end}) of bytevector @var{bv} with
>  byte @var{fill}. @var{start} defaults to 0 and @var{end} defaults to the
> -length of @var{bv}.@footnote{R6RS defines @code{(bytevector-fill! bv
> +length of @var{bv}.@footnote{R6RS only defines @code{(bytevector-fill! bv
>  fill)}. Arguments @var{start} and @var{end} are a Guile extension
>  (cf. @ref{x-vector-fill!,@code{vector-fill!}},
>  @ref{x-string-fill!,@code{string-fill!}}).}
>  @end deffn
>  
> +@anchor{x-r6:bytevector-copy!}
>  @deffn {Scheme Procedure} bytevector-copy! source source-start target 
> target-start len
>  @deffnx {C Function} scm_bytevector_copy_x (source, source_start, target, 
> target_start, len)
>  Copy @var{len} bytes from @var{source} into @var{target}, starting
> -reading from @var{source-start} (a positive index within @var{source})
> +reading from @var{source-start} (an index index within @var{source})
>  and writing at @var{target-start}.
>  
>  It is permitted for the @var{source} and @var{target} regions to
>  overlap. In that case, copying takes place as if the source is first
>  copied into a temporary bytevector and then into the destination.
> +
> +See also @ref{x-r7:bytevector-copy!,the R7RS version}.
>  @end deffn
>  
> +@anchor{x-r6:bytevector-copy}
>  @deffn {Scheme Procedure} bytevector-copy bv
>  @deffnx {C Function} scm_bytevector_copy (bv)
>  Return a newly allocated copy of @var{bv}.
> +
> +See also @ref{x-r7:bytevector-copy,the R7RS version}.
>  @end deffn

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.

> +@subsubheading Bytevector functions in R7RS

Please capitalize and use “procedure”:

  Bytevector Procedures in R7RS.

Here maybe you could first put the two intro sentences that you had
above, possibly listing procedures that are the same in both (rnrs
bytevectors) and (scheme base)?

After than you’d like the new procedures and those that are different,
like you already did.

> +@subsubheading Binary I/O in R7RS

This part LGTM.

Thanks!

Ludo’.