bug#60628: 29.0.60; apropos-documentation does not work for preloaded symbols

[Eli Zaretskii]

Ping!

> Date: Sat, 07 Jan 2023 15:20:07 +0200
> From: Eli Zaretskii <eliz@gnu.org>
> 
> To reproduce:
> 
>   emacs -Q
>   C-h d list.*directory RET
> 
> Note that the resulting *Apropos* buffer only lists built-in functions
> and variables, i.e. those defined in C.  In particular, missing are
> functions/variables from files.el, such as find-directory-functions,
> parse-colon-path, and directory-files-recursively, whose doc strings
> all match the regexp.
> 
> This seems to be due to
> 
>     commit 59732a83c8875c8986d2221600d559a24d8309cc
>     Author: Stefan Monnier <monnier@iro.umontreal.ca>
>     Date:   Thu Dec 30 23:17:45 2021 -0500
> 
>         Don't store docstrings of preloaded .el files in etc/DOC
> 
> The doc string of apropos-documentation does say:
> 
>   Note that by default this command only searches in the file specified by
>   ‘internal-doc-file-name’; i.e., the etc/DOC file.  With C-u prefix,
>   or if ‘apropos-do-all’ is non-nil, it searches all currently defined
>   documentation strings.
> 
> However, since we no longer write the doc strings of preloaded Lisp
> files to DOC, that default no longer makes sense: Emacs should not
> distinguish between built-in primitives and preloaded stuff, and it
> didn't up to and including Emacs 28.
> 
> Moreover, "C-u C-h d" also doesn't work for preloaded functions,
> because:
> 
>   (apropos-documentation-internal 'directory-files-recursively)
>     => nil
> 
> This happens because:
> 
>   (apropos-safe-documentation 'directory-files-recursively)
>     => ("files.elc" . 39940)
> 
> and in that case apropos-documentation-internal calls
> apropos-documentation-check-elc-file, which does something very
> strange: it only looks inside strings that begin with "\n#@", and
> otherwise simply ignores everything else.  Is this also a remnant from
> back when preloaded files had their doc strings in etc/DOC?  Or else
> why does it only look for "#@" comments preceded by a newline?
> 
> Basically, apropos-documentation is currently completely broken on the
> release branch.  The following simple change seems to at least repair
> "C-u C-h d", but I don't think it's sufficient, as we need to
> resurrect the ability to find preloaded symbols without C-u.
> 
> diff --git a/lisp/apropos.el b/lisp/apropos.el
> index b260d88..cff6f1c 100644
> --- a/lisp/apropos.el
> +++ b/lisp/apropos.el
> @@ -1064,7 +1064,9 @@ apropos-documentation-check-elc-file
>        (setq apropos-files-scanned (cons file apropos-files-scanned))
>        (erase-buffer)
>        (insert-file-contents file)
> -      (while (search-forward "\n#@" nil t)
> +      (while (search-forward "#@" nil t)
> +        (or (not (looking-at-p "[0-9]+"))
> +            (progn
>       ;; Read the comment length, and advance over it.
>       (setq end (read)
>             beg (1+ (point))
> @@ -1110,7 +1112,7 @@ apropos-documentation-check-elc-file
>                                              'face apropos-match-face doc)))
>                     (setcar (nthcdr (if this-is-a-variable 3 2)
>                                     apropos-item)
> -                           doc))))))))))
> +                           doc))))))))))))
>  
> 
> Ideas? patches? comments?
> 
> 
> 
> In GNU Emacs 29.0.60 (build 197, i686-pc-mingw32) of 2023-01-07 built on
>  HOME-C4E4A596F7
> Repository revision: 9d410f8de64e91d16999a9bb5dd884d6d06d22bd
> Repository branch: emacs-29
> Windowing system distributor 'Microsoft Corp.', version 5.1.2600
> System Description: Microsoft Windows XP Service Pack 3 (v5.1.0.2600)
> 
> Configured using:
>  'configure -C --prefix=/d/usr --with-wide-int
>  --enable-checking=yes,glyphs 'CFLAGS=-O0 -gdwarf-4 -g3''
> 
> Configured features:
> ACL GIF GMP GNUTLS HARFBUZZ JPEG JSON LCMS2 LIBXML2 MODULES NOTIFY
> W32NOTIFY PDUMPER PNG RSVG SOUND SQLITE3 THREADS TIFF
> TOOLKIT_SCROLL_BARS TREE_SITTER WEBP XPM ZLIB
> 
> Important settings:
>   value of $LANG: ENU
>   locale-coding-system: cp1255
> 
> Major mode: Lisp Interaction
> 
> Minor modes in effect:
>   tooltip-mode: t
>   global-eldoc-mode: t
>   eldoc-mode: t
>   show-paren-mode: t
>   electric-indent-mode: t
>   mouse-wheel-mode: t
>   tool-bar-mode: t
>   menu-bar-mode: t
>   file-name-shadow-mode: t
>   global-font-lock-mode: t
>   font-lock-mode: t
>   blink-cursor-mode: t
>   line-number-mode: t
>   indent-tabs-mode: t
>   transient-mark-mode: t
>   auto-composition-mode: t
>   auto-encryption-mode: t
>   auto-compression-mode: t
> 
> Load-path shadows:
> None found.
> 
> Features:
> (shadow sort mail-extr dabbrev emacsbug message mailcap yank-media puny
> dired dired-loaddefs rfc822 mml mml-sec password-cache epa derived epg
> rfc6068 epg-config gnus-util text-property-search time-date subr-x
> mm-decode mm-bodies mm-encode mail-parse rfc2231 mailabbrev gmm-utils
> mailheader sendmail rfc2047 rfc2045 ietf-drums mm-util mail-prsvr
> mail-utils cl-extra pp cl-print byte-opt gv bytecomp byte-compile
> help-fns radix-tree mule-util help-mode cl-loaddefs cl-lib apropos rmc
> iso-transl tooltip cconv eldoc paren electric uniquify ediff-hook
> vc-hooks lisp-float-type elisp-mode mwheel dos-w32 ls-lisp disp-table
> term/w32-win w32-win w32-vars term/common-win tool-bar dnd fontset image
> regexp-opt fringe tabulated-list replace newcomment text-mode lisp-mode
> prog-mode register page tab-bar menu-bar rfn-eshadow isearch easymenu
> timer select scroll-bar mouse jit-lock font-lock syntax font-core
> term/tty-colors frame minibuffer nadvice seq simple cl-generic
> indonesian philippine cham georgian utf-8-lang misc-lang vietnamese
> tibetan thai tai-viet lao korean japanese eucjp-ms cp51932 hebrew greek
> romanian slovak czech european ethiopic indian cyrillic chinese
> composite emoji-zwj charscript charprop case-table epa-hook
> jka-cmpr-hook help abbrev obarray oclosure cl-preloaded button loaddefs
> theme-loaddefs faces cus-face macroexp files window text-properties
> overlay sha1 md5 base64 format env code-pages mule custom widget keymap
> hashtable-print-readable backquote threads w32notify w32 lcms2 multi-tty
> make-network-process emacs)
> 
> Memory information:
> ((conses 16 54328 11479)
>  (symbols 48 7273 0)
>  (strings 16 20447 2422)
>  (string-bytes 1 523245)
>  (vectors 16 11853)
>  (vector-slots 8 170903 17702)
>  (floats 8 34 42)
>  (intervals 40 449 141)
>  (buffers 888 13))
> 
> 
> 
>