From: Eli Zaretskii <eliz@gnu.org>
To: Doug Evans <xdje42@gmail.com>
Cc: gdb-patches@sourceware.org
Subject: Re: [PATCH v1 02/36] Guile extension language: doc additions
Date: Sun, 19 Jan 2014 16:57:00 -0000 [thread overview]
Message-ID: <83y52bj4dk.fsf@gnu.org> (raw)
In-Reply-To: <CAP9bCMSvvo5KvgK2aFjE4QzpuJ93CHygAjaGiMffkKfA-yeY7w@mail.gmail.com>
> 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.
next prev parent reply other threads:[~2014-01-19 16:57 UTC|newest]
Thread overview: 35+ messages / expand[flat|nested] mbox.gz Atom feed top
2013-12-24 19:03 Doug Evans
2013-12-25 19:27 ` Eli Zaretskii
2014-01-03 21:31 ` Ludovic Courtès
2014-01-04 7:12 ` Eli Zaretskii
2014-01-04 11:57 ` Ludovic Courtès
2014-01-04 14:41 ` Eli Zaretskii
2014-01-04 17:42 ` Ludovic Courtès
2014-01-04 20:00 ` Eli Zaretskii
2014-01-16 4:20 ` Doug Evans
2014-01-18 20:36 ` Doug Evans
2014-01-18 20:52 ` Ludovic Courtès
2014-01-18 20:55 ` Doug Evans
2014-01-19 16:58 ` Eli Zaretskii
2014-01-19 17:19 ` Doug Evans
2014-01-19 17:34 ` Eli Zaretskii
2014-01-19 17:53 ` Doug Evans
2014-01-19 18:10 ` Eli Zaretskii
2014-01-19 21:19 ` Doug Evans
2014-01-18 20:16 ` Doug Evans
2014-01-18 20:42 ` Ludovic Courtès
2014-01-18 21:57 ` Doug Evans
2014-01-19 14:46 ` Ludovic Courtès
2014-01-19 21:37 ` Doug Evans
2014-01-19 22:50 ` Ludovic Courtès
2014-01-18 22:32 ` Doug Evans
2014-01-19 14:47 ` Ludovic Courtès
2014-01-19 15:56 ` Eli Zaretskii
2014-01-19 16:13 ` Ludovic Courtès
2014-01-19 17:05 ` Doug Evans
2014-01-18 20:06 ` Doug Evans
2014-01-18 20:24 ` Eli Zaretskii
2014-01-18 20:53 ` Doug Evans
2014-01-19 16:57 ` Eli Zaretskii [this message]
2014-01-19 17:42 ` Doug Evans
2014-01-19 21:01 ` Doug Evans
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=83y52bj4dk.fsf@gnu.org \
--to=eliz@gnu.org \
--cc=gdb-patches@sourceware.org \
--cc=xdje42@gmail.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).