Incompatible change without "warning"

Incompatible change without "warning"

[Frank Schmitt]

Hello

I see that on 2005-4-18 the tooltip-use-echo-area was renamed to
tooltip-gud-echo-area. This change breaks existing code
(semantic). Isn't it common practise to first deprecate a variable
before deleting it? And shouldn't this make it into NEWS?

-- 
Did you ever realize how much text fits in eighty columns? If you now consider
that a signature usually consists of up to four lines, this gives you enough
space to spread a tremendous amount of information with your messages. So seize
this opportunity and don't waste your signature with bullshit nobody will read.

Re: Incompatible change without "warning"

[Eli Zaretskii]

> From: Frank Schmitt <ich@frank-schmitt.net>
> Date: Tue, 19 Apr 2005 16:48:45 +0200
> 
> I see that on 2005-4-18 the tooltip-use-echo-area was renamed to
> tooltip-gud-echo-area. This change breaks existing code
> (semantic). Isn't it common practise to first deprecate a variable
> before deleting it?

I think we should introduce a defvaralias, so as not to break existing
code.

> And shouldn't this make it into NEWS?

Definitely.

Incompatible change without "warning"

[Nick Roberts]

 > I see that on 2005-4-18 the tooltip-use-echo-area was renamed to
 > tooltip-gud-echo-area. This change breaks existing code
 > (semantic). Isn't it common practise to first deprecate a variable
 > before deleting it? And shouldn't this make it into NEWS?

I've replaced it as an alias. As it was obscure and partly broken I thought
that I could sneak the change through unnoticed.

To emacs-devel:

How about adding an optional argument to defvaralias so that:

(defvaralias 'tooltip-use-echo-area 'tooltip-gud-echo-area)
(make-obsolete-variable 'tooltip-use-echo-area 'tooltip-gud-echo-area "22.1")

can be written as:

(defvaralias 'tooltip-use-echo-area 'tooltip-gud-echo-area nil "22.1")


Nick

Re: Incompatible change without "warning"

[Stefan Monnier]

>> I see that on 2005-4-18 the tooltip-use-echo-area was renamed to
>> tooltip-gud-echo-area. This change breaks existing code
>> (semantic). Isn't it common practise to first deprecate a variable
>> before deleting it? And shouldn't this make it into NEWS?

> I've replaced it as an alias. As it was obscure and partly broken I thought
> that I could sneak the change through unnoticed.

> To emacs-devel:

> How about adding an optional argument to defvaralias so that:

> (defvaralias 'tooltip-use-echo-area 'tooltip-gud-echo-area)
> (make-obsolete-variable 'tooltip-use-echo-area 'tooltip-gud-echo-area "22.1")

> can be written as:

> (defvaralias 'tooltip-use-echo-area 'tooltip-gud-echo-area nil "22.1")

I'd prefer to define the same `define-obsolete-variable-alias' macro as used
in XEmacs.


        Stefan

Incompatible change without "warning"

[Nick Roberts]

 > I see that on 2005-4-18 the tooltip-use-echo-area was renamed to
 > tooltip-gud-echo-area. This change breaks existing code
 > (semantic). Isn't it common practise to first deprecate a variable
 > before deleting it? And shouldn't this make it into NEWS?

I should also add that tooltip-gud-echo-area doesn't do exactly the same thing
as tooltip-use-echo-area: it only uses the echo area for GUD tooltips.  Help
messages are still displayed in their own tooltip frame. Previously using the
echo area for GUD tooltips required help messages to be displayed there also.
Turning tooltip-mode off means that help messages displayed in the echo area
and that GUD tooltips are no longer displayed. Maybe this change is not as
good as I first thought because now it is not possible to have both GUD
tooltips and help messages displayed in the echo area.

Nick

Re: Incompatible change without "warning"

[Kevin Rodgers]

Stefan Monnier wrote:
>>How about adding an optional argument to defvaralias so that:
> 
>>(defvaralias 'tooltip-use-echo-area 'tooltip-gud-echo-area)
>>(make-obsolete-variable 'tooltip-use-echo-area 'tooltip-gud-echo-area "22.1")
> 
>>can be written as:
> 
>>(defvaralias 'tooltip-use-echo-area 'tooltip-gud-echo-area nil "22.1")
> 
> I'd prefer to define the same `define-obsolete-variable-alias' macro as used
> in XEmacs.

I like the way (defobvaralias ...) rolls off the tongue... it sounds 
like I can speak German!

-- 
Kevin Rodgers

Re: Incompatible change without "warning"

[Richard Stallman]

    How about adding an optional argument to defvaralias so that:

    (defvaralias 'tooltip-use-echo-area 'tooltip-gud-echo-area)
    (make-obsolete-variable 'tooltip-use-echo-area 'tooltip-gud-echo-area "22.1")

    can be written as:

    (defvaralias 'tooltip-use-echo-area 'tooltip-gud-echo-area nil "22.1")

It looks good to me.

Re: Incompatible change without "warning"

