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

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 13292 in the body.
You can then email your comments to 13292 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: "Drew Adams" <drew.adams <at> oracle.com>
To: <bug-gnu-emacs <at> gnu.org>
Subject: 24.3.50; wrong sytax description in (elisp) Case Tables
Date: Fri, 28 Dec 2012 07:26:48 -0800

The parameters should be uppercase everywhere.  E.g.,
 
 -- Macro: with-case-table TABLE BODY...
 
not
 
 -- Macro: with-case-table table body...
 
 
 

In GNU Emacs 24.3.50.1 (i386-mingw-nt5.1.2600)
 of 2012-12-18 on MS-W7-DANI
Bzr revision: 111265 eliz <at> gnu.org-20121218190556-x9wmq083vwecgu0f
Windowing system distributor `Microsoft Corp.', version 5.1.2600
Configured using:
 `configure --with-gcc (4.7) --no-opt --enable-checking --cflags
 -Ic:/emacs/libs/libXpm-3.5.10/include -Ic:/emacs/libs/libXpm-3.5.10/src
 -Ic:/emacs/libs/libpng-dev_1.4.3-1_win32/include
 -Ic:/emacs/libs/zlib-dev_1.2.5-2_win32/include
 -Ic:/emacs/libs/giflib-4.1.4-1-lib/include
 -Ic:/emacs/libs/jpeg-6b-4-lib/include
 -Ic:/emacs/libs/tiff-3.8.2-1-lib/include
 -Ic:/emacs/libs/libxml2-2.7.8-w32-bin/include/libxml2
 -Ic:/emacs/libs/gnutls-3.0.9-w32-bin/include
 -Ic:/emacs/libs/libiconv-1.9.2-1-lib/include'
 

Message #8 received at 13292 <at> debbugs.gnu.org (full text, mbox):

From: "Drew Adams" <drew.adams <at> oracle.com>
To: <13292 <at> debbugs.gnu.org>
Subject: RE: bug#13292: 24.3.50; wrong sytax description in (elisp) Case Tables
Date: Fri, 28 Dec 2012 07:30:59 -0800

