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

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]

Any time one wants to write (insert) into a read-only buffer (e.g. *help*), 
one has to make it writable.  Doesn't matter when that time is.  If it's 
read-only you need to make it writable to write into it.

Reading the source for 'with-help-window', it arranges for 'inhibit-read-only' 
to be set to 't' around the call to its body.  Once the body finishes, that 
temporary binding goes out of scope and read-only is in effect again.

The aforementioned resetting  of 'inhibit-read-only' to 't' is an important 
feature that should be included in the docstring for the function 'with-help-window'.

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

[Eli Zaretskii]

> Date: Wed, 13 Sep 2023 10:41:01 +0000
> From:  Heime via "Bug reports for GNU Emacs,
>  the Swiss army knife of text editors" <bug-gnu-emacs@gnu.org>
> 
> Any time one wants to write (insert) into a read-only buffer (e.g. *help*), 
> one has to make it writable.  Doesn't matter when that time is.  If it's 
> read-only you need to make it writable to write into it.
> 
> Reading the source for 'with-help-window', it arranges for 'inhibit-read-only' 
> to be set to 't' around the call to its body.  Once the body finishes, that 
> temporary binding goes out of scope and read-only is in effect again.
> 
> The aforementioned resetting  of 'inhibit-read-only' to 't' is an important 
> feature that should be included in the docstring for the function 'with-help-window'.

I disagree.  The use of inhibit-read-only is an implementation detail
of with-help-window (and of many other functions in Emacs); mentioning
it in the doc string will IMO have no useful purpose.

The doc string of "C-x C-q" (read-only-mode) does mention
inhibit-read-only, which is I think a much more reasonable place for a
reference to that variable.

Stefan, WDYT?

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]

Sent with Proton Mail secure email.

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


> > Date: Wed, 13 Sep 2023 10:41:01 +0000
> > From: Heime via "Bug reports for GNU Emacs,
> > the Swiss army knife of text editors" bug-gnu-emacs@gnu.org
> > 
> > Any time one wants to write (insert) into a read-only buffer (e.g. help),
> > one has to make it writable. Doesn't matter when that time is. If it's
> > read-only you need to make it writable to write into it.
> > 
> > Reading the source for 'with-help-window', it arranges for 'inhibit-read-only'
> > to be set to 't' around the call to its body. Once the body finishes, that
> > temporary binding goes out of scope and read-only is in effect again.
> > 
> > The aforementioned resetting of 'inhibit-read-only' to 't' is an important
> > feature that should be included in the docstring for the function 'with-help-window'.
> 
> 
> I disagree. The use of inhibit-read-only is an implementation detail
> of with-help-window (and of many other functions in Emacs); mentioning
> it in the doc string will IMO have no useful purpose.
> 
> The doc string of "C-x C-q" (read-only-mode) does mention
> inhibit-read-only, which is I think a much more reasonable place for a
> reference to that variable.
> 
> Stefan, WDYT?

Docstrings have become so short at times that reading them is of no practical 
use.  The reality of it is not simply an implementation detail of no consequence.
Because if a developers knows that detail, ho would refrain form introducing
things like 

(with-help-window (help-buffer)
  (setq buffer-read-only nil)
  (insert " Graphic Organisation")
  (setq buffer-read-only t))

and instead immediately write

(with-help-window (help-buffer)
  (insert " Graphic Organisation"))



 

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

[Eli Zaretskii]

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

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.

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]

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

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

[Stefan Kangas]

Eli Zaretskii <eliz@gnu.org> writes:

> I disagree.  The use of inhibit-read-only is an implementation detail
> of with-help-window (and of many other functions in Emacs); mentioning
> it in the doc string will IMO have no useful purpose.
>
> The doc string of "C-x C-q" (read-only-mode) does mention
> inhibit-read-only, which is I think a much more reasonable place for a
> reference to that variable.
>
> Stefan, WDYT?

I tend to agree with you.

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

