Subject: Re: bug#60587: Patch for adding links to symbols' help documentation

From: "H. Dieter Wilhelm" <[email-masked]>
Date: Mon, 09 Jan 2023 21:01:08 +0100

Eli Zaretskii <[email-masked]> writes:
>> >> +(info-initialize)
>> >
>> > Why do you need to call this? and why on top level?
>> 
>> Because I have no better idea to build info-emacs-info-dir-content
>> (maybe dynamically?).  With the code below I force the initialisation of
>> Info-directory-list. It is used for checking if the current info
>> document is relevant to Emacs.
>
> Info-directory-list starts as nil, so you can test its value.
> More generally, this feature displays links in an Info buffer, right?
> If an Info buffer is displayed in Emacs, info-initialize was already
> called, and you don't need to call it again.

That is true. It was not much work to avoid it. :-)

>> >> +;; Turn into regexp list necessary? Stefan
>> >> +;; Switch to alist with explanation of file name?
>> >> +(defcustom info-xref-none-emacs-or-elisp-documents
>> >> +  '("aarm2012" ; Stefan: Ada manual, Elpa archive
>> >> +    "arm2012"  ; Stefan: Ada manual
>> >> +    "sicp"   ; T.V: Structure and Interpretation of Computer Programs,
>> >> +                                        ; Melpa archive
>> >> +    )
>> >> +  "List of all none GNU-Emacs or Elisp documentation.
>> >> +Or other documents not to be checked for linking to their help
>> >> +documentation.  The list must contains only the base name of the
>> >> +files (without their file name extension \".info\")."
>> >> +  :type '(repeat string)
>> >> +  :group 'info-xref)
>> >
>> > Not sure what is this about, and what do the names above signify.
>> 
>> This was a discussion on gmane.emacs.devel (please see
>> [email-masked]) on how to avoid trying to link
>> info documents which don't belong to Emacs. (Core-Utils, Ada
>> documentation from Melpa, etc.)
>
> I cannot access that discussion with this URL (can you tell on which
> date that happened? then I will look in the emacs-devel list
> archives)

Please have a look here:
https://lists.gnu.org/archive/html/emacs-devel/2020-05/msg00994.html
(Above is the message-id from 2020-05-08)

> , and I don't think I understand how such names will creep
> into this feature.  Does the code somehow search every Info manual on
> the system to do its job?

It's not searching, just checking whether Info-current-file has an
extension of .info(.gz) (this is redundant on my system but I forgot to
document in what circumstances this check might be necessary) and is
included in any of the Info-directory-list directories.

Since Info-directory-list may contain info files which are not related
to Emacs, it checks against the "blacklist"
info-none-emacs-or-elisp-documents.  E.g. from Elpa there are packages,
like sicp (Structure and Interpretation of Computer Programs) in info
format.

(defun info-check-docu-p ()
  "Check if the current info file is relevant to Emacs.
That means `Info-current-file' is either found in Emacs' info/
directory or in `package-user-dir' and is not included in the
`info-none-emacs-or-elisp-documents' list."
  (unless info-emacs-info-dir-content
    (info-compile-emacs-info-dir-content))
  (let* ((ifile Info-current-file)
         (ifi (when ifile
                (file-name-sans-extension
                 (file-name-nondirectory ifile))))
         (pdir (when (boundp 'package-user-dir)
                 (expand-file-name
                  package-user-dir)))
         ;; FIXME: Check if pdir is redundant because Package adds
         ;; info package folders to Info-directory-list anyway
         (ifiles info-emacs-info-dir-content)
         (ndocu info-none-emacs-or-elisp-documents))
    (and ifile
         (or (assoc-string (concat ifi ".info") ifiles)
             ;; info files might be archived!
             (assoc-string (concat ifi ".info.gz") ifiles)
             (when pdir (string-match pdir ifile)))
         (not (assoc-string ifi ndocu)))))

-- 
Best wishes)
H. Dieter Wilhelm
Zwingenberg, Germany