(help-fns--first-release): Try and avoid false positives

We used to use a very "optimistic" regexp which worked well for
longish symbol names but suffered from too many false positives on
short names.  Use a more restrictive regexp, which should make the
recent "weed out" change unnecessary.

This in turn requires the use of '...' more consistently in etc/NEWS* files.

* lisp/help-fns.el (help-fns--first-release-regexp): New function.
(help-fns--first-release): Use it.  Fix minor issue with the Emacs
version regexp.
(help-fns--mention-first-release): Undo last change.

* etc/NEWS*: Replace `...' with '...'.  Indent code examples by at
least 2 spaces. Add previously missing '...' quotes around many of
the variables and functions described.

etc/NEWS

@@ -1105,9 +1105,9 @@ in Dired mode by default.  The user options 'dired-bind-man' and
 To get the old behavior back and unbind these keys in Dired mode, add
 the following to your Init file:
 
-(with-eval-after-load 'dired
-  (keymap-set dired-mode-map "N" nil)
-  (keymap-set dired-mode-map "I" nil))
+    (with-eval-after-load 'dired
+      (keymap-set dired-mode-map "N" nil)
+      (keymap-set dired-mode-map "I" nil))
 
 ---
 *** New command 'dired-do-eww'.

etc/NEWS.25

@@ -550,8 +550,8 @@ When you invoke 'shell' interactively, the '*shell*' buffer will now
 display in a new window.  However, you can customize this behavior via
 the 'display-buffer-alist' variable.  For example, to get
 the old behavior -- '*shell*' buffer displays in current window -- use
-(add-to-list 'display-buffer-alist
-     '("^\\*shell\\*$" . (display-buffer-same-window))).
+    (add-to-list 'display-buffer-alist
+         '("\\`\\*shell\\*\\'" . (display-buffer-same-window))).
 
 ** EIEIO
 *** The ':protection' slot option is not obeyed any more.
@@ -1264,7 +1264,7 @@ SWITCH-BUFFER to 'completion-table-dynamic'.
 
 ** window-configurations no longer record the buffers' marks.
 
-** 'inhibit-modification-hooks' now also inhibits lock-file checks, as
+** 'inhibit-modification-hooks' now also inhibits 'lock-file' checks, as
 well as active region handling.
 
 ** 'deactivate-mark' is now buffer-local.

etc/NEWS.26

@@ -736,7 +736,7 @@ keep previous behavior.
 
 ** html2text is now marked obsolete.
 
-** smerge-refine-regions can refine regions in separate buffers.
+** 'smerge-refine-regions' can refine regions in separate buffers.
 
 ** Info menu and index completion uses substring completion by default.
 This can be customized via the 'info-menu' category in
@@ -1506,7 +1506,7 @@ supported by the GnuTLS library used by Emacs.
 
 ** Emacs now supports records for user-defined types, via the new
 functions 'make-record', 'record', and 'recordp'.  Records are now
-used internally to represent cl-defstruct and defclass instances, for
+used internally to represent 'cl-defstruct' and 'defclass' instances, for
 example.
 
 If your program defines new record types, you should use
@@ -1798,11 +1798,11 @@ suitable for use in 'display-buffer-alist'.  For example, to avoid
 creating a new window when opening man pages when there's already one,
 use
 
-(add-to-list 'display-buffer-alist
-     '("\\`\\*Man .*\\*\\'" .
-       (display-buffer-reuse-mode-window
-        (inhibit-same-window . nil)
-        (mode . Man-mode))))
+    (add-to-list 'display-buffer-alist
+         '("\\`\\*Man .*\\*\\'" .
+           (display-buffer-reuse-mode-window
+            (inhibit-same-window . nil)
+            (mode . Man-mode))))
 
 *** New window parameter 'no-delete-other-windows' prevents that
 its window gets deleted by 'delete-other-windows'.

etc/NEWS.27

@@ -233,8 +233,8 @@ into the init file when Emacs was started.  This call can now safely
 be removed.  Alternatively, if you want to ensure that your init file
 is still compatible with earlier versions of Emacs, change it to:
 
-(when (< emacs-major-version 27)
-  (package-initialize))
+    (when (< emacs-major-version 27)
+      (package-initialize))
 
 However, if your init file changes the values of 'package-load-list'
 or 'package-user-dir', or sets 'package-enable-at-startup' to nil then
