bug#54961: 28.1; info-display-manual completions issues

bug#54961: 28.1; info-display-manual completions issues

[Howard Melman]

I'm happy to see info-display-manual added to Emacs 28.1 but
the completions offered leave something to be desired.

First, they include manuals named "./" and "../" which
shouldn't be there.

Second I seem to see duplicates, if I complete with input
"emacs" I see candidates "emacs" and "emacs.info.gz" and
similar duplicates for emacs-mime and emacs-gnutls, so 3
candidates show as 6.  This may be an artifact of the
macport build I'm using.  It happens from emacs -q and I
can't easily test on vanilla gnu emacs.

Third it would be really nice if there were an
affixation-function that added the one line description of
the manual for a completions framework to show when
completions-detailed is t.  Perhaps it could get the info
from Info-dir-contents?

Howard

In GNU Emacs 28.1 (build 1, x86_64-apple-darwin20.6.0, Carbon Version 164 AppKit 2022.6)
of 2022-04-09 built on Mac-1649520554451.local
Repository revision: ee79b048bbb2fd4a962dfb2204cc7a2f0d5237d8
Repository branch: 28.1-mac-9.0-CI
Windowing system distributor 'Apple Inc.', version 11.6.5
System Description:  macOS 11.6.5

Configured using:
'configure --with-mac
--enable-locallisppath=/usr/local/share/emacs/site-lisp:/opt/homebrew/share/emacs/site-lisp
--enable-mac-app=/Users/runner/work/homebrew-emacsmacport/homebrew-emacsmacport/build-scripts/emacs-source/tmproot
--prefix=/Users/runner/work/homebrew-emacsmacport/homebrew-emacsmacport/build-scripts/emacs-source/tmproot
--enable-mac-self-contained --with-modules'

bug#54961: 28.1; info-display-manual completions issues

[Lars Ingebrigtsen]

Howard Melman <hmelman@gmail.com> writes:

> I'm happy to see info-display-manual added to Emacs 28.1

It was added to Emacs 24.1, apparently?

> but the completions offered leave something to be desired.

Yes, indeed.

> First, they include manuals named "./" and "../" which
> shouldn't be there.
>
> Second I seem to see duplicates, if I complete with input
> "emacs" I see candidates "emacs" and "emacs.info.gz" and
> similar duplicates for emacs-mime and emacs-gnutls, so 3
> candidates show as 6.  This may be an artifact of the
> macport build I'm using.  It happens from emacs -q and I
> can't easily test on vanilla gnu emacs.

It happens on Debian, too.  And it includes NEWS and README and other
non-manual things.

> Third it would be really nice if there were an
> affixation-function that added the one line description of
> the manual for a completions framework to show when
> completions-detailed is t.  Perhaps it could get the info
> from Info-dir-contents?

That would indeed be nice, but it would require opening and partially
parsing hundreds of info files, so it would be painfully slow, I think.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#54961: 28.1; info-display-manual completions issues

[Howard Melman]

Lars Ingebrigtsen <larsi@gnus.org> writes:

> Howard Melman <hmelman@gmail.com> writes:
>
>> I'm happy to see info-display-manual added to Emacs 28.1
>
> It was added to Emacs 24.1, apparently?

Ah, the 28.1 NEWS says: *** New keybinding 'C-h R' prompts
for an Info manual and displays it.  so it's just the
binding that's new, or maybe the completion?

>> Third it would be really nice if there were an
>> affixation-function that added the one line description of
>> the manual for a completions framework to show when
>> completions-detailed is t.  Perhaps it could get the info
>> from Info-dir-contents?
>
> That would indeed be nice, but it would require opening
> and partially parsing hundreds of info files, so it would
> be painfully slow, I think.

Agreed, though on my system it's more like tens of files so
might not be so bad.  Hence, my suggestion of using
Info-dir-contents if it was non-nil, though this wouldn't
work before there was an *info* buffer.

-- 

Howard

