GNU bug report logs - #30792
26.0.91; improve docstring of with-help-window

Previous Next

Full log

View this message in rfc822 format

From: martin rudalics <rudalics <at> gmx.at>
To: Nick Helm <nick <at> tenpoint.co.nz>, Eli Zaretskii <eliz <at> gnu.org>
Cc: 30792 <at> debbugs.gnu.org
Subject: bug#30792: 26.0.91; improve docstring of with-help-window
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

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.