@@ -1761,7 +1761,7 @@ error.
 It can be used to set any buffer as the next one to be used by
 'next-error' and 'previous-error'.
 
-** nxml-mode
+** 'nxml-mode'
 
 *** The default value of 'nxml-sexp-element-flag' is now t.
 This means that pressing 'C-M-SPACE' now selects the entire tree by
@@ -2285,7 +2285,7 @@ Unqualified host name: (was none), now %q
 Login name: was %u, now %l
 User's full name: was %U, now %L
 
-Merely having '(add-hook 'before-save-hook 'time-stamp)' in your
+Merely having '(add-hook 'before-save-hook #'time-stamp)' in your
 Emacs init file does not expose you to this change.  However,
 if you set 'time-stamp-format' or 'time-stamp-pattern' with a
 file-local variable, you may need to update the value.
@@ -2400,7 +2400,7 @@ expansion to backtrace buffers produced by the Lisp debugger, Edebug
 and ERT.  See the node "(elisp) Backtraces" in the Elisp manual for
 documentation of the new mode and its commands.
 
-** so-long.el helps to mitigate performance problems with long lines.
+** 'so-long' helps to mitigate performance problems with long lines.
 When 'global-so-long-mode' has been enabled, visiting a file with very
 long lines will (subject to configuration) cause the user's preferred
 'so-long-action' to be automatically invoked (by default, the buffer's
@@ -2599,8 +2599,8 @@ available by scrolling with the meta modifier key.
 To get the old behavior back, customize the user option
 'mouse-wheel-scroll-amount', or add the following to your init file:
 
-(customize-set-variable 'mouse-wheel-scroll-amount
-                        '(5 ((shift) . 1) ((control) . nil)))
+    (customize-set-variable 'mouse-wheel-scroll-amount
+                            '(5 ((shift) . 1) ((control) . nil)))
 
 By default, the font size will be changed in the window that the mouse
 pointer is over.  To change this behavior, you can customize the user

etc/NEWS.28

@@ -1677,7 +1677,7 @@ and variables.
 
 *** Lisp mode now uses 'common-lisp-indent-function'.
 To revert to the previous behavior,
-'(setq lisp-indent-function 'lisp-indent-function)' from 'lisp-mode-hook'.
+'(setq lisp-indent-function #'lisp-indent-function)' from 'lisp-mode-hook'.
 
 ** Change Logs and VC
 
@@ -2826,7 +2826,7 @@ different timezone causing a difference in the date.
 
 *** 'mspools-show' is now autoloaded.
 
-*** Loading dunnet.el in batch mode doesn't start the game any more.
+*** Loading 'dunnet' in batch mode doesn't start the game any more.
 Instead you need to do "emacs --batch -f dunnet" to start the game in
 batch mode.
 

lisp/help-fns.el

@@ -791,15 +791,40 @@ the C sources, too."
              (function-get function 'disabled))
     (insert "  This function is disabled.\n")))
 
