bug#58131: [PATCH] docview: new customization options for imenu

[Eli Zaretskii <eliz@gnu.org>]

> From: Jose A Ortega Ruiz <jao@gnu.org>
> Date: Wed, 28 Sep 2022 03:21:31 +0100
> 
> A follow up to bug#58103 with a little fix for section title extraction
> and a couple of easy to implement customizable options.  I've tried to
> document them clearly enough in the docstrings and then just mention
> their existence in the manual: is that a good practice or do we prefer
> some duplication?

It's a possibility.  But if you have nothing of essence to say about a
variable, why mention it in the manual at all?  We don't need to
mention every user option in the manual, only the important ones.  We
expect users who want to use a package to review its options (e.g., bu
"M-x customize-group") and decide which ones they want to change from
the default.

> +(defcustom doc-view-imenu-title-format "%t (%p)"
> +  "Format string for document section titles in imenu.
> +
> +The special markers '%t' and '%p' are replaced by the section
> +title and page number in this format string, which uses
> +`format-spec'.

Will users immediately understand what you mean by "document section
title" here?  If no, perhaps a sentence explaining what that is would
be beneficial.

> +(defcustom doc-view-imenu-flatten nil
> +  "Whether to generate a flat list of sections instead of a nested tree."

This doesn't mention imenu in the doc string; should it?