From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: =?utf-8?Q?Ludovic_Court=C3=A8s?= Newsgroups: gmane.lisp.guile.devel Subject: Re: [PATCH] Document R7RS bytevector functions Date: Sat, 14 Jan 2023 15:56:16 +0100 Message-ID: <87bkn19ncf.fsf@gnu.org> References: <4ACA94E8-9A54-448E-86F1-DA1D3B6A044C@sarc.name> Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="27286"; mail-complaints-to="usenet@ciao.gmane.io" User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/28.2 (gnu/linux) Cc: guile-devel@gnu.org To: lloda Original-X-From: guile-devel-bounces+guile-devel=m.gmane-mx.org@gnu.org Sat Jan 14 15:56:49 2023 Return-path: Envelope-to: guile-devel@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1pGhxg-0006vM-VH for guile-devel@m.gmane-mx.org; Sat, 14 Jan 2023 15:56:49 +0100 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1pGhxJ-0000sM-T8; Sat, 14 Jan 2023 09:56:25 -0500 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1pGhxG-0000qb-4U for guile-devel@gnu.org; Sat, 14 Jan 2023 09:56:22 -0500 Original-Received: from fencepost.gnu.org ([2001:470:142:3::e]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1pGhxD-0000vY-Q8; Sat, 14 Jan 2023 09:56:21 -0500 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=MIME-Version:In-Reply-To:Date:References:Subject:To: From; bh=lc+dW/SnQ6oyx8+tHr60oWL0E+hKUcZYeGTmQBcdPNA=; b=JOLmB6BOE+y4wbmeEpWQ fBZbaZ8rhl4huC/qzlwhXSns1DGcq93BhQ0mJVbjVnarv5W83Oola0R1+rqZaySEEI4Xo531i1wWf Lg4XP51aQ40/GVu4pqt/aYKurs7UwQnuz829bc+//e7k4dt+ag+I5jPuaaVyQhTNngV6tBygZ50qR B8NuAh0TdxkBp5W+inXsebuj39AquN7Bs3uu2lCkx7guqslNFL/JejiD4uCvcM99uu7BRInTNSIzx KZFU6GBURJbRiPKEVeAy3S6J3XRJ9rhT3SeolT27c+MEalDomaKfo4XgO1MYBda4CrwSIS7APt4NF gVWP4OPj2oTjPA==; Original-Received: from 91-160-117-201.subs.proxad.net ([91.160.117.201] helo=ribbon) by fencepost.gnu.org with esmtpsa (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1pGhxD-000419-2P; Sat, 14 Jan 2023 09:56:19 -0500 X-URL: http://www.fdn.fr/~lcourtes/ X-Revolutionary-Date: Quintidi 25 =?utf-8?Q?Niv=C3=B4se?= an 231 de la =?utf-8?Q?R=C3=A9volution=2C?= jour du Chat X-PGP-Key-ID: 0x090B11993D9AEBB5 X-PGP-Key: http://www.fdn.fr/~lcourtes/ludovic.asc X-PGP-Fingerprint: 3CE4 6455 8A84 FDC6 9DB4 0CFB 090B 1199 3D9A EBB5 X-OS: x86_64-pc-linux-gnu In-Reply-To: <4ACA94E8-9A54-448E-86F1-DA1D3B6A044C@sarc.name> (lloda@sarc.name's message of "Fri, 13 Jan 2023 19:05:53 +0100") X-BeenThere: guile-devel@gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: "Developers list for Guile, the GNU extensibility library" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: guile-devel-bounces+guile-devel=m.gmane-mx.org@gnu.org Original-Sender: guile-devel-bounces+guile-devel=m.gmane-mx.org@gnu.org Xref: news.gmane.io gmane.lisp.guile.devel:21581 Archived-At: Hi Daniel, lloda skribis: > Right now the manual just mentions (scheme base), but not the contents. T= his patch at least makes sure that at least the bytevector-related R7RS fun= ctions appear in the index. > > The patch documents a first group of purely bytevector functions and a se= cond 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 > 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-bytev= ector > write-bytevector Please specify the node names (see =E2=80=98git log=E2=80=99 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}. >=20=20 > -@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 (=E2=80=98texinfo --html=E2=80=99 doesn=E2=80=99t t= ake 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 t= his > +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{(rnr= s bytevectors)} and by @ref{R7RS Standard Libraries,R7RS} in @code{(scheme = base)}.}. > @end deffn >=20=20 > +@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 >=20=20 > +@anchor{x-r6:bytevector-copy!} > @deffn {Scheme Procedure} bytevector-copy! source source-start target ta= rget-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}. >=20=20 > 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 >=20=20 > +@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 =E2=80=9Cprocedure=E2=80=9D: 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=E2=80=99d like the new procedures and those that are differe= nt, like you already did. > +@subsubheading Binary I/O in R7RS This part LGTM. Thanks! Ludo=E2=80=99.