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

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

[Drew Adams]

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@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'
 

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

[Drew Adams]

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.

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

[Eli Zaretskii]

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

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

[Drew Adams]

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

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

[Eli Zaretskii]

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

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

[Drew Adams]

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

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

[Wolfgang Jenkner]

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

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

[Eli Zaretskii]

> From: Wolfgang Jenkner <wjenkner@inode.at>
> Cc: eliz@gnu.org,  drew.adams@oracle.com
> Date: Sat, 29 Dec 2012 01:21:05 +0100
> 
> 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.

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.

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

[Wolfgang Jenkner]

On Sat, Dec 29 2012, Eli Zaretskii wrote:

>> From: Wolfgang Jenkner <wjenkner@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

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

[Drew Adams]

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