Suggestion for C-h f, describe-function

Suggestion for C-h f, describe-function

[David Kastrup]

Hi, when using C-h f describe-function RET on a function defined in C,
the hyperlink with the source file name takes me to the Emacs source
code tree, which is very convenient.

Doing the same on a Lisp function will instead take me to the actually
loaded file in the installed tree which is quite less convenient since
it means that I constantly have some duplicated buffers with the same
content, and since it means if I do any actual changes to fix
something and try checking them in or comparing versions, this will
fail since I always manage to get the version _not_ under version
control.

Would it be possible to add an option where the source tree was
consulted also for the Lisp files?  There would be the additional
problem that while all sources to C functions are, of course, in the
Emacs source tree, this does not hold for the Lisp tree, so one should
probably have a way to specify different source trees for different
things in the Emacs tree, like mapping the prefix
/usr/local/share/emacs-22.0.50/lisp to "/usr/local/src/emacs/lisp", and
/usr/local/share/emacs/site-lisp/auctex to try both
"/usr/local/src/auctex/preview" and "/usr/local/src/auctex"

Maybe such a list would be specified as something like

(("^/usr/local/share/emacs-22.0.50/lisp/"
     "/usr/local/src/emacs/lisp/\\&")
 ("^/usr/local/share/emacs/site-lisp/auctex/"
     "/usr/local/src/auctex/preview/\\&"
     "/usr/local/src/auctex/\\&"))

which will do the obvious regexp replacements for finding the source
files.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: Suggestion for C-h f, describe-function

[Richard Stallman]

    Hi, when using C-h f describe-function RET on a function defined in C,
    the hyperlink with the source file name takes me to the Emacs source
    code tree, which is very convenient.

    Doing the same on a Lisp function will instead take me to the actually
    loaded file in the installed tree which is quite less convenient since

I don't understand the distinction -- could you explain?

Are you talking about which directory is used?
We could make it try source-directory first, for Lisp files.
In case it works.

Re: Suggestion for C-h f, describe-function

[David Kastrup]

Richard Stallman <rms@gnu.org> writes:

>     Hi, when using C-h f describe-function RET on a function defined in C,
>     the hyperlink with the source file name takes me to the Emacs source
>     code tree, which is very convenient.
>
>     Doing the same on a Lisp function will instead take me to the actually
>     loaded file in the installed tree which is quite less convenient since
>
> I don't understand the distinction -- could you explain?

ignore is an interactive compiled Lisp function in `subr.el'.
It is bound to <mouse-movement>.
(ignore &rest IGNORE)

Do nothing and return nil.
This function accepts any number of arguments, but ignores them.

[back]


If I use the hyperlink on `subr.el', it takes me to

/usr/local/share/emacs/22.0.50/lisp/subr.el.gz

which is the installed tree.  Editing here is useless.  Instead

/usr/local/src/emacs/lisp/subr.el

would have been more useful.


In contrast:

integerp is a built-in function in `C source code'.
(integerp OBJECT)

Return t if OBJECT is an integer.

[back]


Clicking on the `C source code' hyperlink takes me to

/usr/local/src/emacs/src/data.c

instead which is right in file under CVS control.

> Are you talking about which directory is used?

I tried to, yes.

> We could make it try source-directory first, for Lisp files.
> In case it works.

The problem is with stuff compiled in another machine or another
directory: if some user has an installed Emacs and uses the C source
code link, the worst that can happen is that he gets landed in a
nonsensical place instead of no place at all, since there is no C
source code in the installed Emacs tree.

With the Lisp code, there _is_ useful code for a user to jump to, so
we don't have the situation "could as well do something wrong rather
than nothing at all" here, and should be more careful about trying
source-directory first when we don't know whether it points somewhere
useful.

In addition, there might be various external packages in their own CVS
source trees (like AUCTeX).  This can't happen in C, as Emacs has no C
level module interface, but it would be nice if one could set one's
Emacs up at least manually to have it know just where to find the
source trees of stuff.

