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

[Eli Zaretskii <eliz@gnu.org>]

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