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

[Eli Zaretskii <eliz@gnu.org>]

> From: Jose A Ortega Ruiz <jao@gnu.org>
> Cc: 58131@debbugs.gnu.org
> Date: Wed, 28 Sep 2022 16:14:13 +0100
> 
> >> 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.
> 
> To me, the context is that this is read by a user of the functionality,
> wanting to fine-tune it (i rarely start exploring a functionality by
> reading the docstring of one of its customizable variables).

Think about the various Help commands, such as 'apropos': they show
the doc strings or just their first sentence entirely out of any
context.  Users who invoke such commands should be capable to
understand at a glance whether the command/variable is something they
should examine further.  So having important keywords in there helps
immensely to make such triage steps much faster and more efficient.

> Barring that: the Imenu section of the manual calls the items being
> formatted here simply "definitions".  If we assume that the user knows
> about imenu in general, one could have:
> 
>    "Format string for the imenu definitions extracted from documents."
> 
> Or, perhaps, trying to provide the missing context for not-yet-users:
> 
>    "Format string for the section titles extracted by imenu from docview documents."
> 
> Any better?

Yes, thanks.  My suggestion is a very minor variation of the latter:

 Format spec for imenu's display of section titles from docview documents.