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

[Stefan Kangas]

Heime <heimeborgia@protonmail.com> writes:

> Stefan, is this to say that for you it is good that there is no way
> to figure out that there is no requirement to reset buffer-read-only
> from the self documentation ?  And that it is even unnecessary to
> state that the duffer is read only by going through the different
> docstrings.  Such conclusions is seriously deficient with little regard
> to how much time developers waste in working with the language.

No, I just don't see why anyone would assume that you would have to mess
around with buffer-read-only, given that the manual (for example) says:

 -- Macro: with-help-window buffer-or-name body...
     This macro evaluates BODY like ‘with-output-to-temp-buffer’ (*note
     Temporary Displays::), inserting any output produced by its forms
     into a buffer specified by BUFFER-OR-NAME, which can be a buffer or
     the name of a buffer.

The docstring also seems pretty clear to me.  Nothing leads me to think
that I can't just

    (with-help-window "*foo*"
      (insert "bar"))

as indeed I can.  And help mode is read-only so that part is clear too.

I understand that this aspect confused you, but we can't add every
possible confusion to the ELisp manual and/or docstrings.  They would
end up being much too long, which would also "waste time".  Therefore,
we have to focus on clarifying aspects that are confusing to many.

Is this an exact science?  Not really, quite the contrary.  The purpose
of these discussions is precisely to make better decisions in cases such
as these.  In this case, Eli asked for my opinion, so I gave mine.