bug#6521: 23.2; Elisp Manual Ommission

bug#6521: 23.2; Elisp Manual Ommission

[Tim Cross]

It appears the section from the emacs manual that use to describe the
old pre emacs 19.29 behavior with backquotes has been removed. In
previous versions of the manual, it use to describe what this old
behavior was and why it is no longer required. However, it now only
describes the use of backquote as it should now be used.

I think it would be a good idea to put the description of the old
section back into the manual. The reason is that 

        1. The compiler, when warning of code that still uses the old
        backquote format references this node, but there is no reference
        to the old behavior in the node anymore. This makes things less
        clear to new users that perhaps it should be.

        2. It may not be obvious to more recent users exactly what the
        old behavior was, making it more difficult to identify the old
        style and understand how it use to be formatted in order to
        update the code to use the correct modern style.

        3. This is likely to become a bigger issue now that emacs 24 is
        changing to assume a backquote with a space following it is
        modern style. I just encountered code which failed to compile
        due to this. When wanting to clarify my understanding, I found
        nothing relevant in the manual. 

I was referencing version 3 of the elisp manual (for emacs version
24.0.50).

regards,

Tim


-- 
Tim Cross
tcross@rapttech.com.au

There are two types of people in IT - those who do not manage what they 
understand and those who do not understand what they manage.

bug#6521: 23.2; Elisp Manual Ommission

[Drew Adams]

+1 to what Tim said.

bug#6521: 23.2; Elisp Manual Ommission

[Stefan Monnier]

>         3. This is likely to become a bigger issue now that emacs 24 is
>         changing to assume a backquote with a space following it is
                                            ^^^
You mean:                                   out
right?

>         modern style.  I just encountered code which failed to compile
>         due to this.  When wanting to clarify my understanding, I found
>         nothing relevant in the manual. 

Could you send it along, so we could see what it looks like (to better
assess whether it means we have a serious problem, or if it's just
bad luck).


        Stefan

bug#6521: 23.2; Elisp Manual Ommission

[Tim Cross]

From: Stefan Monnier <monnier@iro.umontreal.ca>
Subject: Re: bug#6521: 23.2; Elisp Manual Ommission
Date: Thu, 01 Jul 2010 02:46:39 +0200

>>         3. This is likely to become a bigger issue now that emacs 24 is
>>         changing to assume a backquote with a space following it is
>                                             ^^^
> You mean:                                   out
> right?
>

yep, I meant without a space.
 
>>         modern style.  I just encountered code which failed to compile
>>         due to this.  When wanting to clarify my understanding, I found
>>         nothing relevant in the manual. 
> 
> Could you send it along, so we could see what it looks like (to better
> assess whether it means we have a serious problem, or if it's just
> bad luck).
> 

The code which failed to compile was BBDB as bundled with Debian testing. Do
you want me to send the error message that was generated? (note that the code
still compiles with emacs23).

Tim

bug#6521: 23.2; Elisp Manual Ommission

[Stefan Monnier]

[ Can't remember responding yet. ]
>> Could you send it along, so we could see what it looks like (to better
>> assess whether it means we have a serious problem, or if it's just
>> bad luck).
> The code which failed to compile was BBDB as bundled with Debian testing. Do
> you want me to send the error message that was generated? (note that the code
> still compiles with emacs23).

AFAIK, this problem has been fixed a little while back.


        Stefan

bug#6521: 23.2; Elisp Manual Ommission

[Tim Cross]

Stefan Monnier writes:
 > [ Can't remember responding yet. ]
 > >> Could you send it along, so we could see what it looks like (to
 > >> better assess whether it means we have a serious problem, or if
 > >> it's just bad luck).
 > > The code which failed to compile was BBDB as bundled with Debian
 > > testing. Do you want me to send the error message that was
 > > generated? (note that the code still compiles with emacs23).
 > 
 > AFAIK, this problem has been fixed a little while back.

Yes, the problem with compilation seems to have been fixed. However, there is
still a problem. Now it is a documentation issue rather than a compilation one.

The manual no longer has a section about the deprecated use of the old style
backquote. The warning message generated by the byte compiler still refers the
user to the backquote section of the elisp manual for more information, but
there is no reference to old style backquotes in that section. This makes it
very difficult for anyone who is not familiar with the change in style to
understand what use to be different and what needs to be changed in the code to
get rid of the warning. Given that this change in style happened many years
ago, there is likely a number of users who are unfamiliar with what the old
style was and they would probably benefit from some explanation/guidance. 

I recommend that either a footnote be added to the backquote section of the
elisp reference manual or a new section be added about the old style backquotes
and what needs to be changed to make it compliant with modern usage. The
compiler warning message should probably also be updated to either direct users
to the footnote or new section. 

regards,

Tim

-- 
Tim Cross
tcross@rapttech.com.au

There are two types of people in IT - those who do not manage what
they understand and those who do not understand what they manage.
-- 
Tim Cross
tcross@rapttech.com.au

There are two types of people in IT - those who do not manage what they 
understand and those who do not understand what they manage.