Subject: 29.0.60; apropos-documentation does not work for preloaded symbols

From: Eli Zaretskii <[email-masked]>
Date: Sat, 07 Jan 2023 15:20:07 +0200

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 <[email-masked]>
    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))