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

[Jose A Ortega Ruiz]

On Wed, Sep 28 2022, Eli Zaretskii wrote:

>> 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.

That makes sense.  In this case, there's just 3 variables related to the
functionality, and my impression is that they provide options that users
often will want... which might be taken yet as an argument for /not/
adding them to the manual, now that i think of it :)

>> +(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?

>> +(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.

Thanks,
jao
-- 
Lying to ourselves is more deeply ingrained than lying to
others. -Fyodor Dostoevsky, novelist (1821-1881)