Subject: Re: bug#30792: 26.0.91; improve docstring of with-help-window

From: martin rudalics <[email-masked]>
Date: Thu, 15 Mar 2018 09:20:52 +0100

> Isn't it sufficient that the docstring says it puts the buffer in
 > `help-mode'? If a user wants to find out what that means and how to
 > tweak the result, they can follow the link and read the help
 > documentation. If they're reading the docstring in the first place, they
 > almost certainly know how help works, and that pushing q quits a help
 > window by default.

Agreed.  Please follow Eli's proposal in this regard.

 >> But if we change BUFFER-NAME to BUFFER-OR-NAME this should be
 >> reflected in the Elisp manual.
 >
 > This was just a suggestion, as `with-help-window' simply passes the
 > value along to `with-temp-buffer-window'.
 >
 > I think the expected use of `with-help-window' was to receive output
 > from `help-buffer', which returns an existing help buffer object or
 > "*Help*". But that's not the only way to use `with-help-window' and
 > `with-temp-buffer-window' can accept any existing buffer object or a
 > string name to create a new one. I think it would be useful if
 > `with-help-window' made that clear by using the same name.

Agreed as well.  But we should synchronize argument names in
definitions and manuals so please provide a corresponding change for
help.texi too.

Thanks, martin