Another possibility would be to have an option that would embed the
source tree info into files that are byte-compiled.  Then one could
set this option in the Makefiles for "make install" when one knew that
one was just using Emacs on one's own machine and not handing the
binaries around.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: Suggestion for C-h f, describe-function

[Kim F. Storm]

David Kastrup <dak@gnu.org> writes:

> The problem is with stuff compiled in another machine or another
> directory: if some user has an installed Emacs and uses the C source
> code link, the worst that can happen is that he gets landed in a
> nonsensical place instead of no place at all, since there is no C
> source code in the installed Emacs tree.

My simple solution is: If you intend to change Lisp files, run emacs
out of the source tree.  Then lisp hyperlinks take you to the right files.

-- 
Kim F. Storm <storm@cua.dk> http://www.cua.dk

Re: Suggestion for C-h f, describe-function

[Thien-Thi Nguyen]

storm@cua.dk (Kim F. Storm) writes:

> My simple solution is: If you intend to change Lisp files, run emacs
> out of the source tree.  Then lisp hyperlinks take you to the right files.

works for me:
ln -sf ~/build/GNU/emacs/src/emacs ~/bin/bloody-emacs

thi

Re: Suggestion for C-h f, describe-function

[Richard Stallman]

    The problem is with stuff compiled in another machine or another
    directory: if some user has an installed Emacs and uses the C source
    code link, the worst that can happen is that he gets landed in a
    nonsensical place instead of no place at all, since there is no C
    source code in the installed Emacs tree.

Yes.  That's why I suggest trying source-directory first.
If the file exists there, that is probably the right file.
If not, it can look for the installed Lisp file.

Thanks for bringing it up.

    Another possibility would be to have an option that would embed the
    source tree info into files that are byte-compiled.

I do not understand the idea.

    level module interface, but it would be nice if one could set one's
    Emacs up at least manually to have it know just where to find the
    source trees of stuff.

It sounds like you mean having a list instead of source-directory.
I guess we could.

Re: Suggestion for C-h f, describe-function

[David Kastrup]

storm@cua.dk (Kim F. Storm) writes:

> David Kastrup <dak@gnu.org> writes:
>
>> The problem is with stuff compiled in another machine or another
>> directory: if some user has an installed Emacs and uses the C
>> source code link, the worst that can happen is that he gets landed
>> in a nonsensical place instead of no place at all, since there is
>> no C source code in the installed Emacs tree.
>
> My simple solution is: If you intend to change Lisp files, run emacs
> out of the source tree.  Then lisp hyperlinks take you to the right
> files.

I can't run Emacs "out of the source tree" of both Emacs and AUCTeX.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: Suggestion for C-h f, describe-function

[Kim F. Storm]

David Kastrup <dak@gnu.org> writes:

>> My simple solution is: If you intend to change Lisp files, run emacs
>> out of the source tree.  Then lisp hyperlinks take you to the right
>> files.
>
> I can't run Emacs "out of the source tree" of both Emacs and AUCTeX.

So you cannot put the AUCTeX source directory into load-path.  Why?

-- 
Kim F. Storm <storm@cua.dk> http://www.cua.dk

Re: Suggestion for C-h f, describe-function

[David Kastrup]

storm@cua.dk (Kim F. Storm) writes:

> David Kastrup <dak@gnu.org> writes:
>
>>> My simple solution is: If you intend to change Lisp files, run emacs
>>> out of the source tree.  Then lisp hyperlinks take you to the right
>>> files.
>>
>> I can't run Emacs "out of the source tree" of both Emacs and AUCTeX.
>
> So you cannot put the AUCTeX source directory into load-path.  Why?

Because it is the _source_ directory.  I am doing edits, changes,
half-assed things.  The directory is in a _working_ state every few
weeks at best, and only at _that_ point of time could it make sense to
run "make install" or alternatively run from the source directory (but
the source directory also happens to be scattered among several
places, and it also contains .el-files not intended for installation,
like files used for creating autoload files and similar).  In the mean
time, I still need to edit LaTeX files.  I can't have broken copies of
AUCTeX in my load-path for that.  But _when_ I follow AUCTeX
functions' hyperref docs, I want to get them in the source, even if
they may be off a few lines (like it happens with using the C source
code hyperlinks).

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: Suggestion for C-h f, describe-function

