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

[Doug Evans <xdje42@gmail.com>]

On Sun, Jan 19, 2014 at 8:57 AM, Eli Zaretskii <eliz@gnu.org> wrote:
>> > My pointy was that GDB, AFAIK, is single threaded.  So talking about
>> > "the main GDB thread" creates an illusion that there are other "GDB
>> > threads", which I think don't exist.
>>
>> I could say "the main thread" since that's where GDB "lives".
>
> How about "the GDB thread"?

Done.

>> >> >> +@defun data-directory
>> >> >> +Return a string containing @value{GDBN}'s data directory.
>> >> >
>> >> > Should we mention that this string is in UTF-8 (I think) encoding?
>> >>
>> >> Strings don't have an encoding per se, they're sequences of unicode code points.
>> >
>> > ??? Are you saying the data directory is returned as a wchar_t array?
>>
>> Unicode strings have an internal and an external representation.
>> Internally, they are represented using "code points".
>> It is only when strings are represented in an external representation
>> (e.g. written to a file) that the encoding comes into play.
>
> I'm not sure I understand (or agree).  But in this case, all I care
> about is the POV of the GDB user who writes a Guile script to be used
> with GDB.  Does such a user need to know anything about the
> representation and/or encoding of the data-directory string to be able
> to use it correctly, display it, etc.?

I would apply the same view for data-directory as for all Guile functions that
return strings.  The encoding is not needed when calling things like
string-append.
When the encoding is needed it is the responsibility of *that*
function to provide
a means to specify the encoding, and those functions don't say what encoding
the provided string is in, they specify the encoding to emit the
provided string as.
Guile strings have no encoding (internally, Guile could store strings as utf8,
or a hybrid of narrow and wide (which is what it does today)), but to the Scheme
user a string is a sequence of unicode code points, there is no
inherent encoding.

>> >> >> +A Scheme boolean is converted to @var{type} if provided, otherwise
>> >> >
>> >> > You already described how "type" is handled, no need to repeat that
>> >> > (here and elsewhere in this part).
>> >>
>> >> If a type is not provided I need to say what happens and it's
>> >> different for each kind of value.
>> >> It's not clear to me how to distinguish the two cases in prose without
>> >> having something like the text that is there now.
>> >> Suggestions?
>> >
>> > Which two cases?  (I've read the original way too long ago to
>> > remember.)
>>
>> case 1: the type is not provided and a default must be chosen
>>
>> case 2: the type is provided
>
> Case 2 was already explained before this text:
>
>   +@defun make-value value @r{[}#:type type@r{]}
>   +Many Scheme values can be converted directly to a @code{<gdb:value>} via
>   +with this procedure.  If @var{type} is specified, the result is a value
>   +of this type, and if @var{value} can't be represented with this type
>   +an exception is thrown.  Otherwise the type of the result is determined from
>   +@var{value} as described below.
>
> So all is left is to describe Case 1.  Therefore, I suggest to replace
>
>   +The following Scheme objects are accepted for @var{value}:
>
> with
>
>   Here's how Scheme values are converted when @var{type} argument to
>   @code{make-value} is not specified:
>
> and then rephrase the information about the specific types like this:
>
>   @table @asis
>   @item Scheme boolean
>   A Scheme boolean is converted to the boolean type of the current
>   language.
>
>   @item Scheme integer
>   A Scheme integer is converted to the first of a C @code{int}, ...
>
> etc., you get the idea.

Done.

>> >> >> +@findex TYPE_CODE_INTERNAL_FUNCTION
>> >> >> +@item TYPE_CODE_INTERNAL_FUNCTION
>> >> >> +A function internal to @value{GDBN}.  This is the type used to represent
>> >> >> +convenience functions.
>> >> >
>> >> > A cross-reference to where convenience functions are described would
>> >> > be nice here.
>> >>
>> >> Righto.  But that needs to wait until support for convenience
>> >> functions is implemented.
>> >
>> > I thought we already had them in GDB.
>>
>> GDB does, but there's no access to them yet from Guile.
>> When that is provided the cross-reference should point there.
>
> I meant a cross-reference to where GDB convenience functions are
> described, in case the reader isn't familiar with the concept, or
> wants to refresh her memory for some reason.

Done.