From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Neil Jerram Newsgroups: gmane.lisp.guile.bugs Subject: Re: Typos in the manual Date: Sun, 13 Feb 2011 00:49:43 +0000 Message-ID: <874o88kbbs.fsf@ossau.uklinux.net> References: <20110208202529.GD16805@gmx.de> NNTP-Posting-Host: lo.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Trace: dough.gmane.org 1297558239 19170 80.91.229.12 (13 Feb 2011 00:50:39 GMT) X-Complaints-To: usenet@dough.gmane.org NNTP-Posting-Date: Sun, 13 Feb 2011 00:50:39 +0000 (UTC) Cc: bug-guile@gnu.org To: Ralf Wildenhues Original-X-From: bug-guile-bounces+guile-bugs=m.gmane.org@gnu.org Sun Feb 13 01:50:34 2011 Return-path: Envelope-to: guile-bugs@m.gmane.org Original-Received: from lists.gnu.org ([199.232.76.165]) by lo.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1PoQAa-0006PD-9T for guile-bugs@m.gmane.org; Sun, 13 Feb 2011 01:50:32 +0100 Original-Received: from localhost ([127.0.0.1]:39905 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1PoQAZ-0007Js-Kr for guile-bugs@m.gmane.org; Sat, 12 Feb 2011 19:50:31 -0500 Original-Received: from [140.186.70.92] (port=41573 helo=eggs.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1PoQAT-0007JX-OL for bug-guile@gnu.org; Sat, 12 Feb 2011 19:50:27 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1PoQAR-0004Ls-Gr for bug-guile@gnu.org; Sat, 12 Feb 2011 19:50:25 -0500 Original-Received: from mail3.uklinux.net ([80.84.72.33]:58011) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1PoQAR-0004BU-4P for bug-guile@gnu.org; Sat, 12 Feb 2011 19:50:23 -0500 Original-Received: from arudy (unknown [78.149.124.53]) by mail3.uklinux.net (Postfix) with ESMTP id CEECA1F6092; Sun, 13 Feb 2011 00:49:44 +0000 (GMT) Original-Received: from neil-laptop (unknown [192.168.11.4]) by arudy (Postfix) with ESMTP id 14BAA38013; Sun, 13 Feb 2011 00:49:44 +0000 (GMT) In-Reply-To: <20110208202529.GD16805@gmx.de> (Ralf Wildenhues's message of "Tue, 8 Feb 2011 21:25:30 +0100") User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/23.1 (gnu/linux) X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.4-2.6 X-Received-From: 80.84.72.33 X-BeenThere: bug-guile@gnu.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: "Bug reports for GUILE, GNU's Ubiquitous Extension Language" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Original-Sender: bug-guile-bounces+guile-bugs=m.gmane.org@gnu.org Errors-To: bug-guile-bounces+guile-bugs=m.gmane.org@gnu.org Xref: news.gmane.org gmane.lisp.guile.bugs:5119 Archived-At: Ralf Wildenhues writes: > Hello Guile developers, > > I found a few typos in the manual, actually, comparatively very few for > the size of the manual! The attached patches should fix them. Please > be scrupulous, I'm not firm in Guile language details nor habits. I applied all these except for the following that I wasn't sure about. > diff --git a/doc/ref/api-options.texi b/doc/ref/api-options.texi > index 7121784..57ba02e 100644 > --- a/doc/ref/api-options.texi > +++ b/doc/ref/api-options.texi > @@ -82,10 +82,11 @@ general are stored. On Unix-like systems, this is usually > Return the name of the directory where the Guile Scheme files that > belong to the core Guile installation (as opposed to files from a 3rd > party package) are installed. On Unix-like systems this is usually > -@file{/usr/local/share/guile/} or > -@file{/usr/share/guile/}; > +@file{/usr/local/share/guile/@var{GUILE_EFFECTIVE_VERSION}} or > +@file{/usr/share/guile/@var{GUILE_EFFECTIVE_VERSION}}; > > -@noindent for example @file{/usr/local/share/guile/1.6}. > +@noindent > +for example @file{/usr/local/share/guile/1.6}. > @end deffn > > @deffn {Scheme Procedure} %site-dir Will @var always generate appropriate markup for making it clear that GUILE_EFFECTIVE_VERSION isn't meant literally? I think that is what the < and > intend to indicate. > diff --git a/doc/ref/api-compound.texi b/doc/ref/api-compound.texi > index 2284b0d..e108da8 100644 > --- a/doc/ref/api-compound.texi > +++ b/doc/ref/api-compound.texi > @@ -1820,7 +1820,7 @@ have smaller rank than @var{array}. > @subsubsection Accessing Arrays from C > > Arrays, especially uniform numeric arrays, are useful to efficiently > -represent large amounts of rectangularily organized information, such as > +represent large amounts of information organized in a rectangular way, such as > matrices, images, or generally blobs of binary data. It is desirable to > access these blobs in a C like manner so that they can be handed to > external C code such as linear algebra libraries or image processing I'm afraid "organized in a rectangular way" is just as opaque to me as "rectangularily organized", so this isn't a clear improvement. I think readers will already know what array data is, so perhaps we can just delete that first sentence, and refactor the rest of the para to: " For interworking with external C code, Guile provides an API to allow C code to access the elements of a Scheme array. In particular, for uniform numeric arrays, the API exposes the underlying uniform data as a C array of numbers of the relevant type. " Any other suggestions? > diff --git a/doc/ref/api-data.texi b/doc/ref/api-data.texi > index fd2e7ee..59b6405 100644 > --- a/doc/ref/api-data.texi > +++ b/doc/ref/api-data.texi > @@ -225,8 +225,8 @@ rational is also real, and every real number is also a complex number > In addition to the classification into integers, rationals, reals and > complex numbers, Scheme also distinguishes between whether a number is > represented exactly or not. For example, the result of > -@m{2\sin(\pi/4),2*sin(pi/4)} is exactly @m{\sqrt{2},2^(1/2)}, but Guile > -can represent neither @m{\pi/4,pi/4} nor @m{\sqrt{2},2^(1/2)} exactly. > +@m{2\sin(\pi/4),2*sin(pi/4)} is exactly @m{\sqrt2,2^(1/2)}, but Guile > +can represent neither @m{\pi/4,pi/4} nor @m{\sqrt2,2^(1/2)} exactly. > Instead, it stores an inexact approximation, using the C type > @code{double}. Why is \sqrt2 better than \sqrt{2} ? > @@ -572,7 +572,7 @@ is an integer number or a rational number. > @deffnx {C Function} scm_rational_p (x) > Return @code{#t} if @var{x} is a rational number, @code{#f} otherwise. > Note that the set of integer values forms a subset of the set of > -rational numbers, i. e. the predicate will also be fulfilled if > +rational numbers, i.e.@: the predicate will also be fulfilled if > @var{x} is an integer number. > @end deffn Having read through your comments below, I understand this one, and will apply it. > @@ -4550,7 +4550,7 @@ representing the contents of @var{bv}, decoded according to > @deffnx {Scheme Procedure} sint-list->bytevector lst endianness size > @deffnx {C Function} scm_uint_list_to_bytevector (lst, endianness, size) > @deffnx {C Function} scm_sint_list_to_bytevector (lst, endianness, size) > -Return a new bytevector containing the unsigned (resp. signed) integers > +Return a new bytevector containing the unsigned (resp.@: signed) integers > listed in @var{lst} and encoded on @var{size} bytes according to > @var{endianness}. > @end deffn I don't think "resp." is reliably understood. I propose instead to separate each of the current 3 uses of "resp. signed" into separate signed and unsigned @deffns. > diff --git a/doc/ref/compiler.texi b/doc/ref/compiler.texi > index 8274a96..3c35cc8 100644 > --- a/doc/ref/compiler.texi > +++ b/doc/ref/compiler.texi > @@ -855,7 +855,7 @@ for more information about the Brainfuck language itself. > At this point, we break with the impersonal tone of the rest of the > manual, and make an intervention. Admit it: if you've read this far > into the compiler internals manual, you are a junkie. Perhaps a course > -at your university left you unsated, or perhaps you've always harbored > +at your university left you unsatisfied, or perhaps you've always harbored > a sublimated desire to hack the holy of computer science holies: a > compiler. Well you're in good company, and in a good position. Guile's > compiler needs your help. "unsated" is fine in English too, and I hesitate to tinker with Andy's fine prose. So I'd prefer to leave this as is. > There are a few things that I spotted that I didn't fix, either because > I didn't know which was the right way, or in cases that I've come to > know as contentious among developers. It would be nice if you could go > over them and address them in one way or another. Given consensus, I > might be prodded into patching some, but don't count on me. > > - Word pairs you might want to review and/or maybe just use one set of: > queuing vs. queueing, queuing. Listed by merriam-webster.com before "queueing", wins 2:1 in a googlefight, and is simpler. > destructur.* vs. destruct.* vs. deconstr.* > (unless they have different meanings of course), In general, I believe these are all validly different. I believe the use of "deconstructor" is idiomatic here (which is the only occurrence): " apply @code{force} to arguments of deconstructors (e.g., @code{car}, @code{cdr} and @code{null?}), " Similarly for the use of "destructuring" when talking about syntax. An easily imaginable mistake would be "destruct" (wrong) rather than "destroy" (right), but there aren't actually any instances of this. > uninterned vs. non-internal, "uninterned" is certainly idiomatic in the Lisp world. Where do you see "non-internal"? > latin1 vs. latin-1, I'm happy to defer to you on that. What do you recommend? > parsable vs. parseable. parsable. "parseable" is a clear mistake, I'd say. > - 'postpend': I'd replace this with 'append' throughout the tree > (not just the manual). I'm not seeing this.... (Have I missed some other discussion or patches in this area?) > - Some abbreviations are spelt creatively. The Latin 'id est' is > usually abbreviated 'i.e.' without an intervening space, and for good > spacing you either need a comma right afterwards, or '@:'. Same with > 'e.g.'. Find lots of instances with: > git grep '\<[Ii][. ]*e\.[^,@]' > > My personal preference is to use a comma when what follows is long or > grammatically a full sentence, and '@:' otherwise. (info texinfo "Not > Ending a Sentence"). Agreed. > - The Guile manual seems quite eager in making up new words. This is to > some extent a tendency that just comes with hacking, and has both > distinguished and entertaining aspects. At the same time however, it > can make things less accessible for new users, especially those with a > foreign native language, who then have troubles looking such words up > in some dictionary. It starts with very simple things like 'dir' and > 'arg' which I assume nobody has a serious problem with, yet which I > would always write as 'directory' and 'argument' in prose > (cf. 'info standards "GNU Manuals"'; but this goes beyond that > text). Agreed - patches appreciated. > OTOH, things like 'unpermanent', 'cdring', and 'consing' are not easy > to understand IMVHO. I'd say "consing" is a close call. On the one hand it's certainly idiomatic in Lisp/Scheme. On the other hand, a newbie would not know it. Perhaps the term just needs to be clearly explained in the section that describes lists, and maybe some references added from the other uses? The others are definitely unhelpful, and I'd be happy to accept a patch to fix them. > > - In the Autoconf section, several macros are added to the function > index. They come from doc/ref/autoconf{,-macros}.texi (one being > generated from meta/guile.m4. The macros are: > PKG_CHECK_MODULES > GUILE_PROGS > GUILE_FLAGS > GUILE_SITE_DIR > GUILE_CHECK_RETVAL > GUILE_MODULE_CHECK > GUILE_MODULE_AVAILABLE > GUILE_MODULE_REQUIRED > GUILE_MODULE_EXPORTS > GUILE_MODULE_REQUIRED_EXPORT > > The simplest way to fix this Fix what? > would be to adjust indices.texi to > document that Autoconf macros and variables are also listed in this > index. Karl tells me that one should have less indices anyway for the > autotools manuals (ideally just one), so this would seem like a step > in the right direction. Sorry, I'm not following here at all. > - I love France and the Franc, but there will soon be kids that don't > remember it, for which 'french currency string' will be a foreign > concept. It might be a good idea to update the example eventually. Indeed, yes. > Thanks for maintaining Guile, > Ralf Thanks for your detailed review and patches! Neil