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

[Heime]

------- Original Message -------
On Thursday, September 14th, 2023 at 4:53 PM, Eli Zaretskii <eliz@gnu.org> 
wrote:

> > Date: Wed, 13 Sep 2023 19:16:52 +0000
> > From: uzibalqa uzibalqa@proton.me
> > Cc: Heime heimeborgia@protonmail.com, 65913@debbugs.gnu.org, 
> > stefankangas@gmail.com
> > 
> > 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.

Stefan mentioned a project to have the docstring communicate with the manual
so that finding the information will not be too laborious.
 
> > 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.

The difficulty is that while something is discussion theoretically,
the actual function gives some conveniences that might not be so apparent.
As was the case for with-help-window.  Once such conveniences are
understood, things are good.
 
> 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.

There could be some manual or metadata that could provide rapid search
and association capabilities to find relevant information and avoid much
manual labour.