Make Makefile browser obsolete

* lisp/progmodes/make-mode.el:
(makefile-mode): Don't document Makefile browser mode.
(makefile-browser-toggle-state-for-line):
(makefile-browser-buffer-name, makefile-browser-leftmost-column)
(makefile-browser-cursor-column, makefile-browser-selected-mark)
(makefile-browser-unselected-mark)
(makefile-browser-auto-advance-after-selection-p)
(makefile-browser-hook, makefile-browser-map)
(makefile-browser-client, makefile-browser-selection-vector)
(makefile-browser-format-target-line)
(makefile-browser-format-macro-line, makefile-browser-fill)
(makefile-browser-next-line, makefile-browser-previous-line)
(makefile-browser-quit, makefile-browser-toggle)
(makefile-browser-insert-continuation)
(makefile-browser-insert-selection)
(makefile-browser-insert-selection-and-quit)
(makefile-browser-send-this-line-item)
(makefile-browser-start-interaction, makefile-browse)
(makefile-switch-to-browser, makefile-browser-on-macro-line-p)
(makefile-browser-this-line-target-name)
(makefile-browser-this-line-macro-name)
(makefile-browser-get-state-for-line)
(makefile-browser-set-state-for-line)
(makefile-browser-toggle-state-for-line): Make obsolete.  (Bug#58848)
(makefile-mode-menu): Remove Makefile browser from menu.
* etc/NEWS: Announce its obsoletion.

etc/NEWS

@@ -386,6 +386,13 @@ When this user option is non-nil, 'shell-get-old-input' ('C-RET')
 includes multiple shell "\" continuation lines from command output.
 Default is nil.
 
+** Make mode
+
+*** The Makefile browser is now obsolete.
+The command 'makefile-switch-to-browser' command is now obsolete,
+together with related commands used in the "*Macros and Targets*"
+buffer.  We recommend using an alternative like 'imenu' instead.
+
 ** Prog Mode
 
 +++

lisp/progmodes/make-mode.el

@@ -44,10 +44,6 @@
 ;; prerequisites, which targets are out-of-date, and which have no
 ;; prerequisites.
 ;;
-;; The command C-c C-b pops up a browser window listing all target and
-;; macro names.  You can mark or unmark items with C-c SPC, and insert
-;; all marked items back in the Makefile with C-c TAB.
-;;
 ;; The command C-c TAB in the makefile buffer inserts a GNU make builtin.
 ;; You will be prompted for the builtin's arguments.
 ;;
@@ -66,17 +62,9 @@
 ;;   interact with font-lock.
 ;; * Would be nice to edit the commands in ksh-mode and have
 ;;   indentation and slashification done automatically.  Hard.
-;; * Consider removing browser mode.  It seems useless.
 ;; * ":" should notice when a new target is made and add it to the
 ;;   list (or at least set `makefile-need-target-pickup').
-;; * Make browser into a major mode.
 ;; * Clean up macro insertion stuff.  It is a mess.
-;; * Browser entry and exit is weird.  Normalize.
-;; * Browser needs to be rewritten.  Right now it is kind of a crock.
-;;   Should at least:
-;;    * Act more like dired/buffer menu/whatever.
-;;    * Highlight as mouse traverses.
-;;    * B2 inserts.
 ;; * Update documentation above.
 ;; * Update texinfo manual.
 ;; * Update files.el.
@@ -118,6 +106,7 @@
   "Face to use for additionally highlighting Perl code in Font-Lock mode."
   :version "22.1")
 
+(make-obsolete-variable 'makefile-browser-buffer-name nil "30.1")
 (defcustom makefile-browser-buffer-name "*Macros and Targets*"
   "Name of the macro- and target browser buffer."
   :type 'string)
@@ -152,10 +141,12 @@ Otherwise, a space is inserted.
 The default is t."
   :type 'boolean)
 
+(make-obsolete-variable 'makefile-browser-leftmost-column nil "30.1")
 (defcustom makefile-browser-leftmost-column 10
   "Number of blanks to the left of the browser selection mark."
   :type 'integer)
 
+(make-obsolete-variable 'makefile-browser-cursor-column nil "30.1")
 (defcustom makefile-browser-cursor-column 10
   "Column the cursor goes to when it moves up or down in the Makefile browser."
   :type 'integer)
@@ -168,14 +159,17 @@ The default is t."
   "If non-nil, `makefile-backslash-region' will align backslashes."
   :type 'boolean)
 
+(make-obsolete-variable 'makefile-browser-selected-mark nil "30.1")
 (defcustom makefile-browser-selected-mark "+  "
   "String used to mark selected entries in the Makefile browser."
   :type 'string)
 
+(make-obsolete-variable 'makefile-browser-unselected-mark nil "30.1")
 (defcustom makefile-browser-unselected-mark "   "
   "String used to mark unselected entries in the Makefile browser."
   :type 'string)
 
+(make-obsolete-variable 'makefile-browser-auto-advance-after-selection-p nil "30.1")
 (defcustom makefile-browser-auto-advance-after-selection-p t
   "If non-nil, cursor will move after item is selected in Makefile browser."
   :type 'boolean)
@@ -198,6 +192,7 @@ to MODIFY A FILE WITHOUT YOUR CONFIRMATION when \"it seems necessary\"."
   "Normal hook run by `makefile-mode'."
   :type 'hook)
 
+(make-obsolete-variable 'makefile-browser-hook nil "30.1")
 (defvar makefile-browser-hook '())
 
 ;;
@@ -611,9 +606,6 @@ The function must satisfy this calling convention:
     ;; Other.
     ["Up To Date Overview" makefile-create-up-to-date-overview
      :help "Create a buffer containing an overview of the state of all known targets"]
-    ["Pop up Makefile Browser" makefile-switch-to-browser
-     ;; XXX: this needs a better string, the function is not documented...
-     :help "Pop up Makefile Browser"]
     ("Switch Makefile Type"
      ["GNU make" makefile-gmake-mode
       :help "An adapted `makefile-mode' that knows about GNU make"
@@ -641,6 +633,7 @@ The function must satisfy this calling convention:
       :selected (eq major-mode 'makefile-makepp-mode)])))
 
 
+(make-obsolete-variable 'makefile-browser-map nil "30.1")
 (defvar-keymap makefile-browser-map
   :doc "The keymap that is used in the macro- and target browser."
   "n"       #'makefile-browser-next-line
@@ -695,9 +688,11 @@ The function must satisfy this calling convention:
   "Table of all macro names known for this buffer.")
 (put 'makefile-macro-table 'risky-local-variable t)
 
+(make-obsolete-variable 'makefile-browser-client nil "30.1")
 (defvar makefile-browser-client nil
   "A buffer in Makefile mode that is currently using the browser.")
 
+(make-obsolete-variable 'makefile-browser-selection-vector nil "30.1")
 (defvar makefile-browser-selection-vector nil)
 (defvar makefile-has-prereqs nil)
 (defvar makefile-need-target-pickup t)
@@ -757,15 +752,8 @@ dependency, despite the colon.
 
 \\{makefile-mode-map}
 
-In the browser, use the following keys:
-
-\\{makefile-browser-map}
-
 Makefile mode can be configured by modifying the following variables:
 
-`makefile-browser-buffer-name':
-    Name of the macro- and target browser buffer.
-
 `makefile-target-colon':
     The string that gets appended to all target names
     inserted by `makefile-insert-target'.
@@ -783,24 +771,6 @@ Makefile mode can be configured by modifying the following variables:
    If you want a TAB (instead of a space) to be appended after the
    target colon, then set this to a non-nil value.
 
-`makefile-browser-leftmost-column':
-   Number of blanks to the left of the browser selection mark.
-
-`makefile-browser-cursor-column':
-   Column in which the cursor is positioned when it moves
-   up or down in the browser.
-
-`makefile-browser-selected-mark':
-   String used to mark selected entries in the browser.
-
-`makefile-browser-unselected-mark':
-   String used to mark unselected entries in the browser.
-
-`makefile-browser-auto-advance-after-selection-p':
-   If this variable is set to a non-nil value the cursor
-   will automagically advance to the next line after an item
-   has been selected in the browser.
-
 `makefile-pickup-everything-picks-up-filenames-p':
    If this variable is set to a non-nil value then
    `makefile-pickup-everything' also picks up filenames as targets
@@ -816,10 +786,6 @@ Makefile mode can be configured by modifying the following variables:
    IMPORTANT: Please note that enabling this option causes Makefile mode
    to MODIFY A FILE WITHOUT YOUR CONFIRMATION when \"it seems necessary\".
 
-`makefile-browser-hook':
-   A function or list of functions to be called just before the
-   browser is entered. This is executed in the makefile buffer.
-
 `makefile-special-targets-list':
    List of special targets. You will be offered to complete
    on one of those in the minibuffer whenever you enter a `.'.
@@ -1306,6 +1272,7 @@ Fill comments, backslashed lines, and variable definitions specially."
 ;;; ------------------------------------------------------------
 
 (defun makefile-browser-format-target-line (target selected)
+  (declare (obsolete nil "30.1"))
   (format
    (concat (make-string makefile-browser-leftmost-column ?\ )
 	   (if selected
@@ -1315,6 +1282,7 @@ Fill comments, backslashed lines, and variable definitions specially."
    target makefile-target-colon))
 
 (defun makefile-browser-format-macro-line (macro selected)
+  (declare (obsolete nil "30.1"))
   (format
    (concat (make-string makefile-browser-leftmost-column ?\ )
 	   (if selected
@@ -1323,14 +1291,21 @@ Fill comments, backslashed lines, and variable definitions specially."
 	   (makefile-format-macro-ref macro))))
 
 (defun makefile-browser-fill (targets macros)
+  (declare (obsolete nil "30.1"))
   (let ((inhibit-read-only t))
     (goto-char (point-min))
     (erase-buffer)
     (mapc
-     (lambda (item) (insert (makefile-browser-format-target-line (car item) nil) "\n"))
+     (lambda (item) (insert (with-suppressed-warnings
+                                ((obsolete makefile-browser-format-target-line))
+                              (makefile-browser-format-target-line (car item) nil))
+                            "\n"))
      targets)
     (mapc
-     (lambda (item) (insert (makefile-browser-format-macro-line (car item) nil) "\n"))
+     (lambda (item) (insert (with-suppressed-warnings
+                                ((obsolete makefile-browser-format-macro-line))
+                              (makefile-browser-format-macro-line (car item) nil))
+                            "\n"))
      macros)
     (sort-lines nil (point-min) (point-max))
     (goto-char (1- (point-max)))
@@ -1344,6 +1319,7 @@ Fill comments, backslashed lines, and variable definitions specially."
 
 (defun makefile-browser-next-line ()
   "Move the browser selection cursor to the next line."
+  (declare (obsolete nil "30.1"))
   (interactive)
   (unless (makefile-last-line-p)
     (forward-line 1)
@@ -1351,6 +1327,7 @@ Fill comments, backslashed lines, and variable definitions specially."
 
 (defun makefile-browser-previous-line ()
   "Move the browser selection cursor to the previous line."
+  (declare (obsolete nil "30.1"))
   (interactive)
   (unless (makefile-first-line-p)
     (forward-line -1)
@@ -1362,6 +1339,7 @@ Fill comments, backslashed lines, and variable definitions specially."
 
 (defun makefile-browser-quit ()
   "Leave the browser and return to the makefile buffer."
+  (declare (obsolete nil "30.1"))
   (interactive)
   (let ((my-client makefile-browser-client))
     (setq makefile-browser-client nil)	; we quit, so NO client!
@@ -1375,6 +1353,7 @@ Fill comments, backslashed lines, and variable definitions specially."
 
 (defun makefile-browser-toggle ()
   "Toggle the selection state of the browser item at the cursor position."
+  (declare (obsolete nil "30.1"))
   (interactive)
   (let ((this-line (count-lines (point-min) (point))))
     (setq this-line (max 1 this-line))
@@ -1387,19 +1366,24 @@ Fill comments, backslashed lines, and variable definitions specially."
 	  (let ((macro-name (makefile-browser-this-line-macro-name)))
 	    (delete-region (point) (progn (end-of-line) (point)))
 	    (insert
-	     (makefile-browser-format-macro-line
-		macro-name
-		(makefile-browser-get-state-for-line this-line))))
+             (with-suppressed-warnings
+                 ((obsolete makefile-browser-format-macro-line))
+               (makefile-browser-format-macro-line
+                macro-name
+                (makefile-browser-get-state-for-line this-line)))))
 	(let ((target-name (makefile-browser-this-line-target-name)))
 	  (delete-region (point) (progn (end-of-line) (point)))
 	  (insert
-	   (makefile-browser-format-target-line
-	      target-name
-	      (makefile-browser-get-state-for-line this-line))))))
+           (with-suppressed-warnings
+               ((obsolete makefile-browser-format-target-line))
+             (makefile-browser-format-target-line
+              target-name
+              (makefile-browser-get-state-for-line this-line)))))))
     (beginning-of-line)
     (forward-char makefile-browser-cursor-column)
     (if makefile-browser-auto-advance-after-selection-p
-	(makefile-browser-next-line))))
+        (with-suppressed-warnings ((obsolete makefile-browser-next-line))
+          (makefile-browser-next-line)))))
 
 ;;;
 ;;; Making insertions into the client buffer
@@ -1412,6 +1396,7 @@ character, insert a new blank line, go to that line and indent by one TAB.
 This is most useful in the process of creating continued lines when copying
 large dependencies from the browser to the client buffer.
 \(point) advances accordingly in the client buffer."
+  (declare (obsolete nil "30.1"))
   (interactive)
   (with-current-buffer makefile-browser-client
     (end-of-line)
@@ -1420,6 +1405,7 @@ large dependencies from the browser to the client buffer.
 (defun makefile-browser-insert-selection ()
   "Insert all selected targets and/or macros in the makefile buffer.
 Insertion takes place at point."
+  (declare (obsolete nil "30.1"))
   (interactive)
   (save-excursion
     (goto-char (point-min))
@@ -1431,11 +1417,15 @@ Insertion takes place at point."
 	(setq current-line (1+ current-line))))))
 
 (defun makefile-browser-insert-selection-and-quit ()
+  (declare (obsolete nil "30.1"))
   (interactive)
-  (makefile-browser-insert-selection)
-  (makefile-browser-quit))
+  (with-suppressed-warnings ((obsolete makefile-browser-insert-selection)
+                             (obsolete makefile-browser-quit))
+    (makefile-browser-insert-selection)
+    (makefile-browser-quit)))
 
 (defun makefile-browser-send-this-line-item ()
+  (declare (obsolete nil "30.1"))
   (if (makefile-browser-on-macro-line-p)
       (save-excursion
 	(let ((macro-name (makefile-browser-this-line-macro-name)))
@@ -1447,10 +1437,12 @@ Insertion takes place at point."
 	(insert target-name " ")))))
 
 (defun makefile-browser-start-interaction ()
+  (declare (obsolete nil "30.1"))
   (use-local-map makefile-browser-map)
   (setq buffer-read-only t))
 
 (defun makefile-browse (targets macros)
+  (declare (obsolete imenu "30.1"))
   (if (zerop (+ (length targets) (length macros)))
       (progn
 	(beep)
@@ -1460,19 +1452,23 @@ Insertion takes place at point."
                   "Consider running \\[makefile-pickup-everything]"))))
     (let ((browser-buffer (get-buffer-create makefile-browser-buffer-name)))
       (pop-to-buffer browser-buffer)
-      (makefile-browser-fill targets macros)
+      (with-suppressed-warnings ((obsolete makefile-browser-fill))
+        (makefile-browser-fill targets macros))
       (shrink-window-if-larger-than-buffer)
       (setq-local makefile-browser-selection-vector
                   (make-vector (+ (length targets) (length macros)) nil))
-      (makefile-browser-start-interaction))))
+      (with-suppressed-warnings ((obsolete makefile-browser-start-interaction))
+        (makefile-browser-start-interaction)))))
 
 (defun makefile-switch-to-browser ()
+  (declare (obsolete imenu "30.1"))
   (interactive)
   (run-hooks 'makefile-browser-hook)
   (setq makefile-browser-client (current-buffer))
   (makefile-pickup-targets)
   (makefile-pickup-macros)
-  (makefile-browse makefile-target-table makefile-macro-table))
+  (with-suppressed-warnings ((obsolete makefile-browse))
+    (makefile-browse makefile-target-table makefile-macro-table)))
 
 
 
@@ -1724,12 +1720,14 @@ This acts according to the value of `makefile-tab-after-target-colon'."
 
 (defun makefile-browser-on-macro-line-p ()
   "Determine if point is on a macro line in the browser."
+  (declare (obsolete nil "30.1"))
   (save-excursion
     (beginning-of-line)
     (re-search-forward "\\$[{(]" (line-end-position) t)))
 
 (defun makefile-browser-this-line-target-name ()
   "Extract the target name from a line in the browser."
+  (declare (obsolete nil "30.1"))
   (save-excursion
     (end-of-line)
     (skip-chars-backward "^ \t")
@@ -1737,6 +1735,7 @@ This acts according to the value of `makefile-tab-after-target-colon'."
 
 (defun makefile-browser-this-line-macro-name ()
   "Extract the macro name from a line in the browser."
+  (declare (obsolete nil "30.1"))
   (save-excursion
     (beginning-of-line)
     (re-search-forward "\\$[{(]" (line-end-position) t)
@@ -1755,13 +1754,18 @@ Uses `makefile-use-curly-braces-for-macros-p'."
       (format "$(%s)" macro-name))))
 
 (defun makefile-browser-get-state-for-line (n)
+  (declare (obsolete nil "30.1"))
   (aref makefile-browser-selection-vector (1- n)))
 
 (defun makefile-browser-set-state-for-line (n to-state)
+  (declare (obsolete nil "30.1"))
   (aset makefile-browser-selection-vector (1- n) to-state))
 
 (defun makefile-browser-toggle-state-for-line (n)
-  (makefile-browser-set-state-for-line n (not (makefile-browser-get-state-for-line n))))
+  (declare (obsolete nil "30.1"))
+  (with-suppressed-warnings ((obsolete makefile-browser-set-state-for-line)
+                             (obsolete makefile-browser-get-state-for-line))
+    (makefile-browser-set-state-for-line n (not (makefile-browser-get-state-for-line n)))))
 
 (defun makefile-last-line-p ()
   (= (line-end-position) (point-max)))