bug#702: with-help-window returns nil

bug#702: with-help-window returns nil

[Glenn Morris]

Current CVS trunk:

with-help-window returns nil, rather than the last value of BODY.
This causes, eg, describe-function to return nil, rather than the
description. This breaks, eg, eshell/which:

emacs -Q -f eshell
eshell> which which
Wrong type argument: stringp, nil

bug#702: with-help-window returns nil

[Lennart Borgman (gmail)]

Glenn Morris wrote:
> Current CVS trunk:
> 
> with-help-window returns nil, rather than the last value of BODY.
> This causes, eg, describe-function to return nil, rather than the
> description. This breaks, eg, eshell/which:
> 
> emacs -Q -f eshell
> eshell> which which
> Wrong type argument: stringp, nil


I just reported this problem to the maintainer of eshell and suggested 
to fetch the documentation in another way.

It is not documented that describe-function should return the doc string.

bug#702: with-help-window returns nil

[Drew Adams]

> It is not documented that describe-function should return the 
> doc string.

And rightfully so. It does not return the doc string. It returns the content of
*Help*, that is, everything that is there, which includes the doc-string text.
See `describe-function-1' for what is included.

Yes, we could document that it returns the contents of *Help* as a string, but
I'm not sure that would be helpful to most users of `describe-funtion'. Those
who are concerned about the return value will likely look at the source code,
which already includes a comment about it.

bug#702: with-help-window returns nil

[Lennart Borgman (gmail)]

Drew Adams wrote:
>> It is not documented that describe-function should return the 
>> doc string.
> 
> And rightfully so. It does not return the doc string. It returns the content of
> *Help*, that is, everything that is there, which includes the doc-string text.
> See `describe-function-1' for what is included.
> 
> Yes, we could document that it returns the contents of *Help* as a string, but
> I'm not sure that would be helpful to most users of `describe-funtion'. Those
> who are concerned about the return value will likely look at the source code,
> which already includes a comment about it.

What is wrong with just using (documentation 'my-fun t) instead?

bug#702: with-help-window returns nil

[Drew Adams]

> >> It is not documented that describe-function should return the 
> >> doc string.
> > 
> > And rightfully so. It does not return the doc string. It 
> > returns the content of *Help*, that is, everything that
> > is there, which includes the doc-string text.
> > See `describe-function-1' for what is included.
> > 
> > Yes, we could document that it returns the contents of 
> > *Help* as a string, but I'm not sure that would be helpful
> > to most users of `describe-funtion'. Those who are
> > concerned about the return value will likely look at the
> > source code, which already includes a comment about it.
> 
> What is wrong with just using (documentation 'my-fun t) instead?

Instead of what?

Do you mean return that from `describe-function'? Why?

If you want that in some Lisp code, then just use that - no need to call
`describe-function'. If you want what *Help* displays for `describe-function',
however, then you can use the return value of `describe-function'.

bug#702: with-help-window returns nil

[martin rudalics]

[-- Attachment #1: Type: text/plain, Size: 202 bytes --]

 > with-help-window returns nil, rather than the last value of BODY.
 > This causes, eg, describe-function to return nil, rather than the
 > description.

Do I get away with the attached patch?

martin

[-- Attachment #2: 702.diff --]
[-- Type: text/plain, Size: 3010 bytes --]

*** help.el.~1.341.~	2008-06-06 22:02:42.000000000 +0200
--- help.el	2008-08-13 07:45:02.796875000 +0200
***************
*** 1207,1213 ****
  (defmacro with-help-window (buffer-name &rest body)
    "Display buffer BUFFER-NAME in a help window evaluating BODY.
  Select help window if the actual value of the user option
! `help-window-select' says so."
    (declare (indent 1) (debug t))
    ;; Bind list-of-frames to `frame-list' and list-of-window-tuples to a
    ;; list of one <window window-buffer window-start window-point> tuple
--- 1207,1213 ----
  (defmacro with-help-window (buffer-name &rest body)
    "Display buffer BUFFER-NAME in a help window evaluating BODY.
  Select help window if the actual value of the user option
! `help-window-select' says so.  Return last value in BODY."
    (declare (indent 1) (debug t))
    ;; Bind list-of-frames to `frame-list' and list-of-window-tuples to a
    ;; list of one <window window-buffer window-start window-point> tuple
***************
*** 1221,1244 ****
  			   (window-start window) (window-point window))
  		     list))
  	     'no-mini t)
! 	    list)))
!      ;; We set `help-window' to t in order to trigger `help-mode-finish'
!      ;; to set `help-window' to the actual help window.
       (setq help-window t)
       ;; Make `help-window-point-marker' point nowhere (the only place
       ;; where this should be set to a buffer position is within BODY).
       (set-marker help-window-point-marker nil)
! 
!      (with-output-to-temp-buffer ,buffer-name
!        (progn ,@body))
! 
       (when (windowp help-window)
         ;; Set up help window.
         (help-window-setup list-of-frames list-of-window-tuples))
- 
       ;; Reset `help-window' to nil to avoid confusing future calls of
!      ;; `help-mode-finish' by "plain" `with-output-to-temp-buffer'.
!      (setq help-window nil)))
  \f
  (provide 'help)
  
--- 1221,1246 ----
  			   (window-start window) (window-point window))
  		     list))
  	     'no-mini t)
! 	    list))
! 	 value)
!      ;; Setting `help-window' to t shall trigger `help-mode-finish' to
!      ;; set `help-window' to the actual help window.
       (setq help-window t)
       ;; Make `help-window-point-marker' point nowhere (the only place
       ;; where this should be set to a buffer position is within BODY).
       (set-marker help-window-point-marker nil)
!      ;; Save value returned by `with-output-to-temp-buffer'.
!      (setq value
! 	   (with-output-to-temp-buffer ,buffer-name
! 	     (progn ,@body)))
       (when (windowp help-window)
         ;; Set up help window.
         (help-window-setup list-of-frames list-of-window-tuples))
       ;; Reset `help-window' to nil to avoid confusing future calls of
!      ;; `help-mode-finish' with "plain" `with-output-to-temp-buffer'.
!      (setq help-window nil)
!      ;; Return value returned by `with-output-to-temp-buffer'.
!      value))
  \f
  (provide 'help)
  

bug#702: with-help-window returns nil

[Glenn Morris]

martin rudalics wrote:

> Do I get away with the attached patch?

Yes, or just with a prog1. Thanks.

bug#702: with-help-window returns nil

[martin rudalics]

> Yes, or just with a prog1. Thanks.

Indeed.  I think I'll use prog1.

Thank you, martin.