[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
bug#58131: [PATCH] docview: new customization options for imenu
From: |
Jose A Ortega Ruiz |
Subject: |
bug#58131: [PATCH] docview: new customization options for imenu |
Date: |
Wed, 28 Sep 2022 15:05:50 +0100 |
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)
- bug#58131: [PATCH] docview: new customization options for imenu, Jose A Ortega Ruiz, 2022/09/27
- bug#58131: [PATCH] docview: new customization options for imenu, Lars Ingebrigtsen, 2022/09/28
- bug#58131: [PATCH] docview: new customization options for imenu, Eli Zaretskii, 2022/09/28
- bug#58131: [PATCH] docview: new customization options for imenu,
Jose A Ortega Ruiz <=
- bug#58131: [PATCH] docview: new customization options for imenu, Eli Zaretskii, 2022/09/28
- bug#58131: [PATCH] docview: new customization options for imenu, Jose A Ortega Ruiz, 2022/09/28
- bug#58131: [PATCH] docview: new customization options for imenu, Eli Zaretskii, 2022/09/28
- bug#58131: [PATCH] docview: new customization options for imenu, Jose A Ortega Ruiz, 2022/09/28
- bug#58131: [PATCH] docview: new customization options for imenu, Eli Zaretskii, 2022/09/28