[Richard Stallman]

    I'd prefer to define the same `define-obsolete-variable-alias' macro as used
    in XEmacs.

That sounds useful.

Re: Incompatible change without "warning"

[Luc Teirlinck]

Nick Roberts wrote:

   I should also add that tooltip-gud-echo-area doesn't do exactly the
   same thing as tooltip-use-echo-area: it only uses the echo area for
   GUD tooltips.  Help messages are still displayed in their own
   tooltip frame. Previously using the echo area for GUD tooltips
   required help messages to be displayed there also.  Turning
   tooltip-mode off means that help messages displayed in the echo
   area and that GUD tooltips are no longer displayed. Maybe this
   change is not as good as I first thought because now it is not
   possible to have both GUD tooltips and help messages displayed in
   the echo area.

Why did you make that change?  It would seem that if people prefer to
have GUD tooltip texts displayed in the echo area, they most likely
also want help messages displayed there.

Sincerely,

Luc.

Re: Incompatible change without "warning"

[Nick Roberts]

 >     I'd prefer to define the same `define-obsolete-variable-alias' macro as
 >     used in XEmacs.
 > 
 > That sounds useful.

Does this DTRT?

(defmacro define-obsolete-variable-alias (symbol aliased
						 &optional docstring when)
"Make SYMBOL a variable alias for symbol ALIASED and warn that
SYMBOL is obsolete. If provided, WHEN should be a string
indicating when the variable was first made obsolete, for example
a date or a release number. Fourth arg docstring, if non-nil, is
documentation for symbol."
  (list 'progn
	`(defvaralias ,symbol ,aliased ,docstring)
	`(make-obsolete-variable ,symbol ,aliased ,when)))

The version in XEmacs may be better but I've not looked at at it deliberately,
as I wasn't sure of the implications of copying it.

Nick

Re: Incompatible change without "warning"

[Nick Roberts]

 >    I should also add that tooltip-gud-echo-area doesn't do exactly the
 >    same thing as tooltip-use-echo-area: it only uses the echo area for
 >    GUD tooltips.  Help messages are still displayed in their own
 >    tooltip frame. Previously using the echo area for GUD tooltips
 >    required help messages to be displayed there also.  Turning
 >    tooltip-mode off means that help messages displayed in the echo
 >    area and that GUD tooltips are no longer displayed. Maybe this
 >    change is not as good as I first thought because now it is not
 >    possible to have both GUD tooltips and help messages displayed in
 >    the echo area.
 > 
 > Why did you make that change?  It would seem that if people prefer to
 > have GUD tooltip texts displayed in the echo area, they most likely
 > also want help messages displayed there.

When tooltip-mode is off help messages are displayed in the echo area. It was
confusing and a bit redundant that tooltip-mode turned on and
tooltip-use-echo-area set to t would also display help messages there.

GUD tooltips are generated differently to normal tooltips whose message are
embedded in the text properties. Their display is more erratic and thats why
I thought it might help to display them in the echo area.

There are six cases to consider:


                              Normal

                      Own Frame | Echo Area              Behaviours

   None                   x          x                 x - previous and present
G
U  Own frame              x                            * - previous
D
   Echo area              +          *                 + - present


The asymmetry arises becauses help messages can't be suppressed like
GUD tooltips. I don't think an extra variable to deal with the extra
case is justified. I can revert the change if people prefer the old
behaviour/can't think of a more elegant solution.

As an aside, at some stage in the future I would like to extend GUD tooltips
to display #define directives over identifiers (like in Visual Studio, I
think) when the program is not executing.

Nick

Re: Incompatible change without "warning"

[Lute Kamstra]

Nick Roberts <nickrob@snap.net.nz> writes:

>  >     I'd prefer to define the same `define-obsolete-variable-alias' macro as
>  >     used in XEmacs.
>  > 
>  > That sounds useful.
>
> Does this DTRT?
>
> (defmacro define-obsolete-variable-alias (symbol aliased
> 						 &optional docstring when)
> "Make SYMBOL a variable alias for symbol ALIASED and warn that
> SYMBOL is obsolete. If provided, WHEN should be a string
> indicating when the variable was first made obsolete, for example
> a date or a release number. Fourth arg docstring, if non-nil, is
> documentation for symbol."
>   (list 'progn
> 	`(defvaralias ,symbol ,aliased ,docstring)
> 	`(make-obsolete-variable ,symbol ,aliased ,when)))

The first line of the docstring should be a complete sentence.
Occurrences of argument names in the docstring should be in capitals.
The fourth argument is WHEN, not DOCSTRING.  Personally, I like the
argument names OLDVAR and NEWVAR that XEmacs uses.  What about this:

