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

[martin rudalics]

> 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