+(defun help-fns--first-release-regexp (symbol)
+  (let* ((name (symbol-name symbol))
+         (quoted (regexp-quote name)))
+    ;; We used to use just (concat "\\_<" (regexp-quote name) "\\_>"),
+    ;; which had the advantage of adapting to the various notational
+    ;; conventions we've used over the years in etc/NEWS*, but it was also
+    ;; leading to many false positives.  So we use a more restrictive regexp
+    ;; now (which can still lead to false positives, e.g. because we don't
+    ;; distinguish between occurrences of the same symbol for
+    ;; different purposes, such as function name, var name, face name,
+    ;; property name, ...).
+    (concat
+     ;; The main "canonical" occurence of symbols is within '...'.
+     "'" quoted "'"
+     ;; Commands can also occur as `M-x blabla'.
+     "\\|M-x[ \t\n]+" quoted "\\_>"
+     ;; Other times we do '<key>' (<cmdname>).
+     "\\|(" quoted ")"
+     ;; Finally other times we just include sample code, which we will
+     ;; only recognize if it's indented by at least 2 spaces and start with
+     ;; an open paren.
+     "\\|^\\(?:  \\|\t\\)[ \t]*(\\(.*[( ']\\)?" quoted "\\_>")
+    ))
+
+
 (defun help-fns--first-release (symbol)
   "Return the likely first release that defined SYMBOL, or nil."
   ;; Code below relies on the etc/NEWS* files.
   ;; FIXME: Maybe we should also use the */ChangeLog* files when available.
   ;; FIXME: Maybe we should also look for announcements of the addition
   ;; of the *packages* in which the function is defined.
-  (let* ((name (symbol-name symbol))
-         (re (concat "\\_<" (regexp-quote name) "\\_>"))
+  (let* ((re (help-fns--first-release-regexp symbol))
          (news (directory-files data-directory t "\\`NEWS\\(\\'\\|\\.\\)"))
+         (case-fold-search nil)
          (place nil)
          (first nil))
     (with-temp-buffer
@@ -816,10 +841,11 @@ the C sources, too."
                 ;; Almost all entries are of the form "* ... in Emacs NN.MM."
                 ;; but there are also a few in the form "* Emacs NN.MM is a bug
                 ;; fix release ...".
-                (if (not (re-search-backward "^\\* .* Emacs \\([0-9.]+[0-9]\\)"
-                                             nil t))
-                    (message "Ref found in non-versioned section in %S"
-                             (file-name-nondirectory f))
+                (if (not (re-search-backward
+                          "^\\* \\(?:.* \\)?Emacs \\([0-9.]+[0-9]\\)"
+                          nil t))
+                    (message "Ref to %S found in non-versioned section in %S"
+                             symbol (file-name-nondirectory f))
                   (let ((version (match-string 1)))
                     (when (or (null first) (version< version first))
                       (setq place (list f pos))
@@ -827,6 +853,48 @@ the C sources, too."
     (when first
       (make-text-button first nil 'type 'help-news 'help-args place))))
 
+;; (defun help-fns--check-first-releases ()
+;;   "Compare the old liberal regexp to the new more restrictive one."
+;;   (interactive)
+;;   (let* ((quoted nil)
+;;          (rx-fun (lambda (orig-fun symbol)
+;;                    (if quoted
+;;                        (funcall orig-fun symbol)
+;;                      (format "\\_<%s\\_>"
+;;                              (regexp-quote (symbol-name symbol))))))
+;;          (count
+;;           (let ((count 0))
+;;             (obarray-map (lambda (sym)
+;;                            (when (or (fboundp sym) (boundp sym))
+;;                              (cl-incf count)))
+;;                          obarray)
+;;             count))
+;;          (p (make-progress-reporter "Check first releases..." 0 count)))
+;;     (with-current-buffer (get-buffer-create "*Check-first-release*")
+;;       (unwind-protect
+;;           (progn
+;;             (advice-add 'help-fns--first-release-regexp :around rx-fun)
+;;             (erase-buffer)
+;;             (setq count 0)
+;;             (obarray-map
+;;              (lambda (sym)
+;;                (when (or (fboundp sym) (boundp sym))
+;;                  (cl-incf count)
+;;                  (progress-reporter-update p count)
+;;                  (let ((vt (progn (setq quoted t)
+;;                                   (help-fns--first-release sym)))
+;;                        (vnil (progn (setq quoted nil)
+;;                                     (help-fns--first-release sym))))
+;;                    (when (and vnil (not (equal vt vnil)))
+;;                      (insert (symbol-name sym)
+;;                              "\nnot-quoted: " (or vnil "nil")
+;;                              "\nquoted:     " (or vt "nil")
+;;                              "\n\n")))))
+;;              obarray)
+;;             (progress-reporter-done p))
+;;         (advice-remove 'help-fns--first-release-regexp rx-fun))
+;;       (display-buffer (current-buffer)))))
+
 (add-hook 'help-fns-describe-function-functions
           #'help-fns--mention-first-release)
 (add-hook 'help-fns-describe-variable-functions
@@ -837,15 +905,6 @@ the C sources, too."
   (unless (memq 'help-fns--customize-variable-version
                 help-fns--activated-functions)
     (when-let ((first (and (symbolp object)
-                           ;; Weed out things that probably aren't
-                           ;; official things (so that we don't say
-                           ;; "Introduced in version 1.1" if the user
-                           ;; has done `(setq a 42)').
-                           (or (string-search "-" (symbol-name object))
-                               (and (boundp object)
-                                    (get object 'variable-documentation))
-                               (and (fboundp object)
-                                    (documentation object)))
                            (help-fns--first-release object))))
       (with-current-buffer standard-output
         (insert (format "  Probably introduced at or before Emacs version %s.\n"