compilation-process-setup-function doc bug?

compilation-process-setup-function doc bug?

[Paul Michael Reilly]

I believe the documentation string for the variable
compilation-process-setup-function is wrong or less than clear.
It says:

   *Function to call to customize the compilation process.
   This function is called immediately before the compilation process is
   started.  It can be used to set any variables or functions that are
   used while processing the output of the compilation process.  The
   function is called with variables `compilation-buffer' and
   `compilation-window' bound to the compilation buffer and window,
   respectively.

What does this mean actually?  In my blissful ignorance I thought
it meant I should create a function like so:

(defun test (compilation-buffer compilation-window)
   ...)

and do

(setq compilation-process-setup-function 'test)

but when I do M-x compile, Emacs is not happy with the arguments.
It is actually called with no arguments.  So next I'm thinking maybe 
this is what the documentation means:

(defun test ()
   (message "The args are %s %s" compilation-buffer compilation-window)
   ...)

but Emacs complains that the variables are void, which seems reasonable. 
  My take is that the last sentence in the doc string should be 
expunged.  Am I correct?

-pmr

Re: compilation-process-setup-function doc bug?

[Stefan Monnier]

> I believe the documentation string for the variable
> compilation-process-setup-function is wrong or less than clear.
> It says:

>   *Function to call to customize the compilation process.
>   This function is called immediately before the compilation process is
>   started.  It can be used to set any variables or functions that are
>   used while processing the output of the compilation process.  The
>   function is called with variables `compilation-buffer' and
>   `compilation-window' bound to the compilation buffer and window,
>   respectively.
[...]
> but when I do M-x compile, Emacs is not happy with the arguments.
> It is actually called with no arguments.  So next I'm thinking maybe this is
> what the documentation means:

> (defun test ()
>   (message "The args are %s %s" compilation-buffer compilation-window)
>   ...)

Yes, that's what it means.

> but Emacs complains that the variables are void, which seems reasonable.

Indeed, it appears the doc disagrees with the code.
I'm not sure when the problem appeared, but the `compilation-buffer' is
(current-buffer).  OTOH compilation-window is not
immediately available.  (get-buffer-window (curent-buffer) 0) will
usually return the right window, tho.


        Stefan

Re: compilation-process-setup-function doc bug?

[Paul Michael Reilly]

On 11/04/2009 08:57 PM, Stefan Monnier wrote:
...
> Indeed, it appears the doc disagrees with the code.
> I'm not sure when the problem appeared, but the `compilation-buffer' is
> (current-buffer).  OTOH compilation-window is not
> immediately available.  (get-buffer-window (curent-buffer) 0) will
> usually return the right window, tho.

In that case I'd be happy to fix the code by making both variables 
buffer local to the compilation buffer thus making the documentation 
consistent.  Unless you would prefer to have the last sentence removed 
from the description and leave it to the User to figure out how to get 
the buffer or window should they need it.  My preference is the former.

-pmr

Re: compilation-process-setup-function doc bug?

[Stefan Monnier]

>> Indeed, it appears the doc disagrees with the code.
>> I'm not sure when the problem appeared, but the `compilation-buffer' is
>> (current-buffer).  OTOH compilation-window is not
>> immediately available.  (get-buffer-window (curent-buffer) 0) will
>> usually return the right window, tho.

> In that case I'd be happy to fix the code by making both variables buffer
> local to the compilation buffer thus making the documentation consistent.
> Unless you would prefer to have the last sentence removed from the
> description and leave it to the User to figure out how to get the buffer or
> window should they need it.  My preference is the former.

Since this behavior has been present since at least Emacs-22, I'd just
remove the sentence from the docstring: (current-buffer) is a very good
way to pass a buffer argument.  As for the window, if we really want to
pass it, then we should just select it during that call, but I don't
think it's worth the trouble.


        Stefan