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

[Heime via "Bug reports for GNU Emacs, the Swiss army knife of text editors" <bug-gnu-emacs@gnu.org>]

------- Original Message -------
On Thursday, September 14th, 2023 at 3:14 AM, Stefan Kangas <stefankangas@gmail.com> wrote:

> 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.

There is no problem giving your opinion.  What I contest is that most of the 
opinions are by those who actually know to much, rather than for those who 
know too little.  I am of the School of Thought that this should change because
more information is better than less in many cases.  

The documentation is usually of much more practical value than the docstrings.
I cannot see the harm if after the general docstring description there is

1. A corollary on some additional things that add value from the practical point oy view.
2. A reference to the relevant section of the manual that would be important to read about.

The strain is currently put on the developer to find the way through the jungle.  Most
people find the wolf waiting for them.  This is the opinion from someone who knows too
little.  There are many like me.