news and docs for command-error-function

news and docs for command-error-function

[Jarek Czekalski]

Stefan,

We modified keyboard.c (r114987 114988 114991) and in 114988 you removed 
the following from the docs:

-This variable is initialized with Emacs default error output function.
-It is suggested that user functions are added using add-function. */);

I thought it would be good to describe 3 things:

1. suggested way to use this variable (add-function)
2. the change in its handling introduced in 24.4
3. the way it could be substituted before 24.4 (a lisp snippet, like in 
http://lists.gnu.org/archive/html/emacs-devel/2013-10/msg00819.html)

Now I also think both the variable and the function should go to NEWS.

I can prepare these changes if you like, but first I wanted to have an 
agreement of what should be present there. If someone else wants to do 
the docs themselves, no problem.

Jarek

Re: news and docs for command-error-function

[Stefan Monnier]

> I thought it would be good to describe 3 things:
> 1. suggested way to use this variable (add-function)

All *-function variables should usually be modified via add-function, so
there's no need to include it in the docstring.

> 2. the change in its handling introduced in 24.4

Yes, it should be in NEWS, together wit the various other *-function
variables (and some fields, such as process-filter and process-sentinel)
whose default value was changed from nil to a function.

> 3. the way it could be substituted before 24.4 (a lisp snippet, like in
> http://lists.gnu.org/archive/html/emacs-devel/2013-10/msg00819.html)

This is a problem solved in 24.4 rather than introduced in 24.4, so 24.4
is not the place to document how it could have been solved earlier.

> Now I also think both the variable and the function should go to NEWS.

The function should not be documented.  It's more convenient to
have it defined as a symbol than as a lambda expression, but it should
not be called other than via the variable.


        Stefan

Re: news and docs for command-error-function

[Jarek Czekalski]

W dniu 2013-12-30 14:09, Stefan Monnier pisze:

>> 3. the way it could be substituted before 24.4 (a lisp snippet, like in
>> http://lists.gnu.org/archive/html/emacs-devel/2013-10/msg00819.html)
> This is a problem solved in 24.4 rather than introduced in 24.4, so 24.4
> is not the place to document how it could have been solved earlier.

Let's assume that I am a package writer and will to use 
command-error-function. I have Emacs 24.4, but I want my code to be 
backward compatible with all Emacs versions having command-error-funcion 
at all. Of course I am starting with reading the docs of 
command-error-function. This is usually not enough (for example to 
figure out since what version the variable exists), so I also grep 
NEWS*. Will I be able to do my work after reading these places?

Jarek

Re: news and docs for command-error-function

[Stefan Monnier]

> Let's assume that I am a package writer and will to use
> command-error-function.  I have Emacs 24.4, but I want my code to be backward
> compatible with all Emacs versions having command-error-function at all.

If so, you'll have to figure out which Emacs versions provide it, and
look at each one's documentation to see what is its semantics.

We have enough work trying to document the changes so that someone who
whose code was working with 24.3 can know how to make it work in 24.4.



        Stefan