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

From: Eli Zaretskii <[email-masked]>
Date: Thu, 14 Sep 2023 07:53:36 +0300

> Date: Wed, 13 Sep 2023 19:16:52 +0000
> From: uzibalqa <[email-masked]>
> Cc: Heime <[email-masked]>, [email-masked], [email-masked]
> 
> The purpose of the docstring should be expanded.  And if using the manual
> is required, please provide that information from the self documentation.

We do that when needed, but not in this case.  There's no reason to
mention inhibit-read-only when we document with-help-window, because
with-help-window is not about read-only buffers.

> I disagree with the notion that working with emacs should be hard.

So do we.  But this issue has nothing to do with how hard it is to
work with Emacs.  You simply looked for the information you were after
in the wrong place, when the right place should have been pretty
obvious for someone who writes Lisp programs: the ELisp manual.

> With most people I communicate with, it is generally agreed that
> using the language is hard.  It is the solution that I disagree
> with.  Because the solution that I am usually given is to endure the
> time it takes for everyone to learn it.

The solution you were suggested was to look for information about
read-only buffers where read-only buffers are described, either in the
ELisp manual or in the doc string of the command which toggles the
read-only state of the buffer.

In general, there's no need to mention in each and every doc string
that to learn about some subject you should read the manual where that
subject is described.  This is trivial, and having to repeat that
everywhere will just bloat Emacs for no good reason.  Consulting the
documentation is one of the first lessons that each Emacs user learns,
and resisting that lesson is not recommended.