(defmacro define-obsolete-variable-alias (oldvar newvar
						 &optional when docstring)
  "Make OLDVAR a variable alias for NEWVAR and warn that OLDVAR is obsolete.
If provided, WHEN should be a string indicating when OLDVAR was
first made obsolete, for example a date or a release number.  The
optional argument DOCSTRING specifies the documentation string
for OLDVAR; if it is omitted or nil, OLDVAR uses the documentation
string of NEWVAR"
  `(progn
     (defvaralias ,oldvar ,newvar ,docstring)
     (make-obsolete-variable ,oldvar ,newvar ,when)))

> The version in XEmacs may be better but I've not looked at at it
> deliberately, as I wasn't sure of the implications of copying it.

Lute, who didn't look at XEmacs' implementation either.

Re: Incompatible change without "warning"

[Richard Stallman]

Before you install this, please write the changes for etc/NEWS and the
Lisp manual to install at the same time.

Re: Incompatible change without "warning"

[Nick Roberts]

 > > Does this DTRT?
 > >
 > > (defmacro define-obsolete-variable-alias (symbol aliased
 > > 						 &optional docstring when)
 > > "Make SYMBOL a variable alias for symbol ALIASED and warn that
 > > SYMBOL is obsolete. If provided, WHEN should be a string
 > > indicating when the variable was first made obsolete, for example
 > > a date or a release number. Fourth arg docstring, if non-nil, is
 > > documentation for symbol."
 > >   (list 'progn
 > > 	`(defvaralias ,symbol ,aliased ,docstring)
 > > 	`(make-obsolete-variable ,symbol ,aliased ,when)))
 > 
 > The first line of the docstring should be a complete sentence.

OK.

 > Occurrences of argument names in the docstring should be in capitals.
 > The fourth argument is WHEN, not DOCSTRING.

Yes. I changed the argument list but not the docstring.

 >  Personally, I like the
 > argument names OLDVAR and NEWVAR that XEmacs uses.  What about this:

I've tried to use the same names from defvaralias and make-obsolete-variable.

 > (defmacro define-obsolete-variable-alias (oldvar newvar
 > 						 &optional when docstring)
 >   "Make OLDVAR a variable alias for NEWVAR and warn that OLDVAR is obsolete.
 > If provided, WHEN should be a string indicating when OLDVAR was
 > first made obsolete, for example a date or a release number.  The
 > optional argument DOCSTRING specifies the documentation string
 > for OLDVAR; if it is omitted or nil, OLDVAR uses the documentation
 > string of NEWVAR"
 >   `(progn
 >      (defvaralias ,oldvar ,newvar ,docstring)
 >      (make-obsolete-variable ,oldvar ,newvar ,when)))

Yes, thanks. This is an improvement, but I might stick with my argument names
for consistency.


Nick

Re: Incompatible change without "warning"

[Nick Roberts]

Richard Stallman writes:
 > Before you install this, please write the changes for etc/NEWS and the
 > Lisp manual to install at the same time.

For completeness, I guess there should be one for functions too. Indeed, there
seem to be more uses of make-obsolete than make-obsolete-variable (possibly
bacause defvaralias is newer than defalias). I see XEmacs has
define-obsolete-function-alias so we could do:

(defmacro define-obsolete-function-alias (function aliased
						   &optional docstring when)
  "blurb"
  `(progn
     (defalias ,function ,aliased ,docstring)
     (make-obsolete ,function ,aliased ,when)))

Or we could combine the two e.g

(defmacro define-obsolete-alias (new aliased
				     &optional docstring when)
  "blurb"
  `(if (fboundp ,aliased)
       (progn
	 (defalias ,new ,aliased ,docstring)
	 (make-obsolete ,new ,aliased ,when))
     (progn
       (defvaralias ,new ,aliased ,docstring)
       (make-obsolete-variable ,new ,aliased ,when))))

It would have to be done a bit differently though, to deal with case of
a symbol having both a value and a function definition.

Nick

Re: Incompatible change without "warning"

[Lute Kamstra]

Nick Roberts <nickrob@snap.net.nz> writes:

> Richard Stallman writes:
>  > Before you install this, please write the changes for etc/NEWS and the
>  > Lisp manual to install at the same time.
>
> For completeness, I guess there should be one for functions too.

Good idea.

> Indeed, there seem to be more uses of make-obsolete than
> make-obsolete-variable (possibly bacause defvaralias is newer than
> defalias). I see XEmacs has define-obsolete-function-alias so we
> could do:
>
> (defmacro define-obsolete-function-alias (function aliased
> 						   &optional docstring when)
>   "blurb"
>   `(progn
>      (defalias ,function ,aliased ,docstring)
>      (make-obsolete ,function ,aliased ,when)))

I think it's better to have WHEN before DOCSTRING.  DOCSTRING is
hardly ever used while WHEN is used frequently.

> Or we could combine the two e.g
>
> (defmacro define-obsolete-alias (new aliased
> 				     &optional docstring when)
>   "blurb"
>   `(if (fboundp ,aliased)
>        (progn
> 	 (defalias ,new ,aliased ,docstring)
> 	 (make-obsolete ,new ,aliased ,when))
>      (progn
>        (defvaralias ,new ,aliased ,docstring)
>        (make-obsolete-variable ,new ,aliased ,when))))

