From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 22623 invoked by alias); 4 Jan 2014 07:12:41 -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 22613 invoked by uid 89); 4 Jan 2014 07:12:40 -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: mtaout20.012.net.il Received: from mtaout20.012.net.il (HELO mtaout20.012.net.il) (80.179.55.166) by sourceware.org (qpsmtpd/0.93/v0.84-503-g423c35a) with ESMTP; Sat, 04 Jan 2014 07:12:39 +0000 Received: from conversion-daemon.a-mtaout20.012.net.il by a-mtaout20.012.net.il (HyperSendmail v2007.08) id <0MYV00B007O54K00@a-mtaout20.012.net.il> for gdb-patches@sourceware.org; Sat, 04 Jan 2014 09:12:37 +0200 (IST) Received: from HOME-C4E4A596F7 ([87.69.4.28]) by a-mtaout20.012.net.il (HyperSendmail v2007.08) with ESMTPA id <0MYV00BW88103K40@a-mtaout20.012.net.il>; Sat, 04 Jan 2014 09:12:37 +0200 (IST) Date: Sat, 04 Jan 2014 07:12:00 -0000 From: Eli Zaretskii Subject: Re: [PATCH v1 02/36] Guile extension language: doc additions In-reply-to: <87sit4kb1t.fsf@gnu.org> To: ludo@gnu.org (Ludovic =?utf-8?Q?Court=C3=A8s?=) Cc: gdb-patches@sourceware.org Reply-to: Eli Zaretskii Message-id: <83eh4ow78t.fsf@gnu.org> MIME-version: 1.0 Content-type: text/plain; charset=utf-8 Content-transfer-encoding: 8BIT References: <52b9da59.64ab440a.0b0b.7e1c@mx.google.com> <83ha9w68av.fsf@gnu.org> <87sit4kb1t.fsf@gnu.org> X-IsSubscribed: yes X-SW-Source: 2014-01/txt/msg00024.txt.bz2 > 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{} 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.