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

[ludo at gnu dot 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â.