defcustom :version

defcustom :version

[Bill Wohler]

We don't use any :version keywords in the MH-E package at the moment,
although I'd like to add them. Before doing so, I hope you can help me
answer a couple of questions about them.

First, how are people using the defcustom :version keyword?

The big problem I have with them is that it seems we have to use the
Emacs version. That makes them pretty useless for the MH-E package which
has turned three *major* releases and a score of minor releases since
Emacs 21 came out. In the past few years, I would have used 21.4, 21.5,
22.0, and 22.1 as the "next" version kept creeping up. How would I have
documented the variables? The numbers would have kept changing, and
would have been for a version that turned into a patch release (21.4) or
were never released (21.5) (apologies if I've rewritten history, but you
get the idea). And what would the user, who is using a released version
of MH-E, supposed to do with a documented version that doesn't exist?

I see the Gnus folks are using the Emacs version in their variables. How
have you folks answered these questions?

It seems that the answer is, "Ignore the versions unless you are using
the package bundled with an Emacs release." I guess I could live with
that.

Unless, of course, folks think is reasonable and proper that large
independent packages that happen to be bundled with Emacs can use their
versions with the defcustom :version keyword.

-- 
Bill Wohler <wohler@newt.com>  http://www.newt.com/wohler/  GnuPG ID:610BD9AD
Maintainer of comp.mail.mh FAQ and MH-E. Vote Libertarian!
If you're passed on the right, you're in the wrong lane.

Re: defcustom :version

[Luc Teirlinck]

Bill Wohler wrote:

   Unless, of course, folks think is reasonable and proper that large
   independent packages that happen to be bundled with Emacs can use their
   versions with the defcustom :version keyword.

No, because that would give problems with `customize-changed'.  For
packages included with the Emacs distribution the :version keyword
should be the first released version of Emacs that contains the
defcustom with its current standard value.  Note however that a
defcustom needs no :version keyword if the :version is the same as
that of the defgroup.  Defcustoms in packages not distributed with
Emacs should have no :version keyword.

`M-x customize-changed RET 21.4 RET' is supposed to show the user all
defcustoms that were added, or whose standard value changed, in Emacs
22.1.  That is the main purpose of the :version keyword.  Of course,
the fact that you get a 2811 line long Custom buffer limits the
usefulness of this feature.  Once upon a time, when Emacs releases
used to be much more frequent than they are now, `M-x customize-changed'
was one of the most useful things to do when a new Emacs version came out.

Sincerely,

Luc.

Re: defcustom :version

[Luc Teirlinck]

>From my previous message:

    Of course, the fact that you get a 2811 line long Custom buffer limits
    the usefulness of this feature.

Plus, if you have a slow machine, it might take a while before you get
to see that buffer and plenty of files will be loaded.  So the feature
is definitely not as useful and convenient any more as it used to be,
but it still exists and it uses the :version keyword.

Sincerely,

Luc.

Re: defcustom :version

[Reiner Steib]

On Sat, Mar 11 2006, Bill Wohler wrote:

> We don't use any :version keywords in the MH-E package at the moment,
> although I'd like to add them. Before doing so, I hope you can help me
> answer a couple of questions about them.
>
> First, how are people using the defcustom :version keyword?

Maybe you already know this but... you don't need to add the keyword
to each variable: You can also add it to the custom group. 

> The big problem I have with them is that it seems we have to use the
> Emacs version. That makes them pretty useless for the MH-E package which
> has turned three *major* releases and a score of minor releases since
> Emacs 21 came out. In the past few years, I would have used 21.4, 21.5,
> 22.0, and 22.1 as the "next" version kept creeping up. How would I have
> documented the variables? [...]
>
> I see the Gnus folks are using the Emacs version in their
> variables. 

Admittedly, many Gnus developers weren't aware of :version, so I added
many of version numbers after Jan D. pointed it out on emacs-devel
after Gnus was updated there.

> How have you folks answered these questions?

Not really an answer to the questions you raised, but this is how I
suggest to handle it in Gnus:

,----[ (info "(gnus-coding)Gnus Maintainance Guide") ]
| For new customizable variables introduced in Oort Gnus (including the
| v5-10 branch) use `:version "22.1" ;; Oort Gnus' including the comment.
| If the variable is new in No Gnus use `:version "23.0" ;; No Gnus'.
`----

> Unless, of course, folks think is reasonable and proper that large
> independent packages that happen to be bundled with Emacs can use their
> versions with the defcustom :version keyword.

This only would make sense if `customize-changed-options' could handle
such "package versions".  Maybe extending the format to allow plists
such as...

  :version '(:emacs 22.1 :mh-e 7.0)
  :version '(:emacs 22.1 :gnus 5.10.2)

("mh-e" / "gnus" could either refer to the package or to a
customization group.  The later might be difficult for Gnus because
not everything included in Gnus is within the `gnus' customization
group)

