bug#65913: with-help-window arranges for 'inhibit-read-only' to be set to 't'

[Heime]

Sent with Proton Mail secure email.

------- Original Message -------
On Thursday, September 14th, 2023 at 1:13 AM, Eli Zaretskii <eliz@gnu.org> 
wrote:


> > Date: Wed, 13 Sep 2023 10:41:01 +0000
> > From: Heime via "Bug reports for GNU Emacs,
> > the Swiss army knife of text editors" bug-gnu-emacs@gnu.org
> > 
> > Any time one wants to write (insert) into a read-only buffer (e.g. help),
> > one has to make it writable. Doesn't matter when that time is. If it's
> > read-only you need to make it writable to write into it.
> > 
> > Reading the source for 'with-help-window', it arranges for 
> > 'inhibit-read-only'
> > to be set to 't' around the call to its body. Once the body finishes, that
> > temporary binding goes out of scope and read-only is in effect again.
> > 
> > The aforementioned resetting of 'inhibit-read-only' to 't' is an important
> > feature that should be included in the docstring for the function 
> > 'with-help-window'.
> 
> 
> I disagree. The use of inhibit-read-only is an implementation detail
> of with-help-window (and of many other functions in Emacs); mentioning
> it in the doc string will IMO have no useful purpose.
> 
> The doc string of "C-x C-q" (read-only-mode) does mention
> inhibit-read-only, which is I think a much more reasonable place for a
> reference to that variable.
> 
> Stefan, WDYT?

Docstrings have become so short at times that reading them is of no practical 
use.  The reality of it is not simply an implementation detail of no 
consequence.
Because if a developers knows that detail, ho would refrain form introducing
things like 

(with-help-window (help-buffer)
  (setq buffer-read-only nil)
  (insert " Graphic Organisation")
  (setq buffer-read-only t))

and instead immediately write

(with-help-window (help-buffer)
  (insert " Graphic Organisation"))