[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
bug#58131: [PATCH] docview: new customization options for imenu
From: |
Eli Zaretskii |
Subject: |
bug#58131: [PATCH] docview: new customization options for imenu |
Date: |
Wed, 28 Sep 2022 18:49:58 +0300 |
> 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.