Seems like a bad idea to me.  For one thing, you can use
define-obsolete-{function,variable}-alias before you define ALIASED.
(I think XEmacs requires this.)  That won't work in this case.

> It would have to be done a bit differently though, to deal with case
> of a symbol having both a value and a function definition.

How can you determine what's the right thing, in that case?

Lute.

Re: Incompatible change without "warning"

[Lute Kamstra]

Hi Nick,

I see that you've installed define-obsolete-variable-alias.  Thanks.

In etc/NEWS you've also added an entry for make-obsolete-variable:

  +++
  *** New function make-obsolete-variable to warn that a variable may be removed
  at some stage in the future.

Even though is wasn't documented in the Lisp Manual,
make-obsolete-variable has been part of Emacs since version 19.7.

Lute.


PS. I noticed that make-obsolete isn't documented either.  Maybe you
    can fix that as well?

Re: Incompatible change without "warning"

[Nick Roberts]

 > In etc/NEWS you've also added an entry for make-obsolete-variable:
 > 
 >   +++ *** New function make-obsolete-variable to warn that a variable may
 >   be removed at some stage in the future.
 > 
 > Even though is wasn't documented in the Lisp Manual,
 > make-obsolete-variable has been part of Emacs since version 19.7.

I've removed this entry. I was fooled by defvaralias being new.

 > Lute.
 > 
 > 
 > PS. I noticed that make-obsolete isn't documented either.  Maybe you
 >     can fix that as well?

I'm waiting to see if Richard decides that define-obsolete-function-alias
should be added too. These two functions are so similar to the two that
I've just documented, externally at least, that I wonder if they could
be described somewhere centrally in the Lisp manual i.e a link from the
nodes 'Defining Variables' and 'Defining Functions'to one called
'Obsoletion'.


Nick

Re: Incompatible change without "warning"

[Lute Kamstra]

Nick Roberts <nickrob@snap.net.nz> writes:

>  > In etc/NEWS you've also added an entry for make-obsolete-variable:
>  > 
>  >   +++ *** New function make-obsolete-variable to warn that a variable may
>  >   be removed at some stage in the future.
>  > 
>  > Even though is wasn't documented in the Lisp Manual,
>  > make-obsolete-variable has been part of Emacs since version 19.7.
>
> I've removed this entry. 

Thanks.

> I was fooled by defvaralias being new.

defvaralias is part of Emacs since version 21.1.

It does have an entry in NEWS under "Lisp Changes in Emacs 22.1", tho.
I wonder why it was put there.  Maybe because it wasn't mentioned in
NEWS for 21.1?  We better mention explicitly that it isn't really new
for 22.1, in that case.

Lute.

Re: Incompatible change without "warning"

[David Kastrup]

Lute Kamstra <Lute.Kamstra.lists@xs4all.nl> writes:

> Nick Roberts <nickrob@snap.net.nz> writes:
>
>>  > In etc/NEWS you've also added an entry for make-obsolete-variable:
>>  > 
>>  >   +++ *** New function make-obsolete-variable to warn that a variable may
>>  >   be removed at some stage in the future.
>>  > 
>>  > Even though is wasn't documented in the Lisp Manual,
>>  > make-obsolete-variable has been part of Emacs since version 19.7.
>>
>> I've removed this entry. 
>
> Thanks.
>
>> I was fooled by defvaralias being new.
>
> defvaralias is part of Emacs since version 21.1.

Uh what?

> It does have an entry in NEWS under "Lisp Changes in Emacs 22.1", tho.
> I wonder why it was put there.  Maybe because it wasn't mentioned in
> NEWS for 21.1?  We better mention explicitly that it isn't really new
> for 22.1, in that case.

What makes you think it isn't?  My Emacs-21.3 does not have it.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: Incompatible change without "warning"

[Nick Roberts]

 > defvaralias is part of Emacs since version 21.1.

Well its not in Emacs 21.2. I don't have 21.1 but I doubt that it has it.
Looking at the ChangeLog it seems to have just missed the branch from which
21.2 and 21.3 were also released.


2001-10-20  Gerd Moellmann  <gerd@gnu.org>

	* (Version 21.1 released.)

...
2001-10-04  Gerd Moellmann  <gerd@gnu.org>
...
	(Fdefvaralias): New function.
...
2001-10-04  Gerd Moellmann  <gerd@gnu.org>

	* Branch for 21.1.

So at three and a half, defvaralias must be about the oldest feature still
in CVS!

 > It does have an entry in NEWS under "Lisp Changes in Emacs 22.1", tho.
 > I wonder why it was put there.  Maybe because it wasn't mentioned in
 > NEWS for 21.1?  We better mention explicitly that it isn't really new
 > for 22.1, in that case.

I think the NEWS entry is correct.

Nick

Re: Incompatible change without "warning"

[Eli Zaretskii]