Limiting `customize-changed-options' to certain custom groups (and
subgroups) would be useful independent of extending :version keyword.

Bye, Reiner.
-- 
       ,,,
      (o o)
---ooO-(_)-Ooo---  |  PGP key available  |  http://rsteib.home.pages.de/

Re: defcustom :version

[Bill Wohler]

Luc Teirlinck <teirllm@dms.auburn.edu> wrote:

> `M-x customize-changed RET 21.4 RET' is supposed to show the user all
> defcustoms that were added, or whose standard value changed, in Emacs
> 22.1.  That is the main purpose of the :version keyword.  Of course,
> the fact that you get a 2811 line long Custom buffer limits the
> usefulness of this feature.  Once upon a time, when Emacs releases
> used to be much more frequent than they are now, `M-x customize-changed'
> was one of the most useful things to do when a new Emacs version came out.

Thanks for telling me about customize-changed, Luc. I wasn't aware of
its presence, and yes, I would find it extremely useful with a new
version (of whatever).

I currently use some Perl to generate a list for MH-E's release notes,
but the algorithm probably isn't perfect (grep for defcustom before and
after, grab the second word, and diff).

Taking a quick look at the customize-changed code, it occurred to me
that the following would make sense and be fairly easy to implement
(although I am not suggesting we do it before the release):

1. Create a :package-version customize keyword.
2. Bind it to a custom-package-version symbol.
3. Refactor customize-changed to accept two new optional arguments which is
   the prefix of the package and the version symbol to use
   ('custom-version by default).
4. Add a customize-package-changed function which would call
   (customize-changed since-version prefix 'custom-package-version)

Note that #3 would address your concerns about the copious output from
the current implementation. You could say (customize-changed nil
"custom") to limit the output to changes in customize.

If this seems like a good idea, I would suggest we do make
:package-version a valid keyword (by safely adding a single line to the
cond in custom-handle-keyword) so that I can add it to MH-E before the
release so that it is there for future use.

-- 
Bill Wohler <wohler@newt.com>  http://www.newt.com/wohler/  GnuPG ID:610BD9AD
Maintainer of comp.mail.mh FAQ and MH-E. Vote Libertarian!
If you're passed on the right, you're in the wrong lane.

Re: defcustom :version

[Richard Stallman]

    The big problem I have with them is that it seems we have to use the
    Emacs version. That makes them pretty useless for the MH-E package which
    has turned three *major* releases and a score of minor releases since
    Emacs 21 came out. In the past few years, I would have used 21.4, 21.5,
    22.0, and 22.1 as the "next" version kept creeping up. How would I have
    documented the variables?

It is a minor issue.  Just put in version 22.1.

Re: defcustom :version

[Bill Wohler]

Reiner Steib <reinersteib+gmane@imap.cc> wrote:

> On Sat, Mar 11 2006, Bill Wohler wrote:
> 
> > We don't use any :version keywords in the MH-E package at the moment,
> > although I'd like to add them. Before doing so, I hope you can help me
> > answer a couple of questions about them.
> >
> > First, how are people using the defcustom :version keyword?
> 
> Maybe you already know this but... you don't need to add the keyword
> to each variable: You can also add it to the custom group. 

Yup, I did.

> Not really an answer to the questions you raised, but this is how I
> suggest to handle it in Gnus:
> 
> ,----[ (info "(gnus-coding)Gnus Maintainance Guide") ]
> | For new customizable variables introduced in Oort Gnus (including the
> | v5-10 branch) use `:version "22.1" ;; Oort Gnus' including the comment.
> | If the variable is new in No Gnus use `:version "23.0" ;; No Gnus'.
> `----

Good idea. That way you'll at least have the information available until
it can be incorporated. I'll do that for now.

> > Unless, of course, folks think is reasonable and proper that large
> > independent packages that happen to be bundled with Emacs can use their
> > versions with the defcustom :version keyword.
> 
> This only would make sense if `customize-changed-options' could handle
> such "package versions".  Maybe extending the format to allow plists
> such as...
> 
>   :version '(:emacs 22.1 :mh-e 7.0)
>   :version '(:emacs 22.1 :gnus 5.10.2)

Good. That would actually be more general than the solution I proposed.

-- 
Bill Wohler <wohler@newt.com>  http://www.newt.com/wohler/  GnuPG ID:610BD9AD
Maintainer of comp.mail.mh FAQ and MH-E. Vote Libertarian!
If you're passed on the right, you're in the wrong lane.

Re: defcustom :version

[Richard Stallman]

    `M-x customize-changed RET 21.4 RET' is supposed to show the user all
    defcustoms that were added, or whose standard value changed, in Emacs
    22.1.  That is the main purpose of the :version keyword.  Of course,
    the fact that you get a 2811 line long Custom buffer limits the
    usefulness of this feature.

When a group is new, what does it do?  Include all the options in
that package, or include one item for that group?

Re: defcustom :version