[Kim F. Storm]

David Kastrup <dak@gnu.org> writes:

>> So you cannot put the AUCTeX source directory into load-path.  Why?
>
> Because it is the _source_ directory. 

So what about find-function-source-path ?

-- 
Kim F. Storm <storm@cua.dk> http://www.cua.dk

Re: Suggestion for C-h f, describe-function

[David Kastrup]

storm@cua.dk (Kim F. Storm) writes:

> David Kastrup <dak@gnu.org> writes:
>
>>> So you cannot put the AUCTeX source directory into load-path.  Why?
>>
>> Because it is the _source_ directory. 
>
> So what about find-function-source-path ?

If this variable is nil then `find-function' searches `load-path' by
default.


Would be usable except that setting it up stops the tracking of
further load-path changes, and it requires converting _all_
corresponding directories in the current load-path to their respective
source directory.  This sort of conversion would then more or less
need to be done by defadvice to find-function, using a list of rules
like I described.

But if I have to use defadvice on find-function anyway, one could
almost let-bind load-path around the call (the only advantage of using
find-function-source-path is that any autocalled function triggered
during find-function will not go awry).

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: Suggestion for C-h f, describe-function

[Richard Stallman]

    Would be usable except that setting it up stops the tracking of
    further load-path changes, and it requires converting _all_
    corresponding directories in the current load-path to their respective
    source directory.

Do you actually change load-path during your editing session?  If so,
why?  If not, wouldn't it be fine to set find-function-source-path
once in .emacs?

Re: Suggestion for C-h f, describe-function

[David Kastrup]

Richard Stallman <rms@gnu.org> writes:

>     Would be usable except that setting it up stops the tracking of
>     further load-path changes, and it requires converting _all_
>     corresponding directories in the current load-path to their respective
>     source directory.
>
> Do you actually change load-path during your editing session?  If so,
> why?

Packages triggered by autoload might add the rest of their hierarchy
into load-path.

> If not, wouldn't it be fine to set find-function-source-path once in
> .emacs?

I am not comfortable with that idea.  I now put the following into my
.emacs (of course, others would not need the AUCTeX parts, and if
something similar were to be put into Emacs proper, one would use
variables like source-directory and others to make this more generic).

It seems to do the trick for me, but I am pretty sure that others
might find something similar useful.  It is also undocumented as for
now.

(defcustom find-function-transform-list
  '(("/usr/local/emacs-21/share/emacs/22.0.50"
     "/home/tmp/emacs")
    ("/usr/local/emacs-21/share/emacs/site-lisp/preview"
     "/home/tmp/auctex/preview")
    ("/usr/local/emacs-21/share/emacs/site-lisp/auctex"
     "/home/tmp/auctex/preview"
     "/home/tmp/auctex"))
  "File prefixes to transform `find-function-source-path'."
  :type '(repeat (list string (repeat string))))

(defadvice find-library-name (around find-function-transform activate)
  (let ((find-function-source-path (or find-function-source-path load-path)))
    (let (lst case-fold-search lst2 len elt2)
      (setq find-function-source-path
	    (dolist (elt find-function-source-path (nreverse lst))
	      (setq lst2 find-function-transform-list)
	      (catch 'found
		(while lst2
		  (setq elt2 (pop lst2)
			len (length (car elt2)))
		  (when (or (string= elt (car elt2))
			    (and (< len (length elt))
				 (string= (substring elt 0 (1+ len))
					  (concat (car elt2) "/"))))
		    (while (setq elt2 (cdr elt2))
		      (push (concat (car elt2) (substring elt len)) lst))
		    (throw 'found t)))
		(push elt lst)))))
    ad-do-it))


-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: Suggestion for C-h f, describe-function

[Richard Stallman]

    Packages triggered by autoload might add the rest of their hierarchy
    into load-path.

Emacs has no way of finding the source code automatically when that
happens.  But this could be a good reason to search the .el files in
load-path if it doesn't find them in the source code directory list.

So we can do that, I guess.  It can't hurt.