[Eli Zaretskii]

tags 65913 wontfix
close 65913
thanks

> From: Stefan Kangas <stefankangas@gmail.com>
> Date: Wed, 13 Sep 2023 07:04:31 -0700
> Cc: 65913@debbugs.gnu.org
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > I disagree.  The use of inhibit-read-only is an implementation detail
> > of with-help-window (and of many other functions in Emacs); mentioning
> > it in the doc string will IMO have no useful purpose.
> >
> > The doc string of "C-x C-q" (read-only-mode) does mention
> > inhibit-read-only, which is I think a much more reasonable place for a
> > reference to that variable.
> >
> > Stefan, WDYT?
> 
> I tend to agree with you.

OK, so I'm closing this bug.

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]

Sent with Proton Mail secure email.

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


> tags 65913 wontfix
> close 65913
> thanks
> 
> > From: Stefan Kangas stefankangas@gmail.com
> > Date: Wed, 13 Sep 2023 07:04:31 -0700
> > Cc: 65913@debbugs.gnu.org
> > 
> > Eli Zaretskii eliz@gnu.org writes:
> > 
> > > I disagree. The use of inhibit-read-only is an implementation detail
> > > of with-help-window (and of many other functions in Emacs); mentioning
> > > it in the doc string will IMO have no useful purpose.
> > > 
> > > The doc string of "C-x C-q" (read-only-mode) does mention
> > > inhibit-read-only, which is I think a much more reasonable place for a
> > > reference to that variable.
> > > 
> > > Stefan, WDYT?
> > 
> > I tend to agree with you.
> 
> 
> OK, so I'm closing this bug.

Congratulations for the disregard !  A disease that makes only the
the opinion of maintainers relevant rather than those using it.
A Total Disaster.

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

[Stefan Kangas]

Heime <heimeborgia@protonmail.com> writes:

> Congratulations for the disregard !  A disease that makes only the
> the opinion of maintainers relevant rather than those using it.
> A Total Disaster.

I see that you're disappointed.

It might not look that way, but we always try, to the best of our
abilities, to listen and take arguments into account.  We actually
almost always add some type of clarification when asked to by users.
But in a small minority of cases, we don't.

Please consider our situation too: we have tons of bugs on our table,
and they do have to be decided upon by someone.  Sometimes, there are
judgement calls to be made, and as much as we want to, we can't make
everyone happy.  Perhaps you can see the wisdom in at least some of the
choices we make, even if you disagree with others.

Thanks again for taking the trouble to report this bug, and feel free to
report other issues in the future.  We appreciate the help.

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

[Eli Zaretskii]

> Date: Wed, 13 Sep 2023 14:54:04 +0000
> From: Heime <heimeborgia@protonmail.com>
> Cc: Stefan Kangas <stefankangas@gmail.com>, 65913@debbugs.gnu.org
> 
> > > > Stefan, WDYT?
> > > 
> > > I tend to agree with you.
> > 
> > 
> > OK, so I'm closing this bug.
> 
> Congratulations for the disregard !  A disease that makes only the
> the opinion of maintainers relevant rather than those using it.
> A Total Disaster.

Please don't be unfair.  Your opinions were heard and considered.
They were not rejected because they are irrelevant or for any other
such reason.  We do not have to agree with everything you say,
especially after we explain why the doc string of that particular
function is not the right place to mention inhibit-read-only.  Other
doc strings, which are a better place, do mention it.

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

[uzibalqa via Bug reports for GNU Emacs, the Swiss army knife of text editors]

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

> > Date: Wed, 13 Sep 2023 14:54:04 +0000
> > From: Heime heimeborgia@protonmail.com
> > Cc: Stefan Kangas stefankangas@gmail.com, 65913@debbugs.gnu.org
> > 
> > > > > Stefan, WDYT?
> > > > 
> > > > I tend to agree with you.
> > > 
> > > OK, so I'm closing this bug.
> > 
> > Congratulations for the disregard ! A disease that makes only the
> > the opinion of maintainers relevant rather than those using it.
> > A Total Disaster.
> 
> 
> Please don't be unfair. Your opinions were heard and considered.
> They were not rejected because they are irrelevant or for any other
> such reason. We do not have to agree with everything you say,
> especially after we explain why the doc string of that particular
> function is not the right place to mention inhibit-read-only. Other
> doc strings, which are a better place, do mention it.

