GNU bug report logs - #58131
[PATCH] docview: new customization options for imenu

Previous Next

Full log

View this message in rfc822 format

From: Eli Zaretskii <eliz <at> gnu.org>
To: Jose A Ortega Ruiz <jao <at> gnu.org>
Cc: 58131 <at> debbugs.gnu.org
Subject: bug#58131: [PATCH] docview: new customization options for imenu
Date: Wed, 28 Sep 2022 17:25:19 +0300

> From: Jose A Ortega Ruiz <jao <at> gnu.org>
> Cc: 58131 <at> 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.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.