Help cross reference to source file

Help cross reference to source file

[Drew Adams]

I have a macro that I use to define functions; that is, it expands to and
evaluates a defun. Suppose that I use the macro in file `foo.el' to define
function `fun'. If I then do C-h f fun, I see this in *Help*:

 fun is an interactive compiled Lisp function in `foo.el'.

The library name foo.el is a link here. However, if I click the link, I get
an error message:

 Cannot find definition of `fun' in library `foo.el'

Fair enough; help can't know where the function definition is, though it is
able to identify the file.

Even if help can't take me to the right place in the source file, I think it
should open the file - and provide the error message, inviting me to search
for it in the file.

This would be analogous to what we do when Emacs cannot find the source C
file that defines a built-in - at least on Windows, it opens a file dialog
box that lets you navigate to the source file.

I think it's great that the source file is identified (correctly), and it's
good that the file name is a link. However, if the definition cannot be
located in the file, the file should be opened, and then a message can say
that the definition can't be located.

Re: Help cross reference to source file

[Richard Stallman]

    Even if help can't take me to the right place in the source file, I think it
    should open the file - and provide the error message, inviting me to search
    for it in the file.

Does this give behavior you like?

*** find-func.el	18 Apr 2006 16:51:36 -0400	1.72
--- find-func.el	09 Jul 2006 14:48:06 -0400	
***************
*** 244,249 ****
--- 244,250 ----
  		(progn
  		  (beginning-of-line)
  		  (cons (current-buffer) (point)))
+ 	      (switch-to-buffer (current-buffer))
  	      (error "Cannot find definition of `%s' in library `%s'"
  		     symbol library))))))))

RE: Help cross reference to source file

[Drew Adams]

        Even if help can't take me to the right place in the source
        file, I think it should open the file - and provide the
        error message, inviting me to search for it in the file.

    Does this give behavior you like?
    + 	      (switch-to-buffer (current-buffer))

For some reason, I can't seem to get the error message now, with or without
your fix.

But yes, that looks like it should do the job. Thx.

Re: Help cross reference to source file

[Stefan Monnier]

>     Even if help can't take me to the right place in the source file,
>     I think it should open the file - and provide the error message,
>     inviting me to search for it in the file.

> Does this give behavior you like?

> *** find-func.el	18 Apr 2006 16:51:36 -0400	1.72
> --- find-func.el	09 Jul 2006 14:48:06 -0400	
> ***************
> *** 244,249 ****
> --- 244,250 ----
>   		(progn
>   		  (beginning-of-line)
>   		  (cons (current-buffer) (point)))
> + 	      (switch-to-buffer (current-buffer))
>   	      (error "Cannot find definition of `%s' in library `%s'"
>   		     symbol library))))))))
  
This burps if the selected window is a minibuffer or dedicated window.
I think we should mark switch-to-buffer as "not for use from elisp" (like
insert-buffer and others).


        Stefan

RE: Help cross reference to source file

[Drew Adams]

    >     Even if help can't take me to the right place in the source file,
    >     I think it should open the file - and provide the error message,
    >     inviting me to search for it in the file.

    > Does this give behavior you like?
    > + 	      (switch-to-buffer (current-buffer))

    This burps if the selected window is a minibuffer or dedicated window.
    I think we should mark switch-to-buffer as "not for use from
    elisp" (like insert-buffer and others).

I sympathize with (and share) the problem, but I disagree that
switch-to-buffer shouldn't be used from Lisp (unless a similar functionality
is made available in another function).

The real problem is general: make Emacs play well with dedicated windows and
with non-nil pop-up-frames.

In this case, the code probably needs to explicitly deal with the problem
you raise, working around it. In the future, perhaps such code to side-step
this kind of problem could be made generally available, as part of a
different function that does
`careful-switch-to-buffer-taking-into-account-corner-cases'.

Re: Help cross reference to source file

[Stefan Monnier]

>> Even if help can't take me to the right place in the source file,
>> I think it should open the file - and provide the error message,
>> inviting me to search for it in the file.

>> Does this give behavior you like?
>> + 	      (switch-to-buffer (current-buffer))

>     This burps if the selected window is a minibuffer or dedicated window.
>     I think we should mark switch-to-buffer as "not for use from
>     elisp" (like insert-buffer and others).

> I sympathize with (and share) the problem, but I disagree that
> switch-to-buffer shouldn't be used from Lisp (unless a similar functionality
> is made available in another function).

> The real problem is general: make Emacs play well with dedicated windows and
> with non-nil pop-up-frames.

> In this case, the code probably needs to explicitly deal with the problem
> you raise, working around it. In the future, perhaps such code to side-step
> this kind of problem could be made generally available, as part of a
> different function that does
> `careful-switch-to-buffer-taking-into-account-corner-cases'.