bug#54961: 28.1; info-display-manual completions issues

[Lars Ingebrigtsen]

Howard Melman <hmelman@gmail.com> writes:

> Ah, the 28.1 NEWS says: *** New keybinding 'C-h R' prompts
> for an Info manual and displays it.  so it's just the
> binding that's new, or maybe the completion?

Yes, I think so.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#54961: 28.1; info-display-manual completions issues

[Lars Ingebrigtsen]

Howard Melman <hmelman@gmail.com> writes:

> First, they include manuals named "./" and "../" which
> shouldn't be there.
>
> Second I seem to see duplicates, if I complete with input
> "emacs" I see candidates "emacs" and "emacs.info.gz" and
> similar duplicates for emacs-mime and emacs-gnutls, so 3
> candidates show as 6.  This may be an artifact of the
> macport build I'm using.  It happens from emacs -q and I
> can't easily test on vanilla gnu emacs.

I've now fixed this in Emacs 29.

> Third it would be really nice if there were an
> affixation-function that added the one line description of
> the manual for a completions framework to show when
> completions-detailed is t.  Perhaps it could get the info
> from Info-dir-contents?

But I'm not sure how to fix this in a scalable way.  Info-dir-contents
may not exist, and may include fewer info files than what we want to
have in this prompt, I think?  And as previously noted, I think it'd
just be too slow to look in every file (I've got 133 files now, down
from 300 before filtering duplicates)..

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#54961: 28.1; info-display-manual completions issues

[Howard Melman]

> On Apr 16, 2022, at 10:38 AM, Lars Ingebrigtsen <larsi@gnus.org> wrote:
> 
> Howard Melman <hmelman@gmail.com> writes:
> 
>> First, they include manuals named "./" and "../" which
>> shouldn't be there.
>> 
>> Second I seem to see duplicates, if I complete with input
>> "emacs" I see candidates "emacs" and "emacs.info.gz" and
>> similar duplicates for emacs-mime and emacs-gnutls, so 3
>> candidates show as 6.  This may be an artifact of the
>> macport build I'm using.  It happens from emacs -q and I
>> can't easily test on vanilla gnu emacs.
> 
> I've now fixed this in Emacs 29.

Thank you.  I hope it can make it into an Emacs 28.2.

>> Third it would be really nice if there were an
>> affixation-function that added the one line description of
>> the manual for a completions framework to show when
>> completions-detailed is t.  Perhaps it could get the info
>> from Info-dir-contents?
> 
> But I'm not sure how to fix this in a scalable way.  Info-dir-contents
> may not exist, and may include fewer info files than what we want to
> have in this prompt, I think?  And as previously noted, I think it'd
> just be too slow to look in every file (I've got 133 files now, down
> from 300 before filtering duplicates).

I agree it's problematic.  I believe q in Info defaults to burying the buffer
so I think after first use Info-dir-contents could stick around, which
while not ideal, would be good enough for me

I'm also frustrated that packages I install put their manuals at the top, 
above Emacs and Elisp which are my most referenced manuals.  
I thought there was a bug about this, but I couldn't find it.  There 
are several others about duplicates in the dir dealing with the 
complexities of finding multiple versions of a manual in the info paths.

I think ideally there would be a function that did the scanning to find the 
manuals that stored the information persistently in some data format
(perhaps your new sqlite work).  It could be updated at package install
time or manually (say C-x x g in top level info).  But otherwise
this would be available (with the annotations) for a completion table. On 
first use Info would turn this data into the dir contents and perhaps at that
time could run the update (which is basically what it does now).  That's
certainly a larger project.

Howard

bug#54961: 28.1; info-display-manual completions issues

[Lars Ingebrigtsen]

Howard Melman <hmelman@gmail.com> writes:

> Thank you.  I hope it can make it into an Emacs 28.2.

No, we're only backporting serious bug fixes and regression fixes to
Emacs 28.2.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#54961: 28.1; info-display-manual completions issues

[Juri Linkov]