[Richard Stallman]

    3. Refactor customize-changed to accept two new optional arguments which is
       the prefix of the package and the version symbol to use
       ('custom-version by default).

I don't like that idea, because I don't want to expose version numbers
of parts of Emacs to the user.

What could be acceptable is to have :package-version for use in
defcustom, and provide a table to translate that into Emacs versions,
so that customize-changed can deduce from :package-version which options
have changed since the previous Emacs release.

Re: defcustom :version

[Luc Teirlinck]

Richard Stallman wrote:

       `M-x customize-changed RET 21.4 RET' is supposed to show the user all
       defcustoms that were added, or whose standard value changed, in Emacs
       22.1.  That is the main purpose of the :version keyword.  Of course,
       the fact that you get a 2811 line long Custom buffer limits the
       usefulness of this feature.

   When a group is new, what does it do?  Include all the options in
   that package, or include one item for that group?

It includes only the one item for the group, except that all members
of the group that have themselves a :version keyword are also included.

Sincerely,

Luc.

Re: defcustom :version

[Bill Wohler]

Richard Stallman <rms@gnu.org> wrote:

>     3. Refactor customize-changed to accept two new optional arguments which is
>        the prefix of the package and the version symbol to use
>        ('custom-version by default).
> 
> I don't like that idea, because I don't want to expose version numbers
> of parts of Emacs to the user.

OK. In that case, we'd refactor the meat of customize-changed into an
internal routine that both customize-changed and
customize-package-changed would call. Or something like that.

> What could be acceptable is to have :package-version for use in
> defcustom, and provide a table to translate that into Emacs versions,
> so that customize-changed can deduce from :package-version which options
> have changed since the previous Emacs release.

If I understand correctly, only the :package-version keyword would be
used, rather than both a :version and :package-version in my suggestion,
or a plist in the :version in Reiner's suggestion.

I like your idea too. The table provides a nice historical reference,
and in case the "next" Emacs version changes, you only have to change
the version number in one place.

How would you like me to proceed for this release then? To just use
comments as Reiner suggested, or to use a :package-version keyword and
extend custom-handle-keyword to allow it?

-- 
Bill Wohler <wohler@newt.com>  http://www.newt.com/wohler/  GnuPG ID:610BD9AD
Maintainer of comp.mail.mh FAQ and MH-E. Vote Libertarian!
If you're passed on the right, you're in the wrong lane.

Re: defcustom :version

[Richard Stallman]

	   22.1.  That is the main purpose of the :version keyword.  Of course,
	   the fact that you get a 2811 line long Custom buffer limits the
	   usefulness of this feature.

       When a group is new, what does it do?  Include all the options in
       that package, or include one item for that group?

    It includes only the one item for the group, except that all members
    of the group that have themselves a :version keyword are also included.

How many group members get included in that way,
at present?

That is, could we make the output substantially shorter
if we eliminated all the variables that are in groups
which are themselved mentioned?

Re: defcustom :version

[Richard Stallman]

    How would you like me to proceed for this release then? To just use
    comments as Reiner suggested, or to use a :package-version keyword and
    extend custom-handle-keyword to allow it?

Please try implementing the extension, and see how simple and safe it is.

Re: defcustom :version

[Bill Wohler]

Richard Stallman <rms@gnu.org> writes:

>     How would you like me to proceed for this release then? To just use
>     comments as Reiner suggested, or to use a :package-version keyword and
>     extend custom-handle-keyword to allow it?
>
> Please try implementing the extension, and see how simple and safe it is.

OK. Once it is done, I'll ACK before committing to solicit feedback.

-- 
Bill Wohler <wohler@newt.com>  http://www.newt.com/wohler/  GnuPG ID:610BD9AD
Maintainer of comp.mail.mh FAQ and MH-E. Vote Libertarian!
If you're passed on the right, you're in the wrong lane.

Re: defcustom :version

[Luc Teirlinck]

Richard Stallman wrote:

       It includes only the one item for the group, except that all members
       of the group that have themselves a :version keyword are also included.

   How many group members get included in that way,
   at present?

   That is, could we make the output substantially shorter
   if we eliminated all the variables that are in groups
   which are themselved mentioned?

One could reduce it from 2811 to 2635 and possibly _slightly_ less
because there may be a few cases I overlooked.  This requires
eliminating several :version keywords that are _older_ than the
:version in the defgroup, because the defcustom got moved to a new
group.

Sincerely,

Luc.

Re: defcustom :version

[Luc Teirlinck]

>From my previous reply:

      How many group members get included in that way,
      at present?

      That is, could we make the output substantially shorter
      if we eliminated all the variables that are in groups
      which are themselved mentioned?

   One could reduce it from 2811 to 2635 and possibly _slightly_ less
   because there may be a few cases I overlooked.

No, it could not really be reduced to 2635.  I got confused by
gnus-agent.  That group is not really new in Emacs 22.1.  Something
made me think it was and that group accounted for much of the
reduction I thought possible.

Sincerely,

Luc.

Re: defcustom :version

[Richard Stallman]

    One could reduce it from 2811 to 2635 and possibly _slightly_ less
    because there may be a few cases I overlooked.  This requires
    eliminating several :version keywords that are _older_ than the
    :version in the defgroup, because the defcustom got moved to a new
    group.

I don't follow the scenario you describe, but don't bother explaining
it.  Reduction down to 2635 lines is not enough reduction to make the
situation much better.  We need stronger measures.  We need to give
this some structure.

Here's an idea.  customize-changed could work like customize-browse,
except that it would show only the groups that cover settings which
have changed meanings.

What do you think?

Re: defcustom :version

[Bill Wohler]

Richard Stallman <rms@gnu.org> wrote:

> Here's an idea.  customize-changed could work like customize-browse,
> except that it would show only the groups that cover settings which
> have changed meanings.
> 
> What do you think?

I like it, with one caveat.

As I browsed the output of customized-changed, a couple of variables
caught my eye that I would have missed if they were hidden in a tree
structure. However, that concern would be mitigated with an Expand All
button (with a corresponding Collapse All button).

By the way, the prompt for customize-browse says "(default all
versions)". I don't understand what that means. It tells me, Show all
options that are different from any other version. But this is
essentially *every* option. I think this prompt should read, (default
last version).

-- 
Bill Wohler <wohler@newt.com>  http://www.newt.com/wohler/  GnuPG ID:610BD9AD
Maintainer of comp.mail.mh FAQ and MH-E. Vote Libertarian!
If you're passed on the right, you're in the wrong lane.

Re: defcustom :version

[Luc Teirlinck]

Richard Stallman wrote:

   I don't follow the scenario you describe, but don't bother explaining
   it.  Reduction down to 2635 lines is not enough reduction to make the
   situation much better.  We need stronger measures.  We need to give
   this some structure.

   Here's an idea.  customize-changed could work like customize-browse,
   except that it would show only the groups that cover settings which
   have changed meanings.

   What do you think?

That would obviously not reduce the total number of listed options.
(There quite simply is no way to reduce that substantially.)  It would
not help somebody wanting to take a look at all of them (quite to the
contrary).  And with the current one-buffer layout, at least they are
listed alphabetically and one can use C-s.  It would also not do
anything about the problem that the command may take a very long time
on slow machines (it could actually make it worse).

So I do not believe that this change would be a good idea.  I believe
we should just leave things as they are.

Sincerely,

Luc.

Re: defcustom :version

[Bill Wohler]

[Wondering if we should take ding@gnus.org off of the cc list...]

Luc Teirlinck <teirllm@dms.auburn.edu> wrote:

> Richard Stallman wrote:
> 
>    I don't follow the scenario you describe, but don't bother explaining
>    it.  Reduction down to 2635 lines is not enough reduction to make the
>    situation much better.  We need stronger measures.  We need to give
>    this some structure.
> 
>    Here's an idea.  customize-changed could work like customize-browse,
>    except that it would show only the groups that cover settings which
>    have changed meanings.
> 
>    What do you think?
> 
> That would obviously not reduce the total number of listed options.

I don't think that was the point. If we couldn't reduce the number of
items, the point was to display them differently.

>                                                               It would
> not help somebody wanting to take a look at all of them (quite to the
> contrary).

I think it would, with a "Expand All" button. The user could then close
off sub-trees they knew they were not interested in, which you can't do
in the existing buffer. Or vice versa--the user could start collapsed
and expand sub-trees they were interested in. It occurred to me that
we'd need an Expand Entire Sub-Tree button too.

>             And with the current one-buffer layout, at least they are
> listed alphabetically and one can use C-s.

I rarely know the name of the variable before I know about it ;-).

>                                             It would also not do
> anything about the problem that the command may take a very long time
> on slow machines (it could actually make it worse).

A legitimate concern, but I think the inverse will be true.
Instrumenting the customize-change function, I see that it takes than a
second to gather the options (on my machine), but over 30 seconds to
render them. customize-browse is pretty much instantaneous on my
machine, and would only be slowed by about a second (per above) to
gather the options. Even expanding the entire customize-browse tree
should be faster since it doesn't do as much rendering. But the
advantage of the tree control is that you don't have to pay that price
unless you want to.

p.s. Shouldn't customize-changed-options-previous-release be 21.4, not
21.1?

-- 
Bill Wohler <wohler@newt.com>  http://www.newt.com/wohler/  GnuPG ID:610BD9AD
Maintainer of comp.mail.mh FAQ and MH-E. Vote Libertarian!
If you're passed on the right, you're in the wrong lane.

Re: defcustom :version

[Luc Teirlinck]

Bill Wohler wrote:

   p.s. Shouldn't customize-changed-options-previous-release be 21.4, not
   21.1?

No, it is supposed to be the last _major_ release, which is 21.1.

   By the way, the prompt for customize-browse says "(default all
   versions)". I don't understand what that means. It tells me, Show all
   options that are different from any other version. But this is
   essentially *every* option. I think this prompt should read, (default
   last version).

Last major release, but this is long and the prompt is already long.
We could just make it (default 21.1), without hardcoding the 21.1,
using the following patch, which I can install if desired.

===File ~/cus-edit-diff=====================================
*** cus-edit.el	03 Mar 2006 11:17:02 -0600	1.287
--- cus-edit.el	14 Mar 2006 18:52:54 -0600	
***************
*** 1092,1098 ****
  With argument SINCE-VERSION (a string), customize all settings
  that were added or redefined since that version."
  
!   (interactive "sCustomize options changed, since version (default all versions): ")
    (if (equal since-version "")
        (setq since-version nil)
      (unless (condition-case nil
--- 1092,1102 ----
  With argument SINCE-VERSION (a string), customize all settings
  that were added or redefined since that version."
  
!   (interactive
!    (list
!     (read-from-minibuffer
!      (format "Customize options changed, since version (default %s): "
! 	     customize-changed-options-previous-release))))
    (if (equal since-version "")
        (setq since-version nil)
      (unless (condition-case nil
============================================================

Re: defcustom :version

[Bill Wohler]

Luc Teirlinck <teirllm@dms.auburn.edu> wrote:

> Bill Wohler wrote:
> 
>    p.s. Shouldn't customize-changed-options-previous-release be 21.4, not
>    21.1?
> 
> No, it is supposed to be the last _major_ release, which is 21.1.

Why not the last release? That's usually the one that folks are
upgrading from.

>    By the way, the prompt for customize-browse says "(default all
>    versions)". I don't understand what that means. It tells me, Show all
>    options that are different from any other version. But this is
>    essentially *every* option. I think this prompt should read, (default
>    last version).
> 
> Last major release, but this is long and the prompt is already long.
> We could just make it (default 21.1), without hardcoding the 21.1,
> using the following patch, which I can install if desired.

Even better than my suggestion. Thanks.

-- 
Bill Wohler <wohler@newt.com>  http://www.newt.com/wohler/  GnuPG ID:610BD9AD
Maintainer of comp.mail.mh FAQ and MH-E. Vote Libertarian!
If you're passed on the right, you're in the wrong lane.

Re: defcustom :version

[Richard Stallman]

    By the way, the prompt for customize-browse says "(default all
    versions)". I don't understand what that means. It tells me, Show all
    options that are different from any other version. But this is
    essentially *every* option. I think this prompt should read, (default
    last version).

Do you mean the prompt of customize-changed?

Re: defcustom :version

[Richard Stallman]

       Here's an idea.  customize-changed could work like customize-browse,
       except that it would show only the groups that cover settings which
       have changed meanings.

       What do you think?

    That would obviously not reduce the total number of listed options.
    (There quite simply is no way to reduce that substantially.)  It would
    not help somebody wanting to take a look at all of them (quite to the
    contrary).

That is true, but so what?  The idea is beneficial in other ways.

Most people don't use all of Emacs.  They don't particularly want to
look at all the changed options.  They want to see all the changed
options that are relevant to their usage.

This feature will be very helpful in doing that.

Re: defcustom :version

[Bill Wohler]

Richard Stallman <rms@gnu.org> wrote:

>     By the way, the prompt for customize-browse says "(default all
>     versions)". I don't understand what that means. It tells me, Show all
>     options that are different from any other version. But this is
>     essentially *every* option. I think this prompt should read, (default
>     last version).
> 
> Do you mean the prompt of customize-changed?

Whoops, yes. However, I prefer Luc's idea of inserting the value of
customize-changed-options-previous-release to make the comparison
explicit, especially if the "last version" isn't really the last
version.

-- 
Bill Wohler <wohler@newt.com>  http://www.newt.com/wohler/  GnuPG ID:610BD9AD
Maintainer of comp.mail.mh FAQ and MH-E. Vote Libertarian!
If you're passed on the right, you're in the wrong lane.

Re: defcustom :version

[Richard Stallman]

    We could just make it (default 21.1), without hardcoding the 21.1,
    using the following patch, which I can install if desired.

I like that change.

Re: defcustom :version

[Bill Wohler]

Richard Stallman <rms@gnu.org> wrote:

>     How would you like me to proceed for this release then? To just use
>     comments as Reiner suggested, or to use a :package-version keyword and
>     extend custom-handle-keyword to allow it?
> 
> Please try implementing the extension, and see how simple and safe it is.

Richard,

I think it's both simple and safe to add a :package-version keyword and
create a lookup table to map the package version to the Emacs version as
you asked.

The symbol lookup code took 62 ms before the changes, and 87 ms after
the changes (28%). As I added mappings between MH-E and Emacs versions,
the times slipped to 90 ms or an additional 3%. Given that the display
of the customization buffer takes an additional 103 seconds, I don't
think we have to worry too much here.

I welcome your comments on the names and implementation, as well as a
go-ahead to check in the changes. Once that is done, I'll update NEWS
and the manual appropriately.

Here is how MH-E would tap into the new functionality:

  (add-to-list 'customize-package-emacs-version-alist
	       '(MH-E ("6.0" "22.1") ("6.1" "22.1") ("7.0" "22.1")
	              ("7.1" "22.1") ("7.2" "22.1") ("7.3" "22.1")
		      ("7.4" "22.1") ("8.0" "22.1")))

  ...

  (defgroup mh-e nil
    "Emacs interface to the MH mail system.
  MH is the Rand Mail Handler. Other implementations include nmh
  and GNU mailutils."
    :link '(custom-manual "(mh-e)Top")
    :group 'mail
    :package-version '(MH-E "8.0"))
  ...

Here's a ChangeLog entry to give you context and diffs to the
implementation:

	* custom.el (defcustom, custom-handle-keyword): Add
	:package-version keyword.
	(custom-add-package-version): New function. Sets value of new
	property 'custom-package-version from :package-version keyword.

	* cus-edit.el (customize-package-emacs-version-alist): New
	variable.
	(customize-changed-options): Add check for custom-package-version.
	(customize-package-emacs-version): New function to look up Emacs
	version corresponding to the given package version.


Index: custom.el
===================================================================
RCS file: /cvsroot/emacs/emacs/lisp/custom.el,v
retrieving revision 1.123
diff -u -r1.123 custom.el
--- custom.el	21 Mar 2006 16:44:09 -0000	1.123
+++ custom.el	29 Mar 2006 00:54:57 -0000
@@ -268,6 +268,12 @@
         VALUE should be a string specifying that the variable was
         first introduced, or its default value was changed, in Emacs
         version VERSION.
+:package-version
+        VALUE should be a list with the form (PACKAGE VERSION)
+        specifying that the variable was first introduced, or its
+        default value was changed, in PACKAGE version VERSION. This
+        keyword takes priority over :version. The PACKAGE and VERSION
+        must appear in `customize-package-emacs-version-alist'.
 :tag LABEL
         Use LABEL, a string, instead of the item's name, to label the item
         in customization menus and buffers.
@@ -489,6 +495,8 @@
 	 (custom-add-to-group value symbol type))
 	((eq keyword :version)
 	 (custom-add-version symbol value))
