Jumping to C source from *Help*

Jumping to C source from *Help*

[Stefan Monnier]

As has already been discussed in the past, it would be a good thing to be
able to jump from the *Help* buffer to the source of a var or fun that's
defined in C, just like we can do it when it's defined in Elisp.

Until recently I was using a hack based on TAGS, which was sadly too ugly
and fragile to be installed.  I have re-implemented the feature now in
a much cleaner way.

The source-file-name info is placed directly in DOC by make-docfile.

Please review and tell me of anything that might need to be changed before
installing the change.


        Stefan


Index: lib-src/make-docfile.c
===================================================================
RCS file: /cvsroot/emacs/emacs/lib-src/make-docfile.c,v
retrieving revision 1.56
diff -u -r1.56 make-docfile.c
--- lib-src/make-docfile.c	24 Dec 2003 06:49:23 -0000	1.56
+++ lib-src/make-docfile.c	6 Apr 2004 22:33:59 -0000
@@ -1,5 +1,5 @@
 /* Generate doc-string file for GNU Emacs from source files.
-   Copyright (C) 1985, 86, 92, 93, 94, 97, 1999, 2000, 2001
+   Copyright (C) 1985, 86, 92, 93, 94, 97, 1999, 2000, 01, 2004
    Free Software Foundation, Inc.
 
 This file is part of GNU Emacs.
@@ -105,11 +105,11 @@
 
 /* Like malloc but get fatal error if memory is exhausted.  */
 
-long *
+void *
 xmalloc (size)
      unsigned int size;
 {
-  long *result = (long *) malloc (size);
+  void *result = (void *) malloc (size);
   if (result == NULL)
     fatal ("virtual memory exhausted", 0);
   return result;
@@ -178,6 +178,35 @@
   return (err_count > 0 ? EXIT_FAILURE : EXIT_SUCCESS);
 }
 
+/* Add a source file name boundary marker in the output file.  */
+void
+put_filename (filename)
+     char *filename;
+{
+  char *tmp = filename;
+  int len;
+  
+  while ((tmp = index (filename, '/')))
+    filename = tmp + 1;
+
+  len = strlen (filename);
+  tmp = xmalloc (len + 1);
+  strcpy (tmp, filename);
+  filename = tmp;
+
+  /* Turn object file names into source file names.  */
+  if (len > 4 && !strcmp (filename + len - 4, ".elc"))
+    /* Truncate `.elc' to `.el'.  */
+    filename[len - 1] = '\0';
+  else if (len > 2 && !strcmp (filename + len - 2, ".o"))
+    /* Switch `.o' to `.c'. */
+    filename[len - 1] = 'c';
+
+  putc (037, outfile);
+  putc ('S', outfile);
+  fprintf (outfile, "%s\n", filename);
+}
+
 /* Read file FILENAME and output its doc strings to outfile.  */
 /* Return 1 if file is not found, 0 if it is found.  */
 
@@ -186,6 +215,8 @@
      char *filename;
 {
   int len = strlen (filename);
+
+  put_filename (filename);
   if (len > 4 && !strcmp (filename + len - 4, ".elc"))
     return scan_lisp_file (filename, READ_BINARY);
   else if (len > 3 && !strcmp (filename + len - 3, ".el"))

Index: src/doc.c
===================================================================
RCS file: /cvsroot/emacs/emacs/src/doc.c,v
retrieving revision 1.103
diff -u -r1.103 doc.c
--- src/doc.c	2 Mar 2004 06:11:48 -0000	1.103
+++ src/doc.c	6 Apr 2004 22:33:59 -0000
@@ -1,5 +1,6 @@
 /* Record indices of function doc strings stored in a file.
-   Copyright (C) 1985, 86,93,94,95,97,98,99, 2000 Free Software Foundation, Inc.
+   Copyright (C) 1985, 86,93,94,95,97,98,99,2000,04
+             Free Software Foundation, Inc.
 
 This file is part of GNU Emacs.
 
@@ -612,8 +613,7 @@
 	*p = '_';
       p++;
     }
-#endif /* not VMS4_4 */
-#ifdef VMS4_4
+#else /* VMS4_4 */
   strcpy (name, sys_translate_unix (name));
 #endif /* VMS4_4 */
 #endif /* VMS */
@@ -659,6 +659,9 @@
 	      /* Attach a docstring to a function?  */
 	      else if (p[1] == 'F')
 		store_function_docstring (sym, pos + end + 1 - buf);
+
+	      else if (p[1] == 'S')
+		; /* Just a source file name boundary marker.  Ignore it.  */
 
 	      else
 		error ("DOC file invalid at position %d", pos);

Index: lisp/help-fns.el
===================================================================
RCS file: /cvsroot/emacs/emacs/lisp/help-fns.el,v
retrieving revision 1.36
diff -u -r1.36 help-fns.el
--- lisp/help-fns.el	20 Feb 2004 03:48:32 -0000	1.36
+++ lisp/help-fns.el	6 Apr 2004 22:33:59 -0000
@@ -1,6 +1,6 @@
 ;;; help-fns.el --- Complex help functions
 
-;; Copyright (C) 1985, 1986, 1993, 1994, 1998, 1999, 2000, 2001, 2002, 2003
+;; Copyright (C) 1985, 86, 93, 94, 98, 1999, 2000, 01, 02, 03, 2004
 ;;   Free Software Foundation, Inc.
 
 ;; Maintainer: FSF
@@ -215,6 +215,56 @@
 			(intern (upcase name))))))
 		arglist)))
 
