From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 27453 invoked by alias); 19 Jan 2014 16:57:59 -0000 Mailing-List: contact gdb-patches-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: gdb-patches-owner@sourceware.org Received: (qmail 27427 invoked by uid 89); 19 Jan 2014 16:57:58 -0000 Authentication-Results: sourceware.org; auth=none X-Virus-Found: No X-Spam-SWARE-Status: No, score=-3.0 required=5.0 tests=AWL,BAYES_00,RCVD_IN_DNSWL_NONE,SPF_SOFTFAIL autolearn=no version=3.3.2 X-HELO: mtaout23.012.net.il Received: from mtaout23.012.net.il (HELO mtaout23.012.net.il) (80.179.55.175) by sourceware.org (qpsmtpd/0.93/v0.84-503-g423c35a) with ESMTP; Sun, 19 Jan 2014 16:57:57 +0000 Received: from conversion-daemon.a-mtaout23.012.net.il by a-mtaout23.012.net.il (HyperSendmail v2007.08) id <0MZN00D00QWRQH00@a-mtaout23.012.net.il> for gdb-patches@sourceware.org; Sun, 19 Jan 2014 18:57:54 +0200 (IST) Received: from HOME-C4E4A596F7 ([87.69.4.28]) by a-mtaout23.012.net.il (HyperSendmail v2007.08) with ESMTPA id <0MZN00DMUR4IO630@a-mtaout23.012.net.il>; Sun, 19 Jan 2014 18:57:54 +0200 (IST) Date: Sun, 19 Jan 2014 16:57:00 -0000 From: Eli Zaretskii Subject: Re: [PATCH v1 02/36] Guile extension language: doc additions In-reply-to: To: Doug Evans Cc: gdb-patches@sourceware.org Reply-to: Eli Zaretskii Message-id: <83y52bj4dk.fsf@gnu.org> References: <52b9da59.64ab440a.0b0b.7e1c@mx.google.com> <83ha9w68av.fsf@gnu.org> <83a9etjawt.fsf@gnu.org> X-IsSubscribed: yes X-SW-Source: 2014-01/txt/msg00715.txt.bz2 > Date: Sat, 18 Jan 2014 12:53:11 -0800 > From: Doug Evans > Cc: "gdb-patches@sourceware.org" > > On Sat, Jan 18, 2014 at 12:24 PM, Eli Zaretskii wrote: > >> Date: Sat, 18 Jan 2014 12:06:46 -0800 > >> From: Doug Evans > >> Cc: "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{} 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.