> I'm also frustrated that packages I install put their manuals at the top,
> above Emacs and Elisp which are my most referenced manuals.
> I thought there was a bug about this, but I couldn't find it.  There
> are several others about duplicates in the dir dealing with the
> complexities of finding multiple versions of a manual in the info paths.

The problem is that authors of these packages are using

  @dircategory Emacs

instead of the correct

  @dircategory Emacs misc features

that would put their manuals below Emacs and Elisp.

bug#54961: 28.1; info-display-manual completions issues

[Howard Melman]

On Apr 18, 2022, at 3:02 PM, Juri Linkov <juri@linkov.net> wrote:
> 
> The problem is that authors of these packages are using
> 
>  @dircategory Emacs
> 
> instead of the correct
> 
>  @dircategory Emacs misc features
> 
> that would put their manuals below Emacs and Elisp.

Thanks, I'll file some bugs. :)

Howard

bug#54961: 28.1; info-display-manual completions issues

[Howard Melman]

[-- Attachment #1: Type: text/plain, Size: 713 bytes --]

On Apr 18, 2022, at 3:02 PM, Juri Linkov <juri@linkov.net> wrote:
> 
> The problem is that authors of these packages are using
> 
>  @dircategory Emacs
> 
> instead of the correct
> 
>  @dircategory Emacs misc features
> 
> that would put their manuals below Emacs and Elisp.

Am I supposed to see these section headings in the Info dir?

I see various section headings for other manuals installed in
/usr/local/share/info but not for the ones in the Emacs provided
dir file.  This is vanilla Emacs 28 -Q on a mac.  The top is the Info
dir right after starting Emacs and the bottom is the contents of
/Applications/GnuEmacs.app/Contents/Resources/info/dir.

I can open another bug if this gets involved.

Howard


[-- Attachment #2.1: Type: text/html, Size: 1516 bytes --]

[-- Attachment #2.2: Screen Shot 2022-04-18 at 5.21.53 PM.png --]
[-- Type: image/png, Size: 331334 bytes --]

bug#54961: 28.1; info-display-manual completions issues

[Eli Zaretskii]

> From: Howard Melman <hmelman@gmail.com>
> Date: Mon, 18 Apr 2022 17:28:49 -0400
> Cc: Lars Ingebrigtsen <larsi@gnus.org>, 54961@debbugs.gnu.org
> 
> On Apr 18, 2022, at 3:02 PM, Juri Linkov <juri@linkov.net> wrote:
> > 
> > The problem is that authors of these packages are using
> > 
> >  @dircategory Emacs
> > 
> > instead of the correct
> > 
> >  @dircategory Emacs misc features
> > 
> > that would put their manuals below Emacs and Elisp.
> 
> Am I supposed to see these section headings in the Info dir?

Depends on how are the Info files installed.  If they are installed by
running the install-info command, then yes, these sections should be
in DIR.

> I see various section headings for other manuals installed in
> /usr/local/share/info but not for the ones in the Emacs provided
> dir file.

I don't understand: the DIR file that comes with Emacs already has
sections in it.

> This is vanilla Emacs 28 -Q on a mac.  The top is the Info
> dir right after starting Emacs and the bottom is the contents of
> /Applications/GnuEmacs.app/Contents/Resources/info/dir.

Seems like you have more than one DIR file (which is completely
normal).

> I can open another bug if this gets involved.

I don't see any bug here yet.

bug#54961: 28.1; info-display-manual completions issues

[Howard Melman]

(sorry for the extra email Eli)

On Apr 19, 2022, at 1:35 AM, Eli Zaretskii <eliz@gnu.org> wrote:
> 
>> Am I supposed to see these section headings in the Info dir?
> 
>> I see various section headings for other manuals installed in
>> /usr/local/share/info but not for the ones in the Emacs provided
>> dir file.
> 
> I don't understand: the DIR file that comes with Emacs already has
> sections in it.
> 
>> This is vanilla Emacs 28 -Q on a mac.  The top is the Info
>> dir right after starting Emacs and the bottom is the contents of
>> /Applications/GnuEmacs.app/Contents/Resources/info/dir.
> 
> Seems like you have more than one DIR file (which is completely
> normal).

on emacs -Q (on mac)

Info-default-directory-list
("/Applications/GnuEmacs.app/Contents/Resources/info/" "/usr/local/share/info/" "/usr/share/info/")

after running C-h i, Info-directory-list is the same
("/Applications/GnuEmacs.app/Contents/Resources/info/" "/usr/local/share/info/" "/usr/share/info/")

There's a dir in each of those.  The dir in the GnuEmacs.app has sections
like "Emacs editing modes" and "Emacs misc features" (shown in the bottom
of the screenshot).   /usr/local/share/info/dir has sections like "Programming
& development tools" and "Individual utilities".  When I run C-h i the directory
that's displayed doesn't have sections from the former (as shown in the top
of the screenshot) and has different ones for the latter (there's "Software development"
and "Individual utilities").

When I run info, I don't see sections from the emacs supplied dir like "Emacs
editing modes".  Shouldn't I?  Is that a bug?


I have installed various emacs packages via package-install.  They don't all have
info manuals, but all the ones that do appear above Emacs in top level Info.  
Yesterday I reported bugs for several and several changed to use 
"@dircategory Emacs misc features".  I updated them via list-packages and
see in their info files stuff like:

   INFO-DIR-SECTION Emacs misc features
   START-INFO-DIR-ENTRY
   * Embark: (embark).     Emacs Mini-Buffer Actions Rooted in Keymaps.
   END-INFO-DIR-ENTRY

But when I restart emacs and run C-h i I still see them listed above emacs
and no sections.

Howard

bug#54961: 28.1; info-display-manual completions issues

[Eli Zaretskii]

> From: Howard Melman <hmelman@gmail.com>
> Date: Tue, 19 Apr 2022 09:27:11 -0400
> Cc: Juri Linkov <juri@linkov.net>,
>  Lars Ingebrigtsen <larsi@gnus.org>,
>  54961@debbugs.gnu.org
> 
> >> I see various section headings for other manuals installed in
> >> /usr/local/share/info but not for the ones in the Emacs provided
> >> dir file.
> > 
> > I don't understand: the DIR file that comes with Emacs already has
> > sections in it.
> > 
> >> This is vanilla Emacs 28 -Q on a mac.  The top is the Info
> >> dir right after starting Emacs and the bottom is the contents of
> >> /Applications/GnuEmacs.app/Contents/Resources/info/dir.
> > 
> > Seems like you have more than one DIR file (which is completely
> > normal).
> 
> on emacs -Q (on mac)
> 
> Info-default-directory-list
> ("/Applications/GnuEmacs.app/Contents/Resources/info/" "/usr/local/share/info/" "/usr/share/info/")
> 
> after running C-h i, Info-directory-list is the same
> ("/Applications/GnuEmacs.app/Contents/Resources/info/" "/usr/local/share/info/" "/usr/share/info/")
> 
> There's a dir in each of those.  The dir in the GnuEmacs.app has sections
> like "Emacs editing modes" and "Emacs misc features" (shown in the bottom
> of the screenshot).   /usr/local/share/info/dir has sections like "Programming
> & development tools" and "Individual utilities".  When I run C-h i the directory
> that's displayed doesn't have sections from the former (as shown in the top
> of the screenshot) and has different ones for the latter (there's "Software development"
> and "Individual utilities").
> 
> When I run info, I don't see sections from the emacs supplied dir like "Emacs
> editing modes".  Shouldn't I?  Is that a bug?

I'm afraid I don't know, because it sounds like there's some macOS
specific behavior here.  The doc string of Info-directory-list says:

  When `Info-directory-list' is initialized from the value of
  `Info-default-directory-list', and Emacs is installed in one of the
  standard directories, the directory of Info files that come with Emacs
  is put last (so that local Info files override standard ones).

  When `Info-directory-list' is initialized from the value of
  `Info-default-directory-list', and Emacs is not installed in one
  of the standard directories, the first element of the resulting
  list is the directory where Emacs installs the Info files that
  come with it.  This is so that Emacs's own manual, which suits the
  version of Emacs you are using, will always be found first.  This
  is useful when you install an experimental version of Emacs without
  removing the standard installation.

But then info-initialize, which is supposed to implement the above,
deviates from that behavior on macOS, with this commentary:

      ;; For a self-contained (ie relocatable) NS build, AFAICS we
      ;; always want the included info directory to be at the head of
      ;; the search path, unless it's already in INFOPATH somewhere.
      ;; It's at the head of Info-default-directory-list,
      ;; but there's no way to get it at the head of Info-directory-list
      ;; except by doing it here.

I cannot say I understand this reasoning, and neither do I understand
whether this explains what you see in your case (because I don't know
what is meant by "self-contained i.e. relocatable NS build".

Maybe Alan (CC'ed) can help us out here.

The order of the directories in Info-directory-list then determines
the order of looking for DIR files in those directories, and
eventually the order you see them in the DIR node produced by "C-h i"
by concatenating all those DIR files, see Info-insert-dir.  Maybe you
should step in Edebug through that function to see what happens there
and why.

> I have installed various emacs packages via package-install.  They don't all have
> info manuals, but all the ones that do appear above Emacs in top level Info.  
> Yesterday I reported bugs for several and several changed to use 
> "@dircategory Emacs misc features".  I updated them via list-packages and
> see in their info files stuff like:
> 
>    INFO-DIR-SECTION Emacs misc features
>    START-INFO-DIR-ENTRY
>    * Embark: (embark).     Emacs Mini-Buffer Actions Rooted in Keymaps.
>    END-INFO-DIR-ENTRY
> 
> But when I restart emacs and run C-h i I still see them listed above emacs
> and no sections.

I will ask again: are those manuals installed using the install-info
command?  That is the command responsible for adding manuals to the
DIR menus while paying attention to their sections.

bug#54961: 28.1; info-display-manual completions issues

[Howard Melman]

On Apr 19, 2022, at 12:55 PM, Eli Zaretskii <eliz@gnu.org> wrote:
> 
>> I have installed various emacs packages via package-install.  

>>   INFO-DIR-SECTION Emacs misc features
>>   START-INFO-DIR-ENTRY
>>   * Embark: (embark).     Emacs Mini-Buffer Actions Rooted in Keymaps.
>>   END-INFO-DIR-ENTRY
> 
> I will ask again: are those manuals installed using the install-info
> command?  That is the command responsible for adding manuals to the
> DIR menus while paying attention to their sections.

I thought I answered by saying I used package-install.  I don't know what
it does (it doesn't seem to call install-info) but the above snippet is from
~/.emacs.d/elpa/embark-20220418.2042/embark.info

and that directory is prepended onto Info-directory-list and contains
a dir file that says:

Emacs misc features
* Embark: (embark).             Emacs Mini-Buffer Actions Rooted in Keymaps.

My Info-directory-list looks like this, with another dozen elpa dirs before
the Emacs.app one (which is the "self-contained i.e. relocatable NS build").

("/Users/hmelman/.emacs.d/elpa/embark-20220418.2042"
"/Applications/GnuEmacs.app/Contents/Resources/info/"
"/usr/local/share/info/"
"/usr/share/info/")

I guess info-insert-dir is supposed to collect these and it seems there's an
issue with it using the sections?  I still don't know if that's mac-specific
or not.

I had asked if it's a bug that I don't see sections like "Emacs misc features"
and you didn't answer.  I guess it is?  Do you (or anyone) see them on a 
non-mac system?

Howard

bug#54961: 28.1; info-display-manual completions issues

[Eli Zaretskii]

> From: Howard Melman <hmelman@gmail.com>
> Date: Tue, 19 Apr 2022 14:43:06 -0400
> Cc: Alan Third <alan@idiocy.org>,
>  Juri Linkov <juri@linkov.net>,
>  Lars Ingebrigtsen <larsi@gnus.org>,
>  54961@debbugs.gnu.org
> 
> On Apr 19, 2022, at 12:55 PM, Eli Zaretskii <eliz@gnu.org> wrote:
> > 
> >> I have installed various emacs packages via package-install.  
> 
> >>   INFO-DIR-SECTION Emacs misc features
> >>   START-INFO-DIR-ENTRY
> >>   * Embark: (embark).     Emacs Mini-Buffer Actions Rooted in Keymaps.
> >>   END-INFO-DIR-ENTRY
> > 
> > I will ask again: are those manuals installed using the install-info
> > command?  That is the command responsible for adding manuals to the
> > DIR menus while paying attention to their sections.
> 
> I thought I answered by saying I used package-install.  I don't know what
> it does (it doesn't seem to call install-info) but the above snippet is from
> ~/.emacs.d/elpa/embark-20220418.2042/embark.info
> 
> and that directory is prepended onto Info-directory-list and contains
> a dir file that says:
> 
> Emacs misc features
> * Embark: (embark).             Emacs Mini-Buffer Actions Rooted in Keymaps.
> 
> My Info-directory-list looks like this, with another dozen elpa dirs before
> the Emacs.app one (which is the "self-contained i.e. relocatable NS build").
> 
> ("/Users/hmelman/.emacs.d/elpa/embark-20220418.2042"
> "/Applications/GnuEmacs.app/Contents/Resources/info/"
> "/usr/local/share/info/"
> "/usr/share/info/")
> 
> I guess info-insert-dir is supposed to collect these and it seems there's an
> issue with it using the sections?  I still don't know if that's mac-specific
> or not.

If this is how package installation works, then it's either a bug in
package installation, or a missing feature in info.el.  info.el
doesn't pay any attention to the sections, it just concatenates all
the DIR files into a single DIR node.  The assumption is that Info
files are installed using install-info, and that all the manuals that
belong to some section are already arranged under that section in a
single DIR file.

If we want to support individual DIR files for each package, which
would mean having the same section mentioned on multiple DIR files, I
guess Info-insert-dir should be taught to rearrange the menu items
such as that all the items from the same section wound up together.
(This might make Info startup slower, though.)

> I had asked if it's a bug that I don't see sections like "Emacs misc features"
> and you didn't answer.  I guess it is?  Do you (or anyone) see them on a 
> non-mac system?

Someone else who installs packages via package.el will have to answer
that, because I always install any packages manually by running
install-info, and thus have all of their menu items neatly arranged in
a single system-wide DIR file.  Thus, I never have these problems.

I've CC'ed Stefan who might know more about this.

bug#54961: 28.1; info-display-manual completions issues

[Howard Melman]

> On Apr 19, 2022, at 2:43 PM, Howard Melman <hmelman@gmail.com> wrote:
> 
> I had asked if it's a bug that I don't see sections like "Emacs misc features"
> and you didn't answer.  I guess it is?  Do you (or anyone) see them on a 
> non-mac system?

Now I see  Info-dir-remove-duplicates and Info-streamline-headings so 
I see that no, no one should.  I'm still not sure about the ordering issue
that Juri first mentioned.  Why the package installed ones are before
the info files that come with Emacs and should they be, even if their
heading is "Emacs misc features" as Juri suggested.

Howard

bug#54961: 28.1; info-display-manual completions issues

[Eli Zaretskii]

> From: Howard Melman <hmelman@gmail.com>
> Date: Tue, 19 Apr 2022 15:07:51 -0400
> Cc: Alan Third <alan@idiocy.org>,
>  Juri Linkov <juri@linkov.net>,
>  Lars Ingebrigtsen <larsi@gnus.org>,
>  54961@debbugs.gnu.org
> 
> Now I see  Info-dir-remove-duplicates and Info-streamline-headings so 
> I see that no, no one should.  I'm still not sure about the ordering issue
> that Juri first mentioned.  Why the package installed ones are before
> the info files that come with Emacs and should they be, even if their
> heading is "Emacs misc features" as Juri suggested.

I think they should be first so that people could install packages
that are newer than the same packages which come with Emacs.

bug#54961: 28.1; info-display-manual completions issues

[Juri Linkov]

>> I had asked if it's a bug that I don't see sections like "Emacs misc features"
>> and you didn't answer.  I guess it is?  Do you (or anyone) see them on a 
>> non-mac system?

I don't see these sections on GNU/Linux, but it seems this is by design.

> Now I see  Info-dir-remove-duplicates and Info-streamline-headings so 
> I see that no, no one should.  I'm still not sure about the ordering issue
> that Juri first mentioned.  Why the package installed ones are before
> the info files that come with Emacs and should they be, even if their
> heading is "Emacs misc features" as Juri suggested.

Good question, maybe this needs to be fixed in the Emacs Info reader.

bug#54961: 28.1; info-display-manual completions issues

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

Eli Zaretskii [2022-04-19 21:55:34] wrote:
> If we want to support individual DIR files for each package, which
> would mean having the same section mentioned on multiple DIR files, I
> guess Info-insert-dir should be taught to rearrange the menu items
> such as that all the items from the same section wound up together.
> (This might make Info startup slower, though.)

Isn't that what `Info-insert-dir` does at the end after the

      ;; Now take each node of each of the other buffers
      ;; and merge it into the main buffer.

?


        Stefan

bug#54961: 28.1; info-display-manual completions issues

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Cc: Howard Melman <hmelman@gmail.com>,  alan@idiocy.org,  juri@linkov.net,
>   larsi@gnus.org,  54961@debbugs.gnu.org
> Date: Tue, 19 Apr 2022 15:28:37 -0400
> 
> Eli Zaretskii [2022-04-19 21:55:34] wrote:
> > If we want to support individual DIR files for each package, which
> > would mean having the same section mentioned on multiple DIR files, I
> > guess Info-insert-dir should be taught to rearrange the menu items
> > such as that all the items from the same section wound up together.
> > (This might make Info startup slower, though.)
> 
> Isn't that what `Info-insert-dir` does at the end after the
> 
>       ;; Now take each node of each of the other buffers
>       ;; and merge it into the main buffer.
> 
> ?

Yes, in a function deceptively named Info-dir-remove-duplicates.

bug#54961: 28.1; info-display-manual completions issues

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

> Yes, in a function deceptively named Info-dir-remove-duplicates.

IIRC I'm the one to blame for that code, and my memory is fuzzy but
I seem to remember that the case I wanted to fix was one where there
were indeed several entries by the same name, which might explain why
I ended up naming it that way, although in retrospect it probably wasn't
the best choice ;-)


        Stefan

bug#54961: 28.1; info-display-manual completions issues

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Cc: hmelman@gmail.com,  alan@idiocy.org,  juri@linkov.net,  larsi@gnus.org,
>   54961@debbugs.gnu.org
> Date: Wed, 20 Apr 2022 08:00:02 -0400
> 
> > Yes, in a function deceptively named Info-dir-remove-duplicates.
> 
> IIRC I'm the one to blame for that code, and my memory is fuzzy but
> I seem to remember that the case I wanted to fix was one where there
> were indeed several entries by the same name, which might explain why
> I ended up naming it that way, although in retrospect it probably wasn't
> the best choice ;-)

That function does remove duplicates.  The problem is that it also
rearranges entries of the same section to bring them together, and
that part is not reflected in its name at all.  And since the function
doesn't have a doc string, it's impossible to guess that it does this
second part, except by reading the code.

bug#54961: 28.1; info-display-manual completions issues

[Alan Third]

On Tue, Apr 19, 2022 at 07:55:30PM +0300, Eli Zaretskii wrote:
> > on emacs -Q (on mac)
> > 
> > Info-default-directory-list
> > ("/Applications/GnuEmacs.app/Contents/Resources/info/" "/usr/local/share/info/" "/usr/share/info/")
> > 
> > after running C-h i, Info-directory-list is the same
> > ("/Applications/GnuEmacs.app/Contents/Resources/info/" "/usr/local/share/info/" "/usr/share/info/")
<snip>
> But then info-initialize, which is supposed to implement the above,
> deviates from that behavior on macOS, with this commentary:
> 
>       ;; For a self-contained (ie relocatable) NS build, AFAICS we
>       ;; always want the included info directory to be at the head of
>       ;; the search path, unless it's already in INFOPATH somewhere.
>       ;; It's at the head of Info-default-directory-list,
>       ;; but there's no way to get it at the head of Info-directory-list
>       ;; except by doing it here.
> 
> I cannot say I understand this reasoning, and neither do I understand
> whether this explains what you see in your case (because I don't know
> what is meant by "self-contained i.e. relocatable NS build".

I'm not sure what the reasoning is either.

The self-contained build is where all Emacs's files are installed in a
special directory, in this case "/Applications/GnuEmacs.app" which can
be placed anywhere on the filesystem and run from the GUI.

My uneducated guess is that it's possible to have a "UNIX" style
install already on a machine, which might be in /usr and then want to
run the self-contained version and not pick up the files in /usr
before the self-contained version's files.

I've no idea if that's plausible.

It looks like Glen's included a couple of links about why this was
done in change eb7afdaddc286b57253cf0cd643b2ea594fb130c.
-- 
Alan Third

bug#54961: 28.1; info-display-manual completions issues

[Howard Melman]

On Apr 20, 2022, at 1:01 PM, Alan Third <alan@idiocy.org> wrote:
> 
> My uneducated guess is that it's possible to have a "UNIX" style
> install already on a machine, which might be in /usr and then want to
> run the self-contained version and not pick up the files in /usr
> before the self-contained version's files.
> 
> I've no idea if that's plausible.

Yes this sounds plausible.  MacOS comes with a /usr/share/info/ with
some manuals for the very old versions of somethings it ships with.
homebrew, a popular package manager for mac installs manuals in
/usr/local/share/info/.  

As you said, apps on a mac are installed in a special directory type,
ending in .app and that the window manager knows how to use. Double
clicking on Emacs.app runs the program inside it and it can be dragged
to the trash to delete.  In the Emacs.app is an info/ directory with the
manuals emacs ships with.  

It definitely makes sense that I'd want these three directories ordered as:

("/Applications/GnuEmacs.app/Contents/Resources/info/"
 "/usr/local/share/info/"
 "/usr/share/info/")

IIRC on other systems when building emacs it would install the emacs manuals
in a standard place.  In the NS build it would put it in the .app and of 
course something would need to tell the emacs info reader where that place is.  It 
sounds like older code modified INFOPATH via another NS trick and that
confused users and instead this code just modifies Info-directory-list
directly, which makes more sense.  I'm not sure a standalone info
reader would find it but if that was wanted a user could set INFOPATH
themselves to include the Emacs.app path.

I'm not sure how this interacts with package info files installed in
 ~/.emacs.d/elpa/.  You'd want those directories ahead of the Emacs.app
one and that is what I see happening.  So I think all this is fine.

I think my problem with headings disappearing is entirely the effect
of Info-streamline-headings and it's default value that merges all
headings with Emacs in them to one Emacs heading.  That isn't what
I want, I'm not sure if that's what's wanted by default since the dir
that ships with Emacs has more useful and specific headings, though I think
they could be improved.  I haven't looked if this streamlining preserves
ordering, but the order of manuals listed in the constructed dir need
not be the same as the order of Info-directory-list where they will
be searched for.  The first is just presentation and is what I was commenting
about.

Howard