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

From: Tassilo Horn <[email-masked]>
Date: Sat, 28 Sep 2024 19:02:44 +0200

Eli Zaretskii <[email-masked]> writes:

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

That would be good, yes.

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

Indeed.  And while we are here: doesn anyone know why we have an option
to disable imenu support?  I see that we have that since Jose
contributed the initial imenu support but why?  I can't see any harm
done if it was always enabled and would give a user-error like "For
imenu support for XXX files, program YYY has to be installed" or
something when invoking imenu.  And why someone might want to disable it
even if the required program is available is beyond my imagination.  I
mean, if you don't want to use imenu, then just don't invoke it...

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

Well, if we must keep this defcustom, then it should probably allow
enabling/disabling the feature for each file type separately, i.e., its
value should be a set (pdf djvu).

Bye,
  Tassilo