+	((eq keyword :package-version)
+	 (custom-add-package-version symbol value))
 	((eq keyword :link)
 	 (custom-add-link symbol value))
 	((eq keyword :load)
@@ -540,6 +548,10 @@
   "To the custom option SYMBOL add the version VERSION."
   (put symbol 'custom-version (purecopy version)))
 
+(defun custom-add-package-version (symbol version)
+  "To the custom option SYMBOL add the package version VERSION."
+  (put symbol 'custom-package-version (purecopy version)))
+
 (defun custom-add-load (symbol load)
   "To the custom option SYMBOL add the dependency LOAD.
 LOAD should be either a library file name, or a feature name."

Index: cus-edit.el
===================================================================
RCS file: /cvsroot/emacs/emacs/lisp/cus-edit.el,v
retrieving revision 1.289
diff -u -r1.289 cus-edit.el
--- cus-edit.el	21 Mar 2006 16:44:10 -0000	1.289
+++ cus-edit.el	29 Mar 2006 00:59:18 -0000
@@ -1079,6 +1079,13 @@
 (defvar customize-changed-options-previous-release "21.1"
   "Version for `customize-changed-options' to refer back to by default.")
 
+(defvar customize-package-emacs-version-alist nil
+  "Alist that maps packages to alists of package to Emacs versions.
+Packages are symbols. Versions are strings.
+For example:
+  '((MH-E (\"7.4\" \"22.1\") (\"8.0\" \"22.1\"))
+    (Gnus (\"5.11\" \"22.1\")))")
+
 ;;;###autoload
 (defalias 'customize-changed 'customize-changed-options)
 
@@ -1119,7 +1126,12 @@
   (let (found)
     (mapatoms
      (lambda (symbol)
-       (let ((version (get symbol 'custom-version)))
+        (let* ((package-version (get symbol 'custom-package-version))
+               (version
+                (or (and package-version
+                         (customize-package-emacs-version symbol
+                                                          package-version))
+                    (get symbol 'custom-version))))
 	 (if version
 	     (when (customize-version-lessp since-version version)
 	       (if (or (get symbol 'custom-group)
@@ -1135,6 +1147,31 @@
       (error "No user option defaults have been changed since Emacs %s"
 	     since-version))))
 
+(defun customize-package-emacs-version (symbol package-version)
+  "Return Emacs version of SYMBOL.
+PACKAGE-VERSION has the form (PACKAGE VERSION). The VERSION of
+PACKAGE is looked up in the associated list
+`customize-package-emacs-version-alist' to find the version of
+Emacs that is associated with it."
+  (let (package-versions emacs-version)
+    ;; Use message instead of error since we want user to be able to
+    ;; see the rest of the symbols even if a package author has
+    ;; botched things up.
+    (cond ((not (listp package-version))
+           (message "package-version value incorrect for %s" symbol))
+          ((setq package-versions (assq (car package-version)
+                                        customize-package-emacs-version-alist))
+           (setq emacs-version
+                 (cadr (assoc (cadr package-version) package-versions)))
+           (unless emacs-version
+             (message "Package version of %s not found in %s" symbol
+                      "customize-package-emacs-version-alist")))
+          (t
+           (message "Package %s neglected to update %s"
+                    (car package-version)
+                    "customize-package-emacs-version-alist")))
+    emacs-version))
+
 (defun customize-version-lessp (version1 version2)
   ;; Why are the versions strings, and given that they are, why aren't
   ;; they converted to numbers and compared as such here?  -- fx

-- 
Bill Wohler <wohler@newt.com>  http://www.newt.com/wohler/  GnuPG ID:610BD9AD
Maintainer of comp.mail.mh FAQ and MH-E. Vote Libertarian!
If you're passed on the right, you're in the wrong lane.

Re: defcustom :version

[Richard Stallman]

I think it is worth adding this code now,
so that maintenance can be simpler.

But first I would like a few other people to study the code
and make sure there is no problem with it.  Would people
please study Bill's patch?

Re: defcustom :version

[Bill Wohler]

Richard Stallman <rms@gnu.org> writes:

> I think it is worth adding this code now,
> so that maintenance can be simpler.

Thank you.

> But first I would like a few other people to study the code
> and make sure there is no problem with it.  Would people
> please study Bill's patch?

On a related note, the MH-E and Gnus projects need to provide
backwards compatibility for Emacsen that do not have the
:package-version keyword. I wrote a bit of code to strip the
:package-version keyword and its value before passing it on to
defgroup/defcustom, but have a bit of a bug which I'm sure one of you
can fix handily.

Given the code below, if mh-package-version-defined-flag is nil, the
mh-strip-package-version function does strip the :package-version
keyword and its value, but alas it turns ARGS into (ARGS). For
example, here is the output of macroexpand on the mh-e group:

  (custom-declare-group (quote mh-e) nil
  "Emacs interface to the MH mail system.
  MH is the Rand Mail Handler. Other implementations include nmh
  and GNU mailutils." (:link (quote (custom-manual "(mh-e)Top")) :group
  (quote mail)))

How do I "unlistify" what mh-strip-package-version returns, or
restructure the program to make it unnecessary to do so? I'm not a
strong macro writer, so any other suggestions are solicited as well.
Thanks!


(defvar mh-package-version-defined-flag (and (not mh-xemacs-flag)
                                             (>= emacs-major-version 22))
  "Non-nil means `defgroup' and `defcustom' support :package-version.")

(defmacro mh-defgroup (symbol members doc &rest args)
  "Declare SYMBOL as a customization group containing MEMBERS.
See documentation for `defgroup' for a description of the arguments
SYMBOL, MEMBERS, DOC and ARGS.
This macro is used by Emacs versions that lack the :package-version
keyword, introduced in Emacs 22."
  (declare (doc-string 3))
  (let ((args (if mh-package-version-defined-flag
                  args
                (mh-strip-package-version args))))
    `(defgroup ,symbol ,members ,doc ,args)))

(defun mh-strip-package-version (args)
  "Strip :package-version keyword and its value from ARGS."
  (let (seen)
    (loop for keyword in args
          if (cond ((eq keyword ':package-version) (setq seen t) nil)
                   (seen (setq seen nil) nil)
                   (t t))
          collect keyword)))

-- 
Bill Wohler <wohler@newt.com>  http://www.newt.com/wohler/  GnuPG ID:610BD9AD
Maintainer of comp.mail.mh FAQ and MH-E. Vote Libertarian!
If you're passed on the right, you're in the wrong lane.

Re: defcustom :version

[Luc Teirlinck]

Note that there is a bug in the current implementation of the :version
keyword.  For instance, `M-x customize-changed' lists the group
gnus-agent as new in Emacs 22.1 whereas it was already present in
Emacs 20.7 and possibly earlier.  The problem is that the :version for
`foo' gets stored in the custom-version property of the symbol 'foo.
But `foo' could be two or three of a customizable variable, a custom
group and a face.  All three could have been introduced in different
versions.  One of those could be new in a new release, the others not.
Only that one should be listed by `customize-changed'.  But depending
on luck, either none or all get listed, because only one of the three
:version's winds up being the lucky winner of the "symbol foo
custom-version property contest".

In the case of gnus-agent, the group is not new in 22.1, but the
variable gnus-agent is.

Maybe we should have {option,face,group}-custom-version properties,
maybe after the release.

Sincerely,

Luc.

Re: defcustom :version

[Bill Wohler]

Luc Teirlinck <teirllm@dms.auburn.edu> wrote:

>                                   The problem is that the :version for
> `foo' gets stored in the custom-version property of the symbol 'foo.
> But `foo' could be two or three of a customizable variable, a custom
> group and a face.

I didn't realize that a face could have a version as the defface
docstring doesn't indicate it. Sure enough, defface, as well as
defgroup, call custom-handle-all-keywords so :version is supported. Why
then, are not all the keywords documented in all three macros?

-- 
Bill Wohler <wohler@newt.com>  http://www.newt.com/wohler/  GnuPG ID:610BD9AD
Maintainer of comp.mail.mh FAQ and MH-E. Vote Libertarian!
If you're passed on the right, you're in the wrong lane.

Re: defcustom :version

[Wolfram Fenske]

Bill Wohler <wohler@newt.com> writes:

> [...]
>
> On a related note, the MH-E and Gnus projects need to provide
> backwards compatibility for Emacsen that do not have the
> :package-version keyword. I wrote a bit of code to strip the
> :package-version keyword and its value before passing it on to
> defgroup/defcustom, but have a bit of a bug which I'm sure one of you
> can fix handily.
>
> Given the code below, if mh-package-version-defined-flag is nil, the
> mh-strip-package-version function does strip the :package-version
> keyword and its value, but alas it turns ARGS into (ARGS). For
> example, here is the output of macroexpand on the mh-e group:
>
>   [...]
>
> How do I "unlistify" what mh-strip-package-version returns, or
> restructure the program to make it unnecessary to do so? I'm not a
> strong macro writer, so any other suggestions are solicited as well.
> Thanks!
>
>
> (defvar mh-package-version-defined-flag (and (not mh-xemacs-flag)
>                                              (>= emacs-major-version 22))
>   "Non-nil means `defgroup' and `defcustom' support :package-version.")
>
> (defmacro mh-defgroup (symbol members doc &rest args)
>   "Declare SYMBOL as a customization group containing MEMBERS.
> See documentation for `defgroup' for a description of the arguments
> SYMBOL, MEMBERS, DOC and ARGS.
> This macro is used by Emacs versions that lack the :package-version
> keyword, introduced in Emacs 22."
>   (declare (doc-string 3))
>   (let ((args (if mh-package-version-defined-flag
>                   args
>                 (mh-strip-package-version args))))
>     `(defgroup ,symbol ,members ,doc ,args)))

I think you should replace that last expression with

  `(defgroup ,symbol ,members ,doc ,@args)

",@" works like "," but in addition it "splices" the value into the
enclosing list.  E. g.
  
  (let ((a 1)
        (b '(2 3)))
     `(,a ,b))

evaluates to (1 (2 3)) but

  (let ((a 1)
        (b '(2 3)))
     `(,a ,@b))

evaluates to (1 2 3).
  

> (defun mh-strip-package-version (args)
>   "Strip :package-version keyword and its value from ARGS."
>   (let (seen)
>     (loop for keyword in args
>           if (cond ((eq keyword ':package-version) (setq seen t) nil)
>                    (seen (setq seen nil) nil)
>                    (t t))
>           collect keyword)))


Regards
Wolfram Fenske

Re: defcustom :version

[Bill Wohler]

Wolfram Fenske <Wolfram.Fenske@Student.Uni-Magdeburg.DE> wrote:

> Bill Wohler <wohler@newt.com> writes:
> 
> > Given the code below, if mh-package-version-defined-flag is nil, the
> > mh-strip-package-version function does strip the :package-version
> > keyword and its value, but alas it turns ARGS into (ARGS). For
> > example, here is the output of macroexpand on the mh-e group:

> I think you should replace that last expression with
> 
>   `(defgroup ,symbol ,members ,doc ,@args)
> 
> ",@" works like "," but in addition it "splices" the value into the
> enclosing list.  E. g.

That's it! Thanks for the kind reminder.

-- 
Bill Wohler <wohler@newt.com>  http://www.newt.com/wohler/  GnuPG ID:610BD9AD
Maintainer of comp.mail.mh FAQ and MH-E. Vote Libertarian!
If you're passed on the right, you're in the wrong lane.

Re: defcustom :version

[Richard Stallman]

    Maybe we should have {option,face,group}-custom-version properties,
    maybe after the release.

I think we need to fix this bug now.  Can you write a fix?

Re: defcustom :version

[Richard Stallman]

    I didn't realize that a face could have a version as the defface
    docstring doesn't indicate it. Sure enough, defface, as well as
    defgroup, call custom-handle-all-keywords so :version is supported. Why
    then, are not all the keywords documented in all three macros?

They are, in the node Common Keywords.  

Re: defcustom :version

[Bill Wohler]

Richard Stallman <rms@gnu.org> wrote:

>     I didn't realize that a face could have a version as the defface
>     docstring doesn't indicate it. Sure enough, defface, as well as
>     defgroup, call custom-handle-all-keywords so :version is supported. Why
>     then, are not all the keywords documented in all three macros?
> 
> They are, in the node Common Keywords.  

The docstring implies only :group is supported:

    The remaining arguments should have the form

       [KEYWORD VALUE]...

    The following KEYWORDs are defined:

    :group  VALUE should be a customization group.
	    Add face to that group.

It also doesn't mention the ARGS argument. I would suggest either
enumerating all the legal keywords, or:

    The remaining arguments ARGS should have the form

       [KEYWORD VALUE]...

    See Info node `(elisp)Common Keywords' for the list of KEYWORDs.

-- 
Bill Wohler <wohler@newt.com>  http://www.newt.com/wohler/  GnuPG ID:610BD9AD
Maintainer of comp.mail.mh FAQ and MH-E. Vote Libertarian!
If you're passed on the right, you're in the wrong lane.

Re: defcustom :version

[Richard Stallman]

If you want to work on the doc string of defface, go ahead.

Re: defcustom :version

[Eli Zaretskii]

> Comments: In-reply-to Richard Stallman <rms@gnu.org>
> 	message dated "Fri, 31 Mar 2006 12:28:34 -0500."
> Date: Fri, 31 Mar 2006 10:11:59 -0800
> From: Bill Wohler <wohler@newt.com>
> Cc: ding@gnus.org, emacs-devel@gnu.org
> 
> Richard Stallman <rms@gnu.org> wrote:
> 
> >     I didn't realize that a face could have a version as the defface
> >     docstring doesn't indicate it. Sure enough, defface, as well as
> >     defgroup, call custom-handle-all-keywords so :version is supported. Why
> >     then, are not all the keywords documented in all three macros?
> > 
> > They are, in the node Common Keywords.  
> 
> The docstring implies only :group is supported:
> 
>     The remaining arguments should have the form
> 
>        [KEYWORD VALUE]...
> 
>     The following KEYWORDs are defined:
> 
>     :group  VALUE should be a customization group.
> 	    Add face to that group.
> 
> It also doesn't mention the ARGS argument. I would suggest either
> enumerating all the legal keywords, or:
> 
>     The remaining arguments ARGS should have the form
> 
>        [KEYWORD VALUE]...
> 
>     See Info node `(elisp)Common Keywords' for the list of KEYWORDs.

The reference to the ELisp manual is already in the doc strings, and
the doc string for defgroup already mentions :version explicitly.

Re: defcustom :version

[Bill Wohler]

Richard Stallman <rms@gnu.org> writes:

> I think it is worth adding this code now,
> so that maintenance can be simpler.
>
> But first I would like a few other people to study the code
> and make sure there is no problem with it.  Would people
> please study Bill's patch?

Since no one has reacted negatively, may I go ahead and check in
this patch?

http://article.gmane.org/gmane.emacs.devel/52176

-- 
Bill Wohler <wohler@newt.com> http://www.newt.com/wohler/ GnuPG
ID:610BD9AD Maintainer of comp.mail.mh FAQ and MH-E. Vote Libertarian!
If you're passed on the right, you're in the wrong lane.

Re: defcustom :version

[Richard Stallman]

    Since no one has reacted negatively, may I go ahead and check in
    this patch?

    http://article.gmane.org/gmane.emacs.devel/52176

Please do.

Re: defcustom :version

[Bill Wohler]

Richard Stallman <rms@gnu.org> wrote:

>     Since no one has reacted negatively, may I go ahead and check in
>     this patch?
> 
>     http://article.gmane.org/gmane.emacs.devel/52176
> 
> Please do.

Done. I've updated etc/NEWS and (elisp)Common Keywords accordingly.

Here is the NEWS item. 

  ** defcustom changes:

  *** The package-version keyword has been added to provide
  `customize-changed-options' functionality to packages in the future.
  Developers who make use of this keyword must also update the new
  variable `customize-package-emacs-version-alist'.

I can provide this functionality if you wish. Would you prefer to see an
option argument PACKAGE added to customize-changed-options or a new
customize-package-changed-options function? Would you prefer to see this
before or after the release?

-- 
Bill Wohler <wohler@newt.com>  http://www.newt.com/wohler/  GnuPG ID:610BD9AD
Maintainer of comp.mail.mh FAQ and MH-E. Vote Libertarian!
If you're passed on the right, you're in the wrong lane.

Re: defcustom :version

[Bill Wohler]

Richard Stallman <rms@gnu.org> wrote:

> If you want to work on the doc string of defface, go ahead.

Thanks. This is what I ended up doing.

  (defcustom): Create Common Keywords section in docstring.
  (defface, defgroup): Replace definitions of a select few keywords
  with a reference to the Common Keywords in defcustom.
  (defcustom, defface, defgroup): Replace reference to Customization
  chapter in manual with hyperlink.

-- 
Bill Wohler <wohler@newt.com>  http://www.newt.com/wohler/  GnuPG ID:610BD9AD
Maintainer of comp.mail.mh FAQ and MH-E. Vote Libertarian!
If you're passed on the right, you're in the wrong lane.