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

[Eli Zaretskii <eliz@gnu.org>]

> From: Visuwesh <visuweshm@gmail.com>
> Date: Sat, 28 Sep 2024 20:40:54 +0530
> 
> 
> 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.

Thanks, but can we please not hard-code names of programs, and instead
use variables that can be adjusted by users?  I know that "mutool" was
hard-coded, but adding more hard-coded programs sounds too much.

Adding Tassilo to the discussion.

> +  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}.

This is misleading, I think: it leaves the impression that the two
tools are interchangeable, where in reality each one supports
different format of files.  The text should say explicitly that one is
for PDF, the other for Djvu.

> -(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.

"When available" sounds awkward.  "When possible", perhaps?

Also, "generate imenu outline" is too general.  Don't forget that the
first line of a doc string is shown by apropos commands, and so should
speak for itself.  I would say

  Whether to generate imenu outline for PDF and DJVU files.

The "when available" part is unnecessary, because Emacs checks for
availability, and the user can override that.

> +Optional argument LEVEL is the current heading level.  If nil, then 1 is
> +used."

  Optional argument LEVEL is the current heading level, which defaults
  to 1.

> +(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."

Since FILE-NAME can be omitted, it is better to use our usual style:

  If FILE-NAME is nil or omitted, it defaults to the current buffer's
  file name.

> +  (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)))))

We already tested that the relevant tool is available, so why test
that here again?

Thanks.