bug#41571: 27.0.91; "(elisp) Interpolated Strings" is under "(elisp) Text"

[Basil L. Contovounesios]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: "Basil L. Contovounesios" <contovob@tcd.ie>
>> Cc: 41571@debbugs.gnu.org
>> Date: Sun, 31 May 2020 10:24:46 +0100
>> 
>> > (Btw, why are you attachments appear before the text?  It makes
>> > responding harder, because I need to bring the citations to the
>> > front.)
>> 
>> Sorry, I got into the habit of doing that because I wasn't sure whether
>> attachments should go before or after the email signature.  I'm guessing
>> after?
>
> Yes, after is better if you include text that is worded as a preamble
> to the patch (which is usually the case).

OK.

>> This wording is much clearer, but the description of the output is
>> wrong: 'format-spec' and 'format' both produce the same result - a
>> formatted string, not a format string.
>
> Well, that just reflects on how the original text could lead to a
> grave misunderstanding, doesn't it? ;-)

I thought truth is in the eye of the beholder. ;)

>> > Here you use "key" without first explaining what it is.
>> 
>> I was relying on the preceding xref to the node on alists, which defines
>> the terms "alist", "key", and "associated value".
>
> I don't recommend to rely on that, not in general.  Cross-references
> are there for readers who want to see additional details, but the text
> should be self-explanatory even if the cross-references are not
> followed.  IOW, the cross-references are optional reading.

OK.

>> > How is what's described in the last sentence "an exception"?  Format
>> > strings used by 'format' also behave like that, right?
>> 
>> It's an exception to "beginning with % and ending with a letter".
>
> Ah!  But the text was worded in a way that led me to believe the
> exception was from the similarity between 'format' and 'format-spec'.
>
>> Would it be clearer if I said "the only specification that does not end
>> in a letter is %%, which is replaced with a single % in the output"?
>
> Not sure.  Perhaps that sentence should simply be removed, because it
> looks like the differences between these two APIs are described in the
> following paragraph.  And %% is supported the same by both of them, so
> mentioning it here is just a distraction.

Done.

>> The main use case for format-spec I've seen is where one part of the
>> program produces an alist with all the information that could ever be
>> needed, and another part of the program formats an often
>> user-customisable format string using this data.
>> 
>> An example of such a use case is in battery.el, where the alist produced
>> by battery-status-function is used to format battery-echo-area-format
>> and battery-mode-line-format (battery.el doesn't currently use
>> format-spec, but it could and my WIP patch for master changes that).
>
> How about saying this in the text?  In fact, "user-customizable format
> string" is never mentioned in the text, it is only hinted upon in the
> menu entry leading to this node.

Done.

> If the main use case is to let users customize string-valued variables
> conveniently, that use case should be described and explained in more
> detail, including why it makes customization more convenient.

I already tried doing that in the two opening paragraphs, which is why
the original text said something like "allow the user to control..."
rather than "allow Lisp programs to control...".  I've now mentioned
both in the opening and added a new paragraph at the end of the section.

How's the attached?

Thanks,

-- 
Basil

0001-Improve-format-spec-documentation-bug-41571.patch
Description: Text Data