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

[Eli Zaretskii <eliz@gnu.org>]

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

> >   @defun format-spec template spec-alist &optional only-present
> >   This function returns a format string suitable for using in
> >   @code{format} and similar functions.  The format string is produced
> >   from @var{template} according to conversions specified in
> >   @var{spec-alist}, which is an alist (@pxref{Association Lists}) of
> >   the form @w{@code{(@var{letter} . @var{replacement})}}.  Each
> >   specification @code{%@var{letter}} in @var{template} will be
> >   replaced by @var{replacement} when producing the resulting format
> >   string.
> 
> 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? ;-)

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

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

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

> How's the new attached version?

It is much better, thanks.