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

[Heime]

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


> > Date: Wed, 13 Sep 2023 13:26:51 +0000
> > From: Heime heimeborgia@protonmail.com
> > Cc: Stefan Kangas stefankangas@gmail.com, 65913@debbugs.gnu.org
> > 
> > Docstrings have become so short at times that reading them is of no 
> > practical
> > use.
> 
> Only because you think everything can be learned from scratch by
> reading only some more or less random doc strings. That's not how
> programming in Emacs Lisp should be learned. There's a large Emacs
> Lisp Reference manual, which has a separate section named "Read-Only
> Buffers". If you read it when you started working with read-only
> buffers, you'd have found the inhibit-read-only variable described
> there.

Not everthing but at least the minimum level for the description to
be useful in a practical sense.  Particularly when neither with-help-window  
nor help-buffer ever mention that the buffers are read only.  If one does
not presuppose that the developer knows that the buffer is read only, there
is practically no way this figure out using the self documentation.  
 
Whilst it is claimed that Emacs is a self-documenting real-time display editor,
it hardly ever words that way in practice.  

> Our recommendation is to read the relevant parts of the ELisp manual
> whenever you need for the first time work with a specific aspect of
> Emacs Lisp.

A decent programmer should be capable of extracting some useful information
on using a function directly from its self documenting docstring.  Otherwise
the self documentation is quite pointless from the practical point of view. 

Merely saying that this does THIS and that does THAT is certainly deficient 
in many ways.