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

[Eli Zaretskii <eliz@gnu.org>]

> From: ludo@gnu.org (Ludovic Courtès)
> Date: Fri, 03 Jan 2014 22:30:54 +0100
> 
> >> +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})

Yes, a cross-reference in addition to @dfn is the best.

> 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

This is better, thanks.

> >> +@defun value? object
> 
> What about distinguishing Scheme functions, like:
> 
>   @deffn {Scheme Procedure} value? object

If it's important (is it?), then yes.

> >> +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).

What about long double support?

> >> +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.

It should, because the issue will certainly arise, especially since
(AFAIU) Guile prefers UTF-8.

> >> +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.

Right.

> >> +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.

Then I guess the above should say that explicitly.  But it would be
nice if GDB could support strings in languages that don't
null-terminate even without LENGTH.

Thanks.