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.