From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Wolfgang Jenkner Newsgroups: gmane.emacs.bugs Subject: bug#13292: 24.3.50; wrong sytax description in (elisp) Case Tables Date: Sat, 29 Dec 2012 01:21:05 +0100 Message-ID: <851ue9ofyk.fsf@iznogoud.viz> References: <83a9sym8q8.fsf@gnu.org> <83623mm3lh.fsf@gnu.org> NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain X-Trace: ger.gmane.org 1356741190 19761 80.91.229.3 (29 Dec 2012 00:33:10 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Sat, 29 Dec 2012 00:33:10 +0000 (UTC) To: 13292@debbugs.gnu.org Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Sat Dec 29 01:33:26 2012 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by plane.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1TokMf-0001DQ-O0 for geb-bug-gnu-emacs@m.gmane.org; Sat, 29 Dec 2012 01:33:25 +0100 Original-Received: from localhost ([::1]:55106 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1TokMR-0003Z7-7M for geb-bug-gnu-emacs@m.gmane.org; Fri, 28 Dec 2012 19:33:11 -0500 Original-Received: from eggs.gnu.org ([208.118.235.92]:49349) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1TokMO-0003Z0-BQ for bug-gnu-emacs@gnu.org; Fri, 28 Dec 2012 19:33:09 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1TokMN-0004ua-20 for bug-gnu-emacs@gnu.org; Fri, 28 Dec 2012 19:33:08 -0500 Original-Received: from debbugs.gnu.org ([140.186.70.43]:53363) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1TokMM-0004uU-UR for bug-gnu-emacs@gnu.org; Fri, 28 Dec 2012 19:33:06 -0500 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.72) (envelope-from ) id 1TokNG-0002AJ-31 for bug-gnu-emacs@gnu.org; Fri, 28 Dec 2012 19:34:02 -0500 X-Loop: help-debbugs@gnu.org In-Reply-To: Resent-From: Wolfgang Jenkner Original-Sender: debbugs-submit-bounces@debbugs.gnu.org Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sat, 29 Dec 2012 00:34:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 13292 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: Original-Received: via spool by 13292-submit@debbugs.gnu.org id=B13292.13567412358311 (code B ref 13292); Sat, 29 Dec 2012 00:34:02 +0000 Original-Received: (at 13292) by debbugs.gnu.org; 29 Dec 2012 00:33:55 +0000 Original-Received: from localhost ([127.0.0.1]:35381 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.72) (envelope-from ) id 1TokN7-00029y-GW for submit@debbugs.gnu.org; Fri, 28 Dec 2012 19:33:55 -0500 Original-Received: from mx08.lb01.inode.at ([62.99.145.8]:46248 helo=mx.inode.at) by debbugs.gnu.org with esmtp (Exim 4.72) (envelope-from ) id 1TokN3-00029n-T0 for 13292@debbugs.gnu.org; Fri, 28 Dec 2012 19:33:51 -0500 Original-Received: from [91.119.206.19] (port=7639 helo=iznogoud.viz) by smartmx-08.inode.at with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.69) (envelope-from ) id 1TokM9-0003vD-H9; Sat, 29 Dec 2012 01:32:53 +0100 Original-Received: from wolfgang by iznogoud.viz with local (Exim 4.80.1 (FreeBSD)) (envelope-from ) id 1TokM8-0000Vk-1Z; Sat, 29 Dec 2012 01:32:52 +0100 User-Agent: Gnus/5.130006 (Ma Gnus v0.6) Emacs/24.3.50 (berkeley-unix) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.13 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6.x X-Received-From: 140.186.70.43 X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Original-Sender: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.bugs:69134 Archived-At: On Fri, Dec 28 2012, Eli Zaretskii wrote: >> From: "Drew Adams" [...] >> In that case, there are bugs in the other direction, in other nodes of the >> manual - nodes that use uppercase for parameters. >> >> For example: >> >> `A Sample Function Description' - `count-loop' >> `Syntax Table Functions' - `with-syntax-table' >> `Using Lexical Binding' - `special-variable-p' >> `Syntax Table Internals' - `string-to-syntax' >> `Declare Form' - `declare' >> >> Note that `A Sample Function Description' is the very place where we explain the >> syntax convention and give an example of it. Not a good place to set a bad >> example. > > It's not bad. This is done on purpose, see the Texinfo sources, which > use @var in this case. But other "imaginary" example definitions in intro.texi don't use @var. Nor does any "real" @defspec in doc/lispref use that. Also, in contrast to the makeinfo program, texinfo-format-region would produce -- Special form: count-loop (VAR [FROM TO [INC]]) BODY... in both cases, with or without @var. Perhaps, that's the reason that nobody noticed at the time? So is there anything wrong with Drew's revised suggestion (as I understand it)? === modified file 'doc/lispref/functions.texi' --- doc/lispref/functions.texi 2012-12-05 22:27:56 +0000 +++ doc/lispref/functions.texi 2012-12-28 23:53:49 +0000 @@ -1266,7 +1266,7 @@ convention in Emacs Lisp mode. @anchor{Definition of declare} -@defmac declare @var{specs}@dots{} +@defmac declare specs@dots{} This macro ignores its arguments and evaluates to @code{nil}; it has no run-time effect. However, when a @code{declare} form occurs in the @var{declare} argument of a @code{defun} or @code{defsubst} function === modified file 'doc/lispref/intro.texi' --- doc/lispref/intro.texi 2012-12-05 22:27:56 +0000 +++ doc/lispref/intro.texi 2012-12-28 23:47:55 +0000 @@ -408,7 +408,7 @@ arguments are grouped into additional levels of list structure. Here is an example: -@defspec count-loop (@var{var} [@var{from} @var{to} [@var{inc}]]) @var{body}@dots{} +@defspec count-loop (var [from to [inc]]) body@dots{} This imaginary special form implements a loop that executes the @var{body} forms and then increments the variable @var{var} on each iteration. On the first iteration, the variable has the value === modified file 'doc/lispref/syntax.texi' --- doc/lispref/syntax.texi 2012-12-05 22:27:56 +0000 +++ doc/lispref/syntax.texi 2012-12-28 23:52:25 +0000 @@ -506,7 +506,7 @@ the current buffer. @end defun -@defmac with-syntax-table @var{table} @var{body}@dots{} +@defmac with-syntax-table table body@dots{} This macro executes @var{body} using @var{table} as the current syntax table. It returns the value of the last form in @var{body}, after restoring the old current syntax table. @@ -998,7 +998,7 @@ @samp{4} @tab @code{(lsh 1 19)} @end multitable -@defun string-to-syntax @var{desc} +@defun string-to-syntax desc Given a syntax descriptor @var{desc} (a string), this function returns the corresponding raw syntax descriptor. @end defun === modified file 'doc/lispref/variables.texi' --- doc/lispref/variables.texi 2012-12-05 22:27:56 +0000 +++ doc/lispref/variables.texi 2012-12-28 23:58:13 +0000 @@ -1057,7 +1057,7 @@ (@pxref{Defining Variables}). All other variables are subject to lexical binding. -@defun special-variable-p SYMBOL +@defun special-variable-p symbol This function returns non-@code{nil} if @var{symbol} is a special variable (i.e., it has a @code{defvar}, @code{defcustom}, or @code{defconst} variable definition). Otherwise, the return value is