GNU bug report logs - #13292
24.3.50; wrong sytax description in (elisp) Case Tables

Previous Next

Full log

View this message in rfc822 format

From: Wolfgang Jenkner <wjenkner <at> inode.at>
To: 13292 <at> debbugs.gnu.org
Cc: eliz <at> gnu.org, drew.adams <at> oracle.com
Subject: bug#13292: 24.3.50; wrong sytax description in (elisp) Case Tables
Date: Sat, 29 Dec 2012 01:21:05 +0100

On Fri, Dec 28 2012, Eli Zaretskii wrote:

>> From: "Drew Adams" <drew.adams <at> oracle.com>
[...]
>> 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 <at> 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 <at> 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 <at> 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

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.