The contagion has apparently spread beyond this node.  See also node
`Conditionals'.

A general review is probably required.  Someone is either quite careless or,
more likely?, has not been told what the convention is.

Message #13 received at 13292-done <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 13292-done <at> debbugs.gnu.org
Subject: Re: bug#13292: 24.3.50; wrong sytax description in (elisp) Case Tables
Date: Fri, 28 Dec 2012 18:39:43 +0200

> From: "Drew Adams" <drew.adams <at> oracle.com>
> Date: Fri, 28 Dec 2012 07:26:48 -0800
> 
> 
> The parameters should be uppercase everywhere.

They never were.  This is how Info works.

Closing.

Message #16 received at 13292 <at> debbugs.gnu.org (full text, mbox):

From: "Drew Adams" <drew.adams <at> oracle.com>
To: "'Eli Zaretskii'" <eliz <at> gnu.org>
Cc: 13292 <at> debbugs.gnu.org
Subject: RE: bug#13292: 24.3.50; wrong sytax description in (elisp) Case Tables
Date: Fri, 28 Dec 2012 08:57:28 -0800

> > The parameters should be uppercase everywhere.
> 
> They never were.  This is how Info works.
> Closing.

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.

Reopening.  There is clearly some cleanup to be done.

Message #23 received at 13292-done <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 13292-done <at> debbugs.gnu.org
Subject: Re: bug#13292: 24.3.50; wrong sytax description in (elisp) Case Tables
Date: Fri, 28 Dec 2012 20:30:34 +0200

> From: "Drew Adams" <drew.adams <at> oracle.com>
> Cc: <13292 <at> debbugs.gnu.org>
> Date: Fri, 28 Dec 2012 08:57:28 -0800
> 
> > > The parameters should be uppercase everywhere.
> > 
> > They never were.  This is how Info works.
> > Closing.
> 
> 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.

> Reopening.  There is clearly some cleanup to be done.

Reclosing.  Please stop this ridicule.

Message #26 received at 13292-done <at> debbugs.gnu.org (full text, mbox):

From: "Drew Adams" <drew.adams <at> oracle.com>
To: "'Eli Zaretskii'" <eliz <at> gnu.org>
Cc: 13292-done <at> debbugs.gnu.org
Subject: RE: bug#13292: 24.3.50; wrong sytax description in (elisp) Case Tables
Date: Fri, 28 Dec 2012 10:46:42 -0800

> It's not bad.  This is done on purpose, see the Texinfo sources, which
> use @var in this case.

Really?  Just what is the purpose in this "on purpose"?

Why uppercase sometimes, lowercase other times?  What is the different
message/information that is supposed to be conveyed to readers?

And where is this difference in notation & meaning explained/defined in the
manual?

Message #29 received at 13292 <at> debbugs.gnu.org (full text, mbox):

From: Wolfgang Jenkner <wjenkner <at> inode.at>
To: 13292 <at> debbugs.gnu.org
Cc: eliz <at> gnu.org, drew.adams <at> oracle.com
Subject: Re: 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

Message #32 received at 13292 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Wolfgang Jenkner <wjenkner <at> inode.at>
Cc: 13292 <at> debbugs.gnu.org, drew.adams <at> oracle.com
Subject: Re: bug#13292: 24.3.50; wrong sytax description in (elisp) Case Tables
Date: Sat, 29 Dec 2012 10:30:17 +0200

> From: Wolfgang Jenkner <wjenkner <at> inode.at>
> Cc: eliz <at> gnu.org,  drew.adams <at> oracle.com
> 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.

The Texinfo manual is ambiguous wrt this issue.  It allows using @var
in some cases.  The result in print is a slightly different typeface;
in contrast, the result in the Info output is VERY different.
However, since the references to the arguments in the text _always_
use @var, so are rendered in CAPS in Info, I consider this bug report
a rather petty and even an overly-pedantic one.

> 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?

I doubt that, as no one uses texinfo-format-region anymore, since it
doesn't support so many Texinfo features introduced in recent years.

> So is there anything wrong with Drew's revised suggestion (as
> I understand it)?

See above.  That said, I don't want to argue anymore, so I installed
your changes on the emacs-24 branch; thanks.

Message #35 received at 13292 <at> debbugs.gnu.org (full text, mbox):

From: Wolfgang Jenkner <wjenkner <at> inode.at>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 13292 <at> debbugs.gnu.org, Drew Adams <drew.adams <at> oracle.com>
Subject: Re: bug#13292: 24.3.50; wrong sytax description in (elisp) Case Tables
Date: Sat, 29 Dec 2012 16:48:31 +0100

On Sat, Dec 29 2012, Eli Zaretskii wrote:

>> From: Wolfgang Jenkner <wjenkner <at> inode.at>
>> 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?
>
> I doubt that, as no one uses texinfo-format-region anymore, since it
> doesn't support so many Texinfo features introduced in recent years.

I meant a time closer to when the elisp manual was written, viz.

http://ftp.gnu.org/old-gnu/emacs/elisp-manual-20-2.5.tar.gz

has (in the node we are talking about: A Sample Function Description)

@defun foo integer1 &optional integer2 &rest integers

but the formatted manual included in that tarball has

 - Function: foo INTEGER1 &optional INTEGER2 &rest INTEGERS
 
That's the reason why Drew's report rang a bell: I remembered that years
ago I had become aware of this change from upper-case to lower-case at
some point.

>> So is there anything wrong with Drew's revised suggestion (as
>> I understand it)?

> See above.  That said, I don't want to argue anymore, so I installed
> your changes on the emacs-24 branch; thanks.

I could have done that (which is why I neglected to supply a change log
entry), but thanks.

Wolfgang

Message #38 received at 13292 <at> debbugs.gnu.org (full text, mbox):

From: "Drew Adams" <drew.adams <at> oracle.com>
To: "'Wolfgang Jenkner'" <wjenkner <at> inode.at>, "'Eli Zaretskii'" <eliz <at> gnu.org>
Cc: 13292 <at> debbugs.gnu.org
Subject: RE: bug#13292: 24.3.50; wrong sytax description in (elisp) Case Tables
Date: Sat, 29 Dec 2012 08:17:50 -0800

> I meant a time closer to when the elisp manual was written, viz.
> http://ftp.gnu.org/old-gnu/emacs/elisp-manual-20-2.5.tar.gz
> has (in the node we are talking about: A Sample Function Description)
> 
> @defun foo integer1 &optional integer2 &rest integers
> but the formatted manual included in that tarball has
>  - Function: foo INTEGER1 &optional INTEGER2 &rest INTEGERS
>  
> That's the reason why Drew's report rang a bell: I remembered 
> that years ago I had become aware of this change from upper-case
> to lower-case at some point.

Yes, in Emacs 20 parameters were uppercase - more readable, BTW.

I don't have an Emacs 21 Elisp (Info) manual.  My guess would be that this
regression (intentional, no doubt) was introduced in Emacs 22.

The current bug is that the usage is not consistent - that's the point.
Parameters should either be always uppercase or always lowercase.  They are
instead sometimes all uppercase, sometimes all lowercase.

Previous Next

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