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

Previous Next

Full log

Message #20 received at 65913 <at> debbugs.gnu.org (full text, mbox):

From: Heime <heimeborgia <at> protonmail.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 65913 <at> debbugs.gnu.org, stefankangas <at> gmail.com
Subject: Re: bug#65913: with-help-window arranges for 'inhibit-read-only' to
 be set to 't'
Date: Wed, 13 Sep 2023 14:26:34 +0000

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


> > Date: Wed, 13 Sep 2023 13:26:51 +0000
> > From: Heime heimeborgia <at> protonmail.com
> > Cc: Stefan Kangas stefankangas <at> gmail.com, 65913 <at> 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.

Previous Next

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