bug#13292: 24.3.50; wrong sytax description in (elisp) Case Tables

[Wolfgang Jenkner <wjenkner@inode.at>]

On Fri, Dec 28 2012, Eli Zaretskii wrote:

>> From: "Drew Adams" <drew.adams@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@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