bug#73530: [PATCH] Add imenu index function for Djvu files in doc-view

[Visuwesh <visuweshm@gmail.com>]

[-- Attachment #1: Type: text/plain, Size: 694 bytes --]

Tags: patch

Attached patch adds a function to create imenu index for Djvu files
using djvused.  If you do not have a Djvu file available, I can point to
a file from libgen that can be used as a test file.


In GNU Emacs 31.0.50 (build 7, x86_64-pc-linux-gnu, X toolkit, cairo
 version 1.18.0, Xaw scroll bars) of 2024-09-09 built on astatine
Repository revision: 7d7aa65f63db78c5732f1580213fc3767b767a4a
Repository branch: master
Windowing system distributor 'The X.Org Foundation', version 11.0.12101011
System Description: Debian GNU/Linux trixie/sid

Configured using:
 'configure --with-sound=alsa --with-x-toolkit=lucid --without-xaw3d
 --without-gconf --without-libsystemd --with-cairo'

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Add-imenu-index-function-for-Djvu-files-in-doc-view.patch --]
[-- Type: text/patch, Size: 6720 bytes --]

From 27174371d677f0e79f2291ce3f2849838a28ca0e Mon Sep 17 00:00:00 2001
From: Visuwesh <visuweshm@gmail.com>
Date: Sat, 28 Sep 2024 20:37:50 +0530
Subject: [PATCH] Add imenu index function for Djvu files in doc-view

* lisp/doc-view.el (doc-view-imenu-enabled): Tweak the default
value to check for 'djvused'.
(doc-view--djvu-outline, doc-view--parse-djvu-outline): Add new
functions to return imenu index for a Djvu file.
(doc-view--outline): Add new function to create the imenu index
depending on the file type.
(doc-view-imenu-index, doc-view-imenu-setup): Use new function
instead.
* doc/emacs/misc.texi (DocView Navigation): Mention index
creation using 'djvused' too.
* etc/NEWS: Announce the change.
---
 doc/emacs/misc.texi | 16 ++++++------
 etc/NEWS            |  5 ++++
 lisp/doc-view.el    | 60 +++++++++++++++++++++++++++++++++++++++++----
 3 files changed, 68 insertions(+), 13 deletions(-)

diff --git a/doc/emacs/misc.texi b/doc/emacs/misc.texi
index e19e554fb26..eee6f08ef3b 100644
--- a/doc/emacs/misc.texi
+++ b/doc/emacs/misc.texi
@@ -584,14 +584,14 @@ DocView Navigation
 @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.  You
-can further customize how @code{imenu} items are formatted and
-displayed using the variables @code{doc-view-imenu-format} and
-@code{doc-view-imenu-flatten}.
+  When the @command{mutool} or the @command{djvused} 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 the required program 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-imenu-flatten}.

 @findex doc-view-page-to-register
 @findex doc-view-jump-to-register
diff --git a/etc/NEWS b/etc/NEWS
index 607665a71bb..162af7b3e43 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -268,6 +268,11 @@ Docview can store current page to buffer local registers with the new
 command 'doc-view-page-to-register' (bound to 'm'), and later can be
 restored with 'doc-view-jump-to-register' (bound to ''').

++++
+*** Docview can generate imenu index for Djvu files.
+When the 'djvused' program is available, Docview can now generate imenu
+index for Djvu files from its outline.
+
 ** Tramp

 +++
diff --git a/lisp/doc-view.el b/lisp/doc-view.el
index 395993e6263..d461b606ce6 100644
--- a/lisp/doc-view.el
+++ b/lisp/doc-view.el
@@ -216,10 +216,13 @@ doc-view-mupdf-use-svg
   :type 'boolean
   :version "30.1")

-(defcustom doc-view-imenu-enabled (and (executable-find "mutool") t)
-  "Whether to generate an imenu outline when \"mutool\" is available."
+(defcustom doc-view-imenu-enabled (and (or (executable-find "mutool")
+                                           (executable-find "djvused"))
+                                       t)
+  "Whether to generate an imenu outline when available.
+This uses \"mutool\" for PDF files and \"djvused\" for Djvu files."
   :type 'boolean
-  :version "29.1")
+  :version "31.1")

 (defcustom doc-view-imenu-title-format "%t (%p)"
   "Format spec for imenu's display of section titles from docview documents.
@@ -2004,6 +2007,41 @@ doc-view--imenu-subtree
             (setq outline (cdr outline))))))
     (cons (nreverse index) outline)))

+(defun doc-view--djvu-outline (&optional file-name)
+  "Return a list describing the outline of FILE-NAME.
+If FILE-NAME is nil, use the current file.
+
+For the format, see `doc-view--pdf-outline'."
+  (unless file-name (setq file-name (buffer-file-name)))
+  (with-temp-buffer
+    (call-process "djvused" nil (current-buffer) nil
+                  "-e" "print-outline" file-name)
+    (goto-char (point-min))
+    (when (eobp)
+      (imenu-unavailable-error "Unable to create imenu index using `djvused'"))
+    (nreverse (doc-view--parse-djvu-outline (read (current-buffer))))))
+
+(defun doc-view--parse-djvu-outline (bookmark &optional level)
+  "Return a list describing the djvu outline from BOOKMARK.
+Optional argument LEVEL is the current heading level.  If nil, then 1 is
+used."
+  (unless level (setq level 1))
+  (let ((res))
+    (unless (eq (car bookmark) 'bookmarks)
+      (user-error "Unknown outline type: %S" (car bookmark)))
+    (pcase-dolist (`(,title ,page . ,rest) (cdr bookmark))
+      (push `((level . ,level)
+              (title . ,title)
+              (page . ,(string-to-number (string-remove-prefix "#" page))))
+            res)
+      (when (and rest (listp (car rest)))
+        (setq res (append
+                   (doc-view--parse-djvu-outline
+                    (cons 'bookmarks rest)
+                    (+ level 1))
+                   res))))
+    res))
+
 (defun doc-view-imenu-index (&optional file-name goto-page-fn)
   "Create an imenu index using \"mutool\" to extract its outline.

@@ -2012,16 +2050,28 @@ doc-view-imenu-index
 GOTO-PAGE-FN other than `doc-view-goto-page'."
   (let* ((goto (or goto-page-fn 'doc-view-goto-page))
          (act (lambda (_name _pos page) (funcall goto page)))
-         (outline (or doc-view--outline (doc-view--pdf-outline file-name))))
+         (outline (or doc-view--outline (doc-view--outline file-name))))
     (car (doc-view--imenu-subtree outline act))))

+(defun doc-view--outline (&optional file-name)
+  "Return the outline for the file FILE-NAME.
+If FILE-NAME is nil, use the current file instead."
+  (unless file-name (setq file-name (buffer-file-name)))
+  (pcase doc-view-doc-type
+    ('djvu
+     (when (executable-find "djvused")
+       (doc-view--djvu-outline file-name)))
+    (_
+     (when (executable-find "mutool")
+       (doc-view--pdf-outline file-name)))))
+
 (defun doc-view-imenu-setup ()
   "Set up local state in the current buffer for imenu, if needed."
   (when doc-view-imenu-enabled
     (setq-local imenu-create-index-function #'doc-view-imenu-index
                 imenu-submenus-on-top nil
                 imenu-sort-function nil
-                doc-view--outline (doc-view--pdf-outline))
+                doc-view--outline (doc-view--outline))
     (when doc-view--outline (imenu-add-to-menubar "Outline"))))

 ;;;; User interface commands and the mode
--
2.45.2