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

From: Visuwesh <[email-masked]>
Date: Sat, 28 Sep 2024 23:05:33 +0530

[சனி செப்டம்பர் 28, 2024] Tassilo Horn wrote:

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

Will do.

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

OK, will rewrite.

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

I was wondering the same thing, especially since the cost of making the
imenu index is not that high.
 
>>> -(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).

That would make sense.  I was wondering if we should create separate
defcustom for each program but this is a better approach.

[ BTW, is it "DJVU" or "Djvu"?  The comments in doc-view.el uses the
  latter AFAICT.  ]

> Bye,
>   Tassilo