bug#50936: "(emacs) Help" does say how to find external packages

bug#50936: "(emacs) Help" does say how to find external packages

[Stefan Kangas]

In (info "(emacs) Help"), I read:

     If you are looking for a certain feature, but don’t know what it is
  called or where to look, we recommend three methods.  First, try an
  apropos command, then try searching the manual index, then look in the
  FAQ and the package keywords.
  [...]
  ‘C-h p’
       This displays the available Emacs packages based on keywords.
       *Note Package Keywords::.

The problem with this is that packages from GNU ELPA and NonGNU ELPA
aren't listed here, so the better place to look should actually be
'M-x list-packages'.  Because that's where you'll find important modes
for programming languages, etc.

I'm not sure if the recommendation should be changed, or simply
amended to also mention M-x list-packages.  Or perhaps finder should
list packages that are not installed?

bug#50936: "(emacs) Help" does say how to find external packages

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Date: Fri, 1 Oct 2021 13:48:57 +0200
> 
> In (info "(emacs) Help"), I read:
> 
>      If you are looking for a certain feature, but don’t know what it is
>   called or where to look, we recommend three methods.  First, try an
>   apropos command, then try searching the manual index, then look in the
>   FAQ and the package keywords.
>   [...]
>   ‘C-h p’
>        This displays the available Emacs packages based on keywords.
>        *Note Package Keywords::.
> 
> The problem with this is that packages from GNU ELPA and NonGNU ELPA
> aren't listed here, so the better place to look should actually be
> 'M-x list-packages'.  Because that's where you'll find important modes
> for programming languages, etc.

"Modes" and "features" are not the same.  The latter refers to
features built into Emacs, i.e. to bundled packages.  If that isn't
clear from the text, we could clarify that, although it should be
quite obvious that an Emacs manual talks about bundled features.

> I'm not sure if the recommendation should be changed, or simply
> amended to also mention M-x list-packages.

It's okay to also mention list-packages, but if so, the text should
explicitly say that it's for features and packages not included in
the core distribution.

More importantly, I think we should seriously consider whether such
text has its place in that section.  That section is supposed to be a
cookbook for quickly and efficiently find Emacs features, so it should
be limited to methods and commands that accurate, in the sense that
they don't present the user with long lists of potential hits.  By
contrast, list-packages shows a very long list of packages (more than
400 as of this writing), which can easily overwhelm the user.  Even
"C-h p" doesn't show such long lists (the longest has 50 items), and
it is already too long, which is why it's the last in the list of
recommended methods.

> Or perhaps finder should list packages that are not installed?

Wouldn't that make "C-h p" less efficient, for the reason pointed out
above?

bug#50936: "(emacs) Help" does say how to find external packages

[Stefan Kangas]

Eli Zaretskii <eliz@gnu.org> writes:

> > I'm not sure if the recommendation should be changed, or simply
> > amended to also mention M-x list-packages.
>
> It's okay to also mention list-packages, but if so, the text should
> explicitly say that it's for features and packages not included in
> the core distribution.

I think this sounds like the best solution.

> More importantly, I think we should seriously consider whether such
> text has its place in that section.  That section is supposed to be a
> cookbook for quickly and efficiently find Emacs features, so it should
> be limited to methods and commands that accurate, in the sense that
> they don't present the user with long lists of potential hits.  By
> contrast, list-packages shows a very long list of packages (more than
> 400 as of this writing), which can easily overwhelm the user.  Even
> "C-h p" doesn't show such long lists (the longest has 50 items), and
> it is already too long, which is why it's the last in the list of
> recommended methods.

That's a problem, but there is IMO no way around that as long as Emacs
doesn't bundle packages like php-mode, haskell-mode, eglot or
lsp-mode, markdown-mode, etc.