The purpose of the docstring should be expanded.  And if using the manual
is required, please provide that information from the self documentation.

I disagree with the notion that working with emacs should be hard.  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.

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

[Eli Zaretskii]

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

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

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]

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

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

[Eli Zaretskii]

> Date: Thu, 14 Sep 2023 10:41:06 +0000
> From: Heime <heimeborgia@protonmail.com>
> Cc: uzibalqa <uzibalqa@proton.me>, 65913@debbugs.gnu.org, stefankangas@gmail.com
> 
> > 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.

That's an existing feature, we use it when appropriate.

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

We have commands for that: "M-x apropos", Info-index, and others.

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]

------- Original Message -------
On Friday, September 15th, 2023 at 12:50 AM, Eli Zaretskii <eliz@gnu.org> wrote:

> > Date: Thu, 14 Sep 2023 10:41:06 +0000
> > From: Heime heimeborgia@protonmail.com
> > Cc: uzibalqa uzibalqa@proton.me, 65913@debbugs.gnu.org, stefankangas@gmail.com
> > 
> > > 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.
> 
> 
> That's an existing feature, we use it when appropriate.
> 
> > > 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.
> 
> We have commands for that: "M-x apropos", Info-index, and others.

Many thanks, shall look into this and see how far that gets me.

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

[Drew Adams]

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

Amen.

This is a common request from users, who sometimes
expect a complete answer to their question - aimed
at their particular immediate context/problem - or
a complete understanding of something, to be right
in front of them, at the first page or help msg
they encounter.  And they want it to be aimed at
their particular level of background understanding.

It's an individualistic, "Gimme, gimme, gimme, me!"
approach, naively ignoring the fact that whatever
help they hope to find will likely aim to also help
others, with different backgrounds, questions,
contexts, problems.

I'm guessing this can also come partly from a
frustration from _searching_ as the main - or even
the only - navigation users employ.  Search can be
very good, or very bad.  Some experience/knowledge
are needed to search effectively, as well as good
search tools.

Emacs has good search tools.  The first thing users
should learn is how to Ask Emacs.  The help commands
of course, and later even how to ask using Lisp etc.

A just-what-I-need-right-here-right-now expectation
is a problem for help/documentation in general, but
especially so nowadays, when it's no longer the case
(if it ever was) that readers start at the start of
a book and read sequentially.

Now, more than ever, "Every Page Is Page One".

https://everypageispageone.com/

Readers arrive at a URL by googling or following a
link from somewhere.  Off the web, inside Emacs,
they arrive at an Info node or a *Help* description
directly.

The solution to the "problem" is for every "page"
to provide relevant links to other pages/topics.
Every one.  That way, wherever you start you can
pretty much follow the paths you want, to get the
info you need.

It's not a simple problem with a trivial solution.
Deciding what goes into a given "page"/topic, and
which other topics to link to, is a judgment call
- or more correctly lots of judgment calls.  And
that means that even with the "best" design, for
some set of targeted readers/users, some will be
frustrated.  (Even deciding what the targeted set
of readers should be is non-trivial and involves
compromises.)

A good model of a generally helpful doc system is
Wikipedia.

Emacs help and doc are pretty darn good.  This is
largely because Emacs maintainers - first RMS and
now Eli, in particular - have long been hugely
interested in the help/doc - self-documenting -
feature/aspect of Emacs.  Emacs didn't exactly
invent self-documenting, perhaps, but it nearly
did so.

> Consulting the documentation is one of the
> first lessons that each Emacs user learns,
> and resisting that lesson is not recommended.