> From: Nick Roberts <nickrob@snap.net.nz>
> Date: Sat, 23 Apr 2005 20:10:55 +1200
> Cc: rms@gnu.org, Stefan Monnier <monnier@iro.umontreal.ca>, emacs-devel@gnu.org
> 
> Looking at the ChangeLog it seems to have just missed the branch from which
> 21.2 and 21.3 were also released.
> 
> 
> 2001-10-20  Gerd Moellmann  <gerd@gnu.org>
> 
> 	* (Version 21.1 released.)
> 
> ...
> 2001-10-04  Gerd Moellmann  <gerd@gnu.org>
> ...
> 	(Fdefvaralias): New function.
> ...
> 2001-10-04  Gerd Moellmann  <gerd@gnu.org>
> 
> 	* Branch for 21.1.

It's almost certainly a deliberate omission: Gerd didn't want to add a
new feature to the upcoming release that was already at the end of a
very thorough pretest.

Re: Incompatible change without "warning"

[Richard Stallman]

    For completeness, I guess there should be one for functions too.

We don't add features to Emacs "for completeness".
That is not enough reason.

     I see XEmacs has
    define-obsolete-function-alias so we could do:

Compatibility adds an additional reason.
So please add define-obsolete-function-alias.
Please give it arguments compatible with XEmacs.

    Or we could combine the two e.g

    (defmacro define-obsolete-alias (new aliased

Since this does not provide compatibility,
it is not as good.  Please don't do this.

Re: Incompatible change without "warning"

[Lute Kamstra]

David Kastrup <dak@gnu.org> writes:

[...]

>> defvaralias is part of Emacs since version 21.1.
>
> Uh what?
>
>> It does have an entry in NEWS under "Lisp Changes in Emacs 22.1", tho.
>> I wonder why it was put there.  Maybe because it wasn't mentioned in
>> NEWS for 21.1?  We better mention explicitly that it isn't really new
>> for 22.1, in that case.
>
> What makes you think it isn't?  My Emacs-21.3 does not have it.

I used the Emacs from Debian:

(emacs-version) =>
"GNU Emacs 21.4.1 (i386-pc-linux-gnu, X toolkit, Xaw3d scroll bars)
 of 2005-03-17 on trouble, modified by Debian"
(fboundp 'defvaralias) => t

and also:

,----[ src/ChangeLog.9 ]
| 2001-10-20  Gerd Moellmann  <gerd@gnu.org>
| 
| 	* (Version 21.1 released.)
| 
| [...]
|
| 2001-10-04  Gerd Moellmann  <gerd@gnu.org>
|
| [...]
|
| 	(Fdefvaralias): New function.
`----

But I overlooked an earlier:

,----[ src/ChangeLog.9 ]
| 2001-10-04  Gerd Moellmann  <gerd@gnu.org>
| 
| 	* Branch for 21.1.
`----

and I found out that the Big Brother Database does:

,----[ bbdb.el ]
| (unless (fboundp 'defvaralias)
|   (defun defvaralias (&rest args)))
`----

I guess it ain't called insidious for nothin'.

Sorry for the noise,

  Lute.

Re: Incompatible change without "warning"

[Lute Kamstra]

Nick Roberts <nickrob@snap.net.nz> writes:

[...]

> I think the NEWS entry is correct.

Yup, my mistake.  Sorry.

Lute.

Re: Incompatible change without "warning"

[Nick Roberts]

 >      I see XEmacs has
 >     define-obsolete-function-alias so we could do:
 > 
 > Compatibility adds an additional reason.
 > So please add define-obsolete-function-alias.
 > Please give it arguments compatible with XEmacs.

I have added define-obsolete-function-alias to byte-run.el

I have not provided documentation because I would like guidance:

Me> These two functions are so similar to the two that I've just documented,
Me> externally at least, that I wonder if they could be described somewhere
Me> centrally in the Lisp manual i.e a link from the nodes 'Defining
Me> Variables' and 'Defining Functions'to one called 'Obsoletion'.

The current documentation for these related functions uses different argument
names which I think is confusing:

Manual:
 - Function: defvaralias alias-var base-var &optional docstring

Documentation string:
 (defvaralias symbol aliased &optional docstring)

Shall I change these to

Manual:
 - Function: defvaralias variable new &optional docstring

Documentation string:
 (defvaralias variable new &optional docstring)

for consistency with make-obsolete-variable, define-obsolete-variable-alias?

The manual says:

`string-to-int' is an obsolete alias for this function. (string-to-number)

but string-to-int has not been made obsolete.

Some variables/functions have been obsolete since 19.15. Is now a good time
to purge them?

Nick

Re: Incompatible change without "warning"

[Stefan Monnier]

> The current documentation for these related functions uses different argument
> names which I think is confusing:

I don't think it's confusing:
- `defvaralias' creates a variable alias.
  Neither of the two variables is known to be "old" or "new" or "obsolete".
  One is the "base", the other is the "alias".
- define-obsolete-variable-alias OTOH just *uses* defvaralias in one specific
  context (in order to preserve backward compatibility witha now obsolete
  variable), so the names can be more specific.

>  - Function: defvaralias variable new &optional docstring

That would sound wrong to me: the documentation should generally refer to
what a function *does*, not to how the function is used.


        Stefan

Re: Incompatible change without "warning"

[Nick Roberts]

 > > The current documentation for these related functions uses different
 > > argument names which I think is confusing:
 > 
 > I don't think it's confusing:
 > - `defvaralias' creates a variable alias.
 >   Neither of the two variables is known to be "old" or "new" or "obsolete".
 >   One is the "base", the other is the "alias".
 > - define-obsolete-variable-alias OTOH just *uses* defvaralias in one specific
 >   context (in order to preserve backward compatibility witha now obsolete
 >   variable), so the names can be more specific.
 > 
 > >  - Function: defvaralias variable new &optional docstring
 > 
 > That would sound wrong to me: the documentation should generally refer to
 > what a function *does*, not to how the function is used.

Yes, you're right - I've been too narrow in my thinking. However, my
first point was about using the same argument names in the manual and the
documentation string. Would this not generally be a good idea?

Nick

Re: Incompatible change without "warning"

[Stefan Monnier]

> However, my first point was about using the same argument names in the
> manual and the documentation string. Would this not generally be
> a good idea?

Yes, this is of course usually desirable,


        Stefan

Re: Incompatible change without "warning"

[Nick Roberts]

 >     Some variables/functions have been obsolete since 19.15. Is now a good
 >     time to purge them?
 > 
 > Could be.  What are their names?

Thinking about it, the best time to do this might be just *after* the release,
to give the maximum time to discover any problems it might cause.

Nick

before 19.15:

screen-height
screen-width
set-screen-width
set-screen-height
dot
dot-max
dot-min
dot-marker
buffer-flush-undo
'compiled-function-p

19.23

allout-exposure

19.32

focus-frame
unfocus-frame

19.34

executing-macro

Re: Incompatible change without "warning"

[Richard Stallman]

    Thinking about it, the best time to do this might be just *after* the release,
    to give the maximum time to discover any problems it might cause.

Only pretesting will give any real idea of whether a function is
used in code outside of Emacs.  Since we have not started the pretest,
now is a good time to delete some of these names.

    screen-height
    screen-width
    set-screen-width
    set-screen-height

Those are probably really used in .emacs files.  We shouldn't delete
them now, and maybe not ever.

    dot
    dot-max
    dot-min
    dot-marker

Those can go.  They are not used in the Emacs sources,
and they were not used much.  Note that bytecomp.el defines
properties for compiling them, so delete those too.

    buffer-flush-undo

That was probably used often by users; let's not delete it now.

    'compiled-function-p

Only a few programs would have had reason to use that, so
delete it now.

    19.23

    allout-exposure

That was specialized; delete it now.

    19.32

    focus-frame
    unfocus-frame

Those would have been used rarely; delete them now.

    19.34

    executing-macro

Please delete that too.

Re: Incompatible change without "warning"

[Nick Roberts]

I've removed:

 dot
 dot-max
 dot-min
 dot-marker
 buffer-flush-undo
 compiled-function-p
 allout-exposure
 focus-frame
 unfocus-frame

I wasn't sure how to remove executing-macro as it is a builtin variable:


(make-obsolete-variable 'executing-macro 'executing-kbd-macro "before 19.34")


  DEFVAR_LISP ("executing-macro", &Vexecuting_macro,
	       doc: /* Currently executing keyboard macro (string or vector); nil if none executing.  */);

  DEFVAR_INT ("executing-macro-index", &executing_macro_index,
	      doc: /* Index in currently executing keyboard macro; undefined if none executing.  */);

  DEFVAR_LISP_NOPRO ("executing-kbd-macro", &Vexecuting_macro,
		     doc: /* Currently executing keyboard macro (string or vector); nil if none executing.  */);


Note that if you remove executing-macro you need to change the elisp manual:

   * The state of keyboard macro execution is saved and restored.  While
     Edebug is active, `executing-macro' is bound to
     `edebug-continue-kbd-macro'.

(Edebug -> The Outside Context -> Checking Whether to Stop)

Here are some more obsolete functions/variables:

19.15
unread-command-char

19.23
allout-old-expose-topic

19.34
post-command-idle-hook
post-command-idle-delay

20.1
define-function
truncate-string

20.3
chars-in-region
update-iso-coding-systems
coding-system-parent

20.4
sref

Quite a lot from 21.1
Quite a lot with no timestamp.


Nick

Re: Incompatible change without "warning"

[Luc Teirlinck]

Nick Roberts wrote:

   I wasn't sure how to remove executing-macro as it is a builtin variable:

Please wait before removing this, until the following has been considered.

Richard Stallman wrote:

       19.34

       executing-macro

   Please delete that too.

I believe that Richard may have been unaware of the fact that, until
very recently, executing-macro and _not_ executing-kbd-macro were
documented in the Elisp manual.  This only got changed in August 2004
in CVS.  (Actually, I changed one occurrence of executing-kbd-macro
just moments ago.)  So people using the Elisp manual for reference are
likely to have kept using executing-macro.  Do we still want to remove
it given that?

Sincerely,

Luc.

Re: Incompatible change without "warning"

[Richard Stallman]

      DEFVAR_LISP ("executing-macro", &Vexecuting_macro,
		   doc: /* Currently executing keyboard macro (string or vector); nil if none executing.  */);

      DEFVAR_INT ("executing-macro-index", &executing_macro_index,
		  doc: /* Index in currently executing keyboard macro; undefined if none executing.  */);

      DEFVAR_LISP_NOPRO ("executing-kbd-macro", &Vexecuting_macro,
			 doc: /* Currently executing keyboard macro (string or vector); nil if none executing.  */);

I will change that one.


    Note that if you remove executing-macro you need to change the elisp manual:

       * The state of keyboard macro execution is saved and restored.  While
	 Edebug is active, `executing-macro' is bound to
	 `edebug-continue-kbd-macro'.

That isn't true anyway, so it is a good thing you pointed me at it.

Re: Incompatible change without "warning"

[Richard Stallman]

    19.15
    unread-command-char

That was fairly widely used, so I don't think it should be deleted.
There is likely to be user code that still refers to this.

    19.23
    allout-old-expose-topic

Since that is just part of allout, it is rather specialized;
please delete it.

    19.34
    post-command-idle-hook
    post-command-idle-delay

Some Emacs packages still use these, so we should
leave them alone for now.  I will add something to TODO to
get convert the places that use this, after the release.

    20.1
    define-function
    truncate-string

Those were rather specialized, and existed as non-obsolete
for a short enough time, so pleae delete them.

    20.3
    chars-in-region
    update-iso-coding-systems
    coding-system-parent

Those are rather obscure Mule things, so please get rid of them.

    20.4
    sref

That was a rather obscure Mule thing, so please get rid of it.

Re: Incompatible change without "warning"

[Richard Stallman]

    Quite a lot with no timestamp.

They might be obsolete since long long ago.  What are they?

Re: Incompatible change without "warning"

[Luc Teirlinck]

I guess that the following line should be removed from subr.el:

(make-obsolete-variable 'executing-macro 'executing-kbd-macro "before 19.34")

But just to make sure that there are no misunderstandings.  When I
said that the use of executing-macro was recommended by the Elisp
manual until August 2004, I was not referring to edebug.texi.  I was
referring to `(elisp)Keyboard Macros' which until then used to say:

 -- Variable: executing-macro
     This variable contains the string or vector that defines the
     keyboard macro that is currently executing.  It is `nil' if no
     macro is currently executing.  A command can test this variable so
     as to behave differently when run from an executing macro.  Do not
     set this variable yourself.

It seems strange to remove a variable just one single release after
stopping recommending its use.

Sincerely,

Luc.

Re: Incompatible change without "warning"

[Nick Roberts]

 >     Quite a lot with no timestamp.
 > 
 > They might be obsolete since long long ago.  What are they?

desktop.el: desktop-enable
            desktop-buffer-modes-to-save
            desktop-buffer-misc-functions
            desktop-buffer-handlers
            desktop-load-default

dired-x.el: dired-omit-files-p

font-core.el: font-lock-defaults-alist

font-lock.el: font-lock-reference-face

log-edit.el: cvs-commit-buffer-require-final-newline
             cvs-changelog-full-paragraphs

mwheel.el: mouse-wheel-down-button
           mouse-wheel-up-button
           mouse-wheel-click-button

outline.el: outline-visible

pcvs-defs.el: cvs-diff-ignore-marks
              cvs-diff-buffer-name

subr.el: assoc-ignore-case
         assoc-ignore-representation

tree-widget.el: tree-widget-format-handler

vc-hooks.el: vc-ignore-vc-files
             vc-master-templates
             vc-header-alist

cc-cmds.el: c-comment-line-break-function

cc-vars.el: c-comment-continuation-stars

compile.el: compile-internal

Re: Incompatible change without "warning"

[Richard Stallman]

      So people using the Elisp manual for reference are
    likely to have kept using executing-macro.  Do we still want to remove
    it given that?

They would still have gotten the warning messages when compiling their
code.  However, it looks like a fair variety of programs have reasons
to look at this variable.

So we can put in a defvaralias call.

Re: Incompatible change without "warning"

[Luc Teirlinck]

Richard Stallman wrote:

	 So people using the Elisp manual for reference are
       likely to have kept using executing-macro.  Do we still want to remove
       it given that?

   They would still have gotten the warning messages when compiling their
   code.  However, it looks like a fair variety of programs have reasons
   to look at this variable.

   So we can put in a defvaralias call.

I replaced the make-obsolete-variable with a
define-obsolete-variable-alias, which is equivalent.

Sincerely,

Luc.

Re: Incompatible change without "warning"

[David Kastrup]

Nick Roberts <nickrob@snap.net.nz> writes:

>  >     Quite a lot with no timestamp.
>  > 
>  > They might be obsolete since long long ago.  What are they?
>
> desktop.el: desktop-enable
>             desktop-buffer-modes-to-save
>             desktop-buffer-misc-functions
>             desktop-buffer-handlers
>             desktop-load-default

They are still the standard and only interface in Emacs 21.4.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: Incompatible change without "warning"

[Richard Stallman]

     >     Quite a lot with no timestamp.
     > 
     > They might be obsolete since long long ago.  What are they?

I don't see anything obvious in common between these symbols.  They
have not all been obsolete for a long time; in fact, some (maybe all)
became obsolete recently.

For instance, assoc-ignore-case and assoc-ignore-representation should
be marked as obsolete starting in 22.1.  Likewise, compile-internal.
The others I don't know anything about off hand.

I think what needs to be done is first to determine the history of
each of these symbols.  For some of these symbols, perhaps all, the
right thing to do is to add the argument saying which versions they
became obsolete in.

Re: Incompatible change without "warning"

[Nick Roberts]

 > >  >     Quite a lot with no timestamp.
 > >  > 
 > >  > They might be obsolete since long long ago.  What are they?
 > >
 > > desktop.el: desktop-enable
 > >             desktop-buffer-modes-to-save
 > >             desktop-buffer-misc-functions
 > >             desktop-buffer-handlers
 > >             desktop-load-default
 > 
 > They are still the standard and only interface in Emacs 21.4.

Some of these don't seem to be obsoleted correctly, in any case e.g the only
reference I can find to desktop-buffer-misc-functions is

(make-obsolete-variable 'desktop-buffer-misc-functions
                        'desktop-save-buffer)

i.e desktop-buffer-misc-functions is no longer a variable in Emacs 22.0.50

Shall I replace these with, e.g.:

(define-obsolete-variable-alias 'desktop-buffer-misc-functions
                                'desktop-save-buffer "22.0")


Nick

Re: Incompatible change without "warning"

[Richard Stallman]

    They are still the standard and only interface in Emacs 21.4.

Thanks.  Could you mark them as obsolete since 22.1?

Re: Incompatible change without "warning"

[Luc Teirlinck]

Nick Roberts wrote:

   (define-obsolete-variable-alias 'desktop-buffer-misc-functions
				   'desktop-save-buffer "22.0")

Without commenting on any other part of the message, I believe that it
should be "22.1", that is the first _released_ version in which it is
going to be obsolete, not "22.0".

Sincerely,

Luc.

Re: Incompatible change without "warning"

[David Kastrup]

Nick Roberts <nickrob@snap.net.nz> writes:

>  > >  >     Quite a lot with no timestamp.
>  > >  > 
>  > >  > They might be obsolete since long long ago.  What are they?
>  > >
>  > > desktop.el: desktop-enable
>  > >             desktop-buffer-modes-to-save
>  > >             desktop-buffer-misc-functions
>  > >             desktop-buffer-handlers
>  > >             desktop-load-default
>  > 
>  > They are still the standard and only interface in Emacs 21.4.
>
> Some of these don't seem to be obsoleted correctly, in any case e.g the only
> reference I can find to desktop-buffer-misc-functions is
>
> (make-obsolete-variable 'desktop-buffer-misc-functions
>                         'desktop-save-buffer)
>
> i.e desktop-buffer-misc-functions is no longer a variable in Emacs 22.0.50
>
> Shall I replace these with, e.g.:
>
> (define-obsolete-variable-alias 'desktop-buffer-misc-functions
>                                 'desktop-save-buffer "22.0")

If I remember correctly, this is not going to cut it: I think I had to
change preview-latex to use the new interface since the old interface
was not supported at all any more.  It was not just a matter of
renaming variables: I also had to change other stuff.

There is probably no sense in declaring a variable an obsolete alias
if it does not even work!  I think we should add a compatibility layer
with the old interface (can't be much more than three lines or so)
that we'll remove with 23.1 or so.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: Incompatible change without "warning"

[Richard Stallman]

    Some of these don't seem to be obsoleted correctly, in any case e.g the only
    reference I can find to desktop-buffer-misc-functions is

    (make-obsolete-variable 'desktop-buffer-misc-functions
			    'desktop-save-buffer)

    i.e desktop-buffer-misc-functions is no longer a variable in Emacs 22.0.50

    Shall I replace these with, e.g.:

    (define-obsolete-variable-alias 'desktop-buffer-misc-functions
				    'desktop-save-buffer "22.0")

That might be the right approach, but first can you find which person
deleted it and ask him if it still needs to exist?

Re: Incompatible change without "warning"

[Richard Stallman]

    There is probably no sense in declaring a variable an obsolete alias
    if it does not even work! 

I agree.

			       I think we should add a compatibility layer
    with the old interface (can't be much more than three lines or so)
    that we'll remove with 23.1 or so.

If a compatibility layer can be added, so as to make the old names work,
that would indeed be a good thing to do.