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 22:29:58 +0000 Message-ID: <877hd3wot5.fsf@ossau.uklinux.net> References: <20110208202529.GD16805@gmx.de> <874o88kbbs.fsf@ossau.uklinux.net> <20110213070044.GA26711@gmx.de> NNTP-Posting-Host: lo.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Trace: dough.gmane.org 1297636218 11032 80.91.229.12 (13 Feb 2011 22:30:18 GMT) X-Complaints-To: usenet@dough.gmane.org NNTP-Posting-Date: Sun, 13 Feb 2011 22:30:18 +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 23:30:14 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 1PokSK-0007gU-Px for guile-bugs@m.gmane.org; Sun, 13 Feb 2011 23:30:12 +0100 Original-Received: from localhost ([127.0.0.1]:50749 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1PokSK-0005Bh-9B for guile-bugs@m.gmane.org; Sun, 13 Feb 2011 17:30:12 -0500 Original-Received: from [140.186.70.92] (port=44727 helo=eggs.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1PokSE-00059O-FY for bug-guile@gnu.org; Sun, 13 Feb 2011 17:30:07 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1PokSD-0002Zv-0T for bug-guile@gnu.org; Sun, 13 Feb 2011 17:30:06 -0500 Original-Received: from mail3.uklinux.net ([80.84.72.33]:34860) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1PokSC-0002ZR-Gg for bug-guile@gnu.org; Sun, 13 Feb 2011 17:30:04 -0500 Original-Received: from arudy (unknown [78.149.124.53]) by mail3.uklinux.net (Postfix) with ESMTP id 05EDC1F6635; Sun, 13 Feb 2011 22:30:02 +0000 (GMT) Original-Received: from neil-laptop (unknown [192.168.11.4]) by arudy (Postfix) with ESMTP id 28D473801E; Sun, 13 Feb 2011 22:29:59 +0000 (GMT) In-Reply-To: <20110213070044.GA26711@gmx.de> (Ralf Wildenhues's message of "Sun, 13 Feb 2011 08:00:44 +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:5130 Archived-At: Ralf Wildenhues writes: > Hi Neil, Hi Ralf, I pushed some more changes based on your input. Below has just a few specific notes. > * Neil Jerram wrote on Sun, Feb 13, 2011 at 01:49:43AM CET: >> >> 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. > > Well, @var is the intended way to denote metasyntactic variables. > In info output, it capitalizes, in PDF output it uses a different font > (or small caps IIRC). See 'info texinfo var'. It might sometimes be > a bit hard to always read them correctly in info output. I'm not sure > how info could be improved though. Yes, I'm convinced now and so have applied this. >> Why is \sqrt2 better than \sqrt{2} ? > > No idea, that was pure consistency at work: you already use \sqrt2 > elsewhere. Doesn't matter really. I went for \sqrt{2} everywhere - I think that avoids anyone (who doesn't immediately know the fine detail of TeX's lexer) wondering whether \sqrt2 might be a special TeX token. >> > - 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. > > Well. If you look at the Procedure Index of the manual, you will find > entries for the above Autoconf macros in there. The Procedure Index has > the following intro text: > > This is an alphabetical list of all the procedures and macros in Guile. > > When looking for a particular procedure, please look under its Scheme > name as well as under its C name. The C name can be constructed from > the Scheme names by a simple transformation described in the section > *Note API Overview::. > > In other words, no mention of "Autoconf macros", and I wouldn't expect > to find them there, among all the Scheme and C symbols. Now, you can > either fix the text to match the contents, or change the extractor to > not emit @deffn's for the Autoconf macro in doc/ref/autoconf-macros.texi > so that they don't end being listed in the Procedure Index. > > Is that clearer now? Yes, thanks; done as you and Karl recommend. Neil