master fe002cc8ce: docview: new customization options for imenu

[Lars Ingebrigtsen]

branch: master
commit fe002cc8ce38efb256a2a60660ee626c2b2cdf81
Author: Jose A. Ortega Ruiz <jao@gnu.org>
Commit: Lars Ingebrigtsen <larsi@gnus.org>

    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).
---
 doc/emacs/misc.texi |  9 +++++++--
 lisp/doc-view.el    | 29 +++++++++++++++++++++++++----
 2 files changed, 32 insertions(+), 6 deletions(-)

diff --git a/doc/emacs/misc.texi b/doc/emacs/misc.texi
index 04f7f2e921..cef2580f3b 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 fa583df12b..9e3bb6e46c 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))