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

[Eli Zaretskii <eliz at gnu dot org>]

> Date: Sat, 18 Jan 2014 12:53:11 -0800
> From: Doug Evans <xdje42@gmail.com>
> Cc: "gdb-patches@sourceware.org" <gdb-patches@sourceware.org>
> 
> On Sat, Jan 18, 2014 at 12:24 PM, Eli Zaretskii <eliz@gnu.org> wrote:
> >> Date: Sat, 18 Jan 2014 12:06:46 -0800
> >> From: Doug Evans <xdje42@gmail.com>
> >> Cc: "gdb-patches@sourceware.org" <gdb-patches@sourceware.org>
> >>
> >> >> +@value{GDBN} is not thread-safe.  If your Guile program uses multiple
> >> >> +threads, you must be careful to only call @value{GDBN}-specific
> >> >> +functions in the main @value{GDBN} thread.
> >> >
> >> > What is "the main GDB thread" here?
> >>
> >> I think the current wording is sufficient.
> >
> > 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"?

> >> >> +@emph{Note:} @value{GDBN}'s value history is independent of Guile's.
> >> >> +@code{$1} in @value{GDBN}'s value history is not @code{$1} from Guile's
> >> >> +history, nor is the reverse true.
> >> >
> >> > See comment about this above.  Also, which history are you talking
> >> > about here: the one from Guile evaluation or the one from GDB?
> >>
> >> Not sure I understand, the text refers to both.
> >> $1 when used in a Scheme expression is not the same value as $1 used
> >> in a GDB expression.
> >> I'm happy to reword this as desired, I'm just not sure what.
> >
> > Instead of that $1 is NOT, I suggest to say what it IS.
> 
> How about this?
> 
> @emph{Note:} @value{GDBN}'s value history is independent of Guile's.
> @code{$1} in @value{GDBN}'s value history contains the result of evaluating
> an expression from @value{GDBN}'s command line and @code{$1} from Guile's
> history contains the result of evaluating an expression from Guile's
> command line (@dfn{repl})

That's fine, thanks.

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

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

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