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

[Tassilo Horn <tsdh@gnu.org>]

Visuwesh <visuweshm@gmail.com> writes:

Hi Visuwesh,

[Sorry if this message appears twice but it seems to have bounced
yesterday.]

> Please review the attached.

First of all, the patch doesn't apply on master's NEWS and misc.texi
here.  If I exclude those, the changes to doc-view.el can be applied.
Unfortunately, I didn't find a PDF nor DjVu document on my computer
where an index can be built.  I have the relevant tools installed but
get the message that no index can be built for that document and
doc-view--outline becomes 'unavailable.

I've tried various PDFs generated by LaTeX with many section,
subsections, etc.  For DjVu, my sample size is 1, and that's a
presentation, so at least here I'm not sure if there should be an index
available...

That said, I haven't used the imenu feature before so I can't say if it
ever worked for me...

> diff --git a/doc/emacs/misc.texi b/doc/emacs/misc.texi
> index e19e554fb26..332d5b1468f 100644
> --- a/doc/emacs/misc.texi
> +++ b/doc/emacs/misc.texi
> @@ -581,17 +581,14 @@ DocView Navigation
>  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.  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}.
> +  DocView can generate an outline menu for PDF and Djvu documents using

Didn't Eli say the official spelling was DjVu?  That's at least the
spelling that the djvused man pages also uses and they should know.

> +the @command{mutool} and the @command{djvused} programs respectively
> +when they are available.  This is made accessible via the
> @code{imenu} +facility (@pxref{Imenu}).  You can customize how
> @code{imenu} items are +formatted and displayed using the variables
> @code{doc-view-imenu-format} +and @code{doc-view-imenu-flatten}.

I guess you should mention the new defcustom doc-view-djvused-program
here, too.

> +(defcustom doc-view-imenu-enabled (and (or (executable-find "mutool")
> +                                           (executable-find "djvused"))
> +                                       t)
> +  "Whether to generate imenu outline for PDF and Djvu files.
> +This uses \"mutool\" for PDF files and \"djvused\" for Djvu files."
>    :type 'boolean
> -  :version "29.1")
> +  :version "31.1")
> +(make-obsolete-variable 'doc-view-imenu-enabled
> +   "Imenu index is generated unconditionally, when available"
> +   "31.1")

Ah, I thought our last agreement was that we keep that variable (as
suggested by Jose) as it is used right now but make it possible to have
a value that tells to index only PDF or DjVu documents.

Well, I actually have no strong opinion here.  Technically, I like your
approach better because of its simplicity.  I would like to test with
some larger documents to see how long index building takes, though.

Anyhow, please write a complete sentence in the deprecation, so a dot at
the end.  And remove the comma.

Bye,
  Tassilo