Re: [PATCH v1 02/36] Guile extension language: doc additions

[ludo@gnu.org (Ludovic Courtès)]

Eli Zaretskii <eliz@gnu.org> skribis:

>> +Guile version 2.0.9 is well tested, earlier 2.0 versions are not.
>
> I'm not sure we should say this in the manual.

In practice the parts that are used (mostly the C API) have seen few
additions over 2.0, so it’s likely that it would work with any 2.0.x.

>> +The implementation uses Guile's @code{smob} (small object)
>                                                 ^^^^^^^^^^^^
> This should be in @dfn, as it's new terminology.

Better yet:

  (@pxref{Smobs,,, guile, GNU Guile Reference Manual})

[...]

>> +Therefore @code{eq?} does not work as expected.
>> +However @code{equal?} does work.
>> +
>> +@smallexample
>> +(gdb) guile (eq? (make-value 1) (make-value 1))
>> +$1 = #f
>> +(gdb) guile (equal? (make-value 1) (make-value 1))
>> +$1 = #t
>> +@end smallexample
>
> Wouldn't this be confusing for Scheme programmers?  Is it terribly
> hard to make eq? work?

We discussed this before, and I think that’s fine if it’s not doable, as
long as it’s clearly documented.

However, rather than “does not work as expected” (which could be
misleading), what about something like:

  ‘make-value’ always returns a fresh object.  Therefore,
  @code{<gdb:value>} returned by different calls to ‘make-value’ are
  usually different:

  @example
  (eq? (make-value 1) (make-value 1))
  @result{} #f

  (equal? (make-value 1) (make-value 1))
  @result{} #t
  @end example

>> +@defun value? object

What about distinguishing Scheme functions, like:

  @deffn {Scheme Procedure} value? object

>> +If @var{type} is not provided,
>> +a Scheme real is converted to the C @code{double} type for the
>> +current architecture.
>
> Isn't Guile built with libgmp?  If so, doesn't it support floats
> which, when converted to a double, will lose accuracy?

Guile uses GMP, but GMP is for integers (bignums).

Real numbers in Guile (numbers for which ‘real?’ returns #t) are either
doubles or rationals–called “inexact” and “exact”, respectively (info
"(guile) Real and Rational Numbers"):

  scheme@(guile-user)> (real? 3.14)
  $2 = #t
  scheme@(guile-user)> (real? 22/7)
  $3 = #t
  scheme@(guile-user)> 22/7
  $4 = 22/7
  scheme@(guile-user)> (exact->inexact 22/7)
  $5 = 3.142857142857143

There’s loss of accuracy only when converting a rational to a double.

>> +A Scheme string is converted to a target string, using the current
>> +target encoding.
>
> What if target encoding doesn't support some of the characters in the
> string?

Guile’s behavior can be controlled with
‘%default-port-conversion-strategy’: it can raise an exception, or
substitute any characters that could not be converted, or escape them
(info "(guile) Ports").

Perhaps this should be briefly mentioned, with a cross-ref.

>> +The optional @var{errors} argument is either @code{"strict"}
>> +or @code{"replace"}.  A value of @code{"strict"} corresponds to
>> +Guile's @code{SCM_FAILED_CONVERSION_ERROR} and a value of @code{"replace"}
>> +corresponds to Guile's @code{SCM_FAILED_CONVERSION_QUESTION_MARK}.
>
> Suggest a cross-reference to Guile documentation here.

Agreed.  Also, Guile talks of “conversion strategy” and “conversion
error handler”, with values ‘error’, ‘substitute’, and ‘escape’ (at the
Scheme level), and I’d recommend sticking to those names and terminology.

>> +If the optional @var{length} argument is given, the string will be
>> +fetched and encoded to the length of characters specified.  If
>> +the @var{length} argument is not provided, the string will be fetched
>> +and encoded until a null of appropriate width is found.
>
> Isn't this null termination description skewed towards C-like
> languages?  Aren't there languages where strings don't have to be
> null-terminated?

Yes, and that’s when LENGTH should be provided, AIUI.

(I agree with most of Eli’s other suggestions.)

Thanks to both of you,
Ludo’.