GNU bug report logs - #21225
25.0.50; doc strings of `define-obsolete-*'

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 21225 in the body.
You can then email your comments to 21225 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: 25.0.50; doc strings of `define-obsolete-*'
Date: Sun, 9 Aug 2015 10:28:50 -0700 (PDT)

Argument WHEN is not described at all for some of these macros.  For
others it is described incorrectly or only via an example.  It needs to
be described clearly.

The correct description is, in all cases, what is said in the Elisp
manual for `make-obsolete':

   If provided, WHEN should be a string indicating when the function
   was first made obsolete=81\for example, a date or a release number.

(with "function" replaced by "face" or "variable", as appropriate),
except that "version number" is preferable to "release number".

These macros are used by users and 3rd-party libraries too, not just by
core Emacs development, and in such contexts "release" is not
necessarily appropriate.  The most important remark, however, is that "a
date" should be offered as an example of a WHEN value, in addition to "a
version number".

The same change should be made for the Elisp manual, node `Variable
Aliases'.  It is better to say "for example, a date or a version number"
than just "(usually a version number string)".

In GNU Emacs 25.0.50.1 (i686-pc-mingw32)
 of 2015-07-03 on LEG570
Repository revision: 2b848fadd51e805b2f46da64c5958ea7f009048a
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --host=3Di686-pc-mingw32 --enable-checking=3Dyes,glyphs'

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

From: Drew Adams <drew.adams <at> oracle.com>
To: 21225 <at> debbugs.gnu.org
Subject: RE: bug#21225: 25.0.50; doc strings of `define-obsolete-*'
Date: Sun, 9 Aug 2015 10:35:09 -0700 (PDT)

I forgot to add:

The doc (doc strings and manual) should make clear that the args
are evaluated.  This is not obvious, as these are macros.

For example, this is needed:

(define-obsolete-variable-alias 'last-input-char 'last-input-event
  "at least 19.34")

This is no good:

(define-obsolete-variable-alias last-input-char last-input-event
  "at least 19.34")

The current doc is quite unclear about this, especially by just
referring to the args as "*-NAME".  (Nothing wrong with those
parameter names, as long as you make clear that the args are
evaluated.)

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

From: Artur Malabarba <bruce.connor.am <at> gmail.com>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 21225 <at> debbugs.gnu.org
Subject: Re: bug#21225: 25.0.50; doc strings of `define-obsolete-*'
Date: Tue, 11 Aug 2015 13:50:09 +0100

> The doc (doc strings and manual) should make clear that the args
> are evaluated.  This is not obvious, as these are macros.

Yes please. Everytime I use these I have to manually check their
behavior because I'm never sure just by reading the docstring.

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

From: Stefan Monnier <monnier <at> iro.umontreal.ca>
To: Artur Malabarba <bruce.connor.am <at> gmail.com>
Cc: Drew Adams <drew.adams <at> oracle.com>, 21225 <at> debbugs.gnu.org
Subject: Re: bug#21225: 25.0.50; doc strings of `define-obsolete-*'
Date: Tue, 11 Aug 2015 12:07:46 -0400

>> The doc (doc strings and manual) should make clear that the args
>> are evaluated.  This is not obvious, as these are macros.
> Yes please. Everytime I use these I have to manually check their
> behavior because I'm never sure just by reading the docstring.

Maybe a better fix is to turn them into functions (which basically
means, to add special support for them in the byte-compiler, since
that's the only reason they're defined as macros, AFAIK).


        Stefan

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

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 21225 <at> debbugs.gnu.org
Subject: Re: bug#21225: 25.0.50; doc strings of `define-obsolete-*'
Date: Sat, 30 Apr 2016 23:52:45 +0200

Drew Adams <drew.adams <at> oracle.com> writes:

> Argument WHEN is not described at all for some of these macros.  For
> others it is described incorrectly or only via an example.  It needs to
> be described clearly.
>
> The correct description is, in all cases, what is said in the Elisp
> manual for `make-obsolete':
>
>    If provided, WHEN should be a string indicating when the function
>    was first made obsolete=81\for example, a date or a release number.
>
> (with "function" replaced by "face" or "variable", as appropriate),
> except that "version number" is preferable to "release number".

I've now done so.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Previous Next

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