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

[Eli Zaretskii]

> From: Jose A Ortega Ruiz <jao@gnu.org>
> Cc: 58131@debbugs.gnu.org
> Date: Wed, 28 Sep 2022 15:05:50 +0100
> 
> >> +(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.
> 
> I would say they will: in the context of a docview imenu for a PDF
> document, there's little else it could reasonably be.  But i'm biased: do
> you think otherwise?

FWIW, I couldn't understand what that means.

How does being in the context of docview imenu for a PDF document help
understanding that here?  "Document section title" is general enough
terminology.  Using a "construct state" here doesn't help, either.

> >> +(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?
> 
> Given that the name of the variable does, i think mentioning it would
> just make that first sentence longer without adding too much
> information.  But again, as the implementor of the functionality,
> everything feels "obvious" to me.

My suggestion is

  Whether to flatten the list of sections in an imenu or show it nested.