Agreed.  There's no excuse for not dipping into
the manuals.  Or for not taking advantage of
other sources: tutorials, videos Q&A venues, etc.
Different users learn differently, of course.

That said, more links from *Help* to manuals
could help, I think.

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

[Eli Zaretskii]

> From: Drew Adams <drew.adams@oracle.com>
> CC: "65913@debbugs.gnu.org" <65913@debbugs.gnu.org>,
>         "heimeborgia@protonmail.com" <heimeborgia@protonmail.com>,
>         "stefankangas@gmail.com" <stefankangas@gmail.com>
> Date: Thu, 14 Sep 2023 16:03:56 +0000
> 
> That said, more links from *Help* to manuals
> could help, I think.

Yes -- when either the manuals have information that is generally
expected to be in the doc string, but we decided not to have it there
(e.g., because it's very voluminous), or when the place in the manual
where to look is not trivially clear from the doc string.

In most cases, the place where to look for the related information in
the manuals is quite easily found: just visit the manual and then type
"i SYMBOL RET", where SYMBOL is the name of the variable or the
function whose doc string you are reading.

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

[Christopher Dimech]

> Sent: Friday, September 15, 2023 at 4:15 AM
> From: "Eli Zaretskii" <eliz@gnu.org>
> To: "Drew Adams" <drew.adams@oracle.com>
> Cc: uzibalqa@proton.me, heimeborgia@protonmail.com, stefankangas@gmail.com, 65913@debbugs.gnu.org
> Subject: bug#65913: with-help-window arranges for 'inhibit-read-only' to be set to 't'
>
> > From: Drew Adams <drew.adams@oracle.com>
> > CC: "65913@debbugs.gnu.org" <65913@debbugs.gnu.org>,
> >         "heimeborgia@protonmail.com" <heimeborgia@protonmail.com>,
> >         "stefankangas@gmail.com" <stefankangas@gmail.com>
> > Date: Thu, 14 Sep 2023 16:03:56 +0000
> >
> > That said, more links from *Help* to manuals
> > could help, I think.
>
> Yes -- when either the manuals have information that is generally
> expected to be in the doc string, but we decided not to have it there
> (e.g., because it's very voluminous), or when the place in the manual
> where to look is not trivially clear from the doc string.

I think the whole point is that if the information is available somewhere,
one should be able to access it (voluminous or not).

> In most cases, the place where to look for the related information in
> the manuals is quite easily found: just visit the manual and then type
> "i SYMBOL RET", where SYMBOL is the name of the variable or the
> function whose doc string you are reading.

There could be some information in the "Introduction to Programming in
Emacs Lisp" that illustrates an actual serious problem and how to get
to the information from within Emacs itself in an efficient way.  But,
in my opinion the introduction is more about toy problems rather than
complicated actual work examples.

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

[Eli Zaretskii]

> From: Christopher Dimech <dimech@gmx.com>
> Cc: Drew Adams <drew.adams@oracle.com>, uzibalqa@proton.me,
>  heimeborgia@protonmail.com, stefankangas@gmail.com, 65913@debbugs.gnu.org
> Date: Thu, 14 Sep 2023 18:40:16 +0200
> 
> > Yes -- when either the manuals have information that is generally
> > expected to be in the doc string, but we decided not to have it there
> > (e.g., because it's very voluminous), or when the place in the manual
> > where to look is not trivially clear from the doc string.
> 
> I think the whole point is that if the information is available somewhere,
> one should be able to access it (voluminous or not).

Emacs shines in this area by providing commands that allow such easy
access.  One just has to use them.

> > In most cases, the place where to look for the related information in
> > the manuals is quite easily found: just visit the manual and then type
> > "i SYMBOL RET", where SYMBOL is the name of the variable or the
> > function whose doc string you are reading.
> 
> There could be some information in the "Introduction to Programming in
> Emacs Lisp" that illustrates an actual serious problem and how to get
> to the information from within Emacs itself in an efficient way.

We already have this in the Emacs user manual, see the beginning of
the chapter "Help".  It lists the various methods of finding relevant
information in the available documentation.

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

[Christopher Dimech]

> Sent: Friday, September 15, 2023 at 4:55 AM
> From: "Eli Zaretskii" <eliz@gnu.org>
> To: "Christopher Dimech" <dimech@gmx.com>
> Cc: drew.adams@oracle.com, uzibalqa@proton.me, heimeborgia@protonmail.com, stefankangas@gmail.com, 65913@debbugs.gnu.org
> Subject: Re: bug#65913: with-help-window arranges for 'inhibit-read-only' to be set to 't'
>
> > From: Christopher Dimech <dimech@gmx.com>
> > Cc: Drew Adams <drew.adams@oracle.com>, uzibalqa@proton.me,
> >  heimeborgia@protonmail.com, stefankangas@gmail.com, 65913@debbugs.gnu.org
> > Date: Thu, 14 Sep 2023 18:40:16 +0200
> >
> > > Yes -- when either the manuals have information that is generally
> > > expected to be in the doc string, but we decided not to have it there
> > > (e.g., because it's very voluminous), or when the place in the manual
> > > where to look is not trivially clear from the doc string.
> >
> > I think the whole point is that if the information is available somewhere,
> > one should be able to access it (voluminous or not).
>
> Emacs shines in this area by providing commands that allow such easy
> access.  One just has to use them.
>
> > > In most cases, the place where to look for the related information in
> > > the manuals is quite easily found: just visit the manual and then type
> > > "i SYMBOL RET", where SYMBOL is the name of the variable or the
> > > function whose doc string you are reading.
> >
> > There could be some information in the "Introduction to Programming in
> > Emacs Lisp" that illustrates an actual serious problem and how to get
> > to the information from within Emacs itself in an efficient way.
>
> We already have this in the Emacs user manual, see the beginning of
> the chapter "Help".  It lists the various methods of finding relevant
> information in the available documentation.

I can go through the "Reference Manual" and the "Introduction to Programming
in Emacs Lisp" to make sure users cannot miss it.  Look at some of the questions
by the OP and see how easy it is to figure things out via a specific procedure
that can be followed.

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

[Christopher Dimech]

> Sent: Friday, September 15, 2023 at 4:03 AM
> From: "Drew Adams" <drew.adams@oracle.com>
> To: "Eli Zaretskii" <eliz@gnu.org>, "uzibalqa" <uzibalqa@proton.me>
> Cc: "65913@debbugs.gnu.org" <65913@debbugs.gnu.org>, "heimeborgia@protonmail.com" <heimeborgia@protonmail.com>, "stefankangas@gmail.com" <stefankangas@gmail.com>
> Subject: bug#65913: with-help-window arranges for 'inhibit-read-only' to be set to 't'
>
> > 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.
>
> Amen.
>
> This is a common request from users, who sometimes
> expect a complete answer to their question - aimed
> at their particular immediate context/problem - or
> a complete understanding of something, to be right
> in front of them, at the first page or help msg
> they encounter.  And they want it to be aimed at
> their particular level of background understanding.
>
> It's an individualistic, "Gimme, gimme, gimme, me!"
> approach, naively ignoring the fact that whatever
> help they hope to find will likely aim to also help
> others, with different backgrounds, questions,
> contexts, problems.

Functioning autonomously in the whole point actually.  I support the
capability of being able to access to whatever might be needed in an
automated way for every function.  A function should have a list of
associations that are relevant to that function and have the capability
of giving you that information.


> I'm guessing this can also come partly from a
> frustration from _searching_ as the main - or even
> the only - navigation users employ.  Search can be
> very good, or very bad.  Some experience/knowledge
> are needed to search effectively, as well as good
> search tools.

> Emacs has good search tools.  The first thing users
> should learn is how to Ask Emacs.  The help commands
> of course, and later even how to ask using Lisp etc.

> A just-what-I-need-right-here-right-now expectation
> is a problem for help/documentation in general, but
> especially so nowadays, when it's no longer the case
> (if it ever was) that readers start at the start of
> a book and read sequentially.

At least it should tell you what you wight need no know to
fully take advantage of the capabilities of that function.

> Now, more than ever, "Every Page Is Page One".
>
> https://everypageispageone.com/
>
> Readers arrive at a URL by googling or following a
> link from somewhere.  Off the web, inside Emacs,
> they arrive at an Info node or a *Help* description
> directly.
>
> The solution to the "problem" is for every "page"
> to provide relevant links to other pages/topics.
> Every one.  That way, wherever you start you can
> pretty much follow the paths you want, to get the
> info you need.

Or a separate tool.

> It's not a simple problem with a trivial solution.
> Deciding what goes into a given "page"/topic, and
> which other topics to link to, is a judgment call
> - or more correctly lots of judgment calls.  And
> that means that even with the "best" design, for
> some set of targeted readers/users, some will be
> frustrated.  (Even deciding what the targeted set
> of readers should be is non-trivial and involves
> compromises.)

In many situation, compromises meant that valuable information is missing
and never included.   Instead of deciding the targeted set of readers,
tools should be as broad as they can ever be.  Because one might not know
presumptively what they might need.  Particularly when some function inplements
some convenient shortcuts.

> A good model of a generally helpful doc system is
> Wikipedia.
>
> Emacs help and doc are pretty darn good.  This is
> largely because Emacs maintainers - first RMS and
> now Eli, in particular - have long been hugely
> interested in the help/doc - self-documenting -
> feature/aspect of Emacs.  Emacs didn't exactly
> invent self-documenting, perhaps, but it nearly
> did so.
>
> > Consulting the documentation is one of the
> > first lessons that each Emacs user learns,
> > and resisting that lesson is not recommended.
>
> Agreed.  There's no excuse for not dipping into
> the manuals.  Or for not taking advantage of
> other sources: tutorials, videos Q&A venues, etc.
> Different users learn differently, of course.

The excuse is that one can look at whatever you are saying,
only to find out that it was all a waste of time.  For instance,
would one go through the Xah Talk Shows or go through the EmacsConf
or Libre Planet talks unless you are sure it will be useful ? I don't
think so !

> That said, more links from *Help* to manuals
> could help, I think.

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]

Sent with Proton Mail secure email.

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


> Eli Zaretskii eliz@gnu.org writes:
> 
> > I disagree. The use of inhibit-read-only is an implementation detail
> > of with-help-window (and of many other functions in Emacs); mentioning
> > it in the doc string will IMO have no useful purpose.
> > 
> > The doc string of "C-x C-q" (read-only-mode) does mention
> > inhibit-read-only, which is I think a much more reasonable place for a
> > reference to that variable.
> > 
> > Stefan, WDYT?
> 
> 
> I tend to agree with you.

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.

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

[Stefan Kangas]

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.

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]

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

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

[Stefan Kangas]

Heime <heimeborgia@protonmail.com> writes:

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

I basically agree, but the details on how to do it have to be worked out
in each case individually.

> 2. A reference to the relevant section of the manual that would be
> important to read about.

Agreed.  See Bug#60587 where a more general feature like this is being
worked on.

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]

Sent with Proton Mail secure email.

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


> Heime heimeborgia@protonmail.com writes:
> 
> > 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.
> 
> 
> I basically agree, but the details on how to do it have to be worked out
> in each case individually.

Right Right
 
> > 2. A reference to the relevant section of the manual that would be
> > important to read about.
> 
> 
> Agreed. See Bug#60587 where a more general feature like this is being
> worked on.

Glad to know that some of the deliberations are recognised.  I usually take 
the bother even at the risk of some antagonisms.  Whenever you want perspective
from someone who knows too little, I am available.