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: Tue, 17 Jan 2023 10:17:17 +0100 Message-ID: <87cz7djzaa.fsf@gnu.org> References: <4ACA94E8-9A54-448E-86F1-DA1D3B6A044C@sarc.name> <87bkn19ncf.fsf@gnu.org> 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="5436"; 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 Tue Jan 17 10:18:06 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 1pHi6Y-0001BR-OY for guile-devel@m.gmane-mx.org; Tue, 17 Jan 2023 10:18:06 +0100 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1pHi5x-0004xf-58; Tue, 17 Jan 2023 04:17:29 -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 1pHi5r-0004xK-Q0 for guile-devel@gnu.org; Tue, 17 Jan 2023 04:17:24 -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 1pHi5r-0005uN-36; Tue, 17 Jan 2023 04:17:23 -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=v8Jw6TjQHllkmAHCzVzHzOolyf+m4FU/5+Z9zNN07gk=; b=YP03egpqByItpGih3aBS dBaFMrs5EiAiLXD2ZTtmY6BXWVvkRx0H0pQeyMtdr/7qzv+wcv9h4dCbmo2lFY/kBbp3v9KplnJYn +O6ohF2h3VsZcYPRZowweAu5V2C9LPp357VlXKH4pN4ctcAeFH/wpe+YDBPEEJ0GnwRcNtR2BVICy OXRkk24Kr9o7jMz/EyaKYzABuEoKeRSJ6kr8Hl/B3yAZ6PVQJ38YE3iKl3eibuXfuUaS4vzxU0iIG b41HfufREwivSaSk78D0PcfohBAF3Lg5a2+MS0/vBFsOLI0MjucRCG/ZqIPnpElxIidw18Vn9Gtv7 Poq2pl04Cw+pbg==; Original-Received: from [193.50.110.246] (helo=ribbon) by fencepost.gnu.org with esmtpsa (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1pHi5o-0000RI-KC; Tue, 17 Jan 2023 04:17:22 -0500 X-URL: http://www.fdn.fr/~lcourtes/ X-Revolutionary-Date: Octidi 28 =?utf-8?Q?Niv=C3=B4se?= an 231 de la =?utf-8?Q?R=C3=A9volution=2C?= jour du Zinc 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: (lloda@sarc.name's message of "Sun, 15 Jan 2023 23:06:09 +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:21592 Archived-At: Hi Daniel, lloda skribis: >> We should keep the manual in sync with docstrings in bytevectors.c. >>=20 >> 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 ma= in 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 proc= edure. Just in general, I think there should be many more links in the doc. Yes, I agree with that, I=E2=80=99m just not sure about the initial proposa= l. > From 547bd47887d7096e5568c31edb0b1661b1ac23ec Mon Sep 17 00:00:00 2001 > From: Daniel Llorens > 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=3D, 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 >=20=20 > +@subsubheading Bytevector Procedures in R7RS How about moving it at the bottom, after =E2=80=9CBytevectors as Uniform Vectors=E2=80=9D? Also make sure to update the menu at the beginning of the =E2=80=9CBytevect= ors=E2=80=9D node (you can use =E2=80=98M-x texinfo-make-menu=E2=80=99 if you use Emacs). OK for me with changes along these lines. Thank you! Ludo=E2=80=99.