Re: [PATCH v3 1/2] guile: Add support for Guile 2.2.

[Eli Zaretskii <eliz@gnu.org>]

> From: Ludovic Courtès <ludo@gnu.org>
> Date: Fri, 26 Jun 2020 10:13:32 +0200
> Cc: Ludovic Courtès <ludo@gnu.org>
> 
> diff --git a/gdb/NEWS b/gdb/NEWS
> index a116d62bca..37ab83618e 100644
> --- a/gdb/NEWS
> +++ b/gdb/NEWS
> @@ -117,6 +117,16 @@ GNU/Linux/RISC-V (gdbserver)	riscv*-*-linux*
>    ** Commands written in Python can be in the "TUI" help class by
>       registering with the new constant gdb.COMMAND_TUI.
>  
> +* Guile API
> +
> +  ** GDB can now be built with GNU Guile 2.2 in addition to 2.0.
> +
> +  ** Procedures 'memory-port-read-buffer-size',
> +     'set-memory-port-read-buffer-size!', 'memory-port-write-buffer-size',
> +     and 'set-memory-port-write-buffer-size!' are deprecated.  When
> +     using Guile 2.2 and later, users who need to control the size of
> +     a memory port's internal buffer can use the 'setvbuf' procedure.
> +

This part is OK.

>  @deffn {Scheme Procedure} set-memory-port-read-buffer-size! memory-port size
>  Set the size of the read buffer of @code{<gdb:memory-port>}
>  @var{memory-port} to @var{size}.  The result is unspecified.
> +
> +This procedure is deprecated and will be removed in @value{GDBN} 11.
> +When using Guile 2.2 or later, you can call @code{setvbuf} instead
> +(@pxref{Buffering, @code{setvbuf},, guile, GNU Guile Reference Manual}).

First, instead of "When using" I'd suggest to say "When @value{GDBN}
was built with".  And second, there's a certain conundrum here: the
node "Buffering" doesn't exist in the Guile v2.0.x manual, so I wonder
whether we should say something here about that to prevent user
surprise when the hyperlink causes an error.

>  @deffn {Scheme Procedure} set-memory-port-write-buffer-size! memory-port size
>  Set the size of the write buffer of @code{<gdb:memory-port>}
>  @var{memory-port} to @var{size}.  The result is unspecified.
> +
> +This procedure is deprecated and will be removed in @value{GDBN} 11.
> +When using Guile 2.2 or later, you can call @code{setvbuf} instead
> +(@pxref{Buffering, @code{setvbuf},, guile, GNU Guile Reference Manual}).
>  @end deffn

Here, I'd remove the @pxref: we already have the same hyperlink a
short ways above, so repetition is not necessary.

The documentation parts are okay with those nits fixed.

> +/* Whether we're using Guile < 2.2 and its clumsy port API.  */
> +
> +#define USING_GUILE_BEFORE_2_2					\
> +  (SCM_MAJOR_VERSION < 2					\
> +   || (SCM_MAJOR_VERSION == 2 && SCM_MINOR_VERSION == 0))

Since Guile < 2.0 is not supported, do we need the first part of the
macro?

Thanks.