In this case, the normal control flow displays the buffer somehow so I think
that the right fix is to try to preserve this normal control flow (probably
catching the error and re-raising it later when the buffer has been
displayed).


        Stefan

Re: Help cross reference to source file

[Richard Stallman]

    > + 	      (switch-to-buffer (current-buffer))
    >   	      (error "Cannot find definition of `%s' in library `%s'"
    >   		     symbol library))))))))

    This burps if the selected window is a minibuffer or dedicated window.

What happens in a dedicated window if the symbol IS found in the file?

Re: Help cross reference to source file

[Richard Stallman]

    In this case, the code probably needs to explicitly deal with the problem
    you raise, working around it. In the future, perhaps such code to side-step
    this kind of problem could be made generally available, as part of a
    different function that does
    `careful-switch-to-buffer-taking-into-account-corner-cases'.

That would be plausible.  Or maybe the way this code works needs to be
rearranged so that it is easier to DTRT in this case.

Re: Help cross reference to source file

[Stefan Monnier]

>>>>> "Richard" == Richard Stallman <rms@gnu.org> writes:

>> + 	      (switch-to-buffer (current-buffer))
>> (error "Cannot find definition of `%s' in library `%s'"
>> symbol library))))))))

>     This burps if the selected window is a minibuffer or dedicated window.

> What happens in a dedicated window if the symbol IS found in the file?

It is displayed via pop-to-buffer by the following code in help-mode.el:

(define-button-type 'help-function-def
  :supertype 'help-xref
  'help-function (lambda (fun file)
		   (require 'find-func)
		   (when (eq file 'C-source)
		     (setq file
			   (help-C-file-name (indirect-function fun) 'fun)))
		   ;; Don't use find-function-noselect because it follows
		   ;; aliases (which fails for built-in functions).
		   (let ((location
			  (find-function-search-for-symbol fun nil file)))
		     (pop-to-buffer (car location))
		     (goto-char (cdr location))))
  'help-echo (purecopy "mouse-2, RET: find function's definition"))


-- Stefan

RE: Help cross reference to source file

[Drew Adams]

        > + 	      (switch-to-buffer (current-buffer))

        This burps if the selected window is a minibuffer or
        dedicated window. I think we should mark switch-to-buffer
        as "not for use from elisp" (like insert-buffer and others).

    I disagree that switch-to-buffer shouldn't be used from Lisp
    (unless a similar functionality is made available in another
    function).

Actually, I have a question here. Are these equivalent when pop-up-frames is
non-nil? If not, what's the difference?

1. (switch-to-buffer-other-window foo)
2. (pop-to-buffer foo)

I see some minor differences indicated by the doc strings:
 - NORECORD arg
 - OTHER-WINDOW arg

For pop-to-buffer, it only "preferably" uses a different window, unless
OTHER-WINDOW is non-nil. But I don't notice any major differences. Is one of
these recommended (assuming I have non-nil pop-up-frames) and the other
discouraged?

Thx - Drew

Re: Help cross reference to source file

[Richard Stallman]

    In this case, the normal control flow displays the buffer somehow so I think
    that the right fix is to try to preserve this normal control flow (probably
    catching the error and re-raising it later when the buffer has been
    displayed).

It would definitely be cleaner to preserve the normal control flow.
I will redo it that way.

Re: Help cross reference to source file

[Richard Stallman]

    Actually, I have a question here. Are these equivalent when pop-up-frames is
    non-nil? If not, what's the difference?

    1. (switch-to-buffer-other-window foo)
    2. (pop-to-buffer foo)

pop-to-buffer obeys same-window-buffer-names and
special-display-buffer-names.  switch-to-buffer-other-window does not.