docview: new customization options for imenu

* doc/emacs/misc.texi (DocView Navigation):
* lisp/doc-view.el (doc-view-imenu-title-format, doc-view-imenu-flatten):
(doc-view--imenu-subtree): customizable format for imenu entry titles,
and flag to disable nested submenus.
* lisp/doc-view.el (doc-view--pdf-outline): clean up whitespace
markers '\r' and '\t' in imenu item titles (bug#58131).

2 files changed, 32 insertions, 6 deletions

diff --git a/doc/emacs/misc.texi b/doc/emacs/misc.texi
index 04f7f2e9213..cef2580f3be 100644
--- a/doc/emacs/misc.texi
+++ b/doc/emacs/misc.texi
@@ -585,11 +585,16 @@ default size for DocView, customize the variable
 @code{doc-view-resolution}.
 
 @vindex doc-view-imenu-enabled
+@vindex doc-view-imenu-flatten
+@vindex doc-view-imenu-format
   When the @command{mutool} program is available, DocView will use it
 to generate entries for an outline menu, making it accessible via the
 @code{imenu} facility (@pxref{Imenu}).  To disable this functionality
-even when @command{mutool} can be found on your system, customize
-the variable @code{doc-view-imenu-enabled} to the @code{nil} value.
+even when @command{mutool} can be found on your system, customize the
+variable @code{doc-view-imenu-enabled} to the @code{nil} value.  You
+can further customize how @code{imenu} items are formatted and
+displayed using the variables @code{doc-view-imenu-format} and
+@code{doc-view-flatten}.
 
 @node DocView Searching
 @subsection DocView Searching
diff --git a/lisp/doc-view.el b/lisp/doc-view.el
index fa583df12bd..9e3bb6e46c6 100644
--- a/lisp/doc-view.el
+++ b/lisp/doc-view.el
@@ -219,6 +219,23 @@ are available (see Info node `(emacs)Document View')."
   :type 'boolean
   :version "29.1")
 
+(defcustom doc-view-imenu-title-format "%t (%p)"
+  "Format string for document section titles in imenu.
+
+The special markers '%t' and '%p' are replaced by the section
+title and page number in this format string, which uses
+`format-spec'.
+
+For instance, setting this variable to \"%t\" will produce items
+showing only titles and no page number."
+  :type 'string
+  :version "29.1")
+
+(defcustom doc-view-imenu-flatten nil
+  "Whether to generate a flat list of sections instead of a nested tree."
+  :type 'boolean
+  :version "29.1")
+
 (defcustom doc-view-svg-background "white"
   "Background color for svg images.
 See `doc-view-mupdf-use-svg'."
@@ -1898,7 +1915,8 @@ structure is extracted by `doc-view--imenu-subtree'."
       (goto-char (point-min))
       (while (re-search-forward doc-view--outline-rx nil t)
         (push `((level . ,(length (match-string 1)))
-                (title . ,(match-string 2))
+                (title . ,(replace-regexp-in-string "\\\\[rt]" " "
+                                                    (match-string 2)))
                 (page . ,(string-to-number (match-string 3))))
               outline)))
     (nreverse outline)))
@@ -1911,11 +1929,14 @@ the first node in the outline and all its siblings at the same
 level.  Returns that imenu alist together with any other pending outline
 entries at an upper level."
   (let ((level (alist-get 'level (car outline)))
+        (nested (not doc-view-imenu-flatten))
         (index nil))
-    (while (and (car outline) (<= level (alist-get 'level (car outline))))
+    (while (and (car outline)
+                (or nested (<= level (alist-get 'level (car outline)))))
       (let-alist (car outline)
-        (let ((title (format "%s (%s)" .title .page)))
-          (if (> .level level)
+        (let ((title (format-spec doc-view-imenu-title-format
+                                  `((?t . ,.title) (?p . ,.page)))))
+          (if (and nested (> .level level))
               (let ((sub (doc-view--imenu-subtree outline act))
                     (fst (car index)))
                 (setq index (cdr index))