+(defvar help-C-source-directory
+  (let ((dir (expand-file-name "src" source-directory)))
+    (when (and (file-directory-p dir) (file-readable-p dir))
+      dir))
+  "Directory where the C source files of Emacs can be found.
+If nil, do not try to find the source code of functions and variables
+defined in C.")
+
+(defun help-subr-name (subr)
+  (let ((name (prin1-to-string subr)))
+    (if (string-match "\\`#<subr \\(.*\\)>\\'" name)
+	(match-string 1 name)
+      (error "Unexpected internal name: %s" name))))
+
+(defun help-C-file-name (subr-or-var kind)
+  "Return the name of the C file where SUBR-OR-VAR is defined.
+KIND should be `var' for a variable or `subr' for a subroutine."
+  (let ((docbuf (get-buffer-create " *DOC*"))
+	(name (if (eq 'var kind)
+		  (concat "V" (symbol-name subr-or-var))
+		(concat "F" (help-subr-name subr-or-var)))))
+    (with-current-buffer docbuf
+      (goto-char (point-min))
+	  (if (eobp)
+	      (insert-file-contents-literally
+	       (expand-file-name internal-doc-file-name doc-directory)))
+	  (search-forward (concat "\x1f" name "\n"))
+	  (re-search-backward "\x1fS\\(.*\\)")
+	  (match-string 1))))
+
+(defun help-find-C-source (fun-or-var file kind)
+  (setq file (expand-file-name file help-C-source-directory))
+  (unless (file-readable-p file)
+    (error "The C source file %s is not available"
+	   (file-name-nondirectory file)))
+  (if (eq 'fun kind)
+      (setq fun-or-var (indirect-function fun-or-var)))
+  (with-current-buffer (find-file-noselect file)
+    (goto-char (point-min))
+    (unless (re-search-forward
+	     (if (eq 'fun kind)
+		 (concat "DEFUN[ \t\n]*([ \t\n]*\""
+			 (regexp-quote (help-subr-name fun-or-var))
+			 "\"")
+	       (concat "DEFVAR[A-Z_]*[ \t\n]*([ \t\n]*\""
+		       (regexp-quote (symbol-name fun-or-var))))
+	     nil t)
+      (error "Can't find source for %s" fun))
+    (cons (current-buffer) (match-beginning 0))))
+
 ;;;###autoload
 (defun describe-function-1 (function)
   (let* ((def (if (symbolp function)
@@ -280,8 +330,11 @@
 	    (when (re-search-backward
 		   "^;;; Generated autoloads from \\(.*\\)" nil t)
 	      (setq file-name (match-string 1)))))))
-    (cond
-     (file-name
+    (when (and (null file-name) (subrp def))
+      (if help-C-source-directory
+	  (setq file-name (concat "src/" (help-C-file-name def 'subr)))
+	(princ " in core C code")))
+    (when file-name
       (princ " in `")
       ;; We used to add .el to the file name,
       ;; but that's completely wrong when the user used load-file.
@@ -289,9 +342,9 @@
       (princ "'")
       ;; Make a hyperlink to the library.
       (with-current-buffer standard-output
-	(save-excursion
+        (save-excursion
 	  (re-search-backward "`\\([^`']+\\)'" nil t)
-	  (help-xref-button 1 'help-function-def function file-name)))))
+	  (help-xref-button 1 'help-function-def function file-name))))
     (princ ".")
     (terpri)
     (when (commandp function)
@@ -500,6 +553,13 @@
 		      (when (re-search-backward
 			     "^;;; Generated autoloads from \\(.*\\)" nil t)
 			(setq file-name (match-string 1)))))))
+	      (when (and (null file-name)
+			 (integerp (get variable 'variable-documentation)))
+		;; It's a variable not defined in Elisp but in C.
+		(if help-C-source-directory
+		    (setq file-name
+			  (concat "src/" (help-C-file-name variable 'var)))
+		  (princ "\n\nDefined in core C code.")))
 	      (when file-name
 		(princ "\n\nDefined in `")
 		(princ file-name)

Index: lisp/help-mode.el
===================================================================
RCS file: /cvsroot/emacs/emacs/lisp/help-mode.el,v
retrieving revision 1.23
diff -u -r1.23 help-mode.el
--- lisp/help-mode.el	5 Apr 2004 12:09:53 -0000	1.23
+++ lisp/help-mode.el	6 Apr 2004 22:33:59 -0000
@@ -1,6 +1,6 @@
 ;;; help-mode.el --- `help-mode' used by *Help* buffers
 
-;; Copyright (C) 1985, 1986, 1993, 1994, 1998, 1999, 2000, 2001, 2002
+;; Copyright (C) 1985, 1986, 1993, 1994, 1998, 1999, 2000, 2001, 2002, 2004
 ;;   Free Software Foundation, Inc.
 
 ;; Maintainer: FSF
@@ -150,8 +150,11 @@
 		   ;; Don't use find-function-noselect because it follows
 		   ;; aliases (which fails for built-in functions).
 		   (let ((location
-			  (if (bufferp file) (cons file fun)
-			    (find-function-search-for-symbol fun nil file))))
+			  (cond
+			   ((bufferp file) (cons file fun))
+			   ((string-match "\\`src/\\(.*\\.c\\)" file)
+			    (help-find-C-source fun (match-string 1 file) 'fun))
+			   (t (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"))
@@ -160,7 +163,10 @@
   :supertype 'help-xref
   'help-function (lambda (var &optional file)
 		   (let ((location
-			  (find-variable-noselect var file)))
+			  (cond
+			   ((string-match "\\`src/\\(.*\\.c\\)" file)
+			    (help-find-C-source var (match-string 1 file) 'var))
+			   (t (find-variable-noselect var file)))))
 		     (pop-to-buffer (car location))
 		     (goto-char (cdr location))))
   'help-echo (purecopy"mouse-2, RET: find variable's definition"))

Re: Jumping to C source from *Help*

[Juanma Barranquero]

On 06 Apr 2004 18:35:24 -0400, Stefan Monnier <monnier@iro.umontreal.ca> wrote:

> +  else if (len > 2 && !strcmp (filename + len - 2, ".o"))
> +    /* Switch `.o' to `.c'. */
> +    filename[len - 1] = 'c';

MinGW object files are .o, but MSVC objects are .obj (and conceivably
.OBJ) so something like this should be needed:

+  else if (len > 4 && !stricmp (filename + len - 4, ".obj"))
+    {
+      /* Switch `.obj' to `.c'. */
+      filename[len - 3] = 'c';
+      filename[len - 2] = 0;
+    }

                                                           /L/e/k/t/u

Re: Jumping to C source from *Help*

[Stefan Monnier]

> MinGW object files are .o, but MSVC objects are .obj (and conceivably
> .OBJ) so something like this should be needed:

Thanks.  I've installed my patch (with slight modifications)
and it now deals with the above (though in elisp rather than in C).

Please try it,


        Stefan

Re: Jumping to C source from *Help*

[Kim F. Storm]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

> > MinGW object files are .o, but MSVC objects are .obj (and conceivably
> > .OBJ) so something like this should be needed:
> 
> Thanks.  I've installed my patch (with slight modifications)
> and it now deals with the above (though in elisp rather than in C).
> 
> Please try it,

Brilliant, wonderful, excellent, ... 

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

Re: Jumping to C source from *Help*

[Juri Linkov]

Stefan Monnier <monnier@iro.umontreal.ca> writes:
> Thanks.  I've installed my patch (with slight modifications)
> and it now deals with the above (though in elisp rather than in C).
>
> Please try it,

This is a very good thing!

But it reminded me that jumping from the *Help* buffer to the source
buffer still has one inconvenience: it selects the source buffer in a
different window.  It makes more sense to switch to the source buffer
in the same window, because the same text that is displayed in the
*Help* buffer, after switching will be visible in the docstring in the
source buffer.  So no information is duplicated on the screen.

For some time I used the following patch, and it's very convenient:

diff -u -r1.24 help-mode.el
--- emacs/lisp/help-mode.el	7 Apr 2004 19:35:05 -0000	1.24
+++ emacs/lisp/help-mode.el	8 Apr 2004 05:41:35 -0000
@@ -155,7 +155,8 @@
 			   ((string-match "\\`src/\\(.*\\.c\\)" file)
 			    (help-find-C-source fun (match-string 1 file) 'fun))
 			   (t (find-function-search-for-symbol fun nil file)))))
-		     (pop-to-buffer (car location))
+		     (switch-to-buffer (car location))
 		     (goto-char (cdr location))))
   'help-echo (purecopy "mouse-2, RET: find function's definition"))
 
@@ -167,7 +168,8 @@
 			   ((string-match "\\`src/\\(.*\\.c\\)" file)
 			    (help-find-C-source var (match-string 1 file) 'var))
 			   (t (find-variable-noselect var file)))))
-		     (pop-to-buffer (car location))
+		     (switch-to-buffer (car location))
 		     (goto-char (cdr location))))
   'help-echo (purecopy"mouse-2, RET: find variable's definition"))

-- 
Juri Linkov
http://www.jurta.org/emacs/

Re: Jumping to C source from *Help*

[Kim F. Storm]

Juri Linkov <juri@jurta.org> writes:

> But it reminded me that jumping from the *Help* buffer to the source
> buffer still has one inconvenience: it selects the source buffer in a
> different window.  It makes more sense to switch to the source buffer
> in the same window, because the same text that is displayed in the
> *Help* buffer, after switching will be visible in the docstring in the
> source buffer.  So no information is duplicated on the screen.

Most of the time when I use the link to the source, I opened the help
window for exactly that purpose (to look at the source).  So in
practice, I never need to keep the help window, i.e. I would also like
the source window to replace the help window.

So I vote in favour of your patch.

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

Re: Jumping to C source from *Help*

[Richard Stallman]

    > But it reminded me that jumping from the *Help* buffer to the source
    > buffer still has one inconvenience: it selects the source buffer in a
    > different window.  It makes more sense to switch to the source buffer
    > in the same window, because the same text that is displayed in the
    > *Help* buffer, after switching will be visible in the docstring in the
    > source buffer.  So no information is duplicated on the screen.

I agree.

Re: Jumping to C source from *Help*

[Stefan Monnier]

> -		     (pop-to-buffer (car location))
> +		     (switch-to-buffer (car location))

That signals an error when the *Help* buffer is on a dedicated window (as
is the case for me).  I spend a lot of time getting rid of such misuses of
switch-to-buffer, so I strongly oppose this patch.

Of course, the right way to fix it might be to make switch-to-buffer
delegate to pop-to-buffer rather than signal an error.  But last time
I suggested it, Richard did not like it.


        Stefan

switch-buffer to use other window if dedicated window (was: Jumping to C source from *Help*)

[Drew Adams]

Forgive me if this is not too germane or up-to-date.

To me, it makes sense for `switch-to-buffer' to use another window if the
selected window is dedicated.

FWIW, here's the redefinition of `switch-to-buffer' that I use (Emacs 20 -
sorry):

;; 1) Uses `read-buffer' in interactive spec.
;; 2) If current window is dedicated, then use another window.
;;    NOTE: Emacs versions >= 19.34 signal an error if dedicated window,
;;          instead of using another one.  Don't know what the 19.28 version
did.
;; 3) `fit-frame-if-one-window' if `fit-frame-when-switch-to-p'.

(defun switch-to-buffer (buffer &optional norecord)
  "Select buffer BUFFER in current window, unless the window is dedicated.
If current window is dedicated (`window-dedicated-p'), then another window
is used.  BUFFER may be a buffer or its name.

Optional second arg NORECORD non-nil =>
   Do not put BUFFER at front of list of recently selected buffers.

*WARNING*: This is NOT the way to work on another buffer temporarily
within a Lisp program!  Use `set-buffer' instead, to avoid messing
with window-buffer correspondences.

`fit-frame-if-one-window' if `fit-frame-when-switch-to-p'."

  (interactive
   (list (read-buffer "Switch to buffer: " nil 'existing)))
  (if (window-dedicated-p (selected-window))
      (switch-to-buffer-other-window buffer)
    (old-switch-to-buffer buffer norecord))
  (fit-frame-if-one-window-and-cond fit-frame-when-switch-to-p))


[FYI -

Function `fit-frame-if-one-window-and-cond' shrink-wraps the frame of the
selected window if variable (user option) `fit-frame-when-switch-to-p' is
non-nil.

Function `read-buffer' reads the name of a buffer and returns it as a
string.
Prompts with first arg, PROMPT (a string).
The default buffer is named by the optional 2nd arg, DEFAULT, if a
string or buffer, or by `another-buffer' if nil.
Non-nil optional 3rd arg, EXISTING, means to allow only names of
existing buffers.]

 - Drew

-----Original Message-----
From: emacs-devel-bounces+drew.adams=oracle.com@gnu.org
[mailto:emacs-devel-bounces+drew.adams=oracle.com@gnu.org]On Behalf Of
Stefan Monnier
Sent: Thursday, April 08, 2004 9:47 AM
To: Juri Linkov
Cc: emacs-devel@gnu.org
Subject: Re: Jumping to C source from *Help*


> -		     (pop-to-buffer (car location))
> +		     (switch-to-buffer (car location))

That signals an error when the *Help* buffer is on a dedicated window (as
is the case for me).  I spend a lot of time getting rid of such misuses of
switch-to-buffer, so I strongly oppose this patch.

Of course, the right way to fix it might be to make switch-to-buffer
delegate to pop-to-buffer rather than signal an error.  But last time
I suggested it, Richard did not like it.


        Stefan

Re: Jumping to C source from *Help*

[Richard Stallman]

switch-to-buffer means "I specifically want the buffer in THIS window."
It should get an error if it can't do that.  To display the buffer
in another window would be failing to do the intended job.

Re: Jumping to C source from *Help*

[Kim F. Storm]

Richard Stallman <rms@gnu.org> writes:

> switch-to-buffer means "I specifically want the buffer in THIS window."
> It should get an error if it can't do that.  To display the buffer
> in another window would be failing to do the intended job.

Doc string for set-window-dedicated-p says this:

        If it is dedicated, Emacs will not automatically change
        which buffer appears in it.

What does "automatically change" mean?  

If *I* explicitly do C-x b in a dedicated window, there is no
automatic about it, so shouldn't this be allowed?

Well, I suppose that is exactly not intended to be allowed, so
the doc string for set-window-dedicated-p could be improved.

Also, the restriction should be mentioned in switch-to-buffer.

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

Re: Jumping to C source from *Help*

[Stefan Monnier]

>> switch-to-buffer means "I specifically want the buffer in THIS window."
>> It should get an error if it can't do that.  To display the buffer
>> in another window would be failing to do the intended job.

Obviously we need to distinguish between "switch-to-buffer the command"
and "switch-to-buffer" the function.  I don't care about the behavior
of the command, but of the function.

> Doc string for set-window-dedicated-p says this:
>         If it is dedicated, Emacs will not automatically change
>         which buffer appears in it.

The problem is not only with dedicated windows but also with
minibuffer-windows.

In my experience most uses of switch-to-buffer inside code
(i.e. as a function) lead to problems in setups such as mine
(i.e. with a separate minibuffer-only frame and with many dedicated
windows).

And the problem is made worse because there is currently no function that
does what we want in such case, i.e. "show buffer B, preferably in the
current window".


        Stefan

Re: Jumping to C source from *Help*

[Glenn Morris]

Stefan Monnier wrote:

> The problem is not only with dedicated windows but also with
> minibuffer-windows.
>
> In my experience most uses of switch-to-buffer inside code
> (i.e. as a function) lead to problems in setups such as mine
> (i.e. with a separate minibuffer-only frame and with many dedicated
> windows).
>
> And the problem is made worse because there is currently no function that
> does what we want in such case, i.e. "show buffer B, preferably in the
> current window".

A related (?) issue:

emacs -q --no-site-file --eval "(setq calendar-setup 'calendar-only)"
M-x calendar
C-h k d                ; in the calendar buffer

doesn't show the help, but gives the error "Window is dedicated to
`*Calendar*'".

It seems to be a `with-output-to-temp-buffer' problem - if called
from a dedicated window it barfs when trying to display the temp
buffer.

Re: Jumping to C source from *Help*

[Richard Stallman]

    It seems to be a `with-output-to-temp-buffer' problem - if called
    from a dedicated window it barfs when trying to display the temp
    buffer.

with-output-to-temp-buffer definitely should display its
buffer somewhere else when used in a dedicated window.
But I am surprised it fails.  It does not normally try to
display in the selected window.

Re: Jumping to C source from *Help*

[Glenn Morris]

Richard Stallman wrote:

> with-output-to-temp-buffer definitely should display its buffer
> somewhere else when used in a dedicated window. But I am surprised
> it fails. It does not normally try to display in the selected
> window.

In a vanilla Emacs, I define the following functions:

(defun foo ()
  (interactive)
  (select-frame (make-frame '((unsplittable . t))))
  (set-window-dedicated-p (selected-window) 'foo))

(defun bar ()
  (interactive)
  (with-output-to-temp-buffer "*temp*"
    (princ "text")))

I then call M-x foo, make sure the new frame is selected, then call
M-x bar. Result: "Window is dedicated to `*scratch*'", and no temp
buffer is displayed.

Re: Jumping to C source from *Help*

[Richard Stallman]

    (defun foo ()
      (interactive)
      (select-frame (make-frame '((unsplittable . t))))
      (set-window-dedicated-p (selected-window) 'foo))

Yes, in this situation there is no way for display-buffer
to find or make a window to use.

The question is, is this a bug, or is it just a case
of "So don't do that, then."

Re: Jumping to C source from *Help*

[Kim F. Storm]

My assumption is that only a small fraction of the code that currently
use switch-to-buffer (there are 580 calls in the current lisp files)
has ever actually been tested in the presense of dedicated windows.

It seems like a bug to me that a (seemingly harmless) function which
happens to use switch-to-buffer used may fail (unexpectedly) in some
situations.

Especially because the doc string for switch-to-buffer does NOT warn
against using it in the presense of dedicated buffers.

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

Re: Jumping to C source from *Help*

[Glenn Morris]

Richard Stallman wrote:

> The question is, is this a bug, or is it just a case of "So don't do
> that, then."

Well, if that was not a rhetorical question, and if I understand
correctly that the issue is "ought one to put a dedicated window in an
unsplittable frame", then IMO it doesn't seem like such a crazy thing
to do.

As I alluded to in a previous mail it already happens in at least one
place in Emacs, namely the calendar if one has (setq calendar-setup
'calendar-only). I tried changing the calendar frame to no longer be
unsplittable and the results were not satisfactory.

>From an abstract point of view it seems like something Emacs ought to
be able to deal with when multiple frames are available. Perhaps the
effort required would outweigh the benefits - I wouldn't know.

Strangely, if in my previous example I use t for the second argument
of set-window-dedicated-p, rather than 'foo (say), then there is no
problem. This approach also works for the calendar frames, so I'll
change them to do that. Weird though.

RE: Jumping to C source from *Help*

[Drew Adams]

FWIW, I agree. I use frames instead of windows for nearly everything, by
default. For special buffers I use dedicated frames: (unsplittable . t).

Because (IMO) Emacs (20, at least - I don't know 21) is somewhat biased
toward windows & against frames, I've redefined a few of the built-in
functions slightly to play better with frames. One of those functions was
switch-to-buffer (as mentioned previously).

  - Drew

-----Original Message-----
From: emacs-devel-bounces+drew.adams=oracle.com@gnu.org
[mailto:emacs-devel-bounces+drew.adams=oracle.com@gnu.org]On Behalf Of
Glenn Morris
Sent: Monday, April 19, 2004 5:41 PM
To: rms@gnu.org
Cc: juri@jurta.org; Glenn Morris; emacs-devel@gnu.org;
monnier@iro.umontreal.ca; storm@cua.dk
Subject: Re: Jumping to C source from *Help*

Richard Stallman wrote:

> The question is, is this a bug, or is it just a case of "So don't do
> that, then."

Well, if that was not a rhetorical question, and if I understand
correctly that the issue is "ought one to put a dedicated window in an
unsplittable frame", then IMO it doesn't seem like such a crazy thing
to do.

As I alluded to in a previous mail it already happens in at least one
place in Emacs, namely the calendar if one has (setq calendar-setup
'calendar-only). I tried changing the calendar frame to no longer be
unsplittable and the results were not satisfactory.

>From an abstract point of view it seems like something Emacs ought to
be able to deal with when multiple frames are available. Perhaps the
effort required would outweigh the benefits - I wouldn't know.

Strangely, if in my previous example I use t for the second argument
of set-window-dedicated-p, rather than 'foo (say), then there is no
problem. This approach also works for the calendar frames, so I'll
change them to do that. Weird though.

Re: Jumping to C source from *Help*

[Richard Stallman]

    > The question is, is this a bug, or is it just a case of "So don't do
    > that, then."

    Well, if that was not a rhetorical question, and if I understand
    correctly that the issue is "ought one to put a dedicated window in an
    unsplittable frame", then IMO it doesn't seem like such a crazy thing
    to do.

    As I alluded to in a previous mail it already happens in at least one
    place in Emacs, namely the calendar if one has (setq calendar-setup
    'calendar-only). I tried changing the calendar frame to no longer be
    unsplittable and the results were not satisfactory.

I think you're right.  When people use a special-purpose frame like
this, they would not mind if C-x b switches to a window in another
frame.

    Strangely, if in my previous example I use t for the second argument
    of set-window-dedicated-p, rather than 'foo (say), then there is no
    problem.

Looking at the code, I see that values other than t allow
switch-to-buffer in the window.  It looks like this feature was added
along with making switch-to-buffer check the dedicated flag, and was
not documented at all.

Such a third option could be useful.  However, the name
set-window-dedicated-p implies a flag that is true or false.  With
three significantly different states, this is no longer a binary flag.

Re: Jumping to C source from *Help*

[Glenn Morris]

Richard Stallman wrote:

> When people use a special-purpose frame like this, they would not
> mind if C-x b switches to a window in another frame.

Speaking for myself, I'd actively want that behaviour, rather than
just "not mind". When I set up such a special frame, I want Emacs to
leave it alone, and to use another frame for Help buffers and such.
I'm happy for it to pop-up another frame if it needs to, rather than
messing with the existing one.

> Looking at the code, I see that values other than t allow
> switch-to-buffer in the window. It looks like this feature was added
> along with making switch-to-buffer check the dedicated flag, and was
> not documented at all.
>
> Such a third option could be useful. However, the name
> set-window-dedicated-p implies a flag that is true or false. With
> three significantly different states, this is no longer a binary
> flag.

Indeed, it's a confusing behaviour.

Re: Jumping to C source from *Help*

[Miles Bader]

On Wed, Apr 21, 2004 at 12:33:46AM +0100, Glenn Morris wrote:
> > When people use a special-purpose frame like this, they would not
> > mind if C-x b switches to a window in another frame.
> 
> Speaking for myself, I'd actively want that behaviour, rather than
> just "not mind". When I set up such a special frame, I want Emacs to
> leave it alone, and to use another frame for Help buffers and such.
> I'm happy for it to pop-up another frame if it needs to, rather than
> messing with the existing one.

Are such users generally considered `expert'?  If so maybe it would make
sense to have a `blah-blah-function' variable, which switch-to-buffer would
call in this situation (presumably signaling an error if it's nil).

Then people who have such special environments could make it work exactly
like they wish (some possibilities that come mind are `pop-to-buffer' and
`switch-to-buffer-other-frame').

-Miles
-- 
((lambda (x) (list x x)) (lambda (x) (list x x)))

Re: Jumping to C source from *Help*

[Nick Roberts]

 > > The question is, is this a bug, or is it just a case of "So don't do
 > > that, then."
 > 
 > Well, if that was not a rhetorical question, and if I understand
 > correctly that the issue is "ought one to put a dedicated window in an
 > unsplittable frame", then IMO it doesn't seem like such a crazy thing
 > to do.

In an eerie coincidence, this is what I've just done in gdb-ui.el. I want to
ensure that buffer display command issued from the parent frame doesn't
display in any of the child frames and that one issued from a child frame
must display in the parent frame. It seems to do what I want. Are there any
problems with this approach?

Nick

Re: Jumping to C source from *Help*

[Glenn Morris]

Nick Roberts wrote:

>  > Well, if that was not a rhetorical question, and if I understand
>  > correctly that the issue is "ought one to put a dedicated window in an
>  > unsplittable frame", then IMO it doesn't seem like such a crazy thing
>  > to do.
>
> In an eerie coincidence, this is what I've just done in gdb-ui.el. I want to
> ensure that buffer display command issued from the parent frame doesn't
> display in any of the child frames and that one issued from a child frame
> must display in the parent frame. It seems to do what I want. Are there any
> problems with this approach?

Well, I think that there *ought* not to be any problems with it, but
there may be some aspects of Emacs behaviour that need ironing out in
such setups.

I haven't used gdb-ui.el, so can't comment on that; but as I said with
the calendar there can be, for example, problems with running help
functions in such frames (eg C-h k) - Emacs can have problems
displaying the help buffer.

Re: Jumping to C source from *Help*

[Kim F. Storm]

Glenn Morris <gmorris+emacs@ast.cam.ac.uk> writes:

> I haven't used gdb-ui.el, so can't comment on that; but as I said with
> the calendar there can be, for example, problems with running help
> functions in such frames (eg C-h k) - Emacs can have problems
> displaying the help buffer.

That is indeed a severe consequence IMO.

I still don't really understand why this is such a big issue.

Hey, if I, as an interactive user, uses C-x b to request emacs to
switch to another buffer, and the current window happens to be
dedicated, I still _want_ to switch to that other buffer...  it's just
that currently emacs is very UNHELPFUL in this situation.

In the current situation, I have to manually create and select some
other window before I can do C-x b.  And as has been demonstrated, it
can be very difficult to be able to do just that -- even for an expert
user!

I would rather prefer that emacs did something sensible in this
situation, i.e. showed the buffer in some other window or frame, and
let me get on with my work!   If it (rarely) makes a bad selection
of which other window to use, at least I can correct that "error"
easily with another C-x b - this time in a non-dedicated window...

So IMHO, we should just get rid of that signal in switch-to-buffer,
and get on to other business!!!

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

Re: Jumping to C source from *Help*

[Stefan Monnier]

> I would rather prefer that emacs did something sensible in this
> situation, i.e. showed the buffer in some other window or frame, and
> let me get on with my work!   If it (rarely) makes a bad selection
> of which other window to use, at least I can correct that "error"
> easily with another C-x b - this time in a non-dedicated window...

> So IMHO, we should just get rid of that signal in switch-to-buffer,
> and get on to other business!!!

(with-aol-mode

  Hear! Hear!)


        Stefan

Re: Jumping to C source from *Help*

[Richard Stallman]

    >> switch-to-buffer means "I specifically want the buffer in THIS window."
    >> It should get an error if it can't do that.  To display the buffer
    >> in another window would be failing to do the intended job.

    Obviously we need to distinguish between "switch-to-buffer the command"
    and "switch-to-buffer" the function.  I don't care about the behavior
    of the command, but of the function.

They are the same.  We could make it do something different,
then specially restore the old behavior for interactive calls only.
But I think it would be a change for the worse to do this.

    And the problem is made worse because there is currently no function that
    does what we want in such case, i.e. "show buffer B, preferably in the
    current window".

Perhaps the right thing is to define a new function which does that.
It could be called select-buffer, or switch-to-buffer-somewhere.
It could leave you with that buffer visible in the selected window,
which would be the previously current buffer if that is possible.

Re: Jumping to C source from *Help*

[Stefan Monnier]

>>> switch-to-buffer means "I specifically want the buffer in THIS window."
>>> It should get an error if it can't do that.  To display the buffer
>>> in another window would be failing to do the intended job.

>     Obviously we need to distinguish between "switch-to-buffer the command"
>     and "switch-to-buffer" the function.  I don't care about the behavior
>     of the command, but of the function.

> They are the same.  We could make it do something different,
> then specially restore the old behavior for interactive calls only.

Yes.  E.g. we could add an argument `noother which says: don't try to use
another window if the current one can't be used.  This arg would be set to
non-nil in interactive calls.

> But I think it would be a change for the worse to do this.

Why exactly?

>     And the problem is made worse because there is currently no function that
>     does what we want in such case, i.e. "show buffer B, preferably in the
>     current window".

> Perhaps the right thing is to define a new function which does that.
> It could be called select-buffer, or switch-to-buffer-somewhere.
> It could leave you with that buffer visible in the selected window,
> which would be the previously current buffer if that is possible.

Problem is: many packages (bundled or not with Emacs) use switch-to-buffer
as if it were that new function (i.e. they don't take into account the fact
that switch-to-buffer might fail).

So I'd rather change the behavior of the switch-to-buffer function and
restore it for interactive cases or create a new command (which we'd bind to
C-x b).  Note that for most people, if they call switch-to-buffer instead of
the new command, they won't notice the difference because they never have
any dedicated window and they never use the command when the minibuffer is
the currently selected window.


        Stefan

Re: Jumping to C source from *Help*

[Richard Stallman]

    > But I think it would be a change for the worse to do this.

    Why exactly?

It puts more complexity in something simple.

Re: Jumping to C source from *Help*

[Stefan Monnier]

>> But I think it would be a change for the worse to do this.
>     Why exactly?
> It puts more complexity in something simple.

[ I don't see it, but let's put that aside for now. ]

OK, so you don't want a function that can either use pop-to-buffer or
signal an error depending on an extra argument.  Fair enough.

Given that I think the problem is serious enough for users such as myself
that I'd like to see this resolved, I have three alternatives (from least
preferred to most preferred):
1 - Leave switch-to-buffer as is, but introduce a new function (call it
    `pop-to-buffer-this-window').
2 - Change switch-to-buffer to call pop-to-buffer rather than signal an
    error, and introduce a new command (call it
    `switch-to-buffer-this-window') which we'd then bind to C-h b.
3 - Change switch-to-buffer to call pop-to-buffer rather than signal an
    error and leave everything else unchanged.

Option 1 has the problem that it doesn't fix anything in itself and
requires to change all the packages to use the new function.  In general,
I can't change all those packages, so I'll still have to live with
spurious errors every once in a while.

Option 3 is better because it's the simplest.  Now you might think that you
don't like it because it changes the default behavior, but think again:
it only changes the behavior in the case where you used to get an error
"Cannot switch buffers in minibuffer window" or
"Cannot switch buffers in a dedicated window".  When was the last time
you saw such an error message?  Most users have never seen this message
because they don't have dedicated windows and they never hit C-x b
while they're in the minibuffer.


        Stefan

Re: Jumping to C source from *Help*

[Kim F. Storm]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

> >> But I think it would be a change for the worse to do this.
> >     Why exactly?
> > It puts more complexity in something simple.
> 
> [ I don't see it, but let's put that aside for now. ]
> 
> OK, so you don't want a function that can either use pop-to-buffer or
> signal an error depending on an extra argument.  Fair enough.
> 
> Given that I think the problem is serious enough for users such as myself
> that I'd like to see this resolved, I have three alternatives (from least
> preferred to most preferred):
> 1 - Leave switch-to-buffer as is, but introduce a new function (call it
>     `pop-to-buffer-this-window').
> 2 - Change switch-to-buffer to call pop-to-buffer rather than signal an
>     error, and introduce a new command (call it
>     `switch-to-buffer-this-window') which we'd then bind to C-h b.
> 3 - Change switch-to-buffer to call pop-to-buffer rather than signal an
>     error and leave everything else unchanged.
> 
> Option 1 has the problem that it doesn't fix anything in itself and
> requires to change all the packages to use the new function.  In general,
> I can't change all those packages, so I'll still have to live with
> spurious errors every once in a while.
> 
> Option 3 is better because it's the simplest.  Now you might think that you
> don't like it because it changes the default behavior, but think again:
> it only changes the behavior in the case where you used to get an error
> "Cannot switch buffers in minibuffer window" or
> "Cannot switch buffers in a dedicated window".  When was the last time
> you saw such an error message?  Most users have never seen this message
> because they don't have dedicated windows and they never hit C-x b
> while they're in the minibuffer.

I see the "cannot switch buffers in minibuffer window" from time to time.
And it always annoys me -- of course I don't want to switch buffer in 
the minibuffer window, I obviously want to have the buffer I select to
appear in some ordinary window.

I'd vote for 3 as well.  

I don't see how that can surprise users -- quite the contrary.
Consider this:

(0) suppose we have one dedicated window showing a buffer

(1) enter C-x b
     (notice there is no warning at this point)

(2) enter the name of some other buffer

(3) => "cannot switch buffer in a dedicated window"

        SIGH!

(4) manually split current (dedicated) window, C-x 2
    Hey, no, wait -- that creates another window,
    but leaves the dedicated window selected, so

(5) select the other window, C-x o

(6) repeat step (1)

(7) repeat step (2)

(8) => the buffer you wanted to select is now present in a different window.



Compare this to [option 3]:

(0) suppose we have one dedicated window showing a buffer

(1) enter C-x b
     (notice there is no warning at this point)

(2) enter the name of some other buffer

(3) => the buffer you wanted to select is now present in a different window.



If we are discussing what is simple/non-confusing to the (novice) user, 
I would way that option 3 is much better than the current situation...

And then it solves some "odd" bugs in various packages as an added bonus.


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

RE: Jumping to C source from *Help*

[Drew Adams]

FWIW, I still think this is the best change to make:

(defun switch-to-buffer (buffer &optional norecord)
   ...
  (if (window-dedicated-p (selected-window))
        (switch-to-buffer-other-window buffer) ; <-- instead of
pop-to-buffer
      (old-switch-to-buffer buffer norecord)))

switch-to-buffer-other-window is the same as pop-to-buffer with a local
binding of (pop-up-windows t), so a new window is used. That's the behavior
I want when a dedicated window is involved. And if pop-up-frames is non-nil
(which it is, for me), I get a separate frame - again, the behavior I expect
& want.

Users can of course call whatever functions they like; they need not *try*
to switch to a different buffer in a window that forbids such a switch.

The problem is rather all the calls to switch-to-buffer in the standard
elisp code: about 400 in Emacs 20, no doubt more in Emacs 21. IMO, Emacs (at
least Emacs 20) is somewhat biased toward using Emacs windows, not frames,
so there are built-in calls to switch-to-buffer that can become
inappropriate when using non-nil pop-up-frames and dedicated windows
(frames).

  - Drew

-----Original Message-----
From: emacs-devel-bounces+drew.adams=oracle.com@gnu.org
[mailto:emacs-devel-bounces+drew.adams=oracle.com@gnu.org]On Behalf Of
Kim F. Storm
Sent: Thursday, April 15, 2004 9:28 AM
To: Stefan Monnier
Cc: juri@jurta.org; rms@gnu.org; emacs-devel@gnu.org
Subject: Re: Jumping to C source from *Help*

Stefan Monnier <monnier@iro.umontreal.ca> writes:

> 3 - Change switch-to-buffer to call pop-to-buffer rather than signal an
>     error and leave everything else unchanged.
>
> Option 1 has the problem that it doesn't fix anything in itself and
> requires to change all the packages to use the new function.  In general,
> I can't change all those packages, so I'll still have to live with
> spurious errors every once in a while.
>
> Option 3 is better because it's the simplest.  Now you might think that
you
> don't like it because it changes the default behavior, but think again:
> it only changes the behavior in the case where you used to get an error
> "Cannot switch buffers in minibuffer window" or
> "Cannot switch buffers in a dedicated window".  When was the last time
> you saw such an error message?  Most users have never seen this message
> because they don't have dedicated windows and they never hit C-x b
> while they're in the minibuffer.

I see the "cannot switch buffers in minibuffer window" from time to time.
And it always annoys me -- of course I don't want to switch buffer in
the minibuffer window, I obviously want to have the buffer I select to
appear in some ordinary window.

I'd vote for 3 as well.

Re: Jumping to C source from *Help*

[Richard Stallman]

    I see the "cannot switch buffers in minibuffer window" from time to time.

Could you tell us how this happens?

Re: Jumping to C source from *Help*

[David Kastrup]

Richard Stallman <rms@gnu.org> writes:

>     I see the "cannot switch buffers in minibuffer window" from time to time.
> 
> Could you tell us how this happens?

Easy enough.  Try

M-x customize-variable

[Oops, forgot the name of the variable...]

C-x C-f ~/mylisp.el RET

cannot switch buffers in minibuffer window...

Of course assuming that you have enabled recursive minibuffers.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: Jumping to C source from *Help*

[Richard Stallman]

    3 - Change switch-to-buffer to call pop-to-buffer rather than signal an
	error and leave everything else unchanged.

I don't like the idea of making switch-to-buffer do different things
in interactive and noninteractive calls.  And I don't like the idea
of making it switch windows.

In the case of a single dedicated window, splitting the window
and using one of the new windows does make sense in a way.
However, switching to another existing window just seems wrong.

Re: Jumping to C source from *Help*

[Stefan Monnier]

>     3 - Change switch-to-buffer to call pop-to-buffer rather than signal an
> 	error and leave everything else unchanged.

> I don't like the idea of making switch-to-buffer do different things
> in interactive and noninteractive calls.  And I don't like the idea
> of making it switch windows.

> In the case of a single dedicated window, splitting the window
> and using one of the new windows does make sense in a way.
> However, switching to another existing window just seems wrong.

I never said it should switch to an existing window.
Maybe you inferred it because I used `pop-to-buffer', but I didn't mean to
be so specific.  What I need to change (in order to fix umpteen bugs that
only show up in setups such as mine) is that switch-to-buffer doesn't
signal an error but does something else instead.

What this something else is, I don't care nearly as much.
The (let ((pop-to-window t)) (pop-to-buffer buf)) suggestion seen earlier
sounds good to me, but I'd pretty much accept "anything" in order to fix
the problem of switch-to-buffer signalling an error in dedicated (and
minibuffer) windows.


        Stefan

Re: Jumping to C source from *Help*

[Richard Stallman]

      What I need to change (in order to fix umpteen bugs that
    only show up in setups such as mine) is that switch-to-buffer doesn't
    signal an error but does something else instead.

If the "something else instead" is switching to another existing
window, I feel this is contradictory to the purpose of
switch-to-buffer.  But I don't see how you could make the change you
want and avoid sometimes switching to another existing window.

Re: Jumping to C source from *Help*

[Stefan Monnier]

>       What I need to change (in order to fix umpteen bugs that
>     only show up in setups such as mine) is that switch-to-buffer doesn't
>     signal an error but does something else instead.

> If the "something else instead" is switching to another existing
> window, I feel this is contradictory to the purpose of
> switch-to-buffer.

AFAIk, the purpose of C-x b is to say "I don't need to see the
current buffer right now and I'd like to see buffer FOO instead".
As for switch-to-buffer when called from packages, it very often means "show
this buffer to the user" (and could thus use pop-to-buffer instead, except
the package author doesn't have enough of a clue) and other times it means
"show this buffer to the user in the current window", but without making
any provision for the possibility of an error, thus assuming that somehow
the buffer will be shown to the user.

On what experience do you base your assessment of "contradictory"?
Maybe the situation you're thinking of and the situation I (and Kim and
Drew and several of my friends here) live with can be reconciled?

> But I don't see how you could make the change you
> want and avoid sometimes switching to another existing window.

By creating a new window?
[ At least if that's what the user wants.  I'd also be perfectly happy as
  a user if switch-to-buffer sometimes used some existing window instead
  of signalling an error. ]


        Stefan

Re: Jumping to C source from *Help*

[Richard Stallman]

    Doc string for set-window-dedicated-p says this:

	    If it is dedicated, Emacs will not automatically change
	    which buffer appears in it.

    What does "automatically change" mean?  

It is supposed to mean that display-buffer won't choose the dedicated
window.  Originally, switch-to-buffer was permitted in dedicated
windows, so you could change buffers in them "manually", but Emacs
would not change it "automatically".

However, later on, Fswitch_to_buffer was changed to get an error in
dedicated windows.  I am not sure whether that is the right behavior,
but I would guess it was intended to avoid bad results in some real
situations.

Re: Jumping to C source from *Help*

[Stefan Monnier]

> It is supposed to mean that display-buffer won't choose the dedicated
> window.  Originally, switch-to-buffer was permitted in dedicated
> windows, so you could change buffers in them "manually", but Emacs
> would not change it "automatically".

> However, later on, Fswitch_to_buffer was changed to get an error in
> dedicated windows.  I am not sure whether that is the right behavior,
> but I would guess it was intended to avoid bad results in some real
> situations.

It'd probably be OK if C-x b overrode the `dedicated' bit.  But it's
definitely not OK for the switch-to-buffer function when called from elisp
packages because they all too often use switch-to-buffer without thinking
what it really means (because the author typically rarely if ever uses
multiple frames and has barely heard of pop-to-buffer, let alone
special-display-buffer-names).


        Stefan

Re: Jumping to C source from *Help*

[Juri Linkov]

Stefan Monnier <monnier@iro.umontreal.ca> writes:
> Thanks.  I've installed my patch (with slight modifications)
> and it now deals with the above (though in elisp rather than in C).
>
> Please try it,

This is a very good thing!  (and I like to repeat it :-)

But it reminded me another problem with the *Help* buffer: it doesn't
have a final newline.  This is especially annoying when a large *Help*
buffer with a long last line is scrolled horizontally to the left when
point reaches the end of the buffer.  For example, this problem can be
observed in the *Faces* buffer (invoked by the `list-faces-display').
Adding a final newline solves this problem.

diff -u -r1.24 help-mode.el
--- emacs/lisp/help-mode.el	7 Apr 2004 19:35:05 -0000	1.24
+++ emacs/lisp/help-mode.el	8 Apr 2004 05:41:35 -0000
@@ -432,11 +434,13 @@
 	(goto-char (point-max))
 	(while (and (not (bobp)) (bolp))
 	  (delete-char -1))
+        (insert "\n")
         ;; Make a back-reference in this buffer if appropriate.
         (when help-xref-stack
-	  (insert "\n\n")
+	  (insert "\n")
 	  (help-insert-xref-button help-back-label 'help-back
-				   (current-buffer))))
+				   (current-buffer))
+          (insert "\n")))
       ;; View mode steals RET from us.
       (set (make-local-variable 'minor-mode-overriding-map-alist)
            (list (cons 'view-mode help-xref-override-view-map)))

-- 
Juri Linkov
http://www.jurta.org/emacs/

Re: Jumping to C source from *Help*

[Kim F. Storm]

Juri Linkov <juri@jurta.org> writes:

> But it reminded me another problem with the *Help* buffer: it doesn't
> have a final newline. 

I think it should have for the reasons you mention.

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

Re: Jumping to C source from *Help*

[Richard Stallman]

    But it reminded me another problem with the *Help* buffer: it doesn't
    have a final newline.

It looks good.  Please install it.  Thanks.