bug#50936: "(emacs) Help" does say how to find external packages

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Date: Fri, 1 Oct 2021 15:15:26 +0200
> Cc: 50936@debbugs.gnu.org
> 
> > More importantly, I think we should seriously consider whether such
> > text has its place in that section.  That section is supposed to be a
> > cookbook for quickly and efficiently find Emacs features, so it should
> > be limited to methods and commands that accurate, in the sense that
> > they don't present the user with long lists of potential hits.  By
> > contrast, list-packages shows a very long list of packages (more than
> > 400 as of this writing), which can easily overwhelm the user.  Even
> > "C-h p" doesn't show such long lists (the longest has 50 items), and
> > it is already too long, which is why it's the last in the list of
> > recommended methods.
> 
> That's a problem, but there is IMO no way around that as long as Emacs
> doesn't bundle packages like php-mode, haskell-mode, eglot or
> lsp-mode, markdown-mode, etc.

I don't understand the relevance, please elaborate.

bug#50936: "(emacs) Help" does say how to find external packages

[Stefan Kangas]

Eli Zaretskii <eliz@gnu.org> writes:

> > That's a problem, but there is IMO no way around that as long as Emacs
> > doesn't bundle packages like php-mode, haskell-mode, eglot or
> > lsp-mode, markdown-mode, etc.
>
> I don't understand the relevance, please elaborate.

As a user, I come to "Help" to learn how to find more information on
e.g. "I want indentation for Haskell code", or "how to enable syntax
highlighting for Markdown".  The answer to many such questions is that
you need to look for and install an external package.

Users might also just want to explore existing features in Emacs.  For
that, 'finder' is useful.

bug#50936: "(emacs) Help" does say how to find external packages

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Date: Fri, 1 Oct 2021 16:42:13 +0200
> Cc: 50936@debbugs.gnu.org
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > > That's a problem, but there is IMO no way around that as long as Emacs
> > > doesn't bundle packages like php-mode, haskell-mode, eglot or
> > > lsp-mode, markdown-mode, etc.
> >
> > I don't understand the relevance, please elaborate.
> 
> As a user, I come to "Help" to learn how to find more information on
> e.g. "I want indentation for Haskell code", or "how to enable syntax
> highlighting for Markdown".  The answer to many such questions is that
> you need to look for and install an external package.

The manual explains what is available in Emacs.  If the user looks for
features not in Emacs, it is okay not to find them in our
documentation.  It is unrealistic for use to provide ways to find
features outside of Emacs, because they are too many.  What if the
user is after something that's not on ELPA?

When we figure out how to more closely integrate with ELPA, we should
as part of that try to find ways of searching the documentation of
those packages as part of our "normal" Help commands.  But until we
have done that, I see no reason to make that section in the manual
less efficient just so we could say we are more complete.  I think
doing so will result in net loss.

bug#50936: "(emacs) Help" does say how to find external packages

[Stefan Kangas]

Eli Zaretskii <eliz@gnu.org> writes:

> The manual explains what is available in Emacs.  If the user looks for
> features not in Emacs, it is okay not to find them in our
> documentation.  It is unrealistic for use to provide ways to find
> features outside of Emacs, because they are too many.

I'm not suggesting to list features, but to say that 'list-packages'
exist.  That command is a part of Emacs.

> When we figure out how to more closely integrate with ELPA, we should
> as part of that try to find ways of searching the documentation of
> those packages as part of our "normal" Help commands.  But until we
> have done that, I see no reason to make that section in the manual
> less efficient just so we could say we are more complete.  I think
> doing so will result in net loss.

I don't think mentioning 'list-packages' would make the manual less efficient.

bug#50936: "(emacs) Help" does say how to find external packages

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Date: Fri, 1 Oct 2021 19:28:30 +0200
> Cc: 50936@debbugs.gnu.org
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > The manual explains what is available in Emacs.  If the user looks for
> > features not in Emacs, it is okay not to find them in our
> > documentation.  It is unrealistic for use to provide ways to find
> > features outside of Emacs, because they are too many.
> 
> I'm not suggesting to list features, but to say that 'list-packages'
> exist.  That command is a part of Emacs.

Depends on what you say there, I guess.

bug#50936: "(emacs) Help" does say how to find external packages

[Lars Ingebrigtsen]

Eli Zaretskii <eliz@gnu.org> writes:

>> I'm not sure if the recommendation should be changed, or simply
>> amended to also mention M-x list-packages.
>
> It's okay to also mention list-packages, but if so, the text should
> explicitly say that it's for features and packages not included in
> the core distribution.